supporto di ASP.NET Core per AOT nativo

Di Mitch Denny

La pubblicazione e la distribuzione di applicazioni native in anticipo (AOT) in ASP.NET Core offrono diversi vantaggi:

• Ingombro del disco ridotto. Quando si pubblica un'app usando Native AOT, il processo produce un singolo file eseguibile. L'eseguibile contiene solo il codice delle dipendenze esterne necessarie per supportare l'app. La dimensione del file eseguibile ridotta può portare a:

  • Immagini di contenitori più piccole, ad esempio negli scenari di distribuzione in contenitori.
  • Riduzione del tempo di distribuzione grazie a immagini più grandi.

• Riduzione del tempo di avvio. Le app AOT native possono richiedere meno tempo di avvio, che abilita:

  • L'app per gestire le richieste è più rapida.
  • Distribuzione migliorata, in cui gli agenti di orchestrazione dei contenitori gestiscono la transizione da una versione dell'app a un'altra.

• Riduzione della domanda di memoria. Le app AOT native possono richiedere meno memoria, a seconda del lavoro svolto dall'app. Un consumo ridotto di memoria può comportare una maggiore densità di distribuzione e una maggiore scalabilità.

Il grafico seguente mostra i risultati di un test di benchmarking nelle varie app modello. Il benchmark confronta le prestazioni per un'app pubblicata AOT (barra arancione), un'app runtime tagliata (barra verde) e un'app di runtime non completata (barra gialla). Il test ha rivelato che l'app nativa AOT dimostra dimensioni dell'app inferiori, utilizzo della memoria e tempo di avvio.

Questo articolo descrive il supporto per le app AOT native in ASP.NET Core, inclusa una panoramica della pubblicazione e della distribuzione.

Per le linee guida di ASP.NET Core Blazor WebAssembly Native AOT, che si aggiungono o sostituiscono le linee guida in questo articolo, vedere strumenti di compilazione e compilazione anticipata (AOT) di ASP.NET Core Blazor WebAssembly.

Esaminare ASP.NET Core e compatibilità AOT nativa

Non tutte le funzionalità di ASP.NET Core sono attualmente compatibili con Native AOT.

La tabella seguente riepiloga la compatibilità delle funzionalità di ASP.NET Core con Native AOT.

Funzionalità	Supportato	Supporto parziale	Non supportato
Blazor Server			❌
Condivisione delle Risorse tra Origini Diverse (CORS)	✔️
gRPC	✔️
Controlli di integrità	✔️
HttpLogging	✔️
Autenticazione JWT	✔️
Localizzazione	✔️
API minimali		✔️
MVC			❌
Altre autenticazioni			❌
OutputCaching	✔️
Limitazione del tasso	✔️
RichiestaDecompressione	✔️
Cache delle Risposte	✔️
ResponseCompression	✔️
Riscrivi	✔️
Sessione			❌
SignalR		✔️
Stazione termale			❌
StaticFiles	✔️
WebSocket	✔️

Per altre informazioni sulle limitazioni, vedere:

• Limitazioni della distribuzione AOT nativa
• Avvisi AOT
• Incompatibilità di taglio note
• Correggere gli avvisi di ritaglio

Verificare l'app nel modello di distribuzione AOT nativo

È importante testare attentamente un'app quando si passa a un modello di distribuzione AOT nativo. Testare l'app distribuita con compilazione AOT e verificare che la funzionalità sia invariata rispetto all'app compilata JIT (Just-In-Time) non alleggerita.

Quando compili l'app, esamina e correggi eventuali avvisi AOT. Un'app che genera avvisi AOT durante la pubblicazione potrebbe non funzionare correttamente. Se non vengono generati avvisi AOT in fase di pubblicazione, è possibile prevedere che l'app AOT pubblicata funzioni come l'app non completata e compilata JIT.

Pubblicare un'app AOT nativa (PublishAot)

Abilitare AOT nativo per l'applicazione usando la PublishAot proprietà MSBuild. L'esempio seguente illustra come abilitare Native AOT in un file di progetto:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

La PublishAot proprietà abilita la compilazione AOT nativa durante il processo di pubblicazione e abilita l'analisi dinamica dell'utilizzo del codice durante la compilazione e la modifica. Un progetto che usa la pubblicazione AOT nativa implementa la compilazione JIT quando viene eseguita in locale.

Un'app AOT presenta le seguenti differenze rispetto a un'app compilata JIT:

• Le funzionalità non compatibili con AOT nativo sono disabilitate e generano eccezioni in fase di esecuzione.
• Un analizzatore di origine è abilitato per evidenziare il codice non compatibile con AOT nativo. In fase di pubblicazione, l'intera app, inclusi i pacchetti NuGet, viene analizzata di nuovo per la compatibilità.

L'analisi AOT nativa include tutto il codice dell'applicazione e le librerie da cui dipende l'app. Esaminare gli avvisi AOT nativi e adottare misure correttive. È consigliabile pubblicare spesso le app per individuare i problemi all'inizio del ciclo di vita dello sviluppo.

In .NET 8 e versioni successive, i tipi di app ASP.NET Core seguenti supportano native AOT:

• API minime : per altre informazioni, vedere Esaminare il modello api Web (AOT nativo) più avanti in questo articolo.
• gRPC : per altre informazioni, vedere gRPC e AOT nativo.
• Servizi di lavoratore - Per ulteriori informazioni, vedere Attività in background con servizi ospitati in ASP.NET Core > Native AOT.

Esaminare il modello api Web (AOT nativo)

Il modello ASP.NET Core Web API (AOT nativo) (nome breve webapiaot) crea un progetto con AOT abilitato. Il modello differisce da un modello di progetto API Web standard nei modi seguenti:

• Usa solo API minime, perché MVC non è ancora compatibile con AOT nativo.
• Usa l'API CreateSlimBuilder() per garantire che solo le funzionalità essenziali siano abilitate per impostazione predefinita, riducendo al minimo le dimensioni distribuite dell'app.
• È configurato per l'ascolto solo su HTTP. Il traffico HTTPS viene in genere gestito da un servizio di ingresso nelle distribuzioni native del cloud.
• Non include un profilo di avvio per l'esecuzione in IIS o IIS Express.
• Crea un file .http configurato con richieste HTTP di esempio che possono essere inviate agli endpoint dell'app.
• Include un'API di esempio Todo anziché l'esempio di previsione meteo.
• Aggiunge la PublishAot proprietà al file di progetto, come descritto in precedenza.
• Abilita i generatori di codice sorgente del serializzatore JSON. Il generatore di origine viene usato per generare codice di serializzazione in fase di compilazione, necessario per la compilazione AOT nativa.

Aggiornamenti del codice per la serializzazione JSON (Program.cs)

Il codice nel file Program.cs viene modificato per fornire il supporto per la generazione dell'origine di serializzazione JSON.

Il frammento di codice seguente mostra le modifiche apportate al codice:

using MyFirstAotWebApi;
+using System.Text.Json.Serialization;

-var builder = WebApplication.CreateBuilder();
+var builder = WebApplication.CreateSlimBuilder(args);

+builder.Services.ConfigureHttpJsonOptions(options =>
+{
+  options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
+});

var app = builder.Build();

var sampleTodos = TodoGenerator.GenerateTodos().ToArray();

var todosApi = app.MapGroup("/todos");
todosApi.MapGet("/", () => sampleTodos);
todosApi.MapGet("/{id}", (int id) =>
    sampleTodos.FirstOrDefault(a => a.Id == id) is { } todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.Run();

+[JsonSerializable(typeof(Todo[]))]
+internal partial class AppJsonSerializerContext : JsonSerializerContext
+{
+
+}

Se non si modifica il codice, System.Text.Json usa la reflection per serializzare e deserializzare JSON. La riflessione non è supportata in Nativo AOT.

Per altre informazioni, vedi:

• Combinare generatori di sorgenti
• TypeInfoResolverChain

Modifiche al codice per il profilo di avvio (launchSettings.json)

Il modello API Web (AOT nativo) crea un file launchSettings.json. A differenza di un file di avvio standard, il file generato non include la iisSettings sezione o il IIS Express profilo.

Il frammento di codice seguente mostra le sezioni escluse (rosso colorato):

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
-  "iisSettings": {
-     "windowsAuthentication": false,
-     "anonymousAuthentication": true,
-     "iisExpress": {
-       "applicationUrl": "http://localhost:11152",
-       "sslPort": 0
-     }
-   },
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "todos",
      "applicationUrl": "http://localhost:5102",
        "environmentVariables": {
          "ASPNETCORE_ENVIRONMENT": "Development"
        }
      },
-     "IIS Express": {
-       "commandName": "IISExpress",
-       "launchBrowser": true,
-       "launchUrl": "todos",
-      "environmentVariables": {
-       "ASPNETCORE_ENVIRONMENT": "Development"
-      }
-    }
  }
}

CreateSlimBuilder() chiamato per impostazioni minime predefinite dell'applicazione

Il modello api Web (AOT nativo) usa il CreateSlimBuilder() metodo anziché il CreateBuilder() metodo .

using System.Text.Json.Serialization;
using MyFirstAotWebApi;

var builder = WebApplication.CreateSlimBuilder(args);
builder.Logging.AddConsole();

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
});

var app = builder.Build();

var sampleTodos = TodoGenerator.GenerateTodos().ToArray();

var todosApi = app.MapGroup("/todos");
todosApi.MapGet("/", () => sampleTodos);
todosApi.MapGet("/{id}", (int id) =>
    sampleTodos.FirstOrDefault(a => a.Id == id) is { } todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.Run();

[JsonSerializable(typeof(Todo[]))]
internal partial class AppJsonSerializerContext : JsonSerializerContext
{
}

Il CreateSlimBuilder metodo inizializza WebApplicationBuilder con le funzionalità minime ASP.NET Core necessarie per eseguire un'app.

Come descritto in precedenza, il CreateSlimBuilder metodo non include il supporto per HTTPS o HTTP/3. Questi protocolli in genere non sono necessari per le app eseguite dietro un proxy di terminazione TLS. Ad esempio, vedere Terminazione TLS e TLS end-to-end con Application Gateway. È possibile abilitare HTTPS chiamando il metodo builder.WebHost.UseKestrelHttpsConfiguration o abilitare HTTP/3 chiamando builder.WebHost.UseQuic.

Confrontare CreateSlimBuilder() e CreateBuilder()

Il CreateSlimBuilder metodo fornisce l'accesso a una parte delle funzionalità dell'applicazione disponibili con il CreateBuilder metodo . Come descritto in precedenza, il modello Web API (Native AOT) chiama CreateSlimBuilder per inizializzare WebApplicationBuilder, quindi il generatore usa le funzionalità minime ASP.NET Core necessarie per eseguire l'app.

Entrambi i metodi forniscono le funzionalità necessarie per un'esperienza di sviluppo efficiente:

• Configurazione per i file appsettings.json e appsettings.{EnvironmentName}.json
• Configurazione dei segreti utente
• Log della console
• Configurazione della registrazione

L'inclusione di funzionalità minime offre vantaggi per la riduzione e AOT. Per ulteriori informazioni, vedere Ottimizzazione di distribuzioni ed eseguibili autonomi.

Se si preferisce usare un generatore che omette tutte le funzionalità, vedere il metodo WebApplication.CreateEmptyBuilder .

Funzionalità non disponibili in CreateSlimBuilder

Il CreateSlimBuilder metodo non fornisce le funzionalità seguenti, disponibili in CreateBuilder:

• Ospitare incontri per startup
• UseStartup metodo
• Provider di registrazione:
  • Registro eventi di Windows
  • Debug
  • EventSource
• Funzionalità di hosting Web:
  • metodo UseStaticWebAssets
  • Integrazione di IIS
• Kestrel Configurazione:
  • Endpoint HTTPS
  • QUIC (HTTP/3)
• Regex e i vincoli alfa usati nel routing (GitHub /dotnet/aspnetcore/issues #46142)

Per informazioni più dettagliate, vedere Confronto tra WebApplication.CreateBuilder e CreateSlimBuilder

Usare generatori di codice sorgente ed evitare la riflessione

Durante il processo di pubblicazione per Native AOT, qualsiasi codice inutilizzato viene tagliato. Di conseguenza, un'app non può usare reflection illimitata in fase di esecuzione. È possibile usare generatori di origine che producono codice che evita la necessità di riflessione. In alcuni casi, i generatori di origine generano codice di output ottimizzato per AOT anche quando non è necessario un generatore.

• Per visualizzare il codice sorgente generato, aggiungere la proprietà EmitCompilerGeneratedFiles al file di progetto dell'applicazione (con estensione csproj):

  <Project Sdk="Microsoft.NET.Sdk.Web">
  
     <PropertyGroup>
       <!-- Other properties omitted for brevity -->
       <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
     </PropertyGroup>
  
  </Project>
  

• Per visualizzare il codice generato, eseguire il dotnet build comando . Il comando compila i file di origine e genera i file intermedi necessari per eseguire l'app in un ambiente di sviluppo. L'output include una directory obj/Debug/<.NET>/generated/ che contiene tutti i file generati per il progetto.

• Per preparare l'app per la distribuzione, eseguire il dotnet publish comando . Il comando compila i file di origine e genera tutti i file necessari per distribuire l'app. Passa gli assembly generati a un compilatore IL nativo, che produce l'eseguibile nativo. L'eseguibile nativo contiene il codice nativo del computer.

Usare librerie con Native AOT

Molte librerie comuni usate nei progetti ASP.NET Core presentano attualmente alcuni problemi di compatibilità quando sono incorporati in progetti destinati a AOT nativo, ad esempio:

• Uso della reflection per esaminare e individuare i tipi
• Caricamento condizionale delle librerie in fase di esecuzione
• Generazione di codice in tempo reale per implementare la funzionalità

Le librerie che usano queste funzionalità dinamiche richiedono aggiornamenti per l'uso con AOT nativo. Sono disponibili vari strumenti per l'applicazione degli aggiornamenti necessari, ad esempio i generatori di origine Roslyn.

Gli autori di librerie che sperano di supportare Native AOT sono invitati a esaminare gli articoli seguenti:

• Distribuzione AOT nativa
• Preparare le librerie .NET per la riduzione

Lavorare con API Minimali e payload JSON

Il Minimal API framework è ottimizzato per la ricezione e la restituzione di payload JSON tramite il System.Text.Json.

• Lo spazio dei nomi impone i requisiti di compatibilità per JSON e AOT nativo.
• Richiede l'uso del generatore di origine System.Text.Json.

Tutti i tipi trasmessi come parte del corpo HTTP o restituiti dai delegati di richiesta nelle app API Minimali devono essere configurati in un'istanza JsonSerializerContext. L'istanza deve essere registrata con l'iniezione delle dipendenze di ASP.NET Core.

using System.Text.Json.Serialization;
using MyFirstAotWebApi;

var builder = WebApplication.CreateSlimBuilder(args);
builder.Logging.AddConsole();

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
});

var app = builder.Build();

var sampleTodos = TodoGenerator.GenerateTodos().ToArray();

var todosApi = app.MapGroup("/todos");
todosApi.MapGet("/", () => sampleTodos);
todosApi.MapGet("/{id}", (int id) =>
    sampleTodos.FirstOrDefault(a => a.Id == id) is { } todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.Run();

[JsonSerializable(typeof(Todo[]))]
internal partial class AppJsonSerializerContext : JsonSerializerContext
{
}

• Il contesto del serializzatore JSON viene registrato con il contenitore di inserimento delle dipendenze. Per altre informazioni, vedere Combinare generatori di origine e TypeInfoResolverChain.

• L'oggetto personalizzato JsonSerializerContext viene annotato con l'attributo JsonSerializable , che abilita il codice serializzatore JSON generato dall'origine per il ToDo tipo.

Un parametro nel delegato che non è associato al corpo non ha bisogno di essere serializzabile. Ad esempio, un parametro della stringa di query può essere un tipo di oggetto avanzato che implementa IParsable<T>.

public class Todo
{
    public int Id { get; set; }
    public string? Title { get; set; }
    public DateOnly? DueBy { get; set; }
    public bool IsComplete { get; set; }
}

static class TodoGenerator
{
    private static readonly (string[] Prefixes, string[] Suffixes)[] _parts = new[]
        {
            (new[] { "Walk the", "Feed the" }, new[] { "dog", "cat", "goat" }),
            (new[] { "Do the", "Put away the" }, new[] { "groceries", "dishes", "laundry" }),
            (new[] { "Clean the" }, new[] { "bathroom", "pool", "blinds", "car" })
        };
    // Remaining code omitted for brevity.

Esaminare i problemi noti

Per segnalare o esaminare i problemi relativi al supporto AOT nativo in ASP.NET Core, vedere GitHub /dotnet/core/issues #8288).

Contenuti correlati

• Pubblica un'app ASP.NET Core con AOT nativo
• Distribuzione AOT nativa
• Ottimizzare le distribuzioni AOT