Przejdź do treści

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 — LoggingBehavior zapisuje żą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 (OperationCanceledException przy 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 zapisuje An unhandled exception has occurred while executing the request. na poziomie Error i nie dodaje tagu error.type do metryki http.server.request.duration. Wyjątek trafia do logu na poziomie Debug, w kategorii TailoredApps.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() i WithValidation<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 przez ForkForward.Mediator.IMediator i odwrotnie — to różne typy. Po migracji w aplikacji nie powinno zostać żadne odwołanie do pakietu MediatR.
  • Mediator jest teraz także przestrzenią nazw. Kod, którego własna przestrzeń nazw zaczyna się od TailoredApps.Shared., a który używa klasy Mediator z ForkForward.Mediator po krótkiej nazwie, przestaje się kompilować (CS0118); trzeba tam pisać ForkForward.Mediator.Mediator. IMediator, ISender i 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.Mediator to 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 w PaymentGatewayException.InnerException (StripeException), przy odmowie komunikat Stripe jest w PaymentResponse.ResponseObject.
  • Własne typy w CashbillHttpClient.MakeFormRequest<T>() nie są już obsługiwane (NotSupportedException) — odczytaj odpowiedź jako JsonElement albo 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