dukungan ASP.NET Core untuk AOT Asli

Oleh Mitch Denny

ASP.NET Core 8.0 memperkenalkan dukungan untuk .NET native ahead-of-time (AOT).

Mengapa menggunakan Native AOT dengan ASP.NET Core

Menerbitkan dan menyebarkan aplikasi AOT Asli memberikan manfaat berikut:

• Jejak disk yang diminimalkan: Saat menerbitkan menggunakan Native AOT, satu executable diproduksi hanya berisi kode dari dependensi eksternal yang diperlukan untuk mendukung program. Pengurangan ukuran yang dapat dieksekusi dapat menyebabkan:
  • Gambar kontainer yang lebih kecil, misalnya dalam skenario penyebaran dalam kontainer.
  • Mengurangi waktu penyebaran dari gambar yang lebih kecil.
• Pengurangan waktu mulai: Aplikasi AOT asli dapat menunjukkan pengurangan waktu mulai, yang berarti
  • Aplikasi siap untuk melayani permintaan lebih cepat.
  • Penyebaran yang ditingkatkan di mana orkestrator kontainer perlu mengelola transisi dari satu versi aplikasi ke versi lainnya.
• Pengurangan permintaan memori: Aplikasi AOT asli dapat mengurangi permintaan memori, tergantung pada pekerjaan yang dilakukan oleh aplikasi. Pengurangan konsumsi memori dapat menyebabkan kepadatan penyebaran yang lebih besar dan peningkatan skalabilitas.

Aplikasi templat dijalankan di lab tolok ukur kami untuk membandingkan performa aplikasi yang diterbitkan AOT, aplikasi runtime yang dipangkas, dan aplikasi runtime yang tidak dipisahkan. Bagan berikut ini memperlihatkan hasil tolok ukur:

Bagan sebelumnya menunjukkan bahwa AOT Asli memiliki ukuran aplikasi, penggunaan memori, dan waktu mulai yang lebih rendah.

ASP.NET kompatibilitas AOT Inti dan Asli

Tidak semua fitur di ASP.NET Core saat ini kompatibel dengan AOT Asli. Tabel berikut ini meringkas kompatibilitas fitur ASP.NET Core dengan AOT Asli:

Fitur	Didukung Penuh	Didukung Sebagian	Tidak Didukung
gRPC	✔️Didukung penuh
Minimal API		✔️Didukung sebagian
MVC			❌Tidak didukung
Blazor Server			❌Tidak didukung
SignalR			❌Tidak didukung
Autentikasi JWT	✔️Didukung penuh
Autentikasi Lainnya			❌Tidak didukung
CORS	✔️Didukung penuh
Pemeriksaan Kesehatan	✔️Didukung penuh
HttpLogging	✔️Didukung penuh
Pelokalan	✔️Didukung penuh
OutputCaching	✔️Didukung penuh
RateLimiting	✔️Didukung penuh
RequestDecompression	✔️Didukung penuh
ResponseCaching	✔️Didukung penuh
ResponseCompression	✔️Didukung penuh
Menulis ulang	✔️Didukung penuh
Sesi			❌Tidak didukung
Spa			❌Tidak didukung
StaticFiles	✔️Didukung penuh
WebSockets	✔️Didukung penuh

Untuk informasi selengkapnya tentang batasan, lihat:

• Batasan penyebaran AOT Asli
• Pengantar peringatan AOT
• Ketidaksesuaian pemangkasan yang diketahui
• Pengantar peringatan pemangkasan
• Masalah GitHub dotnet/core #8288

Penting untuk menguji aplikasi secara menyeluruh saat pindah ke model penyebaran AOT Asli. Aplikasi yang disebarkan AOT harus diuji untuk memverifikasi fungsionalitas tidak berubah dari aplikasi yang dikompilasi JIT dan tidak dipicu. Saat membuat aplikasi, tinjau dan koreksi peringatan AOT. Aplikasi yang mengeluarkan peringatan AOT selama penerbitan mungkin tidak berfungsi dengan benar. Jika tidak ada peringatan AOT yang dikeluarkan pada waktu publikasi, aplikasi AOT yang diterbitkan harus berfungsi sama dengan aplikasi yang tidak di-kompilasi dan dikompilasi JIT.

Penerbitan AOT asli

AOT asli diaktifkan dengan PublishAot properti MSBuild. Contoh berikut menunjukkan cara mengaktifkan AOT Asli dalam file proyek:

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

Pengaturan ini memungkinkan kompilasi AOT Asli selama penerbitan dan memungkinkan analisis penggunaan kode dinamis selama build dan pengeditan. Proyek yang menggunakan penerbitan AOT Asli menggunakan kompilasi JIT saat berjalan secara lokal. Aplikasi AOT memiliki perbedaan berikut dari aplikasi yang dikompilasi JIT:

