Suporte ASP.NET Core para AOT nativo

Por Mitch Denny

Publicar e implementar aplicações nativas antecipadas (AOT) no ASP.NET Core oferece vários benefícios:

  • Minimização da pegada do disco. Quando publica uma aplicação usando o AOT nativo, o processo produz um único ficheiro executável. O executável contém apenas o código das dependências externas necessárias para suportar a aplicação. O tamanho reduzido do executável pode levar a:

    • Imagens de contentor mais pequenas, por exemplo, em cenários de implantação em contentores.
    • Tempo de implantação reduzido a partir de imagens menores.

  • Tempo de arranque reduzido. Aplicações nativas AOT podem exigir menos tempo de arranque, o que permite:

    • A aplicação serve para atender pedidos mais rapidamente.
    • Implementação melhorada, onde os orquestradores de contentores gerem a transição de uma versão da aplicação para outra.

  • Menor procura de memória. As aplicações nativas do AOT podem exigir menos memória, dependendo do trabalho feito pela aplicação. O consumo reduzido de memória pode levar a uma maior densidade de implantação e melhor escalabilidade.

O gráfico seguinte mostra os resultados de um teste de benchmarking nas várias aplicações modelo. O benchmark compara o desempenho de uma aplicação publicada em AOT (barra laranja), uma aplicação de runtime reduzida (barra verde) e uma aplicação de runtime não reduzida (barra amarela). O teste revelou que a aplicação Native AOT apresenta menor tamanho da aplicação, uso de memória e tempo de arranque inferiores.

Gráfico que mostra uma comparação entre o tamanho da aplicação, uso de memória e métricas de tempo de arranque. O gráfico compara uma aplicação AOT nativa publicada, uma aplicação de runtime cortada e uma app de runtime não recortada.

Este artigo descreve o suporte para aplicações nativas AOT no ASP.NET Core, incluindo uma visão geral da publicação e implementação.

Para orientação AOT nativa do ASP.NET CoreBlazor WebAssembly, que complementa ou substitui a orientação deste artigo, consulte ferramentas de compilação do ASP.NET Core Blazor WebAssembly e compilação antecipada (AOT).

Revise a compatibilidade ASP.NET Core e Native AOT

Nem todos os recursos do ASP.NET Core são atualmente compatíveis com a AOT nativa.

A tabela a seguir resume a compatibilidade de recursos do ASP.NET Core com o AOT Nativo:

Funcionalidade Suportado Suporte parcial Não suportado
Blazor Server ❌
CORS ✔️
gRPC ✔️
Verificações de saúde ✔️
Registo HTTP ✔️
Autenticação JWT ✔️
Localização ✔️
APIs mínimas ✔️
MVC ❌
Outra autenticação ❌
OutputCaching ✔️
Limitação de Taxa ✔️
PedidoDescompressão ✔️
Cache de Respostas ✔️
CompressãoDeResposta ✔️
Reescrever ✔️
Sessão ❌
SignalR ✔️
Termas ❌
Arquivos Estáticos ✔️
WebSockets ✔️

Para obter mais informações sobre limitações, consulte:

Verificar a aplicação no modelo de implementação Native AOT

É importante testar uma aplicação cuidadosamente quando se passa para um modelo de implementação Native AOT. Teste a aplicação implementada no AOT e confirme que a funcionalidade está inalterada em relação à aplicação compilada sem cortes e just-in-time (JIT).

Quando construir a aplicação, reveja e corrija quaisquer avisos AOT. Uma aplicação que emite avisos AOT durante a publicação pode não funcionar corretamente. Se não forem emitidos alertas de AOT no momento da publicação, pode esperar que a aplicação AOT publicada funcione da mesma forma que a aplicação sem otimizações e compilada por JIT.

Publicar uma aplicação nativa AOT (PublishAot)

Ativa o AOT nativo para a tua aplicação usando a PublishAot propriedade MSBuild. O exemplo a seguir mostra como habilitar o AOT nativo em um arquivo de projeto:

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

A PublishAot propriedade permite a compilação Native AOT durante o processo de publicação e possibilita a análise dinâmica do uso do código durante a compilação e edição. Um projeto que utiliza publicação nativa AOT implementa compilação JIT quando esta é executada localmente.

Um aplicativo AOT tem as seguintes diferenças de um aplicativo compilado por JIT:

  • Os recursos que não são compatíveis com o AOT nativo são desativados e lançam exceções em tempo de execução.
  • Um analisador de código-fonte está habilitado para destacar o código que não é compatível com o AOT nativo. No momento da publicação, todo o aplicativo, incluindo os pacotes NuGet, é analisado quanto à compatibilidade novamente.

A análise nativa de AOT inclui todo o código da aplicação e as bibliotecas de que a aplicação depende. Revise os avisos de AOT nativos e tome medidas corretivas. É uma boa ideia publicar aplicativos com frequência para descobrir problemas no início do ciclo de vida do desenvolvimento.

No .NET 8 e versões posteriores, os seguintes tipos de aplicações ASP.NET Core suportam o AOT nativo:

Consulte o modelo da Web API (Native AOT)

O modelo da API ASP.NET Core Web (Native AOT) (nome abreviado webapiaot) cria um projeto com AOT ativado. O modelo difere de um modelo padrão de projeto Web API das seguintes formas:

  • Usa apenas APIs mínimas, pois o MVC ainda não é compatível com o AOT nativo.
  • Utiliza a CreateSlimBuilder() API para garantir que somente funcionalidades essenciais estão ativadas por padrão, o que minimiza a dimensão do ficheiro da aplicação.
  • Está configurado para ouvir apenas em HTTP. O tráfego HTTPS é normalmente tratado por um serviço de entrada em implementações cloud-native.
  • Não inclui um perfil de inicialização para execução no IIS ou IIS Express.
  • Cria um ficheiro .http configurado com exemplos de HTTP que podem ser enviados para os endpoints da aplicação.
  • Inclui uma amostra Todo API em vez da amostra de previsão do tempo.
  • Adiciona a PublishAot propriedade ao ficheiro do projeto, conforme descrito anteriormente.
  • Habilita os geradores de código-fonte do serializador JSON . O gerador de código-fonte é usado para gerar código de serialização em tempo de compilação, o que é necessário para a compilação AOT nativa.

Atualizações de código para serialização JSON (Program.cs)

O código no ficheiro Program.cs é modificado para fornecer suporte à geração de código-fonte de serialização JSON.

O seguinte excerto mostra as alterações ao código:

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 não modificares o código, System.Text.Json usa reflexão para serializar e desserializar JSON. A reflexão não é suportada em Native AOT.

Para mais informações, consulte:

Alterações de código para o perfil de lançamento (launchSettings.json)

O modelo Web API (Native AOT) cria um ficheirolaunchSettings.json . Em contraste com um ficheiro de lançamento padrão, o ficheiro gerado não inclui a iisSettings secção nem o IIS Express perfil.

O seguinte excerto mostra as secções excluídas (colorido a vermelho):

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

O CreateSlimBuilder() exigia padrões mínimos de aplicação

O template Web API (Native AOT) utiliza o método CreateSlimBuilder() em vez do método CreateBuilder().

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

O método CreateSlimBuilder inicializa o WebApplicationBuilder com o mínimo de recursos ASP.NET Core necessários para executar um aplicativo.

Como descrito anteriormente, o CreateSlimBuilder método não inclui suporte para HTTPS ou HTTP/3. Esses protocolos normalmente não são necessários para aplicativos executados atrás de um proxy de terminação TLS. Por exemplo, consulte terminação de TLS e TLS fim a fim com o Application Gateway. Podes ativar o HTTPS chamando o método construtor.WebHost.UseKestrelHttpsConfiguration, ou ativar o HTTP/3 chamando o método construtor.WebHost.UseQuic.

Compare CreateSlimBuilder() e CreateBuilder()

O CreateSlimBuilder método proporciona acesso a uma parte das funcionalidades da aplicação disponíveis com o CreateBuilder método. Como descrito anteriormente, o template da API Web (Native AOT) chama CreateSlimBuilder para inicializar WebApplicationBuilder, pelo que o construtor utiliza as funcionalidades mínimas de ASP.NET Core necessárias para executar a aplicação.

Ambos os métodos fornecem as funcionalidades necessárias para uma experiência de desenvolvimento eficiente:

  • Configuração para o appsettings.json e appsettings.{ EnvironmentName}.json ficheiros
  • Configuração dos segredos de utilizador
  • Registo da consola
  • Configuração de registro em log

A inclusão de características mínimas tem benefícios para a otimização, assim como para o AOT. Para obter mais informações, consulte Reduzir implantações independentes e executáveis.

Se preferir usar um construtor que omite todas as funcionalidades, consulte o método WebApplication.CreateEmptyBuilder .

Funcionalidades indisponíveis no CreateSlimBuilder

O CreateSlimBuilder método não oferece as seguintes funcionalidades, que estão disponíveis em CreateBuilder:

Para informações mais detalhadas, consulte Comparar WebApplication.CreateBuilder com CreateSlimBuilder

Use geradores de código-fonte e evite reflexão

Durante o processo de publicação do AOT nativo, qualquer código não utilizado é cortado. Como resultado, uma aplicação não pode usar reflexão ilimitada em tempo de execução. Podes usar geradores de código-fonte que produzem código que evita a necessidade de reflexão. Em alguns casos, os geradores fonte geram código otimizado para AOT mesmo quando um gerador não é necessário.

  • Para visualizar o código-fonte gerado, adicione a propriedade EmitCompilerGeneratedFiles ao ficheiro do projeto da aplicação (.csproj):

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

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

</Project>

  • Para ver o código gerado, execute o dotnet build comando. O comando compila os ficheiros de origem e gera os ficheiros intermédios necessários para executar a aplicação num ambiente de desenvolvimento. A saída inclui um diretório obj/Debug/<.NET version>/generated/ que contém todos os ficheiros gerados para o projeto.

  • Para preparar a aplicação para a implementação, execute o dotnet publish comando. O comando compila os ficheiros de origem e gera todos os ficheiros necessários para implementar a aplicação. Passa os assemblies gerados para um compilador IL nativo, que produz o executável nativo. O executável nativo contém o código da máquina nativa.

Usar bibliotecas com AOT nativo

Muitas bibliotecas populares usadas em projetos ASP.NET Core apresentam atualmente alguns problemas de compatibilidade quando incorporadas em projetos que visam o AOT nativo, tais como:

  • Usar reflexão para inspecionar e descobrir tipos
  • Carregamento condicional de bibliotecas em tempo de execução
  • Gerar código em tempo real para implementar funcionalidades

As bibliotecas que utilizam estas funcionalidades dinâmicas necessitam de atualizações para funcionar com o AOT nativo. Existem várias ferramentas disponíveis para aplicar as atualizações necessárias, como geradores de fonte Roslyn.

Os autores de bibliotecas que pretendam apoiar o AOT nativo são encorajados a rever os seguintes artigos:

Trabalhar com as APIs mínimas e dados JSON

O framework da API Minimal é otimizado para receber e devolver cargas úteis JSON usando o System.Text.Json.

Todos os tipos transmitidos como parte do corpo HTTP ou devolvidos por delegados de pedidos nas aplicações Minimal APIs devem ser configurados na instância JsonSerializerContext. A instância deve ser registada com a injeção de dependência do 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
{
}

  • O contexto do serializador JSON é registado com o container DI. Para mais informações, consulte Combine Source Generators e o TypeInfoResolverChain.

  • O tipo personalizado JsonSerializerContext é anotado com o atributo JsonSerializable, que permite o código de serializador JSON gerado a partir do código fonte para o tipo ToDo.

Um parâmetro no delegado que não está ligado ao corpo não precisa de ser serializável. Por exemplo, um parâmetro de cadeia de consulta pode ser um tipo de objeto rico que 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.

Rever problemas conhecidos

Para reportar ou rever problemas com o suporte nativo de AOT em ASP.NET Core, consulte GitHub /dotnet/core/issues #8288).

Conteúdo relacionado

O .NET 8 introduz suporte para AOT (ahead-of-time) nativo do .NET.

Por que usar AOT nativo com ASP.NET Core

Publicar e implantar um aplicativo AOT nativo oferece os seguintes benefícios:

  • Minimized disk footprint: Ao publicar usando AOT nativo, é produzido um único executável que contém apenas o código das dependências externas necessário para suportar o programa. O tamanho reduzido do executável pode levar a:
    • Imagens de contentor mais pequenas, por exemplo, em cenários de implantação em contentores.
    • Tempo de implantação reduzido a partir de imagens menores.
  • Tempo de inicialização reduzido: Os aplicativos AOT nativos podem mostrar tempos de inicialização reduzidos, o que significa
    • O aplicativo está pronto para atender solicitações mais rapidamente.
    • Implantação aprimorada em que os orquestradores de contêineres precisam gerenciar a transição de uma versão do aplicativo para outra.
  • Demanda de memória reduzida: Os aplicativos AOT nativos podem ter demandas de memória reduzidas, dependendo do trabalho feito pelo aplicativo. O consumo reduzido de memória pode levar a uma maior densidade de implantação e melhor escalabilidade.

O aplicativo de modelo foi executado em nosso laboratório de benchmarking para comparar o desempenho de um aplicativo publicado pela AOT, um aplicativo de tempo de execução cortado e um aplicativo de tempo de execução não cortado. O gráfico a seguir mostra os resultados do benchmarking:

Gráfico mostrando a comparação do tamanho do aplicativo, uso de memória e métricas de tempo de inicialização de um aplicativo publicado pela AOT, um aplicativo de tempo de execução cortado e um aplicativo de tempo de execução não cortado.

O gráfico anterior mostra que a AOT nativa tem menor tamanho de aplicativo, uso de memória e tempo de inicialização.

Compatibilidade do ASP.NET Core com AOT nativo

Nem todos os recursos do ASP.NET Core são atualmente compatíveis com a AOT nativa. A tabela a seguir resume a compatibilidade de recursos do ASP.NET Core com o AOT Nativo:

Funcionalidade Totalmente suportado Parcialmente suportado Não suportado
gRPC ✔️
APIs mínimas ✔️
MVC
Blazor Server
SignalR
Autenticação JWT ✔️
Outra autenticação
CORS ✔️
Verificações de saúde ✔️
Registo HTTP ✔️
Localização ✔️
OutputCaching ✔️
Limitação de Taxa ✔️
PedidoDescompressão ✔️
Cache de Respostas ✔️
CompressãoDeResposta ✔️
Reescrever ✔️
Sessão
Termas
Arquivos Estáticos ✔️
WebSockets ✔️

Para obter mais informações sobre limitações, consulte:

É importante testar um aplicativo completamente ao mudar para um modelo de implantação AOT nativo. O aplicativo compilado pela AOT deve ser testado para garantir que a funcionalidade não sofreu alterações em relação ao aplicativo sem otimização e compilado em JIT. Ao criar o aplicativo, revise e corrija os avisos da AOT. Uma aplicação que emite avisos de AOT durante a publicação pode não funcionar corretamente. Se não forem emitidos avisos de AOT no momento da publicação, a aplicação AOT publicada deverá funcionar da mesma forma que a aplicação não otimizada e compilada em JIT.

Publicação AOT nativa

O Native AOT é habilitado com a propriedade PublishAot MSBuild. O exemplo a seguir mostra como habilitar o AOT nativo em um arquivo de projeto:

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

Essa configuração permite a compilação AOT nativa durante a publicação e permite a análise dinâmica do uso de código durante a compilação e edição. Um projeto que usa a publicação AOT nativa usa a compilação JIT quando executado localmente. Um aplicativo AOT tem as seguintes diferenças de um aplicativo compilado por JIT:

  • Os recursos que não são compatíveis com o AOT nativo são desativados e lançam exceções em tempo de execução.
  • Um analisador de código-fonte está habilitado para destacar o código que não é compatível com o AOT nativo. No momento da publicação, todo o aplicativo, incluindo os pacotes NuGet, é analisado quanto à compatibilidade novamente.

A análise AOT nativa inclui todo o código do aplicativo e as bibliotecas das quais o aplicativo depende. Revise os avisos de AOT nativos e tome medidas corretivas. É uma boa ideia publicar aplicativos com frequência para descobrir problemas no início do ciclo de vida do desenvolvimento.

No .NET 8, a AOT nativa é suportada pelos seguintes tipos de aplicativo ASP.NET Core:

  • APIs mínimas - Para mais informações, consulte a secção do template "The Web API (Native AOT)" mais adiante neste artigo.
  • gRPC - Para mais informações, consulte gRPC e AOT Nativo.
  • Serviços de trabalhador - Para obter mais informações, consulte AOT em Modelos de serviço de trabalhador.

O modelo de API da Web (AOT nativa)

O modelo ASP.NET Core Web API (Native AOT) (nome abreviado webapiaot) cria um projeto com AOT ativado. O modelo difere da API Web modelo de projeto das seguintes maneiras:

  • Usa apenas APIs mínimas, pois o MVC ainda não é compatível com o AOT nativo.
  • Usa a API CreateSlimBuilder() para garantir que apenas os recursos essenciais sejam habilitados por padrão, minimizando o tamanho implantado do aplicativo.
  • Está configurado para escutar somente em HTTP, pois o tráfego HTTPS é normalmente tratado por um serviço de entrada em implantações nativas da nuvem.
  • Não inclui um perfil de inicialização para execução no IIS ou IIS Express.
  • Cria um ficheiro .http configurado com solicitações HTTP de exemplo que podem ser enviadas para os endpoints da aplicação.
  • Inclui uma amostra Todo API em vez da amostra de previsão do tempo.
  • Adiciona PublishAot ao arquivo de projeto, conforme mostrado anteriormente neste artigo.
  • Habilita os geradores de código-fonte do serializador JSON . O gerador de código-fonte é usado para gerar código de serialização em tempo de compilação, o que é necessário para a compilação AOT nativa.

Alterações para dar suporte à geração de código-fonte

O exemplo a seguir mostra o código adicionado ao arquivo Program.cs para dar suporte à geração de origem de serialização 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
+{
+
+}

Sem esse código adicionado, System.Text.Json usa reflexão para serializar e desserializar JSON. A reflexão não é suportada em Native AOT.

Para mais informações, consulte:

Alterações ao launchSettings.json

O arquivo criado pelo modelo de da API Web (AOT nativa) tem a seção e o perfil removidos:

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

O método CreateSlimBuilder

O modelo usa o método CreateSlimBuilder() em vez do método CreateBuilder().

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

O método CreateSlimBuilder inicializa o WebApplicationBuilder com o mínimo de recursos ASP.NET Core necessários para executar um aplicativo.

Como observado anteriormente, o método CreateSlimBuilder não inclui suporte para HTTPS ou HTTP/3. Esses protocolos normalmente não são necessários para aplicativos executados atrás de um proxy de terminação TLS. Por exemplo, consulte terminação de TLS e TLS fim a fim com o Application Gateway. O HTTPS pode ser ativado ao invocar construtor.WebHost.UseKestrelHttpsConfiguration. O HTTP/3 pode ser ativado ao invocar construtor.WebHost.UseQuic.

CreateSlimBuilder vs CreateBuilder

O método CreateSlimBuilder não suporta os seguintes recursos que são suportados pelo método CreateBuilder:

O método CreateSlimBuilder inclui os seguintes recursos necessários para uma experiência de desenvolvimento eficiente:

  • Configuração do arquivo JSON para appsettings.json e appsettings.{EnvironmentName}.json.
  • Configuração de segredos do usuário.
  • Registo de consola.
  • Configuração de registo.

Para um construtor que omite as funcionalidades anteriores, consulte o método CreateEmptyBuilder.

A inclusão de características mínimas tem benefícios para a otimização, assim como para o AOT. Para obter mais informações, consulte Reduzir implantações independentes e executáveis.

Para obter informações mais detalhadas, consulte Comparando WebApplication.CreateBuilder com CreateSlimBuilder

Geradores de origem

Como o código não utilizado é cortado durante a publicação para AOT nativo, o aplicativo não pode usar reflexão ilimitada em tempo de execução. Geradores de código-fonte são usados para produzir código que evita a necessidade de reflexão. Em alguns casos, os geradores de código-fonte produzem código otimizado para AOT, mesmo quando um gerador não é necessário.

Para exibir o código-fonte gerado, adicione a propriedade EmitCompilerGeneratedFiles ao arquivo .csproj de um aplicativo, conforme mostrado no exemplo a seguir:

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

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

</Project>

Execute o comando dotnet build para ver o código gerado. A saída inclui um diretório obj/Debug/net8.0/generated/ que contém todos os arquivos gerados para o projeto.

O comando dotnet publish também compila os arquivos de origem e gera arquivos que são compilados. Além disso, dotnet publish passa os assemblies gerados para um compilador IL nativo. O compilador IL produz o executável nativo. O executável nativo contém o código da máquina nativa.

Usar bibliotecas com AOT nativo

Muitas bibliotecas populares usadas em projetos ASP.NET Core apresentam atualmente alguns problemas de compatibilidade quando incorporadas em projetos que visam o AOT nativo, tais como:

  • Usar reflexão para inspecionar e descobrir tipos
  • Carregamento condicional de bibliotecas em tempo de execução
  • Gerar código em tempo real para implementar funcionalidades

As bibliotecas que utilizam estas funcionalidades dinâmicas necessitam de atualizações para funcionar com o AOT nativo. Existem várias ferramentas disponíveis para aplicar as atualizações necessárias, como geradores de fonte Roslyn.

Os autores de bibliotecas que pretendam apoiar o AOT nativo são encorajados a rever os seguintes artigos:

APIs mínimas e cargas úteis JSON

A API Mínima é otimizada para receber e retornar dados JSON usando System.Text.Json. System.Text.Json:

  • Impõe requisitos de compatibilidade para JSON e AOT nativo.
  • Requer o uso do gerador de fonte System.Text.Json.

Todos os tipos transmitidos como parte do corpo HTTP ou retornados de delegados de solicitação em aplicativos de APIs mínimas devem ser configurados em um JsonSerializerContext registrado por meio da injeção de dependência do 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
{
}

No código destacado anterior:

Um parâmetro no delegado que não está vinculado ao corpo e não precisa ser serializável. Por exemplo, um parâmetro de cadeia de caracteres de consulta que é um tipo de objeto avançado 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.

Problemas conhecidos

Consulte este problema do GitHub para relatar ou revisar problemas com o suporte nativo de AOT no ASP.NET Core.

Ver também

  • Last updated on