Настройка удаленного приложения

Это важно

Приложения Framework и Core должны использовать идентичные макеты виртуальных каталогов.

Настройка виртуального каталога используется для создания маршрутов, авторизации и других служб в системе. На этом этапе надежный метод не найден для включения различных виртуальных каталогов из-за работы ASP.NET Framework.

В некоторых сценариях добавочного обновления полезно для нового приложения ASP.NET Core взаимодействовать с исходным приложением ASP.NET.

Распространенные сценарии, которые становятся возможными благодаря этому:

Возврат к устаревшему приложению с помощью YARP
Проверка подлинности удаленного приложения
Удаленный сеанс

Значения конфигурации

Чтобы приложение ASP.NET Core взаимодействовать с приложением ASP.NET, необходимо внести несколько небольших изменений в каждое приложение.

Необходимо настроить два значения конфигурации в обоих приложениях:

RemoteAppApiKey: ключ, который должен быть читаемым как GUID и используется совместно двумя приложениями. Это должно быть значение GUID, например 12345678-1234-1234-1234-123456789012.
RemoteAppUri: URI удаленного приложения ASP.NET Framework (требуется только в конфигурации приложения ASP.NET Core). Это должен быть полный URL-адрес, в котором размещено приложение ASP.NET Framework, например https://localhost:44300 или https://myapp.example.com.

Настройка приложения ASP.NET Framework

Это важно

Приложение ASP.NET Framework должно размещаться с поддержкой SSL. В настройке удаленного приложения для поэтапной миграции не требуется прямой доступ внешне. Рекомендуется разрешить доступ только из клиентского приложения через прокси-сервер.

Для приложений 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.Services.AddSystemWebAdapters()
            .AddRemoteAppServer(options =>
            {
                // ApiKey is a string representing a GUID
                options.ApiKey = System.Configuration.ConfigurationManager.AppSettings["RemoteAppApiKey"];
            });
    });

    // ...existing code...
}

Добавьте модуль SystemWebAdapterModule в web.config, если он еще не был добавлен NuGet. Эта конфигурация модуля необходима для сценариев хостинга IIS. Модуль SystemWebAdapterModule не добавляется автоматически при использовании проектов стилей ПАКЕТА SDK для ASP.NET Core.
```
  <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 Core

Для приложений ASP.NET Core добавьте эти значения в appsettings.json.

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

Чтобы настроить приложение ASP.NET Core для отправки запросов в приложение ASP.NET, настройте клиент удаленного приложения путем вызова AddRemoteAppClient после регистрации служб адаптера System.Web в AddSystemWebAdapters.

Добавьте эту конфигурацию в Program.cs файл:

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

При обновлении ASP.NET и ASP.NET Основных приложений методы расширения теперь можно использовать для настройки проверки подлинности удаленного приложения или удаленного сеанса по мере необходимости.

Включение прокси-сервера

Чтобы включить прокси-сервер из приложения ASP.NET Core в приложение ASP.NET Framework, можно настроить резервный маршрут, который пересылает несовпаденные запросы в устаревшее приложение. Это обеспечивает постепенную миграцию, когда приложение ASP.NET Core обрабатывает перенесенные функциональные возможности, возвращаясь к исходному приложению для немигрированных функций.

Установите пакет NuGet YARP (еще один обратный прокси-сервер), следуя последним рекомендациям.
Добавьте необходимые инструкции 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. При добавлении пакета включите предварительные пакеты в инструменте (например, выберите Include prerelease в диспетчере пакетов NuGet Visual Studio или используйте аналогичный параметр предварительной версии с помощью интерфейса командной строки .NET).

Добавьте Aspire оркестрацию для приложения ASP.NET Framework
Добавьте новое приложение ASP.NET Core в решение и добавьте его в Aspire оркестрацию.
Добавьте пакет Aspire.Hosting.IncrementalMigration в проект AppHost.

Настройте IIS Express для локального размещения приложения фреймворка и настройте использование резервного варианта для пошаговой миграции с помощью расширений пошаговой миграции.

var builder = DistributedApplication.CreateBuilder(args);

// Add ASP.NET Framework app with IIS Express
var frameworkApp = builder.AddIISExpressProject<Projects.FrameworkApplication>("framework");

// Add ASP.NET Core app with fallback to Framework app
var coreApp = builder.AddProject<Projects.CoreApplication>("core")
    .WithIncrementalMigrationFallback(frameworkApp, options =>
    {
        options.RemoteSession = RemoteSession.Enabled;
        options.RemoteAuthentication = RemoteAuthentication.DefaultScheme;
    });

builder.Build().Run();

Настройте параметры резервного варианта поэтапной миграции для сценариев, которые вы хотите поддерживать.

Настройка ServiceDefaults для поддержки платформы ASP.NET

Добавьте пакет Aspire.Microsoft.AspNetCore.SystemWebAdapters в приложение.

Обновите проект ServiceDefaults для поддержки .NET Framework. Это основано на настройках ServiceDefaults по умолчанию и может отличаться, если вы настроили что-то.

Обновите целевую платформу до multitarget:

- <TargetFramework>net10.0</TargetFramework>
+ <TargetFrameworks>net481;net10.0</TargetFrameworks>

Обновите PackageReferences, чтобы учесть различные платформы:

<ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Http.Resilience" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" />
    <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)' == 'net10.0' ">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" />
</ItemGroup>

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

Чтобы включить телеметрию, обновите метрики и регистрацию трассировки:

        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 Core:

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

Для получения полного и рабочего примера многоцелевой ServiceDefaults конфигурации, поддерживающей как ASP.NET Core, так и ASP.NET Framework, смотрите образец Extensions.cs файла в репозитории адаптеров System.Web https://github.com/dotnet/systemweb-adapters/blob/main/samples/ServiceDefaults/Extensions.cs.

Настройка приложения ASP.NET Framework

Ссылка на проект ServiceDefaults

Добавьте код конфигурации в метод Application_Start файла Global.asax.cs.

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

Настройка приложения ASP.NET Core

Ссылка на проект ServiceDefaults

Добавьте адаптеры System.Web в Programs.cs:

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 2026-01-26

Настройка удаленного приложения

Значения конфигурации

Настройка приложения ASP.NET Framework

Настройка приложения ASP.NET Core

Включение прокси-сервера

Настройка Aspire оркестрации

Настройка ServiceDefaults для поддержки платформы ASP.NET

Настройка приложения ASP.NET Framework

Настройка приложения ASP.NET Core

Обратная связь

Дополнительные ресурсы