SystemWebAdapterConfiguration.AddSystemWebAdapters(HttpApplication)' is obsolete: 'Prefer using HttpApplicationHost.RegisterHost(...) instead

[cas-matt]

Description

Hi Wade

Step 2 in Configure ASP.NET Framework Application is out of date. It generates a

warning CS0618: 'SystemWebAdapterConfiguration.AddSystemWebAdapters(HttpApplication)' is obsolete: 'Prefer using HttpApplicationHost.RegisterHost(...) instead'

I believe the code should be something like this:

        HttpApplicationHost.RegisterHost(builder =>
        {
            builder.AddServiceDefaults();
            builder.RegisterWebObjectActivator();

            builder.AddSystemWebAdapters()
                   .AddVirtualizedContentDirectories();
            builder.AddSystemWebAdapters()
                        .AddRemoteAppServer(options =>
                        {
                            // ApiKey is a string representing a GUID
                            options.ApiKey = System.Configuration.ConfigurationManager.AppSettings["RemoteAppApiKey"];
                        });
        });

Also, we are having trouble trying to get the recipe to work. We have adapted the https://github.com/dotnet/systemweb-adapters/tree/main sample to work using a domain setup (have set up two domains as framework.noho.ca and core.noho.ca) on our dev machines. We can log in to framework and then when we try to load the core app, it does not pick up the login details even though it does have the shared cookie. There are no errors and we are a bit fuzzy regarding the communication mechanism between the two.

Do you know of any example code which show the domain version using the manual setup? We got the Aspire version to run from the sample using the local host and the dashboard and could see login in the core app, and are trying to get a version running that we could apply to our main app. It is a very large project with a million lines of combined code.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/migration/fx-to-core/inc/remote-app-setup?view=aspnetcore-9.0&pivots=manual

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/migration/fx-to-core/inc/remote-app-setup.md

Document ID

f3b2ce81-5438-1d1a-1c2b-6cc9a089a0ea

Platform Id

f8610778-e458-a8a6-8136-0ee8c72f11e8

Article author

@wadepickett

Metadata

• ID: f3b2ce81-5438-1d1a-1c2b-6cc9a089a0ea
• PlatformId: f8610778-e458-a8a6-8136-0ee8c72f11e8
• Service: aspnet-core
• Sub-service: migration

Related Issues

---

Associated WorkItem - 498818

[wadepickett]

Thanks for bringing this up @cas-matt! Greatly appreciated. We will fix it.

Triage notes and draft action plan:

Issue Summary

This is a valid issue. The article "Remote app setup" instructs users to use SystemWebAdapterConfiguration.AddSystemWebAdapters(this) in Global.asax.cs for ASP.NET Framework configuration. As of the latest SystemWebAdapters packages, this API is obsolete and emits CS0618, advising use of HttpApplicationHost.RegisterHost(...) instead. The article does not reflect this change and needs to be updated to prevent confusion and ensure best practices.

Action Items

• Update aspnetcore/migration/fx-to-core/inc/remote-app-setup.md lines 59–73 and any other occurrences of the obsolete API.
• Add additional troubleshooting and real-world setup guidance as requested.
• Confirm sample code matches updated APIs.

Details for Action Plan

Files Impacted

• aspnetcore/migration/fx-to-core/inc/remote-app-setup.md
  • Section: Configure ASP.NET Framework Application
  • Lines: 59–73 (code block using obsolete API)
  • Potential impact: Other sections may also need to reference the new API if it is mentioned elsewhere.

Required Changes

1. Replace obsolete API usage

Current code (lines 62–73):

protected void Application_Start()
{
    SystemWebAdapterConfiguration.AddSystemWebAdapters(this)
        .AddRemoteAppServer(options =>
        {
            // ApiKey is a string representing a GUID
            options.ApiKey = ConfigurationManager.AppSettings["RemoteAppApiKey"];
        });

    // ...existing code...
}

Replace with:

protected void Application_Start()
{
    HttpApplicationHost.RegisterHost(builder =>
    {
        builder.AddServiceDefaults();
        builder.RegisterWebObjectActivator();
        builder.AddSystemWebAdapters()
               .AddVirtualizedContentDirectories();
        builder.AddSystemWebAdapters()
               .AddRemoteAppServer(options =>
               {
                   // ApiKey is a string representing a GUID
                   options.ApiKey = System.Configuration.ConfigurationManager.AppSettings["RemoteAppApiKey"];
               });
    });

    // ...existing code...
}

• Add any necessary explanation about the new API and why it is required.

2. Review for additional obsolete API references

• Check other mentions of SystemWebAdapterConfiguration.AddSystemWebAdapters and update accordingly.
• Ensure YARP and remote session state sections do not refer to obsolete APIs.

3. Add troubleshooting and cross-domain example guidance

• The issue also requests example code for domain setup (multiple subdomains, shared cookies, manual setup). Consider referencing or linking to the official SystemWebAdapters sample repo, and explain key points about domain/cookie configuration and cross-app authentication.
• If possible, clarify the communication mechanism between apps (cookie sharing, remote session state, authentication flow).

4. Metadata and versioning

• Confirm that the NuGet package references match the required versions supporting the new API (SystemWebAdapters >= v2.0.1-preview1.25351.5).
• Add notes about using the daily feed if needed for Aspire scenarios.

Take Note of the Target .NET and Visual Studio Version

• The article targets .NET 6.0 and later (monikerRange: '>= aspnetcore-6.0') for ASP.NET Core and .NET Framework for the legacy app.
• Visual Studio version is not explicitly specified, but the guidance is consistent with Visual Studio 2022+ for .NET 6/8/9 and legacy .NET Framework projects.

This breaking change was made starting with SystemWebAdapters version 2.0.0-preview1.25351.5 and later, as referenced in the docs and Aspire sample guidance. The obsolete warning (CS0618) appears if you use recent versions of SystemWebAdapters in either .NET Framework or ASP.NET Core projects. The new API in both .NET Framework (for legacy apps) and .NET 6.0+ (for ASP.NET Core apps).

It applies to projects using SystemWebAdapters v2.0.0-preview1.25351.5 and later.

The API change is a library-level breaking change in SystemWebAdapters, not directly tied to a .NET runtime version.

Other background info history:
SystemWebAdapters is a modern library for .NET migrations.
The deprecation and switch to HttpApplicationHost.RegisterHost aligned with the updates for .NET 8/9 and Aspire tooling, which reached general availability in late 2023 and 2024.
The preview NuGet package (v2.0.0-preview1.25351.5) mentioning this change was published in mid-2024, and general availability followed soon after.

[wadepickett]

To try to answer your question:

""Do you know of any example code which show the domain version using the manual setup? We got the Aspire version to run from the sample using the local host and the dashboard and could see login in the core app, and are trying to get a version running that we could apply to our main app. It is a very large project with a million lines of combined code.""

Hmm. Well, there is no official, end-to-end example in the docs (yet) that demonstrates cross-domain (multiple domains/subdomains) authentication and remote session setup with SystemWebAdapters using the manual (non-Aspire) setup.

However, the SystemWebAdapters sample repository provides reference implementations for integrating ASP.NET Core with ASP.NET Framework, including cookie and session sharing. These samples focus on localhost scenarios, but the principles apply to domain scenarios as well.

Key points for domain setup:

Shared Cookie Setup:

Ensure both applications use the same MachineKey (for forms authentication or session) and the same cookie name.
Set the cookie domain in both apps to a common parent domain (e.g., .noho.ca for framework.noho.ca and core.noho.ca).
In ASP.NET Framework: set in web.config.
In ASP.NET Core: set options.Cookie.Domain = ".noho.ca" in your cookie authentication options.
Remote Session/Authentication:

Use AddRemoteAppServer and AddRemoteAppClient in the respective apps as the docs describe (with updated APIs).
If you use remote session, ensure both apps are correctly configured for distributed session and authentication.
Cross-domain authentication will only work if cookies are shared and both applications are accessible over HTTPS (SSL).
Manual Setup Example:

The sample code in your issue (using HttpApplicationHost.RegisterHost and related services) is the correct approach.
For manual domain setup, you may need extra configuration for IIS/hosting to ensure cookies and authentication work across domains.

Related references to check out:

SystemWebAdapters samples
Microsoft Docs: Cookie authentication across subdomains
GitHub issue: cross-domain session/cookie sharing
If you need a concrete sample, you can adapt the RemoteApp authentication sample by configuring cookie domains and SSL for your dev setup.

[cas-matt]

Hi Wade,

Thanks for the info. Will dive into it shortly. This link https://github.com/dotnet/systemweb-adapters/tree/main/samples/RemoteAppAuthenticationSample ends up as 404

However, that is the sample we have tried to adapt using the RemoteCore and RemoteFramework. We used the AuthRemoteIdentityAppHost to verify that the concept does work and have been trying to adapt those two apps for the subdomain example I referenced.

Let me go over your comments to see if something is missing in the recipe you provide for the manual adaptation.