Add PowerShell scripting support in Aspire AppHost

Directory.Packages.props

@@ -6,8 +6,9 @@
     <!-- Aspire packages -->
     <PackageVersion Include="Aspire.Hosting" Version="$(AspireVersion)" />
     <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireVersion)" />
+    <PackageVersion Include="Aspire.Hosting.Azure.Storage" Version="$(AspireVersion)" />
     <PackageVersion Include="Aspire.Hosting.Dapr" Version="$(AspireVersion)" />
-		<PackageVersion Include="Aspire.Hosting.Azure.AppContainers" Version="$(AspireVersion)" />
+    <PackageVersion Include="Aspire.Hosting.Azure.AppContainers" Version="$(AspireVersion)" />
     <PackageVersion Include="Aspire.Hosting.Azure.Redis" Version="$(AspireVersion)" />
     <PackageVersion Include="Aspire.Hosting.NodeJS" Version="$(AspireVersion)" />
     <PackageVersion Include="Aspire.Hosting.PostgreSQL" Version="$(AspireVersion)" />
@@ -16,7 +17,7 @@
     <PackageVersion Include="Aspire.Hosting.Redis" Version="$(AspireVersion)" />
     <PackageVersion Include="Aspire.Hosting.MongoDB" Version="$(AspireVersion)" />
     <PackageVersion Include="Aspire.Hosting.MySql" Version="$(AspireVersion)" />
-    <PackageVersion Include="Aspire.Hosting.SqlServer" Version="$(AspireVersion)" />
+    <PackageVersion Include="Aspire.Hosting.SqlServer" Version="$(AspireVersion)" />    
   </ItemGroup>
   <ItemGroup Label="Core Packages">
     <!-- AspNetCore packages -->
@@ -54,11 +55,9 @@
     <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="$(OpenTelemetryVersion)" />
     <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="$(OpenTelemetryVersion)" />
   </ItemGroup>
-
   <ItemGroup Label="Build Dependencies">
     <PackageVersion Include="Microsoft.DotNet.GenAPI.Task" Version="9.0.103-servicing.25071.13" />
   </ItemGroup>
-
   <ItemGroup Label="Integration Packages">
     <PackageVersion Include="Azure.Provisioning.AppContainers" Version="1.0.0" />
     <PackageVersion Include="JsonSchema.Net" Version="7.3.4" />
@@ -82,8 +81,8 @@
     <PackageVersion Include="AspNetCore.HealthChecks.RavenDB" Version="9.0.0" />
     <PackageVersion Include="YamlDotNet" Version="16.3.0" />
     <PackageVersion Include="Swashbuckle.AspNetCore" Version="7.3.1" />
+    <PackageVersion Include="Microsoft.PowerShell.SDK" Version="7.4.10" />
   </ItemGroup>
-
   <ItemGroup Label="Testing">
     <!-- Testing packages -->
     <PackageVersion Include="Aspire.Hosting.Testing" Version="$(AspireVersion)" />
@@ -99,9 +98,8 @@
     <PackageVersion Include="Testcontainers" Version="$(TestContainersVersion)" />
     <PackageVersion Include="Testcontainers.MsSql" Version="$(TestContainersVersion)" />
   </ItemGroup>
-
   <ItemGroup Label=".NET 9 Overrides" Condition="'$(TargetFramework)' == 'net9.0'">
     <PackageVersion Update="Microsoft.Extensions.Logging.Abstractions" Version="9.0.4" />
     <PackageVersion Include="Microsoft.Extensions.Options" Version="9.0.4" />
   </ItemGroup>
-</Project>
+</Project>

examples/powershell/CommunityToolkit.Aspire.PowerShell.AppHost/CommunityToolkit.Aspire.PowerShell.AppHost.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <Sdk Name="Aspire.AppHost.Sdk" Version="$(AspireAppHostSdkVersion)" />
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsAspireHost>true</IsAspireHost>
+    <UserSecretsId>bc193f31-c9f7-4e3d-b70a-0dc39ec3047f</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" />
+    <PackageReference Include="Aspire.Hosting.AppHost" />
+    <PackageReference Include="Aspire.Hosting.Azure.Storage" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\CommunityToolkit.Aspire.Hosting.PowerShell\CommunityToolkit.Aspire.Hosting.PowerShell.csproj" IsAspireProjectResource="false" />
+  </ItemGroup>
+
+</Project>

examples/powershell/CommunityToolkit.Aspire.PowerShell.AppHost/Program.cs

@@ -0,0 +1,39 @@
+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);
+
+// uploads the script in scripts/
+var script1 = ps.AddScript("script1", """
+    param($name)
+
+    write-information "Hello, $name"
+
+    # uncommenting this will hang the script if you don't attach the pwsh debugger
+    # wait-debugger
+
+    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 $pwd
+
+    write-information "Blob uploaded"
+""").WithArgs("world");
+
+// outputs "the sum of 2 and 3 is 5"
+var script2 = ps.AddScript("script2", """
+    & ./scripts/script.ps1 @args
+    """)
+    .WithArgs(2, 3)
+    .WaitForCompletion(script1);
+
+builder.Build().Run();
+

examples/powershell/CommunityToolkit.Aspire.PowerShell.AppHost/Properties/launchSettings.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:17118;http://localhost:15215",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21165",
+        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22038"
+      }
+    },
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15215",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19175",
+        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20201"
+      }
+    }
+  }
+}

examples/powershell/CommunityToolkit.Aspire.PowerShell.AppHost/Scripts/script.ps1

@@ -0,0 +1,3 @@
+param($a, $b)
+
+Write-Information "The sum of $a and $b is: $($a + $b)"

examples/powershell/CommunityToolkit.Aspire.PowerShell.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Aspire.Hosting.Dcp": "Warning"
+    }
+  }
+}

src/CommunityToolkit.Aspire.Hosting.PowerShell/CommunityToolkit.Aspire.Hosting.PowerShell.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AdditionalPackageTags>powershell; pwsh; scripting; script; hosting</AdditionalPackageTags>
+    <Description>Run powershell scripts in-process with your Aspire AppHost, injecting aspire resources and/or object instances as variables, using the command lines tools of your choice like azure cli, azd, or any other terminal tools.</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" />
+    <PackageReference Include="Microsoft.PowerShell.SDK" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="CommunityToolkit.Aspire.Hosting.PowerShell.Tests" />
+  </ItemGroup>
+</Project>

src/CommunityToolkit.Aspire.Hosting.PowerShell/DistributedApplicationBuilderExtensions.cs

@@ -0,0 +1,99 @@
+using Aspire.Hosting;
+using Aspire.Hosting.ApplicationModel;
+using Microsoft.Extensions.DependencyInjection;
+using System.Diagnostics;
+using System.Globalization;
+using System.Management.Automation;
+using System.Management.Automation.Runspaces;
+
+namespace CommunityToolkit.Aspire.Hosting.PowerShell;
+
+/// <summary>
+/// Extensions for the <see cref="IDistributedApplicationBuilder"/> to add PowerShell runspace pool resources.
+/// </summary>
+public static class DistributedApplicationBuilderExtensions
+{
+    /// <summary>
+    /// Adds a PowerShell runspace pool resource to the distributed application.
+    /// </summary>
+    /// <param name="builder"></param>
+    /// <param name="name"></param>
+    /// <param name="languageMode"></param>
+    /// <param name="minRunspaces"></param>
+    /// <param name="maxRunspaces"></param>
+    /// <returns></returns>
+    /// <exception cref="ArgumentException"></exception>
+    /// <exception cref="DistributedApplicationException"></exception>
+    public static IResourceBuilder<PowerShellRunspacePoolResource> AddPowerShell(
+        this IDistributedApplicationBuilder builder,
+        [ResourceName] string name,
+        PSLanguageMode languageMode = PSLanguageMode.ConstrainedLanguage,
+        int minRunspaces = 1,
+        int maxRunspaces = 5)
+    {
+        if (string.IsNullOrWhiteSpace(name))
+            throw new ArgumentException("Value cannot be null or whitespace.", nameof(name));
+
+        if (builder.Resources.OfType<PowerShellRunspacePoolResource>().Any(
+            rsp => rsp.Name == name))
+        {
+            throw new DistributedApplicationException("AddPowerShell failed",
+                new InvalidOperationException(
+                    string.Format(
+                        CultureInfo.InvariantCulture,
+                        "A PowerShell resource with the name '{0}' already exists.", name)));
+        }
+
+        var pool = new PowerShellRunspacePoolResource(name, languageMode, minRunspaces, maxRunspaces);
+
+        builder.Eventing.Subscribe<AfterEndpointsAllocatedEvent>(async (e, ct) =>
+        {
+            var pools = e.Model.Resources.OfType<PowerShellRunspacePoolResource>().ToList();
+
+            foreach (var poolResource in pools)
+            {
+                Debug.Assert(poolResource is not null);
+
+                var loggerService = e.Services.GetRequiredService<ResourceLoggerService>();
+                var notificationService = e.Services.GetRequiredService<ResourceNotificationService>();
+
+                var sessionState = InitialSessionState.CreateDefault();
+
+                foreach (var annotation in poolResource.Annotations)
+                {
+                    if (annotation is PowerShellVariableReferenceAnnotation<ConnectionStringReference> reference)
+                    {
+                        var connectionString = await reference.Value.Resource.GetConnectionStringAsync(ct);
+                        sessionState.Variables.Add(
+                            new SessionStateVariableEntry(reference.Name, connectionString,
+                                $"ConnectionString for {reference.Value.Resource.GetType().Name} '{reference.Name}'",
+                                ScopedItemOptions.ReadOnly | ScopedItemOptions.AllScope));
+                    }
+                }
+
+                var poolName = poolResource.Name;
+                var poolLogger = loggerService.GetLogger(poolName);
+
+                _ = notificationService.WaitForDependenciesAsync(poolResource, ct)
+                    .ContinueWith(
+                        async _ =>
+                            await poolResource.StartAsync(sessionState, notificationService, poolLogger, ct),
+                        ct);
+            }
+        });
+
+        return builder.AddResource(pool)
+            .WithInitialState(new()
+            {
+                ResourceType = "PowerShellRunspacePool",
+                State = KnownResourceStates.NotStarted,
+                Properties = [
+
+                    new ("LanguageMode", pool.LanguageMode.ToString()),
+                    new ("MinRunspaces", pool.MinRunspaces.ToString()),
+                    new ("MaxRunspaces", pool.MaxRunspaces.ToString())
+                ]
+            })
+            .ExcludeFromManifest();
+    }
+}