Wrong syntax when setting-up SystemWebAdapters using HttpApplicationHost in AspNet .Net Framework

[ralencar84]

Description

The Samples contains:
`protected void Application_Start()
{
HttpApplicationHost.RegisterHost(builder =>
{
builder**.AddSystemWebAdapters()**
.AddRemoteAppServer(options =>
{
// ApiKey is a string representing a GUID
options.ApiKey = System.Configuration.ConfigurationManager.AppSettings["RemoteAppApiKey"];
});
});

// ...existing code...

}`

The correct version should be:

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

// ...existing code...

}`

Page URL

https://learn.microsoft.com/en-gb/aspnet/core/migration/fx-to-core/inc/remote-app-setup?view=aspnetcore-10.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 - 547910

[wadepickett]

@ralencar84, thanks very much for pointing this out and taking the time to suggest a solution as well. :)

[wadepickett]

AI Analysis Report

Date: 2025-12-24
Issue: #36520
Model: GitHub Copilot

---

Issue Analysis: Wrong syntax for SystemWebAdapters setup in HttpApplicationHost for .NET Framework

✅ Issue Validation

Status: Valid and actionable

The following are just AI generated suggestions designed to help speed up triage assessment where possible.

📋 Issue Summary

This issue reports a documentation error regarding the shown code sample for configuring SystemWebAdapters in an ASP.NET Framework application using HttpApplicationHost. The sample in the documentation misses the crucial .Services property when calling AddSystemWebAdapters(), which would result in a runtime failure or confusion for users who follow it literally. The correct code should use builder.Services.AddSystemWebAdapters().

📁 Affected Files

File	Path	Lines	Section
Main article	[aspnetcore/migration/fx-to-core/inc/remote-app-setup.md](https://github.com/dotnet/AspNetCore. Docs/blob/main/aspnetcore/migration/fx-to-core/inc/remote-app-setup.md#L62-L77)	62-77	"Configure ASP.NET Framework Application" - Manual pivot code block
Same article	aspnetcore/migration/fx-to-core/inc/remote-app-setup.md	263-272	"Configure ASP. NET Framework Application" - Aspire pivot code block

📝 Proposed Changes

Documentation Update #1 - Manual Pivot Section

File: aspnetcore/migration/fx-to-core/inc/remote-app-setup.md
Location: Lines 62-77, in the section Configure ASP. NET Framework Application (under :::zone pivot="manual"), code block following the sentence "Add the configuration code to the Application_Start method in your Global.asax.cs file:"

Current content (lines 62-77):

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

Proposed change:

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

Additional Note to Add:
After the code block (around line 78), consider adding a clarifying note:

> [!NOTE]
> When registering services within `HttpApplicationHost. RegisterHost`, you must use `builder.Services.AddSystemWebAdapters()` (not `builder.AddSystemWebAdapters()`). The `Services` property provides access to the service collection where SystemWebAdapters and related services are registered. 

Documentation Update #2 - Aspire Pivot Section

File: [aspnetcore/migration/fx-to-core/inc/remote-app-setup.md](https://github.com/dotnet/AspNetCore. Docs/blob/main/aspnetcore/migration/fx-to-core/inc/remote-app-setup.md#L263-L272)
Location: Lines 263-272, in the section Configure ASP.NET Framework Application (under :::zone pivot="aspire"), code block following the sentence "Add the configuration code to the Application_Start method in your Global.asax.cs file:"

Current content (lines 263-272):

    ```CSharp
    protected void Application_Start()
    {
        HttpApplicationHost.RegisterHost(builder =>
        {
            builder. AddServiceDefaults();
            builder.AddSystemWebAdapters();
        });
    }
    ```

Proposed change:

    ```CSharp
    protected void Application_Start()
    {
        HttpApplicationHost.RegisterHost(builder =>
        {
            builder.AddServiceDefaults();
            builder. Services.AddSystemWebAdapters();
        });
    }
    ```

🎯 Action Plan

1. Edit file: aspnetcore/migration/fx-to-core/inc/remote-app-setup.md

   Change 1 - Manual Pivot Section:

   • Navigate to: Lines 62-77
   • Find section: Configure ASP.NET Framework Application (under manual pivot)
   • In the Application_Start() code sample, change line 67 from:

     builder.AddSystemWebAdapters()

     to:

     builder.Services.AddSystemWebAdapters()

   • After the code block (line 78), insert a [!NOTE] block explaining the requirement to use builder.Services

   Change 2 - Aspire Pivot Section:

   • Navigate to: [Lines 263-272](https://github.com/dotnet/AspNetCore. Docs/blob/main/aspnetcore/migration/fx-to-core/inc/remote-app-setup.md#L263-L272)
   • Find section: Configure ASP.NET Framework Application (under aspire pivot)
   • In the Application_Start() code sample, change line 269 from:

     builder.AddSystemWebAdapters();

     to:

     builder.Services.AddSystemWebAdapters();

2. Verify consistency:

   • Cross-check with [hosting.md](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/migration/fx-to-core/areas/hosting. md#L42-L46) which correctly shows the pattern without .Services for different extension methods like AddServiceDefaults() and AddSystemWebDependencyInjection()
   • Confirm whether AddSystemWebAdapters() specifically requires .Services or if certain extension methods are available directly on the builder (based on the actual API)
   • Check if any other files in the repository use the incorrect pattern

3. Add label:

   • Add the ai-reviewed-issue-reported-action-plan label to issue Wrong syntax when setting-up SystemWebAdapters using HttpApplicationHost in AspNet .Net Framework #36520

⚠️ Considerations

• API verification needed: The hosting.md file shows builder.AddSystemWebAdapters() (without .Services) on line 46 and line 83, suggesting there may be API inconsistency or that different extension methods follow different patterns. Need to verify the actual API to ensure consistency across documentation.
• Multiple occurrences: The incorrect pattern appears in:
  • Line 67 in the manual pivot section (needs fixing) ✓
  • Line 269 in the aspire pivot section (needs fixing) ✓
  • The ASP.NET Core example (line 106) correctly uses builder.Services.AddSystemWebAdapters() ✓
• Version-specific: Verify if this applies to all .NET versions or if the API changed between releases
• Cross-reference: Check if any linked samples or external repositories (such as the SystemWeb adapters sample repository) need similar corrections
• Extension method patterns: Some extension methods like AddServiceDefaults() appear to work directly on builder, while others like AddSystemWebAdapters() require builder.Services. This pattern should be documented clearly.

🔗 References

• Published article: https://learn.microsoft.com/en-gb/aspnet/core/migration/fx-to-core/inc/remote-app-setup?view=aspnetcore-10.0&pivots=manual
• Source file: https://github.com/dotnet/AspNetCore. Docs/blob/main/aspnetcore/migration/fx-to-core/inc/remote-app-setup.md
• Related documentation: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/migration/fx-to-core/areas/hosting.md
• Related issue: Wrong syntax when setting-up SystemWebAdapters using HttpApplicationHost in AspNet .Net Framework #36520
• Web search results confirming the correct syntax: Multiple sources confirm that builder.Services.AddSystemWebAdapters() is the correct pattern for service registration

---

Summary

The issue is valid and requires immediate action. The documentation contains incorrect code samples in two locations that will cause confusion or compilation errors for developers following the migration guide. The fix is straightforward: add .Services before AddSystemWebAdapters() in both the manual and aspire pivot sections of the remote-app-setup.md file.

Priority: High - This is a blocking issue for users attempting to follow the migration documentation.

[ralencar84]

@ralencar84, thanks very much for pointing this out and taking the time to suggest a solution as well. :)

Happy new year, I'm glad to contribute!

Cheers!

[CZEMacLeod]

This doesn't match the readme in the package: https://github.com/dotnet/systemweb-adapters/tree/main/src/Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices
Nor the code
https://github.com/dotnet/systemweb-adapters/blob/f9ec3bcd818ed9fa5d38bf5ecf9daba3a28c5195/src/Aspire.Microsoft.AspNetCore.SystemWebAdapters/AspireSystemWebAdapterExtensions.cs#L22
Also the samples all use the method as described.
Note that this requires the Aspire.Microsoft.AspNetCore.SystemWebAdapters package. If you aren't using that, then the older builder.Servicces.AddSystemWebAdapters() method may be required.