supporto di ASP.NET Core per AOT nativo

Di Mitch Denny

ASP.NET Core 8.0 introduce il supporto per .NET Native ahead-of-time (AOT).

Per Blazor WebAssembly indicazioni native AOT, che aggiunge o sostituisce le linee guida in questo articolo, vedere ASP.NET Core Blazor WebAssembly build tools and ahead-of-time (AOT) compilation (AOT).

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 da immagini più piccole.
• 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'app modello è stata eseguita nel lab di benchmarking per confrontare le prestazioni di un'app pubblicata AOT, un'app di runtime tagliata e un'app di runtime non completata. 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 ASP.NET compatibilità delle funzionalità Core con Native AOT:

Funzionalità	Completamente supportato	Parzialmente supportato	Non supportato
gRPC	✔️Completamente supportato
API minime		✔️Parzialmente supportato
MVC			❌Non supportato
Blazor Server			❌Non supportato
SignalR		✔️Parzialmente supportato
Autenticazione JWT	✔️Completamente supportato
Altre autenticazioni			❌Non supportato
CORS	✔️Completamente supportato
Controlli di integrità	✔️Completamente supportato
HttpLogging	✔️Completamente supportato
Localizzazione	✔️Completamente supportato
OutputCaching	✔️Completamente supportato
RateLimiting	✔️Completamente supportato
RequestDecompression	✔️Completamente supportato
ResponseCaching	✔️Completamente supportato
ResponseCompression	✔️Completamente supportato
Riscrivi	✔️Completamente supportato
Sessione			❌Non supportato
Spa			❌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 compilata senza tentativi e alla compilazione JIT. Quando si compila l'app, esaminare e correggere 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 deve funzionare come l'app non completata 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 differenze seguenti 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 altre informazioni, vedere gRPC e AOT nativo.
• 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) (nome webapiaotbreve ) 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 origine 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 dell'origine

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 reflection non è supportata in AOT nativo.

Per altre informazioni, vedi:

• Combinare generatori di origine
• TypeInfoResolverChain

Modifiche apportate a launchSettings.json

Il launchSettings.json file creato dal modello API Web (AOT nativo) include la sezione e IIS Express il iisSettings profilo 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 gateway applicazione. È possibile abilitare HTTPS chiamando il generatore. WebHost.UseKestrelHttpsConfiguration HTTP/3 può essere abilitato chiamando il generatore. WebHost.UseQuic.

Confronto tra CreateSlimBuilder e CreateBuilder

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

• Assembly di avvio dell'hosting
• UseStartup
• I provider di registrazione seguenti:
  • Registro eventi di Windows
  • Debug
  • Origine 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.
• Registrazione della console.
• Configurazione della registrazione.

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

L'inclusione di funzionalità minime offre vantaggi per il taglio e LOT. Per altre informazioni, vedere Trimming 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 non associato in fase di esecuzione. I generatori di origine vengono usati per produrre codice che evita la necessità di reflection. 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 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 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 e 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 origine.

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 origine
  • TypeInfoResolverChain
• L'oggetto personalizzato JsonSerializerContext viene annotato con l'attributo per abilitare il codice serializzatore JSON generato dall'origine [JsonSerializable] per il ToDo tipo.

Parametro nel delegato che non è associato al corpo e non deve essere serializzabile. Ad esempio, un parametro stringa di query che è un tipo di 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 origini con associazione della configurazione
• Uso del generatore di origine del gestore di associazione di configurazione
• Modello di compilazione AOT api minimo
• Confronto con WebApplication.CreateBuilderCreateSlimBuilder
• Esplorazione del nuovo generatore di origine API minimo
• Sostituzione delle chiamate di metodo con intercettori
• Dietro [LogProperties] e il nuovo generatore di origine di registrazione dei dati di telemetria