Поддержка ASP.NET Core для нативного AOT

Митч Денни

Публикация и развертывание Native приложений в режиме предварительной компиляции (AOT) в ASP.NET Core предлагает несколько преимуществ:

• Минимизированный объем занимаемого дискового пространства. При публикации приложения с помощью Native AOT процесс создает один исполняемый файл. Исполняемый файл содержит только код из внешних зависимостей, необходимых для поддержки приложения. Уменьшенный размер исполняемого файла может привести к следующим:

  • Небольшие образы контейнеров, например в сценариях контейнерного развертывания.
  • Сокращение времени развертывания благодаря меньшим образам.

• Сокращено время запуска. Для собственных приложений AOT может потребоваться меньше времени запуска, что позволяет:

  • Приложение для более быстрой обработки заявок.
  • Улучшено развертывание, в котором оркестраторы контейнеров управляют переходом из одной версии приложения в другую.

• Сокращение спроса на память. Собственные приложения AOT могут требовать меньше памяти в зависимости от работы, выполняемой приложением. Снижение потребления памяти может привести к повышению плотности развертывания и повышению масштабируемости.

На следующей диаграмме показаны результаты теста бенчмаркинга различных шаблонных приложений. Эталонный тест сравнивает производительность для опубликованного приложения AOT (оранжевая полоса), усеченного приложения среды выполнения (зеленая полоса) и необрезанного приложения среды выполнения (желтая полоса). Тест показал, что приложение Native AOT демонстрирует более низкий размер приложения, использование памяти и время запуска.

В этой статье описывается поддержка собственных приложений AOT в ASP.NET Core, включая обзор публикации и развертывания.

Инструкции по ASP.NET Core Blazor WebAssembly Native AOT, которые дополняют или заменяют инструкции, приведенные в этой статье, см. в разделе ASP.NET Core Blazor WebAssembly средства сборки и предварительной компиляции (AOT).

Рассмотрение совместимости ASP.NET Core и Native AOT

В настоящее время не все функции в ASP.NET Core совместимы с Native AOT.

В следующей таблице представлена сводка совместимости функций ASP.NET Core с нативной AOT.

Функция	Поддерживается	Частичная поддержка	Не поддерживаются
Blazor Server			❌
CORS (Совместное использование ресурсов разных источников)	✔️
gRPC;	✔️
HealthChecks	✔️
логирование HTTP	✔️
Проверка подлинности JWT	✔️
Локализация	✔️
Минимальные API		✔️
MVC			❌
Другая проверка подлинности			❌
Кэширование выходных данных	✔️
Ограничение Скорости	✔️
ЗапросРазархивирования	✔️
Кэширование ответов	✔️
Сжатие ответа	✔️
Переписать	✔️
Сеанс			❌
SignalR		✔️
Спа			❌
StaticFiles	✔️
ВебСокеты	✔️

Дополнительные сведения об ограничениях см. в следующем разделе:

• Ограничения развертывания Native AOT
• Предупреждения AOT
• Известные несовместимости тримминга
• Устранение предупреждений о тримминге

Проверка приложения в модели развертывания Native AOT

При переходе к нативной модели развертывания AOT важно тщательно протестировать приложение. Тестируйте развернутое приложение AOT и подтверждайте, что функциональность не изменилась по сравнению с нетриммированной и JIT-собранной версией приложения.

При создании приложения просмотрите и исправьте все предупреждения AOT. Приложение, которое выдает предупреждения AOT при публикации, может работать неправильно. Если предупреждения AOT не выдаются во время публикации, вы можете ожидать, что опубликованное приложение AOT будет работать так же, как необрезанное и скомпилированное с JIT приложение.

Публикация собственного приложения AOT (PublishAot)

Включите Native AOT для вашего приложения, используя свойство PublishAot MSBuild. В следующем примере показано, как включить Native AOT в файле проекта:

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

Свойство PublishAot включает компиляцию Native AOT во время процесса публикации и обеспечивает динамический анализ использования кода во время сборки и редактирования. Проект, использующий публикацию Native AOT, выполняет JIT-компиляцию при запуске на локальной машине.

Приложение AOT имеет следующие отличия от скомпилированного JIT-приложения:

• Особенности, несовместимые с Native AOT, отключены и вызывают исключения при выполнении.
• Исходный анализатор включен для выделения кода, несовместимого с национальным AOT. Во время публикации все приложение, включая пакеты NuGet, анализируется повторно для совместимости.

Анализ с использованием Native AOT включает весь код приложения и библиотеки, от которых зависит приложение. Просмотрите предупреждения Native AOT и выполните действия по исправлению. Рекомендуется часто публиковать приложения для обнаружения проблем в начале жизненного цикла разработки.

В .NET 8 и более поздних версиях следующие типы приложений ASP.NET Core поддерживают собственный AOT:

• Минимальные API . Дополнительные сведения см. в разделе "Обзор шаблона веб-API (Native AOT) далее в этой статье.
• gRPC — дополнительные сведения см. в разделе gRPC и Native AOT.
• Службы Worker. Для получения дополнительной информации см. статью Фоновые задачи с размещенными службами в ASP.NET Core> Native AOT.

Обзор шаблона веб-API (нативный AOT)

Шаблон ASP.NET Core Web API (Native AOT) (короткое имя webapiaot) создает проект с включенным AOT. Шаблон отличается от стандартного шаблона проекта веб-API следующим образом:

• Использует только минимальные API, так как MVC еще не совместим с Native AOT.
• CreateSlimBuilder() Использует API для обеспечения включения только основных функций по умолчанию, что позволяет свести к минимуму размер развернутого приложения.
• Настроено для прослушивания только на протоколе HTTP. Трафик HTTPS обычно обрабатывается службой входящего трафика в облачных развертываниях.
• Не включает профиль запуска для работы в IIS или IIS Express.
• Создает HTTP-файл , настроенный с примерами HTTP-запросов, которые можно отправлять в конечные точки приложения.
• Включает пример Todo API вместо примера прогноза погоды.
• Добавляет свойство PublishAot в файл проекта, как описано ранее.
• Включает генераторы исходного кода JSON сериализатора. Генератор исходного кода используется для создания кода сериализации во время сборки, который требуется для компиляции Native AOT.

Обновления кода для сериализации JSON (Program.cs)

Код в файле Program.cs изменяется, чтобы обеспечить поддержку создания источника сериализации 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
+{
+
+}

Если вы не изменяете код, System.Text.Json использует отражение для сериализации и десериализации JSON. В системе Native AOT не поддерживается отражение.

Дополнительные сведения см. в разделе:

• Объединение генераторов источников
• TypeInfoResolverChain

Изменения кода для профиля запуска (launchSettings.json)

Шаблон веб-API (Native AOT) создает файлlaunchSettings.json . В отличие от стандартного файла запуска, созданный файл не включает iisSettings раздел или IIS Express профиль.

В следующем фрагменте кода показаны исключенные разделы (цветной красный):

{
  "$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() вызывается для минимальных настроек приложения по умолчанию

Шаблон веб-API (Native AOT) использует CreateSlimBuilder() метод вместо 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
{
}

Метод CreateSlimBuilder инициализирует WebApplicationBuilder с минимальными функциями ASP.NET Core, необходимыми для запуска приложения.

Как описано ранее, CreateSlimBuilder метод не включает поддержку HTTPS или HTTP/3. Обычно эти протоколы не требуются для приложений, работающих за прокси-сервером завершения TLS. Например, ознакомьтесь с терминацией TLS и сквозным TLS с Шлюзом приложений. Вы можете включить HTTPS, вызвав метод builder.WebHost.UseKestrelHttpsConfiguration, или включить HTTP/3, вызвав метод builder.WebHost.UseQuic.

Сравнение CreateSlimBuilder() и CreateBuilder()

Метод CreateSlimBuilder предоставляет доступ к части функций приложения, доступных с CreateBuilder методом. Как описано ранее, шаблон Web API (Native AOT) вызывает CreateSlimBuilder для инициализации WebApplicationBuilder, поэтому построитель использует минимальные ASP.NET Core функции, необходимые для запуска приложения.

Оба метода предоставляют необходимые функции для эффективной разработки:

• Настройка файлов appsettings.json и appsettings.{EnvironmentName}.json
• Конфигурация секретов пользователей
• Логирование консоли
• Конфигурация ведения журнала

Включение минимальных функций имеет преимущества как для оптимизации, так и для "Ahead-Of-Time" компиляции. Дополнительные сведения см. в статье Обрезка автономных развертываний и исполняемых файлов.

Если вы предпочитаете использовать построитель, который пропускает все функции, см. метод WebApplication.CreateEmptyBuilder .

Недоступные функции в CreateSlimBuilder

Метод CreateSlimBuilderне предоставляет следующие функции, которые доступны в CreateBuilder:

• Размещение начальных сборок
• Метод UseStartup
• Поставщики ведения журнала:
  • Журнал событий Windows
  • Отлаживать
  • EventSource
• Функции размещения веб-сайтов:
  • Метод UseStaticWebAssets
  • Интеграция IIS
• Kestrel Конфигурации:
  • Конечные точки HTTPS
  • QUIC (HTTP/3)
• Regex и альфа-ограничения, используемые в маршрутизации (GitHub /dotnet/aspnetcore/issues #46142)

Дополнительные сведения см. в статье "Сравнение WebApplication.CreateBuilder с CreateSlimBuilder"

Используйте генераторы кода и избегайте рефлексии

Во время процесса публикации для Native AOT все неиспользуемые коды обрезаются. В результате приложение не может использовать несвязанное отражение во время выполнения. Вы можете использовать генераторы источников , которые создают код, который позволяет избежать необходимости отражения. В некоторых случаях генераторы исходного кода создают оптимизированный для AOT код, даже если генератор не требуется.

• Чтобы просмотреть созданный исходный код, добавьте свойство EmitCompilerGeneratedFiles в файл проекта приложения (CSPROJ):

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

• Чтобы просмотреть созданный код, выполните dotnet build команду. Команда компилирует исходные файлы и создает промежуточные файлы, необходимые для запуска приложения в среде разработки. Выходные данные включают каталог obj/Debug/<.NET version>/generated/, содержащий все созданные файлы проекта.

• Чтобы подготовить приложение к развертыванию dotnet publish , выполните команду. Команда компилирует исходные файлы и создает все файлы, необходимые для развертывания приложения. Он передает созданные сборки собственному компилятору IL, который создает собственный исполняемый файл. Собственный исполняемый файл содержит машинный код.

Использование библиотек с Native AOT

Многие популярные библиотеки, используемые в проектах ASP.NET Core, в настоящее время имеют некоторые проблемы совместимости при их включении в проекты, предназначенные для собственного AOT, например:

• Использование отражения для проверки и обнаружения типов
• Условная загрузка библиотек во время выполнения
• Создание кода на лету для реализации функциональных возможностей

Библиотеки, использующие эти динамические функции, требуют обновления для работы с Native AOT. Различные средства доступны для применения необходимых обновлений, таких как генераторы источников Roslyn.

Авторам библиотек, желающим поддерживать нативный AOT, рекомендуется ознакомиться со следующими статьями.

• Нативное развертывание AOT
• Подготовка библиотек .NET для оптимизации

Работа с минимальными API и JSON-загрузками

Минимальный API фреймворк оптимизирован для получения и возврата пейлоадов JSON с помощью System.Text.Json.

• Пространство имен накладывает требования к совместимости для JSON и Native AOT.
• Для этого требуется использовать генератор источника System.Text.Json.

Все типы, передаваемые как часть текста HTTP или возвращенные делегатами запросов в приложениях на основе минимальных API, должны быть настроены на экземпляре JsonSerializerContext. Экземпляр должен быть зарегистрирован с помощью внедрения зависимостей 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
{
}

• Контекст сериализатора JSON регистрируется в контейнере DI. Дополнительные сведения см. в разделе "Объединение генераторов источников" и TypeInfoResolverChain.

• Настраиваемый JsonSerializerContext аннотирован атрибутом JsonSerializable, который позволяет генерировать исходный код сериализатора JSON для типа ToDo.

Параметр делегата, не привязанного к тексту, не должен быть сериализуемым. Например, параметр строки запроса может быть расширенным типом объектов, реализующим 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.

Просмотрите известные проблемы.

Чтобы сообщить о проблемах или ознакомиться с ними, связанных с поддержкой Native AOT в ASP.NET Core, обратитесь к GitHub /dotnet/core/issues #8288).

Связанный контент

• Опубликовать приложение ASP.NET Core с нативной AOT
• Нативное развертывание AOT
• Оптимизация развертываний AOT