PowerShell integration

⭐ Community Toolkit

The Aspire PowerShell hosting integration enables you to run PowerShell Core (pwsh) scripts alongside your Aspire projects in the Aspire app host. This integration allows you to script your resources, reference connection strings, access live resources, and leverage the full power of PowerShell within your distributed application.

Note

This integration requires PowerShell Core (pwsh) 7.4 or later to be installed on your system and available in your PATH. For installation instructions, see Install PowerShell.

Hosting integration

To get started with the Aspire PowerShell hosting integration, install the CommunityToolkit.Aspire.Hosting.PowerShell NuGet package in the app host project.

Install the NuGet package

dotnet add package CommunityToolkit.Aspire.Hosting.PowerShell

Add PowerShell resource

To add a PowerShell resource to your app host, use the AddPowerShell extension method:

using CommunityToolkit.Aspire.Hosting.PowerShell;
  
var builder = DistributedApplication.CreateBuilder(args);
  
var storage = builder.AddAzureStorage("storage").RunAsEmulator();
var blob = storage.AddBlobs("myblob");
  
var ps = builder.AddPowerShell("ps")
    .WithReference(blob)
    .WaitFor(storage);
  
// After adding all resources, run the app...

The AddPowerShell method requires:

name: The name of the PowerShell resource in the Aspire dashboard

Add scripts

To execute PowerShell scripts within your resource, use the AddScript method:

var ps = builder.AddPowerShell("ps")
    .WithReference(blob);
  
var script1 = ps.AddScript("script1", """
    param($name)
  
    Write-Information "Hello, $name"
    Write-Information "`$myblob is $myblob"
  
    az storage container create --connection-string $myblob -n demo
    az storage blob upload --connection-string $myblob -c demo --file ./scripts/script.ps1
  
    Write-Information "Blob uploaded"
""").WithArgs("world");
  
var script2 = ps.AddScript("script2", """
    & ./scripts/script.ps1 @args
""")
    .WithArgs(2, 3)
    .WaitForCompletion(script1);
  
// After adding all resources, run the app...

The AddScript method requires:

name: The name of the script resource in the Aspire dashboard
script: The PowerShell script content to execute

References and dependencies

Use WithReference to pass connection strings and resource references to your PowerShell scripts. Referenced resources are available as variables in your script scope:

var storage = builder.AddAzureStorage("storage").RunAsEmulator();
var blob = storage.AddBlobs("myblob");
  
var ps = builder.AddPowerShell("ps")
    .WithReference(blob);  // The $myblob variable is now available in scripts
  
var script = ps.AddScript("demo", """
    Write-Information "Connection string: $myblob"
""");
  
// After adding all resources, run the app...

Use WaitFor to specify that a PowerShell resource should wait for other resources to be ready before executing:

var storage = builder.AddAzureStorage("storage").RunAsEmulator();
  
var ps = builder.AddPowerShell("ps")
    .WaitFor(storage);  // Wait for storage to be ready before running scripts
  
// After adding all resources, run the app...

Custom arguments

Pass arguments to your PowerShell scripts using the WithArgs method:

var ps = builder.AddPowerShell("ps");
  
var script = ps.AddScript("process-data", """
    param($count, $name)
  
    Write-Information "Processing $count items for $name"
""").WithArgs(5, "demo");
  
// After adding all resources, run the app...

Scripts can define parameters using PowerShell's param() block and receive arguments passed via WithArgs.

Script execution order

Control the execution order of scripts using WaitForCompletion. A script that calls WaitForCompletion will not run until the referenced script completes:

var ps = builder.AddPowerShell("ps");
  
var script1 = ps.AddScript("setup", """
    Write-Information "Setting up resources"
    "setup-data.txt" | Set-Content "ready"
""");
  
var script2 = ps.AddScript("process", """
    Write-Information "Processing after setup"
""").WaitForCompletion(script1);  // Waits for script1 to complete
  
// After adding all resources, run the app...

Working directory

Scripts execute in the context of your app host's working directory. You can access files relative to this directory within your scripts:

var ps = builder.AddPowerShell("ps");
  
var script = ps.AddScript("file-ops", """
    $pwd | Write-Information
    Get-ChildItem ./scripts
""");
  
// After adding all resources, run the app...

Debugging

While your app host is running a script that contains a Wait-Debugger call, you can attach a PowerShell debugger to debug the script interactively.

Open a terminal with PowerShell Core (pwsh) 7.4 or later and use the following commands:

Get-PSHostProcessInfo
Enter-PSHostProcess -Id <ProcessId>
Get-Runspace
Debug-Runspace -Id <RunspaceId>

For more information about PowerShell debugging, see Enter-PSHostProcess documentation.