Yerel AOT için ASP.NET Core desteği

Tarafından Mitch Denny

ASP.NET Core'de Yerel uygulamaları önceden yayımlama ve dağıtma (AOT) çeşitli avantajlar sunar:

• Küçültülmüş disk alanı. Yerel AOT kullanarak bir uygulama yayımladığınızda, işlem tek bir yürütülebilir dosya oluşturur. Yürütülebilir dosya yalnızca uygulamayı desteklemek için gereken dış bağımlılıklardan gelen kodu içerir. Azaltılmış yürütülebilir boyut aşağıdakilere yol açabilir:

  • Konteynerli dağıtım senaryolarında kullanılan daha küçük konteyner görüntüleri.
  • Daha kısa dağıtım süresi, daha küçük görüntülerden kaynaklanır.

• Başlangıç süresi kısaltıldı. Yerel AOT uygulamaları daha az başlangıç süresi gerektirebilir ve bu da şunları sağlar:

  • İstekleri daha hızlı karşılamak için uygulama.
  • Kapsayıcı düzenleyicilerinin bir uygulama sürümünden diğerine geçişi yönettiği geliştirilmiş dağıtım.

• Bellek talebi azaldı. Yerel AOT uygulamaları, uygulama tarafından yapılan çalışmaya bağlı olarak daha az bellek gerektirebilir. Azaltılmış bellek tüketimi, daha fazla dağıtım yoğunluğuna ve geliştirilmiş ölçeklenebilirliğe yol açabilir.

Aşağıdaki grafikte, çeşitli şablon uygulamalarındaki bir karşılaştırma testinin sonuçları gösterilmektedir. Karşılaştırma, AOT yayımlanmış bir uygulamanın (turuncu çubuk), kırpılmış çalışma zamanı uygulamasının (yeşil çubuk) ve denenmemiş çalışma zamanı uygulamasının (sarı çubuk) performansını karşılaştırır. Testte Yerel AOT uygulamasının daha düşük uygulama boyutu, bellek kullanımı ve başlangıç süresi gösterdiği ortaya çıktı.

Bu makalede, yayımlama ve dağıtıma genel bakış da dahil olmak üzere ASP.NET Core Yerel AOT uygulamaları desteği açıklanmaktadır.

Bu makaledeki yönergelere ek yapan veya onları yerine geçen ASP.NET Core Blazor WebAssembly Yerel AOT kılavuzu için bkz. ASP.NET Core Blazor WebAssembly derleme araçları ve ileri zamanlı derleme.

ASP.NET Core ve Yerel AOT uyumluluğunu gözden geçirme

ASP.NET Core'daki tüm özellikler şu anda Yerel AOT ile uyumlu değildir.

Aşağıdaki tabloda Yerel AOT ile ASP.NET Core özellik uyumluluğu özetlenmektedir.

Özellik	Destekleniyor	Kısmi destek	Desteklenmiyor
Blazor Server			❌
Kaynaklar Arası Paylaşım (CORS)	✔️
gRPC	✔️
Sağlık Kontrolleri	✔️
HttpLogging	✔️
JWT Kimlik doğrulama	✔️
Yerelleştirme	✔️
Minimal API'ler		✔️
MVC			❌
OData			❌
Diğer Kimlik Doğrulaması			❌
Çıktı Önbellekleme	✔️
Hız Sınırlama	✔️
İstekSıkıştırmayıGeriAlma	✔️
Yanıt Önbellekleme	✔️
YanıtSıkıştırma	✔️
Yeniden Yaz	✔️
Oturum			❌
SignalR		✔️
Kaplıca			❌
StaticFiles	✔️
WebSockets Protokolü	✔️

Sınırlamalar hakkında daha fazla bilgi için bkz:

• Yerel AOT dağıtımının sınırlamaları
• AOT uyarıları
• Bilinen kırpma uyumsuzlukları
• Kırpma uyarılarını düzeltme

Yerel AOT dağıtım modelinde uygulamayı doğrulama

