Blazor .NET 11 Gateway: Replacing WebAssembly DevServer in Standalone Apps

Blazor WebAssembly applications have traditionally needed a development server to serve the application during development. In earlier setups, Microsoft.AspNetCore.Components.WebAssembly.DevServer was commonly used for this purpose.

That approach changes with .NET 11.

The Blazor WebAssembly development experience now uses a Gateway approach instead of the older DevServer package. The Gateway can handle development-time hosting and proxying while keeping the application structure simpler. Microsoft introduced this change as part of the ASP.NET Core and Blazor development updates.

For developers maintaining an existing standalone Blazor WebAssembly application, this means there are a few things worth understanding before upgrading.

The basic idea is:

Older setup

Blazor WebAssembly
       |
       v
WebAssembly DevServer
       |
       v
Development browser

The newer approach looks more like:

Blazor WebAssembly
       |
       v
Blazor Gateway
       |
       v
Development browser

The change is mainly about the development infrastructure. It does not mean that your application suddenly becomes a server-rendered Blazor application.

In this article, we will look at the role of the Gateway, how it differs from the old development server, how to configure a standalone application, and what to check when moving an existing project.

What Was WebAssembly DevServer?

A standalone Blazor WebAssembly application runs primarily in the browser.

During development, however, the application still needs a server to:

Serve static files
Provide development-time behavior
Support debugging
Handle browser requests
Coordinate development tooling

Historically, a project could reference:

<PackageReference
    Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer"
    Version="..." />

The package provided the development server used to launch the WebAssembly application.

A developer could then run the application using the normal .NET tooling and access it through the development URL.

What Is the Blazor Gateway?

The Gateway is the newer development-time mechanism used for standalone Blazor WebAssembly applications.

Its job is still related to development hosting, but it provides a more integrated way to handle the development application and its associated requests.

The important distinction is:

Gateway
    =
Development infrastructure

It is not your application backend.

If your application calls an ASP.NET Core API, the API remains a separate application or backend service.

For example:

Browser
   |
   v
Blazor WebAssembly
   |
   v
Gateway
   |
   +------> Static application assets
   |
   +------> API/backend

The Gateway should therefore not be confused with an ASP.NET Core Web API.

Why Is the Change Important?

The change matters mostly when maintaining or upgrading existing standalone WebAssembly projects.

A project that still contains the old DevServer package may need changes during an upgrade.

Developers should check:

Project references
Development launch configuration
HTTPS configuration
Proxy configuration
API endpoints
Local development ports
Build and publish behavior

The goal is not to rewrite the application.

The goal is to move the development hosting setup to the newer approach.

Standalone Blazor WebAssembly Architecture

A typical standalone Blazor WebAssembly application looks like this:

+-------------------------+
|        Browser          |
|                         |
|  Blazor WebAssembly     |
|                         |
+------------+------------+
             |
             | HTTP
             v
+-------------------------+
|      Backend API        |
|                         |
| ASP.NET Core / Other    |
+-------------------------+

The WebAssembly application runs in the browser.

The backend API runs separately.

The development server or Gateway is primarily responsible for making the local development experience work.

This distinction becomes important when troubleshooting.

If your application cannot call an API, the problem may be related to CORS, authentication, URL configuration, or the API itself. Replacing the DevServer with Gateway does not automatically solve those issues.

Checking the Project File

Start by checking the .csproj file.

An older project might contain:

<ItemGroup>
    <PackageReference
        Include="Microsoft.AspNetCore.Components.WebAssembly"
        Version="..." />

    <PackageReference
        Include="Microsoft.AspNetCore.Components.WebAssembly.DevServer"
        Version="..." />
</ItemGroup>

The important line is:

Microsoft.AspNetCore.Components.WebAssembly.DevServer

When moving to the newer development model, review the project template and .NET 11 migration guidance rather than blindly copying package versions.

The correct project configuration depends on the exact application template and target framework.

Targeting .NET 11

A project targeting .NET 11 should have the appropriate target framework:

