遠端應用程式設定

這很重要

架構和核心應用程式必須使用相同的虛擬目錄配置。

虛擬目錄設定用於系統內的路由產生、授權和其他服務。此時，由於 ASP.NET Framework 的運作方式，找不到可啟用不同虛擬目錄的可靠方法。

在某些累加升級案例中，新的 ASP.NET Core 應用程式能夠與原始 ASP.NET 應用程式通訊很有用。

這可啟用的常見情境：

使用 YARP 切換回舊版應用程式
遠端應用程式驗證
遠端連線階段

組態值

若要讓 ASP.NET Core 應用程式能夠與 ASP.NET 應用程式通訊，您必須對每個應用程式進行幾個小型變更。

您需要在這兩個應用程式中配置兩個配置值：

RemoteAppApiKey：在兩個應用程式之間共用的金鑰（必須可剖析為 GUID）。這應該是 GUID 值，例如 12345678-1234-1234-1234-123456789012。
RemoteAppUri：遠端 ASP.NET Framework 應用程式的 URI （僅在 ASP.NET Core 應用程式組態中需要）。這應該是裝載 ASP.NET Framework 應用程式的完整 URL，例如 https://localhost:44300 或 https://myapp.example.com。

設定 ASP.NET 架構應用程式

這很重要

ASP.NET Framework 應用程式應在啟用 SSL 的情況下裝載。在增量移轉的遠端應用程式設定中，不需要對外部有直接存取權。建議只允許透過 Proxy 從用戶端應用程式存取。

對於 ASP.NET Framework 應用程式，請將以下值新增至您的 web.config 在 <appSettings> 區段中。

這很重要

ASP.NET Framework 將其 appSettings 儲存在 web.config中。不過，可以使用配置建置器從其他來源（例如環境變數）擷取它們。這使得在此設定中，本機和遠端應用程式之間共用配置值變得更加容易。

<appSettings>
  <add key="RemoteAppApiKey" value="..." />
</appSettings>

若要將應用程式設定為可處理來自 ASP.NET Core用戶端的要求，請設定下列專案：

安裝 NuGet 套件 Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices

請將組態程式碼新增至您的Application_Start文件的Global.asax.cs方法中：

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...
}

如果 NuGet 尚未將 SystemWebAdapterModule 模組新增至 web.config，請新增該模組。 IIS 裝載案例需要此模組設定。使用 SystemWebAdapterModule 適用於 ASP.NET Core 的 SDK 樣式專案時，不會自動新增模組。

  <system.webServer>
    <modules>
+      <remove name="SystemWebAdapterModule" />
+      <add name="SystemWebAdapterModule" type="Microsoft.AspNetCore.SystemWebAdapters.SystemWebAdapterModule, Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices" preCondition="managedHandler" />
    </modules>
</system.webServer>

設定核心應用程式 ASP.NET

對於 ASP.NET 核心應用程式，請將下列值新增至您的 appsettings.json：

{
  "RemoteAppApiKey": "...",
  "RemoteAppUri": "https://localhost:44300"
}

若要設定 ASP.NET Core 應用程式，使其能夠將要求傳送至 ASP.NET 應用程式，請在向註冊 AddRemoteAppClientSystem.Web 配接器服務之後呼叫AddSystemWebAdapters遠端應用程式用戶端。

將此設定新增至您的 Program.cs 檔案：

builder.Services.AddSystemWebAdapters()
    .AddRemoteAppClient(options =>
    {
        options.RemoteAppUrl = new(builder.Configuration["RemoteAppUri"]);
        options.ApiKey = builder.Configuration["RemoteAppApiKey"];
    });

隨著 ASP.NET 和 ASP.NET Core 應用程式的更新，現在可以視需要使用擴充方法來設定遠端應用程式驗證或遠端工作階段。

啟用 Proxy

若要啟用從 ASP.NET Core 應用程式到 ASP.NET Framework 應用程式的 Proxy，您可以設定後援路由，將不相符的要求轉送至舊版應用程式。這允許逐步遷移，其中 ASP.NET Core 應用程序處理遷移的功能，同時回退到原始應用程序以獲取未遷移的功能。

請遵循最新的指引，安裝 YARP （另一個反向 Proxy） NuGet 套件。

將必要的 using 敘述新增至您的 Program.cs：

using Microsoft.Extensions.Options;
using Microsoft.AspNetCore.SystemWebAdapters;

在您的：中註冊反向代理服務 Program.cs：
```
builder.Services.AddReverseProxy();
```

建置應用程式並設定其他中介軟體之後，請新增備援路由映射：

var app = builder.Build();

// Configure your other middleware here (authentication, routing, etc.)

// Map the fallback route
app.MapForwarder("/{**catch-all}", app.Services.GetRequiredService<IOptions<RemoteAppClientOptions>>().Value.RemoteAppUrl.OriginalString)

    // Ensures this route has the lowest priority (runs last)
    .WithOrder(int.MaxValue)

    // Skips remaining middleware when this route matches
    .ShortCircuit();

app.Run();

設定 Aspire 編排

這很重要

這仍處於預覽狀態，無法在 NuGet.org 上使用，因此您必須設定 NuGet 設定，才能從 .NET 程式庫每日摘要提取程式庫：

<?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>

注意：這需要 System.Web 配接器的 v2.0.1-preview1.25351.5 版本或更新版本。

警告

注意：這是第 3 方元件，可協助應用程式在Aspire中執行。目前，ASP.NET Framework 應用程式在 Aspire 尚未直接支援，但這個專案有助於解決這個問題。此相依性適用於建置和開發，但不需要部署到生產環境中。

新增 Aspire ASP.NET Framework 應用程式的協調流程
將新的 ASP.NET Core 應用程式新增至解決方案，並將它新增至協調 Aspire 流程

更新 AppHost 以支援 Windows，因為 IIS 整合需要這樣做：

- <TargetFramework>net9.0</TargetFramework>
+ <TargetFramework>net9.0-windows</TargetFramework>

將下列 Aspire 整合新增至您的應用程式主機：
- Aspire.Hosting.IncrementalMigration
- C3D.Extensions.Aspire.IISExpress

設定 IIS Express 以在本機裝載您的架構應用程式，並設定累加移轉後援：

var builder = DistributedApplication.CreateBuilder(args);

var frameworkApp = builder.AddIISExpress("iis")
    .AddSiteProject<Projects.FrameworkApplication>("framework")
    .WithDefaultIISExpressEndpoints()
    .WithOtlpExporter()
    .WithHttpHealthCheck();

var coreApp = builder.AddProject<Projects.CoreApplication>("core")
    .WithHttpHealthCheck()
    .WaitFor(frameworkApp)
    .WithIncrementalMigrationFallback(frameworkApp, options => options.RemoteSession = RemoteSession.Enabled);

builder.Build().Run();

針對您想要支援的案例設定累加式移轉後援的選項。

設定 ServiceDefaults 以支援 ASP.NET Framework

將套件 Aspire.Microsoft.AspNetCore.SystemWebAdapters 新增至您的應用程式。

更新 ServiceDefaults 專案以支援 .NET Framework。這是以預設的 ServiceDefaults 為基礎，如果您已自訂任何內容，則可能會有所不同。

將目標架構更新為多目標：

- <TargetFramework>net9.0</TargetFramework>
+ <TargetFrameworks>net9.0;net48</TargetFrameworks>

請更新 PackageReferences 以適應不同的框架：

 <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
    <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'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" />
  </ItemGroup>

  <ItemGroup Condition=" '$(TargetFramework)' == 'net48' ">
    <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNet" />
  </ItemGroup>

在Extensions.cs檔案中，您必須有條件地排除 ServiceDiscovery API，因為 .NET Framework 目前不支援這些 API：

+ #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
        });

若要啟用遙測，請更新計量和追蹤註冊：

        builder.Services.AddOpenTelemetry()
            .WithMetrics(metrics =>
            {
                metrics
+ #if NET
                    .AddAspNetCoreInstrumentation()
+ #else
+                   .AddAspNetInstrumentation()
+ #endif
                    .AddSqlClientInstrumentation()
                    .AddHttpClientInstrumentation()
                    .AddRuntimeInstrumentation();
            })
            .WithTracing(tracing =>
            {
                tracing.AddSource(builder.Environment.ApplicationName)
+ #if NET
                    .AddAspNetCoreInstrumentation()
+ #else
+                   .AddAspNetInstrumentation()
+ #endif
                    .AddSqlClientInstrumentation()
                    .AddHttpClientInstrumentation();
            });

停用預設端點，因為這僅適用於 ASP.NET 核心：

+ #if NET
    public static WebApplication MapDefaultEndpoints(this WebApplication app)
    {
        // Default endpoint registrations
    }
+ #endif

設定 ASP.NET 架構應用程式

參考 ServiceDefaults 專案

請將組態程式碼新增至您的Application_Start文件的Global.asax.cs方法中：

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

設定核心應用程式 ASP.NET

參考 ServiceDefaults 專案

在Programs.cs中新增 System.Web 配接器：

var builder = WebApplication.CreateBuilder();

builder.AddServiceDefaults();
+ builder.AddSystemWebAdapters();

...

var app = builder.Build();

...

+ // Must be placed after routing if manually added
+ app.UseSystemWebAdapters();

...

+ app.MapRemoteAppFallback()
+
+   // Optional, but recommended unless middleware is needed
+   .ShortCircuit();

app.Run();

使用此組態：

本機路由優先：如果 ASP.NET Core應用程式有相符的路由，則會在本機處理請求
回退至舊版應用程式：不相符的請求會自動轉送到 ASP.NET Framework 應用程式
中間件最佳化：該 .ShortCircuit() 方法可防止轉送請求時不必要的中間件執行

此設定可在增量移轉期間提供順暢的使用者體驗，使用者可以透過單一端點存取移轉和舊版功能。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-12

共用方式為

遠端應用程式設定

組態值

設定 ASP.NET 架構應用程式

設定核心應用程式 ASP.NET

啟用 Proxy

設定 Aspire 編排

設定 ServiceDefaults 以支援 ASP.NET Framework

設定 ASP.NET 架構應用程式

設定核心應用程式 ASP.NET

意見反應

其他資源