Update System.Web adapters docs for 2.2.0 (#36481)

* Update System.Web adapters docs for 2.2.0

* add to toc

* spelling

* clean up doc

* remove note

* explains the value of swa machinekey

* reorganize for clairy

* Apply suggestions from code review

Co-authored-by: Wade Pickett <wpickett@microsoft.com>

---------

Co-authored-by: Wade Pickett <wpickett@microsoft.com>

Author: twsouthwick

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

@@ -1,10 +1,11 @@
 ---
 title: ASP.NET Framework to Core Authentication Migration
+ai-usage: ai-assisted
+author: twsouthwick
 description: ASP.NET Framework to Core Authentication Migration
-author: wadepickett
-ms.author: wpickett
 monikerRange: '>= aspnetcore-6.0'
-ms.date: 09/24/2025
+ms.author: tasou
+ms.date: 12/10/2025
 ms.topic: article
 uid: migration/fx-to-core/areas/authentication
 zone_pivot_groups: migration-remote-app-setup
@@ -216,6 +217,15 @@ var coreApp = builder.AddProject<Projects.AuthRemoteIdentityCore>("core")
 Once this is done, it will be automatically hooked up in both the framework and core applications.
 :::zone-end
 
+#### Remote authentication with YARP fallback
+
+When using remote authentication with YARP-based fallback to the ASP.NET Framework app, make sure that fallback requests don't invoke remote authentication. If remote authentication runs during fallback, the app makes unnecessary extra calls back to the Framework app and can lead to confusing behavior.
+
+To avoid running remote authentication for fallback requests, use one of these approaches:
+
+* Use routing short-circuit metadata on the YARP fallback route so that the route bypasses the rest of the middleware pipeline. For example, call `ShortCircuit` on the fallback endpoint as shown in the remote app setup guidance and in [Short-circuit middleware after routing](xref:fundamentals/routing#short-circuit-middleware-after-routing).
+* Don't use remote authentication as the default authentication scheme. Instead, configure remote authentication only for the endpoints that need it. For example, pass `false` to `AddAuthenticationClient` and specify the remote authentication scheme explicitly on those endpoints.
+
 #### Using Remote Authentication with Specific Endpoints
 
 When you set the default scheme to `false`, you can specify remote authentication for specific controllers or actions:
@@ -340,7 +350,7 @@ Note that because signing in typically depends on a specific database, not all a
 * Both apps are able to see the users' identity and claims.
 * Both apps are able to sign the user out.
 
-Details on how to configure sharing auth cookies between ASP.NET and ASP.NET Core apps are available in [cookie sharing documentation](xref:security/cookie-sharing). For more information about cookie authentication in ASP.NET Core, see <xref:security/authentication/cookie>.
+Details on how to configure sharing auth cookies between ASP.NET and ASP.NET Core apps are available in [cookie sharing documentation](xref:security/cookie-sharing). For more information about cookie authentication in ASP.NET Core, see <xref:security/authentication/cookie>. For guidance on configuring `<machineKey>` and data protection when sharing protected values between Framework and Core apps, see <xref:migration/fx-to-core/areas/machine-key>.
 
 The following samples in the [System.Web adapters](https://github.com/dotnet/systemweb-adapters) GitHub repo demonstrates remote app authentication with shared cookie configuration enabling both apps to sign users in and out:
 

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

@@ -5,7 +5,7 @@ ai-usage: ai-assisted
 author: twsouthwick
 ms.author: tasou
 monikerRange: '>= aspnetcore-6.0'
-ms.date: 11/10/2025
+ms.date: 12/10/2025
 ms.topic: article
 uid: migration/fx-to-core/areas/hosting
 ---
@@ -61,9 +61,6 @@ The `HttpApplicationHost.RegisterHost` method configures a generic host that run
 
 ## Dependency injection
 
-> [!NOTE]
-> This currently is in a preview version of the adapters. You must be using 2.2.0-preview1.25554.5 or greater to use this feature.
-
 The `AddSystemWebDependencyInjection` method enables dependency injection throughout your ASP.NET Framework application. Services registered with the generic host's service collection become available to controllers, handlers, and other components.
 
 This extension method is an internal method that will be source generated depending on what you have referenced. The following frameworks are supported:
@@ -72,6 +69,9 @@ This extension method is an internal method that will be source generated depend
 - ASP.NET MVC using <xref:System.Web.Mvc.DependencyResolver>
 - ASP.NET WebApi using [DependencyResolver](/previous-versions/aspnet/hh969140(v=vs.108))
 
+> [!NOTE]
+> The `builder.AddSystemWebDependencyInjection()` extension method is generated by a C# source generator and is only available in C# projects. For VB.NET apps, create an intermediate C# class library that references the ASP.NET MVC/Web API and SystemWebAdapters packages. Configure dependency injection in that library and expose a public method that your VB.NET project can call.
+
 ### Registering services
 
 Register services with the dependency injection container by accessing the `Services` property on the host builder:

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

@@ -1,9 +1,10 @@
 ---
 title: Complex migration scenarios - Deep dive areas
+ai-usage: ai-assisted
 description: Detailed guidance for complex ASP.NET Framework to ASP.NET Core migration scenarios
 author: twsouthwick
 ms.author: tasou
-ms.date: 11/10/2025
+ms.date: 12/10/2025
 uid: migration/fx-to-core/areas
 ---
 # Technology specific guidance
@@ -14,6 +15,7 @@ uid: migration/fx-to-core/areas
 * [HttpContext](http-context.md)
 * [HTTP Handlers](http-handlers.md)
 * [HTTP Modules](http-modules.md)
+* [Machine Key](machine-key.md)
 * [Membership](membership.md)
 * [Miscellaneous](misc.md)
 * [OWIN](owin.md)

aspnetcore/migration/fx-to-core/areas/machine-key.md

@@ -0,0 +1,102 @@
+---
+title: ASP.NET machineKey to ASP.NET Core migration
+ai-usage: ai-assisted
+author: twsouthwick
+description: Migrate ASP.NET machineKey-based cryptography to ASP.NET Core data protection in incremental and full migrations.
+monikerRange: '>= aspnetcore-6.0'
+ms.author: tasou
+ms.date: 12/10/2025
+ms.topic: article
+uid: migration/fx-to-core/areas/machine-key
+---
+
+# Migrate ASP.NET machineKey by using System.Web adapters
+
+[!INCLUDE[](~/migration/fx-to-core/includes/uses-systemweb-adapters.md)]
+
+In the ASP.NET Framework app, configure `<machineKey>` and the System.Web adapters host so that both apps can share a compatible data protection configuration. For full background on replacing `<machineKey>`, see <xref:security/data-protection/compatibility/replacing-machinekey>.
+
+This guidance builds on the `System.Web` adapters hosting model so that data protection services are registered in the host dependency injection (DI) container and made available throughout the ASP.NET Framework app. By integrating with the host DI provided by the adapters, existing ASP.NET Framework components can resolve `IDataProtectionProvider`, `IDataProtector`, and related types.
+
+Both the ASP.NET Framework app and the ASP.NET Core app must use a shared application name and key repository for data protection so that protected payloads can round-trip between apps.
+
+* Call `SetApplicationName` with the same logical application name in both apps (for example, `"my-app"`).
+* Configure `PersistKeysToFileSystem` to point to the same key repository location that both apps can read and write.
+
+> [!NOTE]
+> The directory used with `PersistKeysToFileSystem` is the backing store for the shared data protection keys. In production, use a durable, shared store (such as a UNC share, Redis, or Azure Blob Storage) and follow the key management guidance in <xref:security/data-protection/configuration/overview> and <xref:security/data-protection/introduction>.
+
+## Configure the ASP.NET Framework app
+
+To implement this configuration in the ASP.NET Framework app, ensure the `Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices` package is installed in the ASP.NET Framework app.
+
+When you install the `Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices` package in the ASP.NET Framework app, it normally configures `<machineKey>` automatically. If `<machineKey>` isn't present or you need to verify the settings, configure `` in *Web.config* to use the compatibility data protector as shown:
+
+```xml
+<configuration>
+  <system.web>
+    <httpRuntime targetFramework="4.8.1" />
+    <machineKey
+      compatibilityMode="Framework45"
+      dataProtectorType="Microsoft.AspNetCore.DataProtection.SystemWeb.CompatibilityDataProtector,
+      Microsoft.AspNetCore.DataProtection.SystemWeb" />
+  </system.web>
+</configuration>
+```
+
+Next, in `Global.asax.cs`, register the System.Web adapters host and configure data protection using the same application name and key repository that the ASP.NET Core app will use. The following example is adapted from the MachineKey Framework sample:
+
+```csharp
+using System.IO;
+using System.Web;
+using Microsoft.AspNetCore.DataProtection;
+using Microsoft.AspNetCore.SystemWebAdapters.Hosting;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+namespace DataProtectionDemo
+{
+    public class MvcApplication : HttpApplication
+    {
+        protected void Application_Start()
+        {
+            HttpApplicationHost.RegisterHost(builder =>
+            {
+                builder.AddServiceDefaults();
+
+                builder.AddDataProtection()
+                    .SetApplicationName("my-app")
+                    .PersistKeysToFileSystem(new DirectoryInfo(@"\\server\share\myapp-keys\"));
+            });
+        }
+    }
+}
+```
+
+This configuration:
+
+* Sets a shared application name (`my-app`) that the ASP.NET Core app must also use.
+* Configures a shared key repository (for example, a UNC share) that both apps can access.
+* Ensures `<machineKey>` operations (forms auth, view state, `MachineKey.Protect`, and related APIs) are routed through ASP.NET Core data protection.
+* Runs as part of the ASP.NET Framework host so that existing `<machineKey>`-based features use the same data protection system as ASP.NET Core.
+
+## Configure the ASP.NET Core app
+
+No additional configuration is required for data protection in the ASP.NET Core app. Just configure the same application name and key storage location that the ASP.NET Framework app uses.
+
+```csharp
+using Microsoft.AspNetCore.DataProtection;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDataProtection()
+    .SetApplicationName(MachineKeyExampleHandler.AppName)
+    .PersistKeysToFileSystem(
+        new DirectoryInfo(Path.Combine(Path.GetTempPath(), "sharedkeys", MachineKeyExampleHandler.AppName)));
+
+var app = builder.Build();
+
+// Configure application
+
+app.Run();
+```

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

@@ -1,10 +1,11 @@
 ---
 title: Remote app setup
-description: Remote app setup
+ai-usage: ai-assisted
 author: wadepickett
-ms.author: wpickett
+description: Remote app setup
 monikerRange: '>= aspnetcore-6.0'
-ms.date: 10/08/2025
+ms.author: wpickett
+ms.date: 12/10/2025
 ms.topic: article
 uid: migration/fx-to-core/inc/remote-app-setup
 zone_pivot_groups: migration-remote-app-setup
@@ -157,51 +158,27 @@ To enable proxying from the ASP.NET Core application to the ASP.NET Framework ap
 ## Setup Aspire orchestration
 
 > [!IMPORTANT]
-> 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>
-> ```
->
-> **NOTE**: This requires v2.0.1-preview1.25351.5 of the System.Web adapters or later.
-
-> [!WARNING]
-> **NOTE**: This is a 3rd party component that helps run the application in Aspire. At the current time, ASP.NET Framework applications are not supported directly in Aspire, but this project helps with that. This dependency is intended for build and development, but does not need to be deployed into production.
+> This integration is currently in preview and is published as a prerelease package on NuGet.org. When adding the package, enable prerelease packages in your tooling (for example, select `Include prerelease` in Visual Studio's NuGet Package Manager or use the equivalent prerelease option with the .NET CLI).
 
 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:
+1. Add the `Aspire.Hosting.IncrementalMigration` package to your AppHost project.
+1. Configure IIS Express to locally host your framework application and configure incremental migration fallback using the incremental migration extensions:
 
     ```csharp
     var builder = DistributedApplication.CreateBuilder(args);
-    
-    var frameworkApp = builder.AddIISExpress("iis")
-        .AddSiteProject<Projects.FrameworkApplication>("framework")
-        .WithDefaultIISExpressEndpoints()
-        .WithOtlpExporter()
-        .WithHttpHealthCheck();
-    
+
+    // Add ASP.NET Framework app with IIS Express
+    var frameworkApp = builder.AddIISExpressProject<Projects.FrameworkApplication>("framework");
+
+    // Add ASP.NET Core app with fallback to Framework app
     var coreApp = builder.AddProject<Projects.CoreApplication>("core")
-        .WithHttpHealthCheck()
-        .WaitFor(frameworkApp)
-        .WithIncrementalMigrationFallback(frameworkApp, options => options.RemoteSession = RemoteSession.Enabled);
-    
+        .WithIncrementalMigrationFallback(frameworkApp, options =>
+        {
+            options.RemoteSession = RemoteSession.Enabled;
+            options.RemoteAuthentication = RemoteAuthentication.DefaultScheme;
+        });
+
     builder.Build().Run();
     ```
 1. Configure the options of the incremental migration fallback for the scenarios you want to support.
@@ -212,48 +189,30 @@ To enable proxying from the ASP.NET Core application to the ASP.NET Framework ap
 1. Update the ServiceDefaults project to support .NET Framework. This is based off of the default ServiceDefaults and may differ if you have customized anything.
     * Update the target framework to multitarget:
         ```diff
-        - <TargetFramework>net9.0</TargetFramework>
-        + <TargetFrameworks>net9.0;net48</TargetFrameworks>
+        - <TargetFramework>net10.0</TargetFramework>
+        + <TargetFrameworks>net481;net10.0</TargetFrameworks>
         ```
     * Update the PackageReferences to account for the different frameworks:
         ```xml
-         <ItemGroup>
+        <ItemGroup>
             <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
+            <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" />
             <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'">
+        </ItemGroup>
+
+        <ItemGroup Condition=" '$(TargetFramework)' == 'net10.0' ">
             <FrameworkReference Include="Microsoft.AspNetCore.App" />
-        
-            <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" />
             <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" />
-          </ItemGroup>
-        
-          <ItemGroup Condition=" '$(TargetFramework)' == 'net48' ">
+        </ItemGroup>
+
+        <ItemGroup Condition=" '$(TargetFramework)' == 'net481' ">
             <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
-                });
+        </ItemGroup>
         ```
     * To enable telemetry, update the metrics and tracing registrations:
 
@@ -294,6 +253,8 @@ To enable proxying from the ASP.NET Core application to the ASP.NET Framework ap
         + #endif
         ```
 
+    For a complete, working example of a multi-targeted `ServiceDefaults` configuration that supports both ASP.NET Core and ASP.NET Framework, see the sample `Extensions.cs` file in the System.Web adapters repository: `https://github.com/dotnet/systemweb-adapters/blob/main/samples/ServiceDefaults/Extensions.cs`.
+
 ## Configure ASP.NET Framework Application
 
 1. Reference the ServiceDefaults project

aspnetcore/toc.yml

@@ -2177,6 +2177,8 @@ items:
               uid: migration/fx-to-core/areas/http-modules
             - name: HTTP Handlers
               uid: migration/fx-to-core/areas/http-handlers
+            - name: Machine Key
+              uid: migration/fx-to-core/areas/machine-key
             - name: Session
               uid: migration/fx-to-core/areas/session
             - name: Authentication