Aktualizacja do 3.0 (wersja testowa)¶
Faza testowa
Linia 3.0 jest wydawana jako wersje przedpremierowe (3.0.0-preview.N). API może się jeszcze zmienić przed wydaniem 3.0.0.
Aplikacje produkcyjne zostają przy 2.1.x (gałąź release/2.1, poprawki), dopóki 3.0 nie wyjdzie z fazy testów.
Ta strona zbiera to, co trzeba zrobić w kodzie aplikacji przy przejściu z 2.x na 3.0.
Co się zmienia¶
Biblioteki mediatora przestają zależeć od pakietu MediatR i korzystają z
ForkForward.Mediator — społecznościowego forka MediatR 12.5.0, ostatniej wersji
na licencji Apache-2.0 (MediatR od wersji 13 ma licencję komercyjną). Fork ma te same typy, składowe i zachowanie, ale własną przestrzeń
nazw i własny zestaw: ForkForward.Mediator zamiast MediatR.
Biblioteki mediatora zmieniają nazwę¶
Skoro nie ma już pakietu MediatR, biblioteki tracą też jego nazwę. Pakiety, zestawy i przestrzenie nazw zmieniają się razem:
| 2.x | 3.0 |
|---|---|
TailoredApps.Shared.MediatR |
TailoredApps.Shared.Mediator |
TailoredApps.Shared.MediatR.Caching |
TailoredApps.Shared.Mediator.Caching |
TailoredApps.Shared.MediatR.Email |
TailoredApps.Shared.Mediator.Email |
TailoredApps.Shared.MediatR.PagedRequest |
TailoredApps.Shared.Mediator.PagedRequest |
TailoredApps.Shared.MediatR.ML (przestrzeń nazw TailoredApps.Shared.MediatR.ImageClassification) |
TailoredApps.Shared.Mediator.ML (przestrzeń nazw TailoredApps.Shared.Mediator.ImageClassification) |
Każda przestrzeń nazw poniżej zmienia się tak samo (TailoredApps.Shared.MediatR.DI → TailoredApps.Shared.Mediator.DI itd.). Typy, składowe
i klucze konfiguracji zachowują nazwy.
Stare identyfikatory pakietów zostają na nuget.org z wersjami 2.x i nie dostaną wydania 3.0. Wydania 3.0.0-preview.1 i
3.0.0-preview.2 wyszły jeszcze pod starymi nazwami.
Biblioteki zależą od ForkForward.Mediator 13: linia 13 jest wydawana tylko dla net10.0 i net11.0 (tak jak te biblioteki), jej asset
net11.0 jest skompilowany z runtime async i działa w aplikacjach publikowanych z NativeAOT. Dla kodu aplikacji różnic względem 12.x nie ma;
aplikacja, która sama odwołuje się do ForkForward.Mediator, podnosi go do 13.
Stripe zgłasza błędy bramki tak jak pozostali dostawcy¶
W 2.x dostawca Stripe przepuszczał każdy błąd API jako StripeException z SDK Stripe.net. Od 3.0 stosuje te same reguły co
pozostałe osiem dostawców:
| Sytuacja | 2.x | 3.0 |
|---|---|---|
RegisterPayment: Stripe nie obsłużył wywołania (5xx, 408, 429, brak odpowiedzi) |
StripeException |
PaymentGatewayException (to HttpRequestException), StripeException w InnerException |
RegisterPayment: Stripe odmówił (4xx — złe parametry, nieaktywna metoda płatności, zły klucz) |
StripeException |
PaymentStatus = Rejected, komunikat Stripe w ResponseObject |
GetStatus: dowolny błąd, także 404 |
StripeException |
PaymentGatewayException |
Aplikacja, która już łapie HttpRequestException wokół RegisterPayment i GetStatus (zalecane od 2.0), obsługuje teraz Stripe tym
samym blokiem. Obsługa webhooków Stripe się nie zmienia.
Odrzucone żądania nie są już logowane jako błędy¶
- Mediator —
LoggingBehaviorzapisuje żądanie odrzucone przez walidację (ValidationException) na poziomie Information:Request GetProduct rejected by validation …; invalid: Id, z samymi nazwami pól (komunikaty walidacji mogą cytować wartości wysłane przez klienta). Żądanie anulowane przez wywołującego (OperationCanceledExceptionprzy anulowanym tokenie żądania) — też Information. Każdy inny wyjątek handlera, jak dotąd, Error. - ExceptionHandling —
ConfigureExceptionHandler()nie oznacza już jako błędu wyjątku, któremu provider nadał status 4xx: middleware nie zapisujeAn unhandled exception has occurred while executing the request.na poziomie Error i nie dodaje taguerror.typedo metrykihttp.server.request.duration. Wyjątek trafia do logu na poziomie Debug, w kategoriiTailoredApps.Shared.ExceptionHandling. Odpowiedzi 5xx — bez zmian.
Wcześniej jeden błąd walidacji dawał dwa wpisy Error ze stosem wywołań.
Usunięte przestarzałe składowe¶
Składowe oznaczone w 2.x jako [Obsolete] zostały usunięte. Kompilator 2.x ostrzegał o każdym ich użyciu (CS0618).
| Usunięte | Zamiast | Po aktualizacji bez zmiany |
|---|---|---|
IDateTimeProvider.UtcTimeOfDaty, DateTimeProvider.UtcTimeOfDaty (literówka) |
UtcTimeOfDay |
Błąd kompilacji (CS1061) |
FilterCollection.AddExceptionHAndlingFilterAttribute() (literówka) |
AddExceptionHandlingFilterAttribute() |
Błąd kompilacji (CS1061) |
PayNowServiceOptions.ApiUrl, klucz Payments:Providers:PayNow:ApiUrl |
ServiceUrl |
Kod: błąd kompilacji. Konfiguracja: host nie startuje z komunikatem 'Payments:Providers:PayNow:ApiUrl' is no longer read (removed in 3.0): rename it to 'ServiceUrl'. |
TpayServiceOptions.ApiUrl, klucz Payments:Providers:Tpay:ApiUrl |
ServiceUrl |
jak wyżej, dla Tpay |
Stary klucz konfiguracji jest wykrywany celowo: gdyby był tylko pomijany, konfiguracja sandboxu (ApiUrl z adresem sandboxu) po aktualizacji
łączyłaby się po cichu z produkcyjnym adresem domyślnym ServiceUrl.
Nowe paczki dla minimal API¶
Dwie nowe, osobne paczki — nic nie zmieniają w istniejących i niczego nie trzeba migrować:
ExceptionHandling.MinimalApi—WithExceptionHandling()iWithValidation<TRequest>()jako filtry endpointów, z tym samym modelem błędu co middleware i filtr MVC; zgodna z NativeAOT.EntityFramework.UnitOfWork.MinimalApi—WithUnitOfWorkTransaction(): commit po sukcesie, rollback po wyjątku albo wyniku ze statusem ≥ 400, czyli reguły filtra MVC.
Trimming i NativeAOT¶
DateTime, Querying, Email, Email.Models, ExceptionHandling, WebApi, Payments i ośmiu dostawców HTTP (wszyscy poza Stripe)
deklarują w 3.0 zgodność z trimmingiem i NativeAOT (w Web API: na minimal API, nie na kontrolerach): opcje są wiązane kodem generowanym w czasie kompilacji, a JSON bramek serializowany przez generowane metadane. Dla aplikacji
nic się nie zmienia — treść żądań i podpisy są identyczne. Szczegóły i lista bibliotek: Trimming i NativeAOT.
To samo dotyczy Mediator, Mediator.Caching, Mediator.Email i Mediator.PagedRequest (na ForkForward.Mediator 13). Zwykła aplikacja nie zmienia
niczego: skanowanie i RegisterPipelineBehaviors() działają jak dotąd. Aplikacja trimowana lub publikowana z NativeAOT rejestruje handlery,
behaviory i polityki po nazwie nowymi metodami PipelineRegistration (AddPipelineBehaviors<,>(), AddCachePolicy<,,>(),
AddFallbackHandler<,,>(), AddRetryPolicy<,,>(), AddCacheSerialization(...)) — zob. Mediator: Trimming i NativeAOT.
RegisterPipelineBehaviors(assembly) ma teraz adnotacje RequiresUnreferencedCode / RequiresDynamicCode: projekt z włączonymi analizatorami
trimmingu dostaje w miejscu wywołania ostrzeżenie IL2026 / IL3050.
Jedna zmiana zachowania: CashbillHttpClient.MakeFormRequest<T>() odczytuje odpowiedzi tylko jako typy, dla których biblioteka ma metadane
JSON — modele CashBill (Payment, PaymentStatus, List<PaymentChannels>) i typy wbudowane. Dla własnego typu zgłasza
NotSupportedException, zanim żądanie zostanie wysłane.
Poza tym biblioteki nie mają w 3.0 zmian wymagających modyfikacji kodu.
Lista kontrolna¶
| # | Co zrobić | Skutek pominięcia |
|---|---|---|
| 1 | Usunąć z aplikacji pakiet MediatR (i MediatR.Contracts), dodać ForkForward.Mediator — albo polegać na zależności przechodniej z TailoredApps.Shared.Mediator |
Dwa różne zestawy typów IRequest / IRequestHandler; handlery nie są znajdowane |
| 2 | Zamienić using MediatR; na using ForkForward.Mediator; (także MediatR.Pipeline → ForkForward.Mediator.Pipeline itd.) |
Błędy kompilacji (CS0246) lub niezgodność typów |
| 3 | Zamienić AddMediatR(...) na AddMediator(...), a MediatRServiceConfiguration na MediatorServiceConfiguration |
Błąd kompilacji (CS1061) |
| 4 | Zamienić referencje do pakietów TailoredApps.Shared.MediatR* na TailoredApps.Shared.Mediator* |
Stare pakiety kończą się na 3.0.0-preview.2: restore nie powiedzie się albo po cichu zostanie stare wydanie testowe |
| 5 | Zamienić using TailoredApps.Shared.MediatR na using TailoredApps.Shared.Mediator (każda podprzestrzeń) |
Błąd kompilacji (CS0234) |
| 6 | Podnieść wszystkie pakiety TailoredApps.Shared.* do tej samej wersji 3.0 |
Mieszanie 2.x i 3.0 daje dwa mediatory w jednym procesie |
| 7 | Stripe: obsłużyć awarię przez catch (HttpRequestException), a odmowę przez PaymentStatus == Rejected; usunąć catch (StripeException) wokół RegisterPayment i GetStatus |
Awaria Stripe omija dotychczasowy blok catch (StripeException), a odmowa nie jest wyjątkiem i zostaje nieobsłużona |
| 8 | Przejrzeć alerty i zapytania, które liczą wpisy Error lub error.type dla odpowiedzi 4xx |
Alert na „błędy walidacji” przestaje się uruchamiać |
| 9 | Zamienić UtcTimeOfDaty na UtcTimeOfDay, AddExceptionHAndlingFilterAttribute na AddExceptionHandlingFilterAttribute, a w konfiguracji PayNow i Tpay klucz ApiUrl na ServiceUrl |
Błąd kompilacji albo host, który nie startuje |
Przykład¶
// 2.x
using MediatR;
using TailoredApps.Shared.MediatR.DI;
builder.Services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));
var pipeline = new PipelineRegistration(builder.Services);
pipeline.RegisterPipelineBehaviors();
pipeline.RegisterPipelineBehaviors(typeof(Program).Assembly);
public record GetProduct(int Id) : IRequest<ProductDto>;
public class GetProductHandler : IRequestHandler<GetProduct, ProductDto>
{
public Task<ProductDto> Handle(GetProduct request, CancellationToken cancellationToken) => /* … */;
}
// 3.0
using ForkForward.Mediator;
using TailoredApps.Shared.Mediator.DI;
builder.Services.AddMediator(cfg => cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));
var pipeline = new PipelineRegistration(builder.Services); // rejestracja bibliotek TailoredApps — bez zmian
pipeline.RegisterPipelineBehaviors();
pipeline.RegisterPipelineBehaviors(typeof(Program).Assembly);
public record GetProduct(int Id) : IRequest<ProductDto>;
public class GetProductHandler : IRequestHandler<GetProduct, ProductDto>
{
public Task<ProductDto> Handle(GetProduct request, CancellationToken cancellationToken) => /* … */;
}
Zmieniają się tylko dyrektywy using i nazwa metody rejestrującej mediator. IRequest<>, IRequestHandler<,>, IPipelineBehavior<,>,
IMediator, ISender, INotification i pozostałe typy mają te same nazwy i składowe.
W dużym projekcie wystarczą trzy zastąpienia w całym rozwiązaniu: TailoredApps.Shared.MediatR → TailoredApps.Shared.Mediator
(pliki źródłowe i pliki projektów), using MediatR → using ForkForward.Mediator oraz AddMediatR( → AddMediator(.
Działający przykład na ForkForward.Mediator — cały pipeline (walidacja, cache, retry, fallback) razem z pozostałymi bibliotekami — jest w aplikacji demo.
Na co uważać¶
- Nie mieszaj obu mediatorów. Handler implementujący
MediatR.IRequestHandler<,>nie zostanie wywołany przezForkForward.Mediator.IMediatori odwrotnie — to różne typy. Po migracji w aplikacji nie powinno zostać żadne odwołanie do pakietuMediatR. Mediatorjest teraz także przestrzenią nazw. Kod, którego własna przestrzeń nazw zaczyna się odTailoredApps.Shared., a który używa klasyMediatorz ForkForward.Mediator po krótkiej nazwie, przestaje się kompilować (CS0118); trzeba tam pisaćForkForward.Mediator.Mediator.IMediator,ISenderi pozostałych typów to nie dotyczy, podobnie jak kodu w innych przestrzeniach nazw.- Biblioteki firm trzecich oparte na MediatR (np. własne pakiety z handlerami) trzeba przebudować na
ForkForward.Mediator, zanim zadziałają z 3.0. - Zachowanie jest to z MediatR 12.5.0 — kolejność behaviorów, publikowanie powiadomień i rejestracja z assembly działają tak samo.
ForkForward.Mediatorto młody pakiet. Dlatego 3.0 jest w fazie testowej: sprawdź go w jednej aplikacji, zanim przeniesiesz kolejne.- Szczegóły błędu Stripe (
StripeError.Code,Type) są dalej dostępne: przy awarii wPaymentGatewayException.InnerException(StripeException), przy odmowie komunikat Stripe jest wPaymentResponse.ResponseObject. - Własne typy w
CashbillHttpClient.MakeFormRequest<T>()nie są już obsługiwane (NotSupportedException) — odczytaj odpowiedź jakoJsonElementalbo użyj własnego klienta HTTP. - Wyjątek zamieniany przez providera na 4xx nie jest już widoczny w logu na poziomie Error. Jeśli aplikacja zamienia na 4xx wyjątki, które są w rzeczywistości błędami serwera, niech provider nadaje im 5xx.
Opis bibliotek: Mediator. Aktualizacja z 1.x: Aktualizacja do 2.0.
🤖 AI Agent Prompt¶
## Aktualizacja TailoredApps.Shared.* z 2.x do 3.0 (preview) — Instrukcja dla agenta AI
Aktualizujesz aplikację .NET 10 lub .NET 11 z paczek TailoredApps.Shared.* 2.x do 3.0.0-preview. Zmiany wymagające modyfikacji kodu: mediator, obsługa błędów Stripe i usunięte przestarzałe składowe.
### Rejestracja
- Podnieś wszystkie paczki TailoredApps.Shared.* do tej samej wersji 3.0.0-preview.N
- Usuń odwołania do paczek MediatR i MediatR.Contracts; w razie potrzeby dodaj ForkForward.Mediator
- Zamień referencje do paczek TailoredApps.Shared.MediatR, .MediatR.Caching, .MediatR.Email, .MediatR.PagedRequest i .MediatR.ML na TailoredApps.Shared.Mediator, .Mediator.Caching, .Mediator.Email, .Mediator.PagedRequest i .Mediator.ML
- builder.Services.AddMediatR(...) zamień na builder.Services.AddMediator(...)
### Co wymaga zmian w kodzie
- using TailoredApps.Shared.MediatR... -> using TailoredApps.Shared.Mediator... (każda podprzestrzeń, np. .DI, .PipelineBehaviours, .ImageClassification)
- using MediatR; -> using ForkForward.Mediator; (oraz MediatR.Pipeline -> ForkForward.Mediator.Pipeline itd.)
- MediatRServiceConfiguration -> MediatorServiceConfiguration
- Nazwy i składowe IRequest, IRequestHandler, IPipelineBehavior, IMediator, ISender, INotification pozostają bez zmian
- Stripe: catch (StripeException) wokół RegisterPayment/GetStatus zastąp catch (HttpRequestException) (awaria) i sprawdzeniem PaymentStatus == Rejected (odmowa)
- Alerty liczące wpisy Error dla błędów walidacji przestaną działać: walidacja jest logowana na poziomie Information
- UtcTimeOfDaty -> UtcTimeOfDay; AddExceptionHAndlingFilterAttribute -> AddExceptionHandlingFilterAttribute; w appsettings*.json, zmiennych środowiskowych i sekretach: Payments:Providers:PayNow:ApiUrl i Payments:Providers:Tpay:ApiUrl -> ServiceUrl (stary klucz zatrzymuje start hosta)
### Konfiguracja
- Brak nowych kluczy konfiguracji
### Zasady
- Po migracji w rozwiązaniu nie może zostać żadne odwołanie do paczki ani przestrzeni nazw MediatR, także TailoredApps.Shared.MediatR*
- Zmieniają się tylko identyfikatory paczek i przestrzenie nazw: nie zmieniaj nazw typów ani składowych bibliotek TailoredApps
- W kodzie, którego przestrzeń nazw zaczyna się od TailoredApps.Shared., pisz ForkForward.Mediator.Mediator dla klasy Mediator (inaczej CS0118)
- Nie mieszaj paczek TailoredApps.Shared.* w wersjach 2.x i 3.0 w jednej aplikacji
- 3.0 jest wersją przedpremierową: nie wdrażaj jej produkcyjnie bez wyraźnej decyzji właściciela aplikacji