Condividi tramite

Configurazione remota dell'app

Importante

Le applicazioni Framework e Core devono usare layout di directory virtuali identici.

La configurazione della directory virtuale viene usata per la generazione di route, l'autorizzazione e altri servizi all'interno del sistema. A questo punto, non è stato trovato alcun metodo affidabile per abilitare directory virtuali diverse a causa del funzionamento di ASP.NET Framework.

In alcuni scenari di aggiornamento incrementale, è utile che la nuova app ASP.NET Core sia in grado di comunicare con l'app ASP.NET originale.

Scenari comuni che consentono di:

Valori di configurazione

Per consentire all'app ASP.NET Core di comunicare con l'app ASP.NET, è necessario apportare alcune piccole modifiche a ogni app.

È necessario configurare due valori di configurazione in entrambe le applicazioni:

  • RemoteAppApiKey: chiave (necessaria per l'analisi come GUID) condivisa tra le due applicazioni. Deve essere un valore GUID come 12345678-1234-1234-1234-123456789012.
  • RemoteAppUri: URI dell'applicazione remote ASP.NET Framework (richiesta solo nella configurazione dell'applicazione ASP.NET Core). Deve trattarsi dell'URL completo in cui è ospitata l'app ASP.NET Framework, ad esempio https://localhost:44300 o https://myapp.example.com.

Configurare l'applicazione ASP.NET Framework

Importante

L'applicazione ASP.NET Framework deve essere ospitata con SSL abilitato. Nella configurazione remota dell'app per la migrazione incrementale non è necessario avere accesso diretto esternamente. È consigliabile consentire l'accesso solo dall'applicazione client tramite il proxy.

Per le applicazioni ASP.NET Framework, aggiungere questi valori alla web.config<appSettings> sezione :

Importante

ASP.NET Framework archivia appSettings in web.config. Tuttavia, possono essere recuperati da altre origini (ad esempio le variabili di ambiente) con l'uso di Generatori di configurazione. In questo modo, la condivisione dei valori di configurazione risulta molto più semplice tra le applicazioni locali e remote in questa configurazione.

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

Per configurare l'applicazione in modo che sia disponibile per gestire le richieste dal client ASP.NET Core, configurare quanto segue:

  1. Installare il pacchetto NuGet Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices

  2. Aggiungere il codice di configurazione al Application_Start metodo nel Global.asax.cs file:

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

  3. Aggiungere il SystemWebAdapterModule modulo a web.config se non è già stato aggiunto da NuGet. Questa configurazione del modulo è necessaria per gli scenari di hosting IIS. Il SystemWebAdapterModule modulo non viene aggiunto automaticamente quando si usano progetti di stile SDK per 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>

Configurare l'applicazione ASP.NET Core

Per le applicazioni ASP.NET Core, aggiungere questi valori a appsettings.json:

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

Per configurare l'app ASP.NET Core per poter inviare richieste all'app ASP.NET, configurare il client dell'app remota chiamando AddRemoteAppClient dopo aver registrato i servizi dell'adapter System.Web con AddSystemWebAdapters.

Aggiungere questa configurazione al Program.cs file:

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

Con le app ASP.NET e ASP.NET Core aggiornate, i metodi di estensione possono ora essere usati per configurare l'autenticazione remota dell'app o la sessione remota, in base alle esigenze.

Abilitare il proxy

Per abilitare il proxy dall'applicazione ASP.NET Core all'applicazione ASP.NET Framework, è possibile configurare una route di fallback che inoltra richieste non corrispondenti all'applicazione legacy. Ciò consente una migrazione graduale in cui l'app ASP.NET Core gestisce la funzionalità migrata, ricorrendo all'app originale per le funzionalità non migrate.

  1. Installare il pacchetto NuGet YARP (Yet Another Reverse Proxy) seguendo le indicazioni più recenti.

  2. Aggiungere le istruzioni using necessarie al codice Program.cs:

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

  3. Registrare i servizi proxy inversi in Program.cs:

    builder.Services.AddReverseProxy();

  4. Dopo aver compilato l'app e configurato altri middleware, aggiungere la mappatura della route di fallback.

    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();

Configurazione dell'orchestrazione Aspire

Importante

Questa opzione è ancora in anteprima e non è disponibile in NuGet.org, quindi è necessario configurare la configurazione NuGet per eseguire il pull delle librerie dal feed giornaliero delle librerie .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>

NOTA: richiede la versione 2.0.1-preview1.25351.5 degli adattatori System.Web o versioni successive.

Avvertimento

NOTA: si tratta di un componente di terze parti che consente di eseguire l'applicazione in Aspire. Al momento corrente, le applicazioni framework di ASP.NET non sono supportate direttamente in Aspire, ma questo progetto è utile. Questa dipendenza è destinata alla compilazione e allo sviluppo, ma non deve essere distribuita nell'ambiente di produzione.

  1. Aggiungere Aspire l'orchestrazione per l'applicazione ASP.NET Framework

  2. Aggiungere una nuova applicazione ASP.NET Core alla soluzione e includerla nell'orchestrazione Aspire

  3. Aggiornare AppHost per mirare a Windows poiché l'integrazione IIS richiede che:

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

  4. Aggiungi le seguenti integrazioni Aspire all'host dell'app:

    • Aspire.Hosting.IncrementalMigration
    • C3D.Extensions.Aspire.IISExpress

  5. Configurare IIS Express per ospitare localmente l'applicazione framework e configurare il fallback di migrazione incrementale:

    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();

  6. Configurare le opzioni del fallback di migrazione incrementale per gli scenari che si desidera supportare.

Configurare ServiceDefaults per supportare ASP.NET Framework

  1. Aggiungere il pacchetto Aspire.Microsoft.AspNetCore.SystemWebAdapters all'applicazione.
  2. Aggiornare il progetto ServiceDefaults per supportare .NET Framework. Questa opzione è basata su ServiceDefaults predefinite e può essere diversa se è stato personalizzato qualsiasi elemento.

    • Aggiornare il framework di destinazione per il multitargeting.

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

    • Aggiornare PackageReferences per tenere conto dei diversi framework:

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

    • Nel file di Extensions.cs è necessario escludere in modo condizionale le API ServiceDiscovery perché attualmente non sono supportate in .NET Framework:

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

    • Per abilitare la telemetria, aggiornare le metriche e le registrazioni di traccia:

              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();
            });

    • Disabilitare gli endpoint predefiniti come applicabile solo per ASP.NET Core:

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

Configurare l'applicazione ASP.NET Framework

  1. Fare riferimento al progetto ServiceDefaults

  2. Aggiungere il codice di configurazione al Application_Start metodo nel Global.asax.cs file:

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

Configurare l'applicazione ASP.NET Core

  1. Fare riferimento al progetto ServiceDefaults

  2. Aggiungere gli adattatori System.Web in 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();

Con questa configurazione:

  1. Le route locali hanno la precedenza: se l'applicazione ASP.NET Core ha una route corrispondente, gestirà la richiesta in locale
  2. Passaggio all'app legacy: le richieste non corrispondenti vengono inoltrate automaticamente all'applicazione ASP.NET Framework
  3. Ottimizzazione del middleware: il .ShortCircuit() metodo impedisce l'esecuzione di middleware non necessari durante l'inoltro delle richieste

Questa configurazione consente un'esperienza utente senza problemi durante la migrazione incrementale, in cui gli utenti possono accedere alle funzionalità di cui è stata eseguita la migrazione e legacy tramite un singolo endpoint.

  • Last updated on