Update SystemWebAdapters API from obsolete AddSystemWebAdapters to HttpApplicationHost.RegisterHost

[Copilot]

Summary

This PR updates the ASP.NET Framework configuration examples to use the current HttpApplicationHost.RegisterHost API instead of the obsolete SystemWebAdapterConfiguration.AddSystemWebAdapters(this) method, which generates warning CS0618 in recent versions of the SystemWebAdapters library.

Problem

The documentation was instructing users to use an obsolete API that causes the following compiler warning:

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

This affected users following the remote app setup guide for incremental ASP.NET Framework to ASP.NET Core migrations.

Changes

Updated all instances of the obsolete API pattern across documentation and sample code:

Before:

protected void Application_Start()
{
    SystemWebAdapterConfiguration.AddSystemWebAdapters(this)
        .AddRemoteAppServer(options =>
        {
            options.ApiKey = ConfigurationManager.AppSettings["RemoteAppApiKey"];
        });
}

After:

protected void Application_Start()
{
    HttpApplicationHost.RegisterHost(builder =>
    {
        builder.AddSystemWebAdapters()
            .AddRemoteAppServer(options =>
            {
                options.ApiKey = System.Configuration.ConfigurationManager.AppSettings["RemoteAppApiKey"];
            });
    });
}

Files Modified

• aspnetcore/migration/fx-to-core/inc/remote-app-setup.md - Updated manual setup instructions and metadata
• aspnetcore/migration/fx-to-core/areas/authentication/samples/AspNetApp.cs - Updated authentication sample
• aspnetcore/migration/fx-to-core/areas/session/samples/remote/Global.asax.cs - Updated session sample

All changes maintain consistency with the Aspire section pattern already present in the documentation.

Related Issue

Fixes #[issue number] - CS0618 warning about obsolete SystemWebAdapterConfiguration API

Original prompt

---

This section details on the original issue you should resolve

<issue_title>SystemWebAdapterConfiguration.AddSystemWebAdapters(HttpApplication)' is obsolete: 'Prefer using HttpApplicationHost.RegisterHost(...) instead</issue_title>
<issue_description>### 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</issue_description>

Comments on the Issue (you are @copilot in this section)

@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.AddS...

</details>
Fixes dotnet/AspNetCore.Docs#36197

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

<!-- PREVIEW-TABLE-START -->

---

#### Internal previews

| 📄 File | 🔗 Preview link |
|:--|:--|
| [aspnetcore/migration/fx-to-core/inc/remote-app-setup.md](https://github.com/dotnet/AspNetCore.Docs/blob/0be75490ea40cf2f65e45dadd308fc8bfc6347f4/aspnetcore/migration/fx-to-core/inc/remote-app-setup.md) | [aspnetcore/migration/fx-to-core/inc/remote-app-setup](https://review.learn.microsoft.com/en-us/aspnet/core/migration/fx-to-core/inc/remote-app-setup?branch=pr-en-us-36198) |

<!-- PREVIEW-TABLE-END -->

[wadepickett]

Note:
I built up a very detailed action plan in the issue, and with the additions I made to the copilot instructions, I'm testing to see if Copilot can pull this off, or at least much of it.

[wadepickett]

@copilot, verify if changes are required to match the new code in the topic that includes the code here:
aspnetcore/migration/fx-to-core/inc/remote-app-setup.md
If changes are needed proceed with making them and summarize in the discussion what was changed and why. If no changes are needed state why.

[Copilot]

@copilot, verify if changes are required to match the new code in the topic that includes the code here:
aspnetcore/migration/fx-to-core/inc/remote-app-setup.md
If changes are needed proceed with ma...

No changes are required. The authentication.md file is already consistent with the updated code from remote-app-setup.md.

Verification details:

• Line 190 of authentication.md includes the code snippet from AspNetApp.cs using :::code directive
• The AspNetApp.cs sample was already updated in commit 0be7549 to use the new HttpApplicationHost.RegisterHost API
• Line 182 references the remote-app-setup instructions, which were also updated in the same commit
• Session.md similarly includes the updated Global.asax.cs sample
• No inline code examples in either file contain the obsolete API

All documentation files that reference the remote app setup code are automatically pulling in the updated samples via the :::code directives, so they display the correct new API pattern.

[wadepickett]

@twsouthwick, could use your review on this migration doc sample update.

[wadepickett]

Reviewed and approved.