Yerel AOT dağıtım modeline geçtiğiniz zaman uygulamayı kapsamlı bir şekilde test etmek önemlidir. AOT tarafından dağıtılan uygulamayı test edin ve işlevselliğin sıkıştırılmamış ve anında (JIT) derlenen uygulamadan değişmediğini onaylayın.

Uygulamayı oluştururken AOT uyarılarını gözden geçirin ve düzeltin. Yayımlama sırasında AOT uyarıları veren bir uygulama düzgün çalışmayabilir. Yayımlama zamanında hiçbir AOT uyarısı verilmediyse, yayımlanan AOT uygulamasının denenmeyen ve JIT ile derlenmiş uygulamayla aynı şekilde çalışmasını bekleyebilirsiniz.

Yerel AOT uygulaması yayımlama (PublishAot)

MSBuild özelliğini kullanarak uygulamanız için Yerel AOT'yi PublishAot etkinleştirin. Aşağıdaki örnekte proje dosyasında Yerel AOT'nin nasıl etkinleştirileceği gösterilmektedir:

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

PublishAot özelliği, yayımlama işlemi sırasında Yerel AOT derlemesini etkinleştirir ve derleme ve düzenleme sırasında dinamik kod kullanım analizini etkinleştirir. Yerel AOT yayımlama kullanan bir proje, yerel olarak çalıştırıldığında JIT derlemesi uygular.

AOT uygulaması, JIT ile derlenmiş bir uygulamadan aşağıdaki farklara sahiptir:

• Yerel AOT ile uyumlu olmayan özellikler devre dışı bırakılır ve çalışma anında istisnalar fırlatır.
• Yerel AOT ile uyumlu olmayan kodu vurgulamak için bir kaynak çözümleyici etkinleştirilir. Yayımlama zamanında NuGet paketleri de dahil olmak üzere uygulamanın tamamı uyumluluk açısından yeniden analiz edilir.

Yerel AOT analizi tüm uygulama kodunu ve uygulamanın bağımlı olduğu kitaplıkları içerir. Yerel AOT uyarılarını gözden geçirin ve düzeltici adımları uygulayın. Geliştirme yaşam döngüsünün başlarındaki sorunları keşfetmek için uygulamaları sık sık yayımlamak iyi bir fikirdir.

.NET 8 ve sonraki sürümlerde, aşağıdaki ASP.NET Core uygulama türleri Yerel AOT'yi destekler:

• Minimum API'ler - Daha fazla bilgi için bu makalenin devamında Web API'sini (Yerel AOT) gözden geçirme bölümüne bakın.
• gRPC - Daha fazla bilgi için bkz. gRPC ve Yerel AOT.
• Worker services - Daha fazla bilgi için bkz. ASP.NET Core Native AOT içinde barındırılan hizmetler ile Arka Plan Görevleri.

Web API (Yerel AOT) şablonunu gözden geçirin

ASP.NET Core Web API 'si (Yerel AOT) şablonu (kısa ad webapiaot) AOT etkin bir proje oluşturur. Şablon, aşağıdaki yollarla standart bir Web API'si proje şablonundan farklıdır:

• MVC henüz Yerel AOT ile uyumlu olmadığından sadece Minimal API'ler kullanır.
• Yalnızca temel özelliklerin CreateSlimBuilder() varsayılan olarak etkinleştirildiğinden emin olmak için API'yi kullanır ve bu da uygulamanın dağıtılan boyutunu en aza indirir.
• Yalnızca HTTP'de dinleyecek şekilde yapılandırılmıştır. HTTPS trafiği genellikle buluta özel dağıtımlarda giriş hizmeti tarafından işlenir.
• IIS veya IIS Express altında çalıştırmak için başlatma profili içermez.
• Uygulamanın uç noktalarına gönderilebilen örnek HTTP istekleriyle yapılandırılmış bir .http dosyası oluşturur.
• Hava durumu tahmini örneği yerine bir örnek Todo API içerir.
• PublishAot Özelliğini daha önce açıklandığı gibi proje dosyasına ekler.
• JSON seri hale getirici kaynak oluşturucularını etkinleştirir. Kaynak kod oluşturucu, Native AOT derlemesi için gerekli olan serileştirme kodunu derleme sırasında oluşturmak için kullanılır.

JSON serileştirme için kod güncelleştirmeleri (Program.cs)

Program.cs dosyasındaki kod, JSON serileştirme kaynağı oluşturma desteği sağlamak üzere değiştirilir.

Aşağıdaki kod parçacığı kodda yapılan değişiklikleri gösterir:

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

Kodu değiştirmezseniz, System.Text.Json JSON serileştirme ve seriden çıkarma için yansıma kullanır. Reflection Native AOT'de desteklenmez.

Daha fazla bilgi için bkz.

• Kaynak oluşturucuları birleştirme
• TypeInfoResolverChain

Başlatma profili için kod değişiklikleri (launchSettings.json)

Web API (Yerel AOT) şablonu bir launchSettings.json dosyası oluşturur. Standart başlatma dosyasının aksine, oluşturulan dosya iisSettings bölümünü veya IIS Express profilini içermez.

Aşağıdaki kod parçacığı, dışlanan bölümleri (kırmızı renkli) gösterir:

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

Minimum uygulama varsayılanları için CreateSlimBuilder() çağrıldı

Web API'si CreateSlimBuilder() şablonu yöntemi yerine CreateBuilder() yöntemini kullanır.

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 yöntemi, WebApplicationBuilder, bir uygulamayı çalıştırmak için gerekli olan minimum ASP.NET Core özellikleriyle başlatır.

Daha önce açıklandığı gibi, CreateSlimBuilder yöntemi HTTPS veya HTTP/3 desteğini içermez. Bu protokoller genellikle TLS sonlandırma ara sunucusunun arkasında çalışan uygulamalar için gerekli değildir. Örneğin, Application Gateway ile TLS sonlandırma ve uçtan uca TLS örneğine bakın. HTTPS'yi, builder.WebHost.UseKestrelHttpsConfiguration yöntemini çağırarak etkinleştirebilirsiniz veya HTTP/3'ü builder.WebHost.UseQuic yöntemini çağırarak etkinleştirin.

CreateSlimBuilder() ve CreateBuilder() karşılaştırması

CreateSlimBuilder yöntemi, CreateBuilder yöntemiyle kullanılabilen uygulama özelliklerinin bir bölümüne erişim sağlar. Daha önce açıklandığı gibi, Web API (Yerel AOT) şablonu CreateSlimBuilder başlatmak için WebApplicationBuilder çağırır, böylece oluşturucu uygulamayı çalıştırmak için gereken en düşük ASP.NET Core özelliklerini kullanır.

Her iki yöntem de verimli bir geliştirme deneyimi için gerekli özellikleri sağlar:

• appsettings.json ve uygulama ayarları için yapılandırma.{ EnvironmentName}.json dosyaları
• Kullanıcı gizli bilgileri yapılandırması
• Konsol loglama
• Günlük ayarları

Minimum özelliklerin dahil edilmesi, kırpma işlemi ve AOT için yarar sağlar. Daha fazla bilgi için Bağımsız dağıtımları ve yürütülebilir dosyaları kırpma bölümüne bakın.

Tüm özellikleri atlayan bir oluşturucu kullanmayı tercih ediyorsanız Bkz. WebApplication.CreateEmptyBuilder yöntemi.

CreateSlimBuilder'da kullanılamayan özellikler

CreateSlimBuilder yöntemi, içinde kullanılabilen aşağıdaki özellikleri CreateBuilder:

• Başlangıç bütünleştirilmiş kodlarını barındırma
• UseStartup yöntemi
• Günlüğe kaydetme sağlayıcıları:
  • Windows EventLog
  • Hata Ayıklama
  • EventSource
• Web barındırma özellikleri:
  • UseStaticWebAssets yöntemi
  • IIS tümleştirmesi
• Kestrel Yapılandırma:
  • HTTPS uç noktaları
  • QUIC (HTTP/3)
• Regex ve yönlendirmede kullanılan alfa kısıtlamaları (GitHub /dotnet/aspnetcore/issues #46142)

Daha ayrıntılı bilgi için bkz. WebApplication.CreateBuilder ile CreateSlimBuilder karşılaştırması

Kaynak oluşturucuları kullanma ve yansımayı önleme

Native AOT için yayımlama işlemi sırasında kullanılmayan tüm kodlar kırpılır. Sonuç olarak, bir uygulama çalışma zamanında ilişkisiz yansıma kullanamaz. Yansıma gereksinimini önleyen kod üreten kaynak oluşturucuları kullanabilirsiniz. Bazı durumlarda, bir oluşturucu gerekli olmadığında bile kaynak oluşturucular AOT için iyileştirilmiş çıkış kodu oluşturur.

• Oluşturulan kaynak kodu görüntülemek için EmitCompilerGeneratedFiles özelliğini uygulama projesi (.csproj) dosyasına ekleyin:

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

• Oluşturulan kodu görmek için komutunu çalıştırın dotnet build . komutu kaynak dosyaları derler ve uygulamayı geliştirme ortamında çalıştırmak için gereken ara dosyaları oluşturur. Çıktı, proje için oluşturulan tüm dosyaları içeren bir obj/Debug/<.NET sürümü>/generated/ dizini içerir.

• Uygulamayı dağıtıma hazırlamak için komutunu çalıştırın dotnet publish . komutu kaynak dosyaları derler ve uygulamayı dağıtmak için gereken tüm dosyaları oluşturur. Oluşturulan derlemeleri yerel yürütülebilir dosyayı üreten yerel bir IL derleyicisine geçirir. Yerel yürütülebilir dosya yerel makine kodunu içerir.

Yerel AOT ile kitaplıkları kullanma

ASP.NET Core projelerinde kullanılan birçok popüler kitaplık şu anda Yerel AOT'yi hedefleyen projelere dahil edildiğinde bazı uyumluluk sorunlarına sahiptir, örneğin:

• Türleri incelemek ve bulmak için yansıma kullanma
• Kitaplıkları çalışma zamanında koşullu olarak yükleme
• İşlevselliği uygulamak için anında kod oluşturma

Bu dinamik özellikleri kullanan kitaplıkların Yerel AOT ile çalışması için güncelleştirmeler gerekir. Roslyn kaynak oluşturucuları gibi gerekli güncelleştirmeleri uygulamak için çeşitli araçlar mevcuttur.

Yerel AOT'yi desteklemeyi umut eden kitaplık yazarlarının aşağıdaki makaleleri gözden geçirmesi teşvik edilir:

• Yerel AOT dağıtımı
• .NET kitaplıklarını kırpmaya hazırlayın

Minimum API'ler ve JSON yükleriyle çalışma

Minimal API çerçevesi, JSON yüklerini almak ve döndürmek için System.Text.Json kullanılarak optimize edilmiştir.

• Ad alanı JSON ve Yerel AOT için uyumluluk gereksinimleri uygular.
• System.Text.Json kaynak oluşturucunun kullanılmasını gerektirir.

HTTP gövdesinin bir parçası olarak iletilen veya Minimal API uygulamalarındaki istek temsilcilerinden döndürülen tüm türler, bir JsonSerializerContext örneğinde yapılandırılmalıdır. ASP.NET Core bağımlılık enjeksiyonu ile örneğin kaydedilmesi gerekir.

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 seri hale getirici bağlamı DI kapsayıcısıyla kaydedilir. Daha fazla bilgi için bkz Kaynak oluşturucularını birleştirme ve TypeInfoResolverChain.

• Özel JsonSerializerContext, türü için kaynak tarafından üretilen JSON seri hale getirici kodunu etkinleştiren ToDo özniteliği ile açıklanır.

Temsilcide gövdeye bağlı olmayan bir parametrenin serileştirilebilir olması gerekmez. Örneğin, sorgu dizesi parametresi uygulayan IParsable<T>zengin bir nesne türü olabilir.

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.

Bilinen sorunları gözden geçirme

ASP.NET Core'da Yerel AOT desteğiyle ilgili sorunları bildirmek veya gözden geçirmek için bkz. GitHub /dotnet/core/issues #8288).

İlgili içerik

• > Native AOT
• Yerel AOT dağıtımı
• AOT dağıtımlarını iyileştirme