• Fitur yang tidak kompatibel dengan AOT Asli dinonaktifkan dan melemparkan pengecualian pada waktu proses.
• Penganalisis sumber diaktifkan untuk menyoroti kode yang tidak kompatibel dengan AOT Asli. Pada waktu publikasi, seluruh aplikasi, termasuk paket NuGet, dianalisis untuk kompatibilitas lagi.

Analisis AOT asli mencakup semua kode aplikasi dan pustaka yang bergantung pada aplikasi. Tinjau Peringatan AOT Asli dan ambil langkah-langkah korektif. Ada baiknya untuk sering menerbitkan aplikasi untuk menemukan masalah di awal siklus hidup pengembangan.

Di .NET 8, AOT Asli didukung oleh jenis aplikasi ASP.NET Core berikut:

• API minimal - Untuk informasi selengkapnya, lihat bagian templat API Web (AOT Asli) nanti di artikel ini.
• gRPC - Untuk informasi selengkapnya, lihat gRPC dan Native AOT.
• Layanan pekerja - Untuk informasi selengkapnya, lihat AOT di templat Layanan Pekerja.

Templat API Web (AOT Asli)

Templat ASP.NET Core Web API (Native AOT) (nama webapiaotpendek) membuat proyek dengan AOT diaktifkan. Templat berbeda dari templat proyek API Web dengan cara berikut:

• Hanya menggunakan API minimal, karena MVC belum kompatibel dengan AOT Asli.
• CreateSlimBuilder() Menggunakan API untuk memastikan hanya fitur penting yang diaktifkan secara default, meminimalkan ukuran aplikasi yang disebarkan.
• Dikonfigurasi untuk mendengarkan di HTTP saja, karena lalu lintas HTTPS biasanya ditangani oleh layanan ingress dalam penyebaran cloud-native.
• Tidak menyertakan profil peluncuran untuk berjalan di bawah IIS atau IIS Express.
• Membuat file yang dikonfigurasi .http dengan contoh permintaan HTTP yang dapat dikirim ke titik akhir aplikasi.
• Menyertakan sampel Todo API alih-alih sampel prakiraan cuaca.
• PublishAot Menambahkan ke file proyek, seperti yang ditunjukkan sebelumnya dalam artikel ini.
• Mengaktifkan generator sumber serializer JSON. Generator sumber digunakan untuk menghasilkan kode serialisasi pada waktu build, yang diperlukan untuk kompilasi AOT Asli.

Perubahan untuk mendukung pembuatan sumber

Contoh berikut menunjukkan kode yang ditambahkan ke Program.cs file untuk mendukung pembuatan sumber serialisasi 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
+{
+
+}

Tanpa kode tambahan ini, System.Text.Json menggunakan refleksi untuk menserialisasikan dan mendeserialisasi JSON. Refleksi tidak didukung di AOT Asli.

Untuk informasi selengkapnya, lihat:

• Menggabungkan generator sumber
• TypeInfoResolverChain

Perubahan pada launchSettings.json

File launchSettings.json yang dibuat oleh templat WEB API (Native AOT) memiliki iisSettings bagian dan IIS Express profil yang dihapus:

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

Metode CreateSlimBuilder

Templat menggunakan metode alih-alih CreateSlimBuilder() CreateBuilder() metode .

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
{

}

Metode ini CreateSlimBuilder menginisialisasi WebApplicationBuilder dengan fitur minimum ASP.NET Core yang diperlukan untuk menjalankan aplikasi.

Seperti disebutkan sebelumnya, CreateSlimBuilder metode ini tidak menyertakan dukungan untuk HTTPS atau HTTP/3. Protokol ini biasanya tidak diperlukan untuk aplikasi yang berjalan di belakang proksi penghentian TLS. Misalnya, lihat penghentian TLS dan TLS end to end dengan Application Gateway. HTTPS dapat diaktifkan dengan memanggil penyusun . WebHost.UseKestrelHttpsConfiguration HTTP/3 dapat diaktifkan dengan memanggil penyusun. WebHost.UseQuic.

CreateSlimBuilder vs CreateBuilder

Metode CreateSlimBuilder ini tidak mendukung fitur berikut yang didukung oleh CreateBuilder metode :

• Rakitan startup hosting
• UseStartup
• Penyedia pengelogan berikut:
  • Windows EventLog
  • Debug
  • Sumber Kejadian
• Fitur hosting web:
  • UseStaticWebAssets
  • Integrasi IIS
• Kestrel Konfigurasi
  • Titik akhir HTTPS di Kestrel
  • Quic (HTTP/3)
• Batasan regex dan alfa yang digunakan dalam perutean

Metode ini CreateSlimBuilder mencakup fitur-fitur berikut yang diperlukan untuk pengalaman pengembangan yang efisien:

• Konfigurasi file JSON untuk appsettings.json dan appsettings.{EnvironmentName}.json.
• Konfigurasi rahasia pengguna.
• Pengelogan konsol.
• Konfigurasi pengelogan.

Untuk penyusun yang menghilangkan fitur sebelumnya, lihat MetodeCreateEmptyBuilder.

Termasuk fitur minimal memiliki manfaat untuk pemangkasan serta AOT. Untuk informasi selengkapnya, lihat Memangkas penyebaran mandiri dan executable.

Untuk informasi selengkapnya, lihat Membandingkan WebApplication.CreateBuilder dengan CreateSlimBuilder

Generator sumber

Karena kode yang tidak digunakan dipangkas selama penerbitan untuk AOT Asli, aplikasi tidak dapat menggunakan pantulan yang tidak terbatas saat runtime. Generator sumber digunakan untuk menghasilkan kode yang menghindari kebutuhan akan pantulan. Dalam beberapa kasus, generator sumber menghasilkan kode yang dioptimalkan untuk AOT bahkan ketika generator tidak diperlukan.

Untuk melihat kode sumber yang dihasilkan, tambahkan EmitCompilerGeneratedFiles properti ke file aplikasi .csproj , seperti yang ditunjukkan dalam contoh berikut:

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

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

</Project>

Jalankan dotnet build perintah untuk melihat kode yang dihasilkan. Output mencakup obj/Debug/net8.0/generated/ direktori yang berisi semua file yang dihasilkan untuk proyek.

Perintah ini dotnet publish juga mengkompilasi file sumber dan menghasilkan file yang dikompilasi. Selain itu, dotnet publish meneruskan rakitan yang dihasilkan ke kompilator IL asli. Kompilator IL menghasilkan executable asli. Executable asli berisi kode mesin asli.

Pustaka dan AOT Asli

Banyak pustaka populer yang digunakan dalam proyek ASP.NET Core saat ini memiliki beberapa masalah kompatibilitas saat digunakan dalam proyek yang menargetkan AOT Asli, seperti:

• Penggunaan refleksi untuk memeriksa dan menemukan jenis.
• Memuat pustaka secara kondisional saat runtime.
• Membuat kode dengan cepat untuk mengimplementasikan fungsionalitas.

Pustaka yang menggunakan fitur dinamis ini perlu diperbarui untuk bekerja dengan AOT Asli. Mereka dapat diperbarui menggunakan alat seperti generator sumber Roslyn.

Penulis pustaka berharap untuk mendukung AOT Asli didorong untuk:

• Baca tentang persyaratan kompatibilitas AOT Asli.
• Siapkan pustaka untuk pemangkasan.

API minimal dan payload JSON

Kerangka kerja API Minimal dioptimalkan untuk menerima dan mengembalikan payload JSON menggunakan System.Text.Json. System.Text.Json:

• Memberlakukan persyaratan kompatibilitas untuk JSON dan Native AOT.
• Memerlukan penggunaan System.Text.Json generator sumber.

Semua jenis yang ditransmisikan sebagai bagian dari isi HTTP atau dikembalikan dari delegasi permintaan di aplikasi API Minimal harus dikonfigurasi pada JsonSerializerContext yang terdaftar melalui injeksi dependensi 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
{

}

Dalam kode yang disorot sebelumnya:

• Konteks serializer JSON terdaftar di kontainer DI. Untuk mengetahui informasi selengkapnya, silakan lihat:
  • Menggabungkan generator sumber
  • TypeInfoResolverChain
• Kustom JsonSerializerContext diannotasikan dengan [JsonSerializable] atribut untuk mengaktifkan kode serializer JSON yang dihasilkan sumber untuk jenis tersebut ToDo .

Parameter pada delegasi yang tidak terikat ke isi dan tidak perlu diserialisasikan. Misalnya, parameter string kueri yang merupakan jenis objek kaya dan mengimplementasikan 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.

Masalah umum

Lihat masalah GitHub ini untuk melaporkan atau meninjau masalah dengan dukungan AOT Asli di ASP.NET Core.

Lihat juga

• Tutorial: Menerbitkan aplikasi ASP.NET Core menggunakan AOT Asli
• Penyebaran AOT asli
• Mengoptimalkan penyebaran AOT
• Generator sumber pengikatan konfigurasi
• Menggunakan generator sumber pengikat konfigurasi
• Templat kompilasi API AOT minimal
• Membandingkan WebApplication.CreateBuilder dengan CreateSlimBuilder
• Menjelajahi generator sumber API minimal baru
• Mengganti panggilan metode dengan Interceptors
• Di belakang [LogProperties] dan generator sumber pengelogan telemetri baru