supporto di ASP.NET Core per AOT nativo

Di Mitch Denny

Per le indicazioni per il Native AOT, che aggiungono o sostituiscono le linee guida in questo articolo, vedere Blazor WebAssembly.

Perché usare AOT nativo con ASP.NET Core

La pubblicazione e la distribuzione di un'app AOT nativa offre i vantaggi seguenti:

• Footprint del disco ridotto al minimo: quando si pubblica con AOT nativo, viene generato un singolo eseguibile contenente solo il codice dalle dipendenze esterne necessarie per supportare il programma. Le dimensioni del file eseguibile ridotte possono 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 applicazioni native AOT possono mostrare tempi di avvio ridotti, ovvero
  • L'app è pronta per gestire le richieste più rapidamente.
  • Distribuzione migliorata in cui gli agenti di orchestrazione dei contenitori devono gestire la transizione da una versione dell'app a un'altra.
• Riduzione della domanda di memoria: le app native AOT possono avere richieste di memoria ridotte, a seconda del lavoro svolto dall'app. Un consumo ridotto di memoria può comportare una maggiore densità di distribuzione e una maggiore scalabilità.

L'applicazione modello è stata eseguita nel laboratorio di benchmarking per confrontare le prestazioni di un'app pubblicata AOT, un'app di runtime ridotta e un'app di runtime non ridotta. Il grafico seguente mostra i risultati del benchmarking:

Il grafico precedente mostra che Native AOT ha dimensioni dell'app inferiori, utilizzo della memoria e tempo di avvio.

compatibilità ASP.NET Core e Native AOT

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à	Completamente supportato	Parzialmente supportato	Non supportato
gRPC	✔️Completamente supportato
API minimali		✔️Parzialmente supportato
MVC			❌ Non supportato
Blazor Server			❌ Non supportato
SignalR		✔️Parzialmente supportato
Autenticazione JWT	✔️Completamente supportato
Altre autenticazioni			❌ Non supportato
Condivisione delle Risorse tra Origini Diverse (CORS)	✔️Completamente supportato
Controlli di integrità	✔️Completamente supportato
HttpLogging	✔️Completamente supportato
Localizzazione	✔️Completamente supportato
OutputCaching	✔️Completamente supportato
Limitazione del tasso	✔️Completamente supportato
RichiestaDecompressione	✔️Completamente supportato
Cache delle Risposte	✔️Completamente supportato
ResponseCompression	✔️Completamente supportato
Riscrivi	✔️Completamente supportato
Sessione			❌ Non supportato
Stazione termale			❌ Non supportato
StaticFiles	✔️Completamente supportato
WebSocket	✔️Completamente supportato

Per altre informazioni sulle limitazioni, vedere:

• Limitazioni della distribuzione AOT nativa
• Introduzione agli avvisi AOT
• Incompatibilità di taglio note
• Introduzione agli avvisi di taglio
• Problema di GitHub dotnet/core #8288

È importante testare attentamente un'app quando si passa a un modello di distribuzione AOT nativo. L'app distribuita AOT deve essere testata per verificare che la funzionalità non sia cambiata rispetto all'app non ridotta e alla compilazione JIT. Durante la compilazione dell'app, esamina e correggi gli 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, l'app AOT pubblicata dovrebbe funzionare come l'app non ottimizzata e compilata JIT.

Pubblicazione AOT nativa

L'AOT nativo è abilitato con la PublishAot proprietà MSBuild. L'esempio seguente illustra come abilitare Native AOT in un file di progetto:

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

Questa impostazione abilita la compilazione AOT nativa durante la pubblicazione e abilita l'analisi dinamica dell'utilizzo del codice durante la compilazione e la modifica. Un progetto che usa la pubblicazione AOT nativa usa la compilazione JIT durante l'esecuzione 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'app 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, Native AOT è supportato dai tipi di app core ASP.NET seguenti:

• API minime: per altre informazioni, vedere la sezione Modello api Web (AOT nativo) più avanti in questo articolo.
• gRPC - Per ulteriori informazioni, vedere gRPC e Native AOT.
• Servizi di lavoro: per altre informazioni, vedere AOT nei modelli di servizio di lavoro.

Modello API Web (AOT nativo)

Il modello ASP.NET Core Web API (Native AOT), con nome breve webapiaot, crea un progetto con AOT abilitato. Il modello differisce dal modello di progetto API Web 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, poiché il traffico HTTPS viene generalmente 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 .http file 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 PublishAot al file di progetto, come illustrato in precedenza in questo articolo.
• 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.

Modifiche per supportare la generazione del codice sorgente

L'esempio seguente mostra il codice aggiunto al Program.cs file per supportare la generazione dell'origine della serializzazione JSON:

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
+{
+
+}

Senza questo codice aggiunto, 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 apportate a launchSettings.json

Il launchSettings.json file creato dal modello API Web (AOT nativo) ha la sezione iisSettings e il profilo IIS Express rimossi.

{
  "$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"
-      }
-    }
  }
}

Metodo CreateSlimBuilder

Il modello 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 indicato 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 builder.WebHost.UseKestrelHttpsConfiguration HTTP/3 può essere abilitato chiamando builder.WebHost.UseQuic.

Confronto tra CreateSlimBuilder e CreateBuilder

Il CreateSlimBuilder metodo non supporta le funzionalità seguenti supportate dal CreateBuilder metodo :

• Ospitare incontri per startup
• UseStartup
• I provider di registrazione seguenti:
  • Registro eventi di Windows
  • Debug
  • Origine dell'evento
• Funzionalità di hosting Web:
  • UseStaticWebAssets
  • Integrazione di IIS
• Kestrel configurazione
  • Endpoint HTTPS in Kestrel
  • Quic (HTTP/3)
• Vincoli regex e alfa usati nel routing

Il CreateSlimBuilder metodo include le funzionalità seguenti necessarie per un'esperienza di sviluppo efficiente:

• Configurazione del file JSON per appsettings.json e appsettings.{EnvironmentName}.json.
• Configurazione dei segreti utente.
• Log della console.
• Configurazione dei log.

Per un generatore che omette le funzionalità precedenti, vedere Il CreateEmptyBuilder metodo .

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

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

Generatori di origini

Poiché il codice inutilizzato viene tagliato durante la pubblicazione per AOT nativo, l'app non può usare reflection senza limiti durante l'esecuzione. I generatori di codice vengono utilizzati per produrre codice che evita la necessità di riflessione. In alcuni casi, i generatori di origine producono codice ottimizzato per AOT anche quando non è necessario un generatore.

Per visualizzare il codice sorgente generato, aggiungere la EmitCompilerGeneratedFiles proprietà al file di .csproj un'app, come illustrato nell'esempio seguente:

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

  <PropertyGroup>
    <!-- Other properties omitted for brevity -->
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  </PropertyGroup>

</Project>

Eseguire il dotnet build comando per visualizzare il codice generato. L'output include una obj/Debug/net8.0/generated/ directory che contiene tutti i file generati per il progetto.

Il dotnet publish comando compila anche i file di origine e genera i file compilati. Inoltre, dotnet publish passa gli assembly generati a un compilatore IL nativo. Il compilatore IL produce l'eseguibile nativo. L'eseguibile nativo contiene il codice nativo del computer.

Librerie e AOT nativo

Molte delle librerie più diffuse usate nei progetti ASP.NET Core presentano attualmente alcuni problemi di compatibilità quando vengono usati in un progetto destinato a AOT nativo, ad esempio:

• Uso della reflection per ispezionare 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 devono essere aggiornate per lavorare con AOT nativo. Possono essere aggiornati usando strumenti come generatori di origine Roslyn.

Gli autori di librerie che sperano di supportare native AOT sono invitati a:

• Informazioni sui requisiti di compatibilità AOT nativi.
• Preparare la libreria per tagliare.

API minime con payload JSON

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

• Impone i requisiti di compatibilità per JSON e AOT nativo.
• Richiede l'uso del System.Text.Json generatore di sorgente.

Tutti i tipi trasmessi come parte del corpo HTTP o restituiti dai delegati di richiesta nelle app api minime devono essere configurati in un oggetto JsonSerializerContext registrato tramite l'inserimento 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
{
}

Nel codice evidenziato precedente:

• Il contesto del serializzatore JSON viene registrato con il contenitore di inserimento delle dipendenze. Per altre informazioni, vedere:
  • Combinare generatori di sorgenti
  • TypeInfoResolverChain
• L'oggetto personalizzato JsonSerializerContext viene annotato con l'attributo [JsonSerializable] per abilitare il codice serializzatore JSON generato automaticamente per il tipo ToDo.

Un parametro nel delegato che non è associato al corpo e non è necessario che sia serializzabile. Ad esempio, un parametro della stringa di query che è di tipo oggetto avanzato e 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.

Problemi noti

Vedere questo problema di GitHub per segnalare o esaminare i problemi relativi al supporto AOT nativo in ASP.NET Core.

Vedi anche

• Esercitazione: Pubblicare un'app ASP.NET Core con AOT nativo
• Distribuzione AOT nativa
• Ottimizzare le distribuzioni AOT
• Generatore di sorgenti per l'associazione della configurazione
• Utilizzo del generatore di origine dell'aggregatore di configurazione
• Modello di compilazione AOT API minimo
• Confronto tra WebApplication.CreateBuilder e CreateSlimBuilder
• Esplorazione del nuovo generatore di origine API minimo
• Sostituzione delle chiamate di metodo con intercettori
• Dietro [LogProperties] e il nuovo generatore di sorgenti per la registrazione della telemetria