Add documentation for using incremental setup with Aspire

Author: twsouthwick

aspnetcore/migration/fx-to-core/areas/authentication.md

@@ -181,6 +181,8 @@ There are just a few small code changes needed to enable remote authentication i
 
 First, follow the [remote app setup](xref:migration/fx-to-core/inc/remote-app-setup) instructions to connect the ASP.NET Core and ASP.NET apps. Then, there are just a couple extra extension methods to call to enable remote app authentication.
 
+:::zone pivot="manual"
+
 #### ASP.NET app configuration
 
 The ASP.NET app needs to be configured to add the authentication endpoint. Adding the authentication endpoint is done by calling the `AddAuthenticationServer` extension method to set up the HTTP module that watches for requests to the authentication endpoint. Note that remote authentication scenarios typically want to add proxy support as well, so that any authentication related redirects correctly route to the ASP.NET Core app rather than the ASP.NET one.
@@ -195,6 +197,25 @@ Next, the ASP.NET Core app needs to be configured to enable the authentication h
 
 The boolean that is passed to the `AddAuthenticationClient` call specifies whether remote app authentication should be the default authentication scheme. Passing `true` will cause the user to be authenticated via remote app authentication for all requests, whereas passing `false` means that the user will only be authenticated with remote app authentication if the remote app scheme is specifically requested (with `[Authorize(AuthenticationSchemes = RemoteAppAuthenticationDefaults.AuthenticationScheme)]` on a controller or action method, for example). Passing false for this parameter has the advantage of only making HTTP requests to the original ASP.NET app for authentication for endpoints that require remote app authentication but has the disadvantage of requiring annotating all such endpoints to indicate that they will use remote app auth.
 
+:::zone-end
+
+:::zone pivot="aspire"
+When using Aspire, the configuration will be done via environment variables and are set by the AppHost. To enable remote session, the option must be enabled:
+
+```csharp
+...
+
+var coreApp = builder.AddProject<Projects.AuthRemoteIdentityCore>("core")
+    .WithHttpHealthCheck()
+    .WaitFor(frameworkApp)
+    .WithIncrementalMigrationFallback(frameworkApp, options => options.RemoteAuthentication = RemoteAuthentication.DefaultScheme);
+
+...
+```
+
+Once this is done, it will be automatically hooked up in both the framework and core applications.
+:::zone-end
+
 #### Using Remote Authentication with Specific Endpoints
 
 When you set the default scheme to `false`, you can specify remote authentication for specific controllers or actions:

aspnetcore/migration/fx-to-core/areas/session.md

@@ -7,6 +7,7 @@ monikerRange: '>= aspnetcore-6.0'
 ms.date: 11/9/2022
 ms.topic: article
 uid: migration/fx-to-core/areas/session
+zone_pivot_groups: migration-remote-app-setup
 ---
 
 # Migrate ASP.NET Framework Session to ASP.NET Core
@@ -178,6 +179,7 @@ Out of the box, there is a simple JSON serializer that allows each session key t
 
 ### Application configuration
 
+:::zone pivot="manual"
 **ASP.NET Core configuration:**
 
 Call `AddRemoteAppSession` and `AddJsonSessionSerializer` to register known session item types:
@@ -200,6 +202,26 @@ Add this change to `Global.asax.cs`:
 
 :::code language="csharp" source="~/migration/fx-to-core/areas/session/samples/remote/Global.asax.cs":::
 
+:::zone-end
+
+:::zone pivot="aspire"
+When using Aspire, the configuration will be done via environment variables and are set by the AppHost. To enable remote session, the option must be enabled:
+
+```csharp
+...
+
+var coreApp = builder.AddProject<Projects.CoreApplication>("core")
+    .WithHttpHealthCheck()
+    .WaitFor(frameworkApp)
+    .WithIncrementalMigrationFallback(frameworkApp, options => options.RemoteSession = RemoteSession.Enabled);
+
+...
+```
+
+Once this is done, it will be automatically hooked up in both the framework and core applications.
+
+:::zone-end
+
 ### Communication protocol
 
 #### Readonly sessions

aspnetcore/migration/fx-to-core/inc/remote-app-setup.md

@@ -7,6 +7,7 @@ monikerRange: '>= aspnetcore-6.0'
 ms.date: 11/9/2022
 ms.topic: article
 uid: migration/fx-to-core/inc/remote-app-setup
+zone_pivot_groups: migration-remote-app-setup
 ---
 
 # Remote app setup
@@ -26,6 +27,8 @@ Common scenarios this enables:
 >
 > The virtual directory setup is used for route generation, authorization, and other services within the system. At this point, no reliable method has been found to enable different virtual directories due to how ASP.NET Framework works.
 
+:::zone pivot="manual"
+
 To enable the ASP.NET Core app to communicate with the ASP.NET app, it's necessary to make a couple small changes to each app.
 
 You need to configure two configuration values in both applications:
@@ -144,6 +147,195 @@ To enable proxying from the ASP.NET Core application to the ASP.NET Framework ap
     app.Run();
     ```
 
+:::zone-end
+
+:::zone pivot="aspire"
+
+> [!NOTE]
+> This is still in preview and not available on NuGet.org, so you must configure your NuGet config to pull libraries from the .NET Libraries daily feed:
+>
+> ```xml
+> <?xml version="1.0" encoding="utf-8"?>
+> <configuration>
+>   <packageSources>
+>     <!--To inherit the global NuGet package sources remove the <clear/> line below -->
+>     <clear />
+>     <add key="nuget" value="https://api.nuget.org/v3/index.json" />
+>     <add key=".NET Libraries Daily" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-libraries/nuget/v3/index.json" />
+>   </packageSources>
+> </configuration>
+> ```
+
+## Setup Aspire orchestration
+
+1. Add Aspire orchestration for the ASP.NET Framework application
+1. Add a new ASP.NET Core application to the solution and add it to your Aspire orchestration
+1. Update the AppHost to target Windows as IIS integration requires that:
+    ```diff
+    - <TargetFramework>net9.0</TargetFramework>
+    + <TargetFramework>net9.0-windows</TargetFramework>
+    ```
+1. Add the following Aspire integrations to your app host:
+    * `Aspire.Hosting.IncrementalMigration`
+    * `C3D.Extensions.Aspire.IISExpress`
+1. Configure IIS Express to locally host your framework application and configure incremental migration fallback:
+
+    ```csharp
+    var builder = DistributedApplication.CreateBuilder(args);
+    
+    var frameworkApp = builder.AddIISExpress("iis")
+        .AddSiteProject<Projects.FrameworkApplication>("framework")
+        .WithDefaultIISExpressEndpoints()
+        .WithOtlpExporter()
+        .WithHttpHealthCheck(path: "/framework");
+    
+    var coreApp = builder.AddProject<Projects.CoreApplication>("core")
+        .WithHttpHealthCheck()
+        .WaitFor(frameworkApp)
+        .WithIncrementalMigrationFallback(frameworkApp, options => options.RemoteSession = RemoteSession.Enabled);
+    
+    builder.Build().Run();
+    ```
+1. Configure the options of the incremental migration fallback for the scenarios you want to support.
+
+## Configure ServiceDefaults to support ASP.NET Framework
+
+1. Add the package `Aspire.Microsoft.AspNetCore.SystemWebAdapters` to your application.
+1. Update the ServiceDefaults project to support .NET Framework. This is based off of the default ServiceDefaults and may different if you have customized anything.
+    * Update the target framework to multitarget:
+        ```diff
+        - <TargetFramework>net9.0</TargetFramework>
+        + <TargetFrameworks>net9.0;net48</TargetFrameworks>
+        ```
+    * Update the PackageReferences to account for the different frameworks:
+        ```xml
+         <ItemGroup>
+            <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
+            <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
+            <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
+            <PackageReference Include="OpenTelemetry.Instrumentation.Http" />
+            <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" />
+            <PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" />
+          </ItemGroup>
+        
+          <ItemGroup Condition=" '$(TargetFramework)' == 'net9.0'">
+            <FrameworkReference Include="Microsoft.AspNetCore.App" />
+        
+            <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" />
+            <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" />
+        
+            <Compile Remove="Framework/**/*" />
+          </ItemGroup>
+        
+          <ItemGroup Condition=" '$(TargetFramework)' == 'net48' ">
+            <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
+            <PackageReference Include="OpenTelemetry.Instrumentation.AspNet" />
+          </ItemGroup>
+        ```
+    * In the Extensions.cs file, you'll need to conditionally exclude the ServiceDiscovery APIs as those are currently not supported on .NET Framework:
+        ```diff
+        + #if NET
+                builder.Services.AddServiceDiscovery();
+        + #endif
+        
+                builder.Services.ConfigureHttpClientDefaults(http =>
+                {
+                    // Turn on resilience by default
+                    http.AddStandardResilienceHandler();
+        
+        + #if NET
+                    // Turn on service discovery by default
+                    http.AddServiceDiscovery();
+        + #endif
+                });
+        ```
+    * To enable telemetry, update the metrics and tracing registrations:
+
+        ```diff
+                builder.Services.AddOpenTelemetry()
+                    .WithMetrics(metrics =>
+                    {
+                        metrics
+        + #if NET
+                            .AddAspNetCoreInstrumentation()
+        + #else
+        +                     .AddAspNetInstrumentation()
+        + #endif
+                            .AddSqlClientInstrumentation()
+                            .AddHttpClientInstrumentation()
+                            .AddRuntimeInstrumentation();
+                    })
+                    .WithTracing(tracing =>
+                    {
+                        tracing.AddSource(builder.Environment.ApplicationName)
+        + #if NET
+                            .AddAspNetCoreInstrumentation()
+        + #else
+        +                     .AddAspNetInstrumentation()
+        + #endif
+                            .AddSqlClientInstrumentation()
+                            .AddHttpClientInstrumentation();
+                    });
+        ```
+    * Disable the default endpoints as that only applies for ASP.NET Core:
+
+        ```diff
+        + #if NET
+            public static WebApplication MapDefaultEndpoints(this WebApplication app)
+            {
+                // Default endpoint registrations
+            }
+        + #endif
+        ```
+
+## Configure ASP.NET Framework Application
+
+1. Reference the ServiceDefaults project
+1. Add the configuration code to the `Application_Start` method in your `Global.asax.cs` file:
+
+    ```CSharp
+    protected void Application_Start()
+    {
+        HttpApplicationHost.RegisterHost(builder =>
+        {
+            builder.AddServiceDefaults();
+            builder.AddSystemWebAdapters();
+        });
+    }
+    ```
+
+## Configure ASP.NET Core Application
+
+1. Reference the ServiceDefaults project
+1. Add the System.Web adapters in Programs.cs:
+
+    ```diff
+    var builder = WebApplication.CreateBuilder();
+    
+    builder.AddServiceDefaults();
+    + builder.AddSystemWebAdapters();
+    
+    ...
+
+    var app = builder.Build();
+
+    ...
+
+    + // Must be placed after routing if manually added
+    + app.UseSystemWebAdapters();
+
+    ...
+
+    + app.MapRemoteAppFallback()
+    +
+    +   // Optional, but recommended unless middleware is needed
+    +   .ShortCircuit();
+
+    app.Run();
+    ```
+
+:::zone-end
+
 With this configuration:
 
 1. **Local routes take precedence**: If the ASP.NET Core application has a matching route, it will handle the request locally

aspnetcore/zone-pivot-groups.yml

@@ -118,3 +118,11 @@ groups:
       title: MSTest
     - id: nunit
       title: NUnit
+- id: migration-remote-app-setup
+  title: Remote app setup
+  prompt: Choose how to configure remote app
+  pivots:
+    - id: manual
+      title: Manually
+    - id: aspire
+      title: Aspire