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

Tarafından Mitch Denny

ASP.NET Core 8.0, .NET yerel önceden (AOT) desteği sağlar.

ASP.NET Core ile Yerel AOT neden kullanılır?

Yerel AOT uygulamasını yayımlama ve dağıtma aşağıdaki avantajları sağlar:

• En aza indirgenmiş disk ayak izi: Yerel AOT kullanılarak yayımlanırken, yalnızca programı desteklemek için gereken dış bağımlılıkların kodunu içeren tek bir yürütülebilir dosya oluşturulur. Yürütülebilir boyutun küçültülmesi şu yollara yol açabilir:
  • Kapsayıcılı dağıtım senaryoları gibi daha küçük kapsayıcı görüntüleri.
  • Daha küçük görüntülerden daha kısa dağıtım süresi.
• Daha kısa başlangıç süresi: Yerel AOT uygulamaları daha az başlatma süresi gösterebilir, yani
  • Uygulama, isteklere daha hızlı hizmet vermek için hazırdır.
  • Kapsayıcı düzenleyicilerinin uygulamanın bir sürümünden diğerine geçişi yönetmesi gereken geliştirilmiş dağıtım.
• Daha az bellek talebi: Yerel AOT uygulamaları, uygulama tarafından yapılan çalışmaya bağlı olarak daha az bellek talebine sahip olabilir. Azaltılmış bellek tüketimi, daha fazla dağıtım yoğunluğuna ve geliştirilmiş ölçeklenebilirliğe yol açabilir.

Şablon uygulaması, AOT tarafından yayımlanan bir uygulamanın, kırpılmış bir çalışma zamanı uygulamasının ve denenmemiş bir çalışma zamanı uygulamasının performansını karşılaştırmak için karşılaştırma laboratuvarımızda çalıştırıldı. Aşağıdaki grafikte karşılaştırmanın sonuçları gösterilmektedir:

Yukarıdaki grafik, Yerel AOT'nin daha düşük uygulama boyutuna, bellek kullanımına ve başlangıç süresine sahip olduğunu gösterir.

ASP.NET Core ve Yerel AOT uyumluluğu

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 özetlenmiştir:

Özellik	Tam Olarak Desteklenir	Kısmen Desteklenir	Desteklenmiyor
gRPC	✔️Tam olarak desteklenir
Minimal API'ler		✔️Kısmen desteklenir
MVC			❌Desteklenmiyor
Blazor Server			❌Desteklenmiyor
SignalR			❌Desteklenmiyor
JWT Kimlik Doğrulaması	✔️Tam olarak desteklenir
Diğer Kimlik Doğrulaması			❌Desteklenmiyor
CORS	✔️Tam olarak desteklenir
Sistem Durumu Denetimleri	✔️Tam olarak desteklenir
HttpLogging	✔️Tam olarak desteklenir
Localization (Yerelleştirme)	✔️Tam olarak desteklenir
OutputCaching	✔️Tam olarak desteklenir
RateLimiting	✔️Tam olarak desteklenir
RequestDecompression	✔️Tam olarak desteklenir
ResponseCaching	✔️Tam olarak desteklenir
ResponseCompression	✔️Tam olarak desteklenir
Rewrite	✔️Tam olarak desteklenir
Oturum			❌Desteklenmiyor
Kaplıca			❌Desteklenmiyor
StaticFiles	✔️Tam olarak desteklenir
WebSockets	✔️Tam olarak desteklenir

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

• Yerel AOT dağıtımının sınırlamaları
• AOT uyarılarına giriş
• Bilinen kırpma uyumsuzlukları
• Kırpma uyarılarına giriş
• GitHub sorunu dotnet/core #8288

Yerel AOT dağıtım modeline geçerken bir uygulamayı kapsamlı bir şekilde test etmek önemlidir. AOT ile dağıtılan uygulama, işlevselliğin denenmemiş ve JIT ile derlenmiş uygulamadan değişmediğini doğrulamak için test edilmelidir. 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ı denenmeyen ve JIT ile derlenmiş uygulamayla aynı şekilde çalışmalıdır.

Yerel AOT yayımlama

Yerel AOT, MSBuild özelliğiyle PublishAot etkinleştirilir. Aşağıdaki örnekte proje dosyasında Yerel AOT'nin nasıl etkinleştirileceği gösterilmektedir:

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

Bu ayar yayımlama 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ılırken JIT derlemesi kullanır. 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 zamanında özel durumlar oluşturur.
• 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, uygulamanın tüm 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'de Yerel AOT, aşağıdaki ASP.NET Core uygulama türleri tarafından desteklenir:

• minimal API'ler - Daha fazla bilgi için bu makalenin devamında yer alan Web API'si (Yerel AOT) şablonu bölümüne bakın.
• gRPC - Daha fazla bilgi için bkz . gRPC ve Yerel AOT.
• Çalışan hizmetleri - Daha fazla bilgi için bkz . Çalışan Hizmeti şablonlarında AOT.

Web API'si (Yerel AOT) şablonu

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

• MVC henüz Yerel AOT ile uyumlu olmadığından yalnızca en düşük API'leri kullanır.
• Api'yi CreateSlimBuilder() kullanarak yalnızca temel özelliklerin varsayılan olarak etkinleştirildiğinden emin olur ve uygulamanın dağıtılan boyutunu en aza indirir.
• HTTPS trafiği genellikle buluta özel dağıtımlarda giriş hizmeti tarafından işlendiğinden yalnızca HTTP'de dinleyecek şekilde yapılandırılır.
• 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 dosya oluşturur.
• Hava durumu tahmini örneği yerine bir örnek Todo API içerir.
• Bu makalenin önceki bölümlerinde gösterildiği gibi proje dosyasına eklerPublishAot.
• JSON seri hale getirici kaynak oluşturucularını etkinleştirir. Kaynak oluşturucu, yerel AOT derlemesi için gerekli olan derleme zamanında serileştirme kodu oluşturmak için kullanılır.

Kaynak oluşturmayı desteklemek için yapılan değişiklikler

Aşağıdaki örnekte, JSON serileştirme kaynağı oluşturmayı desteklemek için dosyaya eklenen Program.cs kod gösterilmektedir:

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

Bu kod eklenmeden, System.Text.Json JSON serileştirmek ve seri durumdan çıkarmak için yansıma kullanır. Yansıma Yerel AOT'de desteklenmez.

Daha fazla bilgi için bkz.

• Kaynak oluşturucuları birleştirme
• TypeInfoResolverChain

Değişiklikler: launchSettings.json

launchSettings.json Web API'si (Yerel AOT) şablonu tarafından oluşturulan dosyada iisSettings bölüm ve IIS Express profil kaldırıldı:

{
  "$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 yöntemi

Şablon yöntemi yerine CreateBuilder() yöntemini kullanırCreateSlimBuilder().

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
{

}

yöntemi, CreateSlimBuilder uygulamasını çalıştırmak için gereken en düşük ASP.NET Core özellikleriyle başlatır WebApplicationBuilder .

Daha önce belirtildiği gibi, CreateSlimBuilder yöntem 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 bkz . Application Gateway ile TLS sonlandırma ve uçtan uca TLS. HTTPS, oluşturucu çağrılarak etkinleştirilebilir. WebHost.UseKestrelHttpsConfiguration HTTP/3 oluşturucu çağrılarak etkinleştirilebilir. WebHost.UseQuic.

CreateSlimBuilder ve CreateBuilder

yöntemi, CreateSlimBuilder yöntemi tarafından CreateBuilder desteklenen aşağıdaki özellikleri desteklemez:

• Başlangıç bütünleştirilmiş kodlarını barındırma
• UseStartup
• Aşağıdaki günlük sağlayıcıları:
  • Windows EventLog
  • Hata Ayıklama
  • Olay Kaynağı
• Web barındırma özellikleri:
  • UseStaticWebAssets
  • IIS Tümleştirmesi
• Kestrel konfigürasyon
  • içindeki HTTPS uç noktaları Kestrel
  • Quic (HTTP/3)
• Yönlendirmede kullanılan regex ve alfa kısıtlamaları

yöntemi, CreateSlimBuilder verimli bir geliştirme deneyimi için gereken aşağıdaki özellikleri içerir:

• ve appsettings.{EnvironmentName}.jsoniçin appsettings.json JSON dosya yapılandırması.
• Kullanıcı gizli dizileri yapılandırması.
• Konsol günlüğü.
• Günlük yapılandırması.

Önceki özellikleri atlayan bir oluşturucu için bkz. YöntemiCreateEmptyBuilder.

Minimum özelliklerin dahil olması, AOT'nin yanı sıra kırpmaya da yarar sağlar. Daha fazla bilgi için bkz . Bağımsız dağıtımları ve yürütülebilir dosyaları kırpma.

Daha ayrıntılı bilgi için bkz. Karşılaştırma WebApplication.CreateBuilderCreateSlimBuilder

Kaynak oluşturucular

Yerel AOT için yayımlama sırasında kullanılmayan kod kırpıldığından, uygulama çalışma zamanında ilişkisiz yansıma kullanamaz. Kaynak oluşturucular , yansıma gereksinimini önleyen kod üretmek için kullanılır. Bazı durumlarda, kaynak oluşturucular bir oluşturucu gerekli olmadığında bile AOT için iyileştirilmiş kod üretir.

Oluşturulan kaynak kodunu görüntülemek için, aşağıdaki örnekte gösterildiği gibi özelliğini uygulamanın .csproj dosyasına ekleyinEmitCompilerGeneratedFiles:

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

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

</Project>

dotnet build Oluşturulan kodu görmek için komutunu çalıştırın. Çıktı, proje için oluşturulan tüm dosyaları içeren bir obj/Debug/net8.0/generated/ dizin içerir.

Komut dotnet publish ayrıca kaynak dosyaları derler ve derlenmiş dosyalar oluşturur. Ayrıca, dotnet publish oluşturulan derlemeleri yerel bir IL derleyicisine geçirir. IL derleyicisi yerel yürütülebilir dosyayı üretir. Yerel yürütülebilir dosya yerel makine kodunu içerir.

Kitaplıklar ve Yerel AOT

ASP.NET Core projelerinde kullanılan popüler kitaplıkların çoğunda şu anda Yerel AOT'yi hedefleyen bir projede kullanıldığında bazı uyumluluk sorunları vardır, örneğin:

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

Yerel AOT ile çalışabilmek için bu dinamik özellikleri kullanan kitaplıkların güncelleştirilmesi gerekir. Roslyn kaynak oluşturucuları gibi araçlar kullanılarak güncelleştirilebilirler.

Yerel AOT'yi desteklemeyi uman kitaplık yazarlarının şunlar için teşvik edilir:

• Yerel AOT uyumluluk gereksinimleri hakkında bilgi edinin.
• Kitaplığı kırpma için hazırlayın.

Minimum API'ler ve JSON yükleri

Minimal API çerçevesi, kullanarak System.Text.JsonJSON yüklerini almak ve döndürmek için iyileştirilmiştir. System.Text.Json:

• JSON ve Yerel AOT için uyumluluk gereksinimleri uygular.
• Kaynak oluşturucunun System.Text.Jsonkullanılmasını gerektirir.

HTTP gövdesinin bir parçası olarak iletilen veya Minimum API'lerdeki istek temsilcilerinden döndürülen tüm türler, ASP.NET Core'un bağımlılık eklemesi yoluyla kaydedilen bir JsonSerializerContext üzerinde yapılandırılmalıdı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
{

}

Yukarıdaki vurgulanan kodda:

• JSON seri hale getirici bağlamı DI kapsayıcısıyla kaydedilir. Daha fazla bilgi için, şuraya bakın:
  • Kaynak oluşturucuları birleştirme
  • TypeInfoResolverChain
• Türü için kaynak tarafından oluşturulan JSON seri hale getirici kodunu etkinleştirmek için ToDo özel JsonSerializerContext öğesine özniteliğiyle [JsonSerializable] ek açıklama eklenir.

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

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

ASP.NET Core'da Yerel AOT desteğiyle ilgili sorunları bildirmek veya gözden geçirmek için bu GitHub sorununa bakın.

Ayrıca bkz.

• Öğretici: Yerel AOT kullanarak ASP.NET Core uygulaması yayımlama
• Yerel AOT dağıtımı
• AOT dağıtımlarını iyileştirme
• Yapılandırma bağlama kaynak oluşturucu
• Yapılandırma bağlayıcısı kaynak oluşturucuyu kullanma
• En düşük API AOT derleme şablonu
• Karşılaştırma:WebApplication.CreateBuilderCreateSlimBuilder
• Yeni en düşük API kaynak oluşturucusunu keşfetme
• Yöntem çağrılarını Kesicilerle değiştirme
• Ve yeni telemetri günlüğü kaynak oluşturucusunun arkasında [LogProperties]