Aktualizacja do 2.0¶
Ta strona zbiera to, co trzeba zrobić w kodzie aplikacji przy przejściu z 1.x na 2.0. Opis nowych możliwości jest na stronach poszczególnych bibliotek; tutaj są tylko zmiany, po których kod się nie skompiluje albo zachowa inaczej.
Wymagania
Biblioteki 2.0 są wydawane dla net10.0 i net11.0. Aplikacje na starszych platformach zostają przy paczkach 1.6.x
(poprawki bezpieczeństwa). Szczegóły: Platformy docelowe.
Lista kontrolna¶
| # | Biblioteka | Co zrobić | Skutek pominięcia |
|---|---|---|---|
| 1 | Payments | Łapać HttpRequestException wokół RegisterPayment i GetStatus |
Awaria bramki kończy żądanie błędem 500 |
| 2 | Payments | Ustawiać PaymentProvider, Amount i Currency w każdym PaymentRequest |
Błąd kompilacji CS9035 |
| 3 | Payments (Tpay, Adyen) | Przekazywać surowe body webhooka, odpowiadać tekstem oczekiwanym przez bramkę, podawać własny numer zamówienia | Powiadomienia są odrzucane lub ponawiane; webhooka nie da się powiązać z zamówieniem |
| 4 | Payments | Obsłużyć wynik webhooka jako jeden z trzech rekordów | — (stare właściwości działają) |
| 5 | MediatR | Usunąć rejestrację ICache, wyczyścić współdzielony cache |
Błąd kompilacji; odczyt wpisów w starym formacie |
| 6 | DateTime | Nic — opcjonalnie AddDateTimeProvider() i OffsetUtcNow |
— |
Payments¶
1. Awaria bramki jest wyjątkiem, nie statusem Rejected¶
W 1.x bramka, która odpowiedziała błędem 5xx albo odrzuciła zapytanie o status, była raportowana jako PaymentStatusEnum.Rejected.
Aplikacja działająca na podstawie tego statusu anulowała zamówienie, którego płatność mogła się udać.
W 2.0 Rejected oznacza wyłącznie odpowiedź bramki. Gdy bramka nie daje użytecznej odpowiedzi, wywołanie rzuca
PaymentGatewayException (dziedziczy po HttpRequestException) — stan płatności jest wtedy nieznany.
// 1.x
var payment = await _payments.GetStatus("Tpay", paymentId);
if (payment.PaymentStatus == PaymentStatusEnum.Rejected)
await _orders.CancelAsync(orderId); // także przy awarii bramki!
// 2.0
try
{
var payment = await _payments.GetStatus("Tpay", paymentId, cancellationToken);
if (payment.PaymentStatus == PaymentStatusEnum.Rejected)
await _orders.CancelAsync(orderId, cancellationToken); // bramka odpowiedziała: odrzucona
}
catch (HttpRequestException exception) // obejmuje PaymentGatewayException
{
// Stan płatności nieznany: zostaw zamówienie bez zmian i sprawdź ponownie później.
_logger.LogWarning(exception, "Gateway unavailable for payment {PaymentId}", paymentId);
}
To samo dotyczy RegisterPayment: błąd 5xx, 408 lub 429 przy tworzeniu płatności rzuca wyjątek, bo płatność mogła, ale nie musiała
powstać. Odpowiedź 4xx to nadal Rejected z treścią błędu bramki w ResponseObject.
PaymentGatewayExceptionmaProvider,StatusCode,IsTransient(czy ponowienie ma sens) iResponseBody.- Przekroczenie czasu zgłasza
TaskCanceledException. - Stripe zgłasza awarie jako
StripeException, jak w 1.x (od 3.0 takżePaymentGatewayException— zob. Aktualizacja do 3.0). CashBill w 2.0.0 i 2.0.1 zgłasza jeszczeWebException; od kolejnej wersjiPaymentGatewayException.
Pełna tabela przypadków: Payments — Awaria bramki to nie odmowa.
2. PaymentRequest wymaga providera, kwoty i waluty¶
PaymentProvider, Amount i Currency są składowymi required. Inicjalizator, który pominie którąś z nich, nie skompiluje się
(CS9035), a System.Text.Json odrzuci dokument bez nich — endpoint przyjmujący PaymentRequest z body odpowie kodem 400.
// 1.x — kompilowało się, błąd wychodził dopiero w bramce
var request = new PaymentRequest { Title = "Zamówienie 7", Amount = 49.99m };
// 2.0
var request = new PaymentRequest
{
PaymentProvider = "Tpay",
Amount = 49.99m,
Currency = "PLN",
Title = "Zamówienie 7",
};
// albo krócej
var request = new PaymentRequest("Tpay", 49.99m, "PLN") { Title = "Zamówienie 7" };
RegisterPayment dodatkowo odrzuca pusty klucz providera lub pustą walutę (ArgumentException) oraz kwotę mniejszą lub równą zero
(ArgumentOutOfRangeException), zanim wywoła bramkę.
3. Webhooki Tpay i Adyen¶
W 1.x weryfikacja powiadomień obu operatorów nie odpowiadała ich protokołom i odrzucała prawdziwe powiadomienia. W 2.0 działa, ale wymaga trzech rzeczy po stronie aplikacji.
a) Przekaż surowe body. Podpis obejmuje dokładne bajty żądania. Czytaj body ze strumienia — nie przez [FromForm], [FromBody]
ani ponowną serializację.
b) Odpowiedz tekstem, którego oczekuje bramka. Jest on w PaymentResponse.ResponseObject wyniku oraz w stałych
TpayProvider.Acknowledgement (TRUE) i AdyenProvider.Acknowledgement ([accepted]). Inna odpowiedź powoduje ponawianie powiadomienia.
c) Podaj własny numer zamówienia w PaymentRequest.AdditionalData. Powiadomienia Tpay i Adyen nie zawierają identyfikatora
zwróconego przez RegisterPayment. PaymentUniqueId w wyniku webhooka to wartość z AdditionalData
(Tpay: tr_crc, Adyen: merchantReference); bez niej dostaniesz tylko referencję bramki, której aplikacja nie zna.
[HttpPost("webhooks/tpay")]
public async Task<IActionResult> TpayWebhook(CancellationToken cancellationToken)
{
using var reader = new StreamReader(Request.Body, Encoding.UTF8);
var body = await reader.ReadToEndAsync(cancellationToken); // a) surowe body
var result = await _payments.HandleWebhookAsync("Tpay", new PaymentWebhookRequest
{
Body = body,
ContentType = Request.ContentType,
Headers = Request.Headers.ToDictionary(h => h.Key, h => h.Value),
}, cancellationToken);
if (result is PaymentWebhookProcessed processed)
await _orders.ApplyPaymentAsync(processed.Payment.PaymentUniqueId, processed.Payment.PaymentStatus, cancellationToken); // c) numer zamówienia
return result is PaymentWebhookRejected
? BadRequest("FALSE")
: Content(TpayProvider.Acknowledgement, "text/plain"); // b) "TRUE"
}
Dodatkowo:
- Tpay: nagłówek podpisu to
X-JWS-Signature(nieX-Signature); w sandboxie ustawJwsCertificateBaseUrlnahttps://secure.sandbox.tpay.com. Własna implementacjaITpayServiceCallermusi miećVerifyNotificationAsynczamiastVerifyNotification. - Adyen: podpis jest w
additionalData.hmacSignatureelementu powiadomienia, nie w nagłówku. W panelu Adyen włącz podpis HMAC webhooka i skopiuj klucz doNotificationHmacKey.
Szczegóły i tabele statusów: Tpay, Adyen.
4. Inne zmiany w Payments¶
- Wynik webhooka to jeden z trzech rekordów:
PaymentWebhookProcessed,PaymentWebhookIgnored,PaymentWebhookRejected(z powodem wRejection). DotychczasoweSuccess,IgnorediErrorMessagenadal działają. CancellationTokenjest opcjonalnym parametrem każdej metody asynchronicznej. Wywołania nie wymagają zmian; własny provider (IPaymentProvider,I*ServiceCaller) musi dodać ten parametr do implementowanych metod.- Walidacja konfiguracji przy starcie:
Register*Provider()zatrzymuje start hosta (OptionsValidationException), gdy brakuje danych dostępowych lub sekretu webhooka. Rejestruj tylko skonfigurowanych providerów.
Opis: Payments.
MediatR¶
CachingBehavior korzysta z HybridCache. Interfejs ICache i klasa Cache zostały usunięte razem z zależnością od Newtonsoft.Json:
- usuń własną rejestrację
ICache, ICachePolicy.SlidingExpirationnie jest już obsługiwane,- po aktualizacji wyczyść współdzielony cache albo zmień prefiks kluczy — wpisy zapisane przez 1.x mają inny format.
Ponawianie i wyłącznik obwodu nie używają już Polly. Opis: Mediator (w 2.x pod nazwą MediatR).
DateTime¶
Kod używający IDateTimeProvider nie wymaga zmian; własne implementacje interfejsu i istniejące mocki kompilują się jak dotąd.
DateTimeProviderczyta czas zSystem.TimeProvider, więc w aplikacji jest jeden zegar.- Nowe:
OffsetUtcNowiOffsetNow(DateTimeOffset) oraz rejestracjabuilder.Services.AddDateTimeProvider(). UtcTimeOfDaty(literówka) jest przestarzałe — użyjUtcTimeOfDay(usunięte w 3.0).- Zmiana zachowania:
NowiTodayraportują strefę czasową użytegoTimeProvider(dla zegara systemowego bez różnicy).
Opis: DateTime.
Pozostałe biblioteki¶
- Wszystkie: publiczne API ma adnotacje nullable — projekt z włączonym
<Nullable>enable</Nullable>może zobaczyć nowe ostrzeżenia (Platformy docelowe). - EntityFramework:
PagingAsyncdziała dla niepustych stron (w 1.x rzucałoInvalidOperationException). - WebApi: domyślna odporność klienta HTTP nie ponawia żądań zmieniających stan (WebApi — Bezpieczeństwo).
🤖 AI Agent Prompt¶
## Aktualizacja TailoredApps.Shared.* z 1.x do 2.0 — Instrukcja dla agenta AI
Aktualizujesz aplikację .NET 10 lub .NET 11 z paczek TailoredApps.Shared.* 1.x do 2.0. Wykonaj kolejno:
### Rejestracja
- Podnieś wszystkie paczki TailoredApps.Shared.* do tej samej wersji 2.x
- Usuń rejestrację ICache (MediatR); opcjonalnie dodaj builder.Services.AddDateTimeProvider()
### Co wymaga zmian w kodzie
- Payments: każde wywołanie IPaymentService.RegisterPayment i GetStatus otocz try/catch (HttpRequestException) — awaria bramki to stan nieznany, nie odmowa
- Payments: każdy new PaymentRequest musi ustawiać PaymentProvider, Amount (> 0) i Currency
- Payments: endpointy webhooków przekazują surowe body ze strumienia żądania i wszystkie nagłówki
- Tpay: odpowiedź HTTP 200 z treścią "TRUE" (TpayProvider.Acknowledgement); Adyen: "[accepted]" (AdyenProvider.Acknowledgement)
- Tpay i Adyen: ustaw PaymentRequest.AdditionalData na numer zamówienia; w webhooku dopasuj zamówienie po PaymentUniqueId
- Własne implementacje IPaymentProvider / I*ServiceCaller: dodaj parametr CancellationToken cancellationToken = default
### Konfiguracja
- Tpay sandbox: Payments:Providers:Tpay:JwsCertificateBaseUrl = "https://secure.sandbox.tpay.com"
- Adyen: Payments:Providers:Adyen:NotificationHmacKey = klucz HMAC webhooka (hex) z panelu Adyen
- Każdy zarejestrowany provider musi mieć komplet danych dostępowych i sekret webhooka, inaczej host nie wystartuje
### Zasady
- Nie anuluj zamówienia po wyjątku z RegisterPayment / GetStatus; status Rejected jest wiarygodny tylko, gdy wywołanie zwróciło wynik
- Nie czytaj body webhooka przez [FromForm] ani [FromBody] — podpis obejmuje surowe bajty
- Nie zastępuj weryfikacji podpisu stubem zwracającym true
- Po aktualizacji MediatR wyczyść współdzielony cache albo zmień prefiks kluczy
- Aplikacje na net8.0 / net9.0 / netstandard zostają przy 1.6.x — nie podnoś ich do 2.0