Przejdź do treści

Platformy docelowe, runtime async i NativeAOT

License: MIT GitHub

Każda paczka TailoredApps.Shared.* jest budowana dla kilku platform docelowych jednocześnie (multi-targeting). NuGet sam wybiera asset pasujący do TargetFramework Twojej aplikacji — nie trzeba niczego konfigurować.


Wspierane platformy docelowe

Biblioteki Platformy docelowe
DateTime, Email, Email.Models, Email.Office365, EntityFramework, EntityFramework.UnitOfWork.MinimalApi, EntityFramework.UnitOfWork.WebApiCore, ExceptionHandling, ExceptionHandling.MinimalApi, Mediator, Mediator.Caching, Mediator.Email, Mediator.ML, Mediator.PagedRequest, Payments i wszyscy providerzy płatności, Querying, WebApi net10.0, net11.0

Wersja 2.0 a starsze platformy

Od wersji 2.0 każda biblioteka jest budowana wyłącznie dla net10.0 i net11.0. Aplikacje na net8.0, net9.0, .NET Framework lub innej platformie netstandard2.0 / netstandard2.1 pozostają przy paczkach 1.x (1.6.x), które nadal otrzymują poprawki bezpieczeństwa z gałęzi release/1.x.

Zależności dopasowane do platformy

Paczki powiązane z wersją runtime'u (Microsoft.Extensions.*, Microsoft.EntityFrameworkCore*) mają osobną wersję dla każdej platformy docelowej: asset net11.0 zależy od linii 11.x, a net10.0 od 10.x. Wersje wszystkich paczek są zapisane w jednym miejscu, w Directory.Packages.props; pliki projektów wymieniają paczki tylko z nazwy. Aplikacja na .NET 11 nie dostaje więc w zależnościach paczek z poprzedniej generacji.

Wyjątek: WebApi na net11.0

W dniu wydania .NET 11 na nuget.org nie było jeszcze linii 11.x paczek Microsoft.Extensions.Http.Resilience i Microsoft.Extensions.ServiceDiscovery, dlatego asset net11.0 biblioteki WebApi korzysta tymczasowo z ich linii 10.x.


Runtime async (.NET 11)

W .NET 11 zawieszaniem i wznawianiem metod async może zająć się sam runtime. Kompilator C# nie generuje wtedy osobnego typu maszyny stanów dla każdej metody async — metoda zostaje zwykłą metodą oznaczoną flagą MethodImplOptions.Async. Celem jest mniejszy narzut wywołań asynchronicznych i mniejszy kod IL. Kod źródłowy i publiczne API pozostają bez zmian: sygnatury nadal zwracają Task / ValueTask.

Biblioteki z tego repozytorium korzystają z tego mechanizmu w assetach net11.0:

Asset w paczce Sposób kompilacji metod async
net11.0 runtime async
net10.0 maszyna stanów generowana przez kompilator (bez zmian)

Co to oznacza dla Twojej aplikacji

  • Nic nie musisz włączać. Aplikacja na net11.0 dostaje asset z runtime async automatycznie; aplikacje na net10.0 dostają dokładnie to, co wcześniej.
  • Twoja aplikacja nie musi sama używać runtime async. Kod skompilowany klasycznie może swobodnie wywoływać metody bibliotek skompilowane jako runtime async i odwrotnie — testy tego repozytorium są kompilowane klasycznie i uruchamiane zarówno na net10.0, jak i na net11.0.
  • Nie potrzeba zmiennych środowiskowych ani <EnablePreviewFeatures>.

Wymaga CoreCLR lub NativeAOT

Runtime async działa na CoreCLR i NativeAOT. Runtime Mono — używany m.in. przez Blazor WebAssembly — nie potrafi w .NET 11 wykonać takich metod. Jeżeli chcesz użyć którejś z bibliotek zawierających kod async po stronie klienta Blazor WebAssembly na net11.0, zbuduj ją z wyłączonym runtime async (patrz niżej). Biblioteki DateTime, Email.Models, Mediator.Caching i Querying nie zawierają kodu async i nie są tym objęte.

Status funkcji

W .NET 11 runtime async jest funkcją typu opt-in, którą dokumentacja Microsoftu wciąż opisuje jako preview: What's new in the .NET 11 runtime.

Jak to jest włączone w repozytorium

Jedno miejsce: eng/RuntimeAsync.targets, importowany przez src/Directory.Build.targets (wszystkie biblioteki) i samples/Directory.Build.targets (aplikacja demo). Plik dopisuje runtime-async=on do właściwości Features kompilatora wyłącznie dla platform zgodnych z net11.0:

<PropertyGroup Condition="'$(UseRuntimeAsync)' != 'false' and '$(TargetFramework)' != '' and $([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net11.0'))">
  <Features>$(Features);runtime-async=on</Features>
</PropertyGroup>

Warunek jest konieczny: ustawienie tej flagi dla net10.0 kończy build błędami SYSLIB5007 / CA2252, a na starszych platformach flaga jest po cichu ignorowana.

Projekty testów są celowo kompilowane klasycznie, więc na net11.0 każdy test przechodzi z kodu z maszynami stanów do kodu runtime async i z powrotem. Test RuntimeAsyncTests sprawdza refleksją, że w assetach net11.0 bibliotek i demo nie ma maszyn stanów, a w net10.0 nie ma metod runtime async — gdyby flaga przestała docierać do kompilatora, nic innego by tego nie zauważyło. Runtime async pod NativeAOT sprawdza aplikacja kontrolna opisana w sekcji Trimming i NativeAOT.

Wyłączanie

Zakres Jak
Cały build dotnet build TailoredApps.Shared.slnx -p:UseRuntimeAsync=false
Jedna biblioteka lub aplikacja <UseRuntimeAsync>false</UseRuntimeAsync> w jej pliku .csproj

Po wyłączeniu asset net11.0 jest kompilowany tak samo jak pozostałe — z maszynami stanów.


Trimming i NativeAOT

Od wersji 3.0 część bibliotek deklaruje zgodność z trimmingiem i NativeAOT (IsAotCompatible). Aplikacja publikowana z <PublishAot>true</PublishAot> albo <PublishTrimmed>true</PublishTrimmed> nie dostaje z nich żadnych ostrzeżeń IL2xxx / IL3xxx, a ich kod działa po skompilowaniu do kodu natywnego.

Biblioteki Stan
DateTime, Querying, Email.Models, Payments, Payments.Provider.Adyen, .CashBill, .HotPay, .PayNow, .PayU, .Przelewy24, .Revolut, .Tpay Zgodne. Sprawdzane natywnie w CI na net10.0 i net11.0, na Linuksie i Windows
Email, ExceptionHandling, ExceptionHandling.MinimalApi, WebApi Zgodne w aplikacji na minimal API (zob. niżej). Filtr MVC z ExceptionHandling nie ma zastosowania: ASP.NET Core nie obsługuje kontrolerów w NativeAOT
Mediator, Mediator.Caching, Mediator.Email, Mediator.PagedRequest Zgodne (na ForkForward.Mediator 13), gdy handlery, behaviory i polityki są rejestrowane po nazwie, a nie skanowaniem — zob. Mediator: Trimming i NativeAOT. Aplikacja, która cache'uje odpowiedzi, dostaje ostrzeżenia z samego Microsoft.Extensions.Caching.Hybrid; cache działa natywnie
EntityFramework, EntityFramework.UnitOfWork.WebApiCore, EntityFramework.UnitOfWork.MinimalApi Niezgodne: EF Core buduje model i zapytania w czasie działania; audyt zmian tworzy typy przez MakeGenericType
Email.Office365, Mediator.ML, Payments.Provider.Stripe Niezgodne: zależności (Microsoft.Identity.Web, ML.NET, Stripe.net) opierają się na refleksji

Web API: minimal API tak, kontrolery nie

NativeAOT w ASP.NET Core obejmuje minimal API, a nie MVC. Sprawdzone na .NET 11 w tym repozytorium:

Scenariusz Wynik po PublishAot
Minimal API + WebApi + ExceptionHandling (middleware i filtry endpointów z walidatorem FluentValidation) + Email + [Authorize] z JWT (401 / 403 / 200) Bez ostrzeżeń, działa natywnie — to robi tests/TailoredApps.Shared.AotSmoke.Web
Kontrolery (AddControllers, [ApiController], [Authorize]) Około 160 ostrzeżeń z samego MVC; aplikacja startuje, ale każda trasa kontrolera odpowiada 404 — kontrolery nie są odnajdywane
Kontrolery + EF Core + filtr transakcji Kilkaset ostrzeżeń z EF Core; aplikacja kończy się przy starcie

Autoryzacja nie jest przeszkodą: [Authorize], polityki i JWT działają natywnie na endpointach minimal API. Przeszkodą są kontrolery i EF Core. Aplikacja z kontrolerami korzysta więc z bibliotek jak dotąd (JIT, ewentualnie ReadyToRun), a NativeAOT wymaga przepisania endpointów na minimal API i dostępu do danych bez EF Core.

Dla minimal API są osobne paczki z odpowiednikami filtrów MVC: ExceptionHandling.MinimalApi (wyjątki i walidacja, zgodna z NativeAOT) oraz EntityFramework.UnitOfWork.MinimalApi (transakcja na żądanie; działa bez AOT, bo zależy od EF Core).

Blazor

  • Blazor Server / Blazor Web App z renderowaniem po stronie serwera działa na zwykłym CoreCLR: biblioteki działają bez ograniczeń, NativeAOT nie ma tu zastosowania.
  • Blazor WebAssembly działa na runtime Mono, który w .NET 11 nie wykonuje metod runtime async. Sprawdzone: wywołanie asynchronicznej metody biblioteki z assetu net11.0 kończy się wyjątkiem PlatformNotSupportedException: Runtime Async is not supported on this platform. Kod bez async (np. DateTime, Querying, Email.Models) działa. Do czasu wydania paczek z osobnym assetem dla przeglądarki aplikacja WebAssembly na net11.0 nie może używać asynchronicznych metod tych bibliotek; aplikacja na net10.0 dostaje asset z maszynami stanów i działa.
  • W przeglądarce liczy się trimming (jest zawsze włączony przy publikacji), a nie NativeAOT — biblioteki z tabeli „Zgodne” nie zgłaszają ostrzeżeń trimmera.

Co zostało zrobione

  • Opcje z konfiguracji wiąże kod generowany w czasie kompilacji (generator bindera konfiguracji), a nie refleksja. Wyjątkiem jest Email.Office365, gdzie generator nie potrafi powiązać opisu certyfikatu.
  • JSON bramek płatności jest serializowany przez metadane generowane w czasie kompilacji (JsonSerializerContext); treść żądań i podpisy są identyczne co do bajta. To samo dotyczy odpowiedzi błędu w ExceptionHandling.
  • Rejestracje w kontenerze z parametrem generycznym (RegisterPaymentProvider<T>(), AddPayments<,>(), AddExceptionHandlingForWebApi<,>()) mają adnotacje, dzięki którym trimmer zachowuje konstruktory wywoływane przez dependency injection.
  • Mediator ma rejestrację bez skanowania (AddPipelineBehaviors<,>(), AddCachePolicy<,,>(), AddFallbackHandler<,,>(), AddRetryPolicy<,,>()), serializację odpowiedzi w cache generowanymi metadanymi (AddCacheSerialization) i klucz cache liczony z JsonTypeInfo. Skanowanie assembly zostaje dla zwykłych aplikacji i jest oznaczone RequiresUnreferencedCode.

Jak to jest pilnowane

  • W bibliotece z <IsAotCompatible>true</IsAotCompatible> każde ostrzeżenie analizatorów trimmingu, AOT i single-file jest błędem kompilacji (eng/AotCompatible.globalconfig, podłączany w src/Directory.Build.targets).
  • tests/TailoredApps.Shared.AotSmoke to aplikacja konsolowa, która używa tych bibliotek tak jak aplikacja: kontener, opcje z konfiguracji, płatność w każdej bramce HTTP (przez tę samą podstawioną bramkę co aplikacja demo), powiadomienia, podpisy, a także mediator z behaviorami: walidacja, odpowiedź typu wartościowego, retry i fallback, request stronicowany, SendMail. tests/TailoredApps.Shared.AotSmoke.Web to Web API na minimal API: uruchamia się na wolnym porcie i woła własne endpointy — zdrowie, odpowiedzi błędów, szablon e-mail i SMTP, [Authorize] z JWT, klient HTTP z odpornością. Zadanie NativeAOT smoke test w sprawdzeniach PR publikuje obie z NativeAOT dla net10.0 i net11.0, na Linuksie i Windows, i uruchamia; w tych projektach każde ostrzeżenie trim/AOT — także z zależności — jest błędem. Analizatory widzą kod jednej biblioteki, kompilator AOT całe drzewo zależności.
  • tests/TailoredApps.Shared.AotSmoke.Caching sprawdza natywnie cache odpowiedzi: obiekt i typ wartościowy, serializowane generowanymi metadanymi. Jest osobną aplikacją, bo Microsoft.Extensions.Caching.Hybrid wciąż zgłasza ostrzeżenia trim/AOT dla swojego zapasowego serializatora JSON. Tylko tutaj są one przepuszczane, a to samo zadanie CI kończy się błędem, gdy ostrzeżenie tego rodzaju wskazuje jakiekolwiek inne assembly.
dotnet publish tests/TailoredApps.Shared.AotSmoke -c Release -f net11.0 -r linux-x64   # wymaga clang i zlib; na Windows: -r win-x64 i narzędzi C++
./artifacts/publish/TailoredApps.Shared.AotSmoke/release_net11.0_linux-x64/TailoredApps.Shared.AotSmoke

Nullable reference types

Od wersji 2.0 każda biblioteka jest kompilowana z włączonymi nullable reference types, więc publiczne API informuje kompilator, które wartości mogą być null:

  • Składowe, które nigdy nie miały gwarancji wartości, są teraz zadeklarowane jako nullable — na przykład PaymentRequest.Currency, PaymentResponse.RedirectUrl, MailMessage.Body czy opcjonalne właściwości klas opcji. Jeśli Twój projekt ma <Nullable>enable</Nullable>, kompilator ostrzeże w miejscach, gdzie taka wartość jest używana bez sprawdzenia.
  • Parametry, które zawsze przyjmowały null, są tak oznaczone — np. załączniki w IEmailProvider.SendMail.
  • W czasie działania nic się nie zmienia dla kodu, który już działał. Różnice dotyczą wyłącznie ścieżek, które kończyły się wyjątkiem NullReferenceException — teraz zgłaszają wyjątek z opisem, np. żądanie płatności bez waluty rzuca ArgumentException, a audyt encji bez klucza głównego InvalidOperationException.

W samym repozytorium ostrzeżenia nullable są błędami kompilacji dla wszystkiego w src/ (src/Directory.Build.props), więc adnotacje nie mogą rozjechać się z kodem.


Budowanie repozytorium

  • Wymagany jest .NET SDK 11.0.100 lub nowszy — buduje obie platformy docelowe: net10.0 i net11.0.
  • Testy uruchamiają się na net10.0 i net11.0, więc lokalnie potrzebne są oba runtime'y.
  • Workflowy CI instalują SDK 10.0.x (runtime dla testów net10.0) oraz 11.0.x (build).
dotnet build TailoredApps.Shared.slnx
dotnet test TailoredApps.Shared.slnx

Nowa biblioteka

  • Nie ustawiaj TargetFrameworks, autora, licencji ani wersji języka w pliku .csproj — są dziedziczone z Directory.Build.props i src/Directory.Build.props. Plik projektu zawiera tylko to, co własne: PackageId, Title, Description, PackageTags, referencje.
  • Paczki dodawaj jako <PackageReference Include="Nazwa" /> bez wersji; wersję dopisz w Directory.Packages.props. Paczkę powiązaną z wersją runtime'u dopisz do obu grup warunkowych (10.* dla net10.0, 11.* dla net11.0).
  • Nie ustawiaj Features w pliku .csproj — runtime async jest dziedziczony z eng/RuntimeAsync.targets.
  • Jeśli biblioteka ma być zgodna z NativeAOT: ustaw <IsAotCompatible>true</IsAotCompatible>, dodaj ją do tests/TailoredApps.Shared.AotSmoke razem ze sprawdzeniem jej scenariusza i dopisz do tabeli w sekcji Trimming i NativeAOT.
  • Projekt testów umieść w tests/ — dziedziczy te same platformy docelowe, więc asset net11.0 jest faktycznie testowany.

🤖 AI Agent Prompt

## TailoredApps Shared Components — platformy docelowe i runtime async — Instrukcja dla agenta AI

Pracujesz z paczkami TailoredApps.Shared.* albo z repozytorium SharedComponents.

### Rejestracja
- Brak. Wybór platformy docelowej nie wymaga żadnych wywołań w Program.cs — NuGet sam dobiera
  asset zgodny z TargetFramework aplikacji.

### Co jest skonfigurowane
- Platformy od wersji 2.0: net10.0 i net11.0 dla każdej biblioteki. Starsze platformy
  (net8.0, net9.0, netstandard2.x) obsługują wyłącznie paczki 1.x (1.6.x).
- Assety net11.0 mają metody async skompilowane jako runtime async; pozostałe assety używają
  maszyn stanów generowanych przez kompilator. Publiczne API jest identyczne na każdej platformie.
- Zależności Microsoft.Extensions.* / EF Core są dopasowane do platformy (net11.0 -> 11.x).

### Konfiguracja
- W repozytorium: właściwość MSBuild UseRuntimeAsync (domyślnie włączona dla net11.0+),
  obsługiwana w eng/RuntimeAsync.targets (biblioteki i aplikacja demo). Wyłączenie: -p:UseRuntimeAsync=false albo
  <UseRuntimeAsync>false</UseRuntimeAsync> w csproj biblioteki.
- W aplikacji konsumującej paczki: brak ustawień.

### Zasady
- Nie dodawaj <Features>runtime-async=on</Features> ani <EnablePreviewFeatures> do plików csproj
  bibliotek — przełącznik jest centralny i warunkowany platformą.
- Nie ustawiaj runtime-async dla net10.0 ani starszych platform: build kończy się błędami
  SYSLIB5007 / CA2252.
- Nie używaj assetów net11.0 bibliotek z kodem async w Blazor WebAssembly (Mono nie obsługuje
  runtime async w .NET 11) — zbuduj je z UseRuntimeAsync=false.
- Nowa biblioteka: nie ustawiaj TargetFrameworks ani metadanych paczki w csproj (są dziedziczone);
  PackageReference bez wersji, wersje w Directory.Packages.props (paczki runtime'owe w obu grupach
  warunkowych: 10.* i 11.*); projekt testów w tests/.
- Do budowania repozytorium używaj .NET SDK 11.0.100 lub nowszego.
- Zgodne z trimmingiem i NativeAOT (IsAotCompatible) są: DateTime, Querying, Email, Email.Models, ExceptionHandling,
  ExceptionHandling.MinimalApi, WebApi, Mediator, Mediator.Caching, Mediator.Email, Mediator.PagedRequest,
  Payments oraz providerzy Adyen, CashBill, HotPay, PayNow, PayU, Przelewy24, Revolut, Tpay.
- NativeAOT w ASP.NET Core to minimal API: kontrolery MVC nie działają natywnie (trasy odpowiadają 404). [Authorize] i JWT działają.
- Blazor WebAssembly na net11.0 nie wykonuje metod runtime async (PlatformNotSupportedException): nie wywołuj tam asynchronicznych
  metod bibliotek z assetu net11.0. W nich ostrzeżenia IL2xxx/IL3xxx są błędami kompilacji:
  nie używaj refleksji, JsonSerializer bez JsonTypeInfo ani ConfigurationBinder poza generatorem.
- Biblioteki EntityFramework*, Email.Office365, Mediator.ML i Payments.Provider.Stripe nie są zgodne z NativeAOT -
  nie proponuj ich w aplikacji publikowanej z PublishAot.
- Mediator w aplikacji z PublishAot: bez skanowania - cfg.AddRequestHandler<,,>() dla handlerów, AddPipelineBehaviors<,>() dla każdego
  requestu, AddCachePolicy / AddFallbackHandler / AddRetryPolicy, AddCacheSerialization(context) i własny GetCacheKey.