<TargetFramework>net11.0</TargetFramework>

A simplified project file might look like:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

    <PropertyGroup>
        <TargetFramework>net11.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
    </PropertyGroup>

</Project>

The exact SDK and package references should come from the application template being used.

Do not remove package references simply because their names look related to the old server.

Check whether your application actually requires them.

Development Launch Configuration

A standalone WebAssembly application may also have a Properties directory containing development launch settings.

For example:

{
  "profiles": {
    "BlazorApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
      "applicationUrl": "https://localhost:7001;http://localhost:5001"
    }
  }
}

Do not copy these ports directly into another project.

The port values are application-specific.

When migrating, compare your existing launch configuration with the configuration generated by the current .NET template.

Gateway and API Proxying

One useful role of development infrastructure is helping the browser communicate with backend services during local development.

Suppose the WebAssembly application runs at:

https://localhost:7001

and the API runs at:

https://localhost:8001

The browser needs to make requests between these origins.

Depending on the application architecture, you may need:

CORS configuration
A proxy
A shared origin
Authentication configuration

The Gateway can be part of the local development routing architecture, but it does not remove the need to understand browser security rules.

For example, a direct API call might look like:

var response =
    await Http.GetAsync("https://localhost:8001/api/products");

If the two applications use different origins, the API must permit the browser request where CORS applies.

CORS Still Matters

A common mistake during migration is assuming that changing the development server automatically fixes cross-origin requests.

It does not.

If the browser reports a CORS error, investigate the API configuration.

A typical ASP.NET Core API might have:

builder.Services.AddCors(options =>
{
    options.AddPolicy("BlazorClient", policy =>
    {
        policy.WithOrigins("https://localhost:7001")
              .AllowAnyHeader()
              .AllowAnyMethod();
    });
});

Then:

app.UseCors("BlazorClient");

The actual origin must match your development environment.

Avoid using:

.AllowAnyOrigin()

as a quick production fix.

CORS should be configured according to the application's actual requirements.

Gateway vs DevServer

The two approaches can be compared at a high level.

Area	WebAssembly DevServer	Blazor Gateway
Purpose	Development hosting	Development hosting and routing
Standalone WASM	Yes	Yes
Application backend	Separate	Separate
Production hosting	Not the same concern	Not the same concern
Migration impact	Existing projects may use it	Newer approach
Main developer concern	Package/configuration	Template/configuration

The Gateway is not a replacement for your production API.

It is part of the development experience.

Migration Strategy

If you have an existing standalone Blazor WebAssembly project, avoid changing everything at once.

Use a controlled migration.

Step 1: Create a Backup

Commit your existing project before changing the development infrastructure.

git status
git add .
git commit -m "Before Blazor Gateway migration"

This gives you a clean rollback point.

Step 2: Check the Target Framework

Verify:

<TargetFramework>net11.0</TargetFramework>

Also make sure the required .NET SDK is installed.

You can check the SDK with:

dotnet --info

Step 3: Inspect DevServer References

Search the project file for:

Microsoft.AspNetCore.Components.WebAssembly.DevServer

Do not remove it blindly.

First compare your application with the appropriate .NET 11 project template and migration guidance.

Step 4: Review Launch Settings

Check:

Properties/launchSettings.json

Look for:

Application URLs
HTTPS settings
Browser launch settings
Debugging configuration
Proxy-related settings

Step 5: Build the Project

Run:

dotnet build

Fix build errors before testing browser behavior.

Step 6: Run the Application

Start the application normally:

dotnet run

Then verify that:

The application opens.
Static assets load.
Navigation works.
API requests work.
Browser debugging works where required.

Step 7: Test API Calls

Open browser developer tools and inspect the Network tab.

Check requests to your API.

A successful response should show the expected status code.

If you see:

CORS error

investigate CORS.

If you see:

check the API URL and route.

If you see:

check authentication.

If you see:

check the API logs.

This separates Gateway problems from application problems.

Common Migration Mistakes

Removing DevServer Without Checking the Template

Do not simply delete the package and assume the project is migrated.

The correct configuration depends on the project structure and target framework.

Treating Gateway as the Backend

The Gateway does not replace your API.

Your application can still have:

Blazor WASM
      |
      v
Gateway
      |
      v
ASP.NET Core API
      |
      v
Database

The API remains responsible for application and business logic.

Ignoring CORS

If your client and API have different origins, browser security still applies.

Hard-Coding Development Ports

Avoid putting values such as:

https://localhost:7001

throughout your code.

Centralize environment-specific configuration.

Testing Only the Home Page

A migration is not complete just because the home page opens.

Test:

Routing
API calls
Authentication
Static assets
Forms
Browser refresh
Deep links
Debugging
Error handling

Troubleshooting

The Application Does Not Start

Run:

dotnet --info

and:

dotnet build

Check that the installed SDK supports the target framework.

Then inspect the project file and launch configuration.

The Page Loads but API Calls Fail

Check the browser Network tab.

Verify:

API URL
HTTP status
CORS headers
Authentication
Request method
Request payload

The issue may be in the API rather than the Gateway.

Static Assets Return 404

Check the browser request path and the generated build output.

Also verify that the application is being started using the expected development profile.

Deep Links Fail

Test a URL such as:

/products/42

directly in the browser.

Do not test only by clicking from the home page.

A standalone WebAssembly application needs to serve the correct entry point for client-side routes during development and deployment.

HTTPS Certificate Problems

If local HTTPS fails, check the development certificate:

dotnet dev-certs https --check

If necessary, recreate the development certificate using the appropriate .NET tooling.

Do not disable HTTPS simply to hide a certificate problem.

Production Hosting Is a Separate Decision

One important point is that the development Gateway should not be confused with production hosting.

Your production architecture may look like:

Browser
   |
   v
CDN / Web Server
   |
   +----> Blazor WebAssembly static files
   |
   +----> API

The exact architecture depends on the application.

You might host the WebAssembly files through:

A web server
A CDN
Cloud storage
A hosting platform
Another static-file service

The development server is not automatically the production hosting architecture.

Advantages

The newer Gateway-based development approach provides several useful benefits:

Aligns standalone Blazor WebAssembly development with newer .NET tooling.
Reduces reliance on the older DevServer approach.
Provides a more integrated development-hosting model.
Can simplify local development routing.
Keeps development hosting separate from application business logic.
Works naturally with the newer Blazor project templates.

Disadvantages

There are also some migration costs:

Existing projects may require configuration changes.
Custom development setups can require additional investigation.
Old launch settings may not match newer templates.
API and CORS configuration still need to be handled separately.
Teams maintaining several older applications may need to support different development setups during migration.

A Practical Migration Checklist

Before considering the migration complete, verify:

[ ] Project targets the intended .NET version
[ ] Required SDK is installed
[ ] Old DevServer configuration has been reviewed
[ ] Project builds successfully
[ ] Application starts successfully
[ ] Static assets load correctly
[ ] Client-side routing works
[ ] Deep links work
[ ] API requests work
[ ] CORS configuration is correct
[ ] Authentication still works
[ ] HTTPS works locally
[ ] Browser debugging works
[ ] Production hosting configuration is unchanged or intentionally updated

Summary

The move from Microsoft.AspNetCore.Components.WebAssembly.DevServer to the newer Blazor Gateway approach is mainly a change to the development hosting experience for standalone Blazor WebAssembly applications.

The WebAssembly application still runs in the browser, and your backend API remains responsible for server-side business logic. The Gateway should not be treated as a replacement for that API.

When migrating an existing project, the safest approach is to compare your application with the appropriate .NET 11 template, review project and launch configuration, build the application, and then test routing, static files, API calls, authentication, and HTTPS separately.

CORS problems, API errors, and routing problems should also be investigated independently instead of assuming they are caused by the Gateway.

For new projects, following the current Blazor template is generally the simplest approach. For existing applications, a small and controlled migration is safer than making several infrastructure changes at the same time.