Platformy docelowe, runtime async i NativeAOT¶
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.0dostaje asset z runtime async automatycznie; aplikacje nanet10.0dostają 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 nanet11.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.0kończy się wyjątkiemPlatformNotSupportedException: Runtime Async is not supported on this platform. Kod bezasync(np.DateTime,Querying,Email.Models) działa. Do czasu wydania paczek z osobnym assetem dla przeglądarki aplikacja WebAssembly nanet11.0nie może używać asynchronicznych metod tych bibliotek; aplikacja nanet10.0dostaje 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 wExceptionHandling. - 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 zJsonTypeInfo. Skanowanie assembly zostaje dla zwykłych aplikacji i jest oznaczoneRequiresUnreferencedCode.
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 wsrc/Directory.Build.targets). tests/TailoredApps.Shared.AotSmoketo 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.Webto 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 dlanet10.0inet11.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.Cachingsprawdza natywnie cache odpowiedzi: obiekt i typ wartościowy, serializowane generowanymi metadanymi. Jest osobną aplikacją, boMicrosoft.Extensions.Caching.Hybridwciąż 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.Bodyczy 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 wIEmailProvider.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 rzucaArgumentException, a audyt encji bez klucza głównegoInvalidOperationException.
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.0inet11.0. - Testy uruchamiają się na
net10.0inet11.0, więc lokalnie potrzebne są oba runtime'y. - Workflowy CI instalują SDK
10.0.x(runtime dla testównet10.0) oraz11.0.x(build).
Nowa biblioteka¶
- Nie ustawiaj
TargetFrameworks, autora, licencji ani wersji języka w pliku.csproj— są dziedziczone zDirectory.Build.propsisrc/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 wDirectory.Packages.props. Paczkę powiązaną z wersją runtime'u dopisz do obu grup warunkowych (10.*dlanet10.0,11.*dlanet11.0). - Nie ustawiaj
Featuresw pliku.csproj— runtime async jest dziedziczony zeng/RuntimeAsync.targets. - Jeśli biblioteka ma być zgodna z NativeAOT: ustaw
<IsAotCompatible>true</IsAotCompatible>, dodaj ją dotests/TailoredApps.Shared.AotSmokerazem 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 assetnet11.0jest 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.