PowerShell integration

The Aspire PowerShell hosting integration enables you to run PowerShell Core (pwsh) scripts alongside your Aspire projects in the 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.

⭐ Community Toolkit

Hosting integration

aspire add communitytoolkit-powershell

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> communitytoolkit-powershell (CommunityToolkit.Aspire.Hosting.PowerShell)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.PowerShell@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.PowerShell" Version="*" />

Add PowerShell resource

In your AppHost, call AddPowerShell to register a PowerShell resource. Provide the resource name that appears in the Aspire dashboard:

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);

builder.Build().Run();

Add scripts

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

var builder = DistributedApplication.CreateBuilder(args);

var ps = builder.AddPowerShell("ps");

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);

builder.Build().Run();

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 builder = DistributedApplication.CreateBuilder(args);

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"
""");

builder.Build().Run();

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

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator();

var ps = builder.AddPowerShell("ps")
    .WaitFor(storage);

builder.Build().Run();

Custom arguments

Pass arguments to your PowerShell scripts using the WithArgs method:

var builder = DistributedApplication.CreateBuilder(args);

var ps = builder.AddPowerShell("ps");

var script = ps.AddScript("process-data", """
    param($count, $name)

    Write-Information "Processing $count items for $name"
""").WithArgs(5, "demo");

builder.Build().Run();

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 builder = DistributedApplication.CreateBuilder(args);

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);

builder.Build().Run();

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 builder = DistributedApplication.CreateBuilder(args);

var ps = builder.AddPowerShell("ps");

var script = ps.AddScript("file-ops", """
    $pwd | Write-Information
    Get-ChildItem ./scripts
""");

builder.Build().Run();

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.