Przejdź do treści

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.

  • PaymentGatewayException ma Provider, StatusCode, IsTransient (czy ponowienie ma sens) i ResponseBody.
  • Przekroczenie czasu zgłasza TaskCanceledException.
  • Stripe zgłasza awarie jako StripeException, jak w 1.x (od 3.0 także PaymentGatewayException — zob. Aktualizacja do 3.0). CashBill w 2.0.0 i 2.0.1 zgłasza jeszcze WebException; od kolejnej wersji PaymentGatewayException.

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 (nie X-Signature); w sandboxie ustaw JwsCertificateBaseUrl na https://secure.sandbox.tpay.com. Własna implementacja ITpayServiceCaller musi mieć VerifyNotificationAsync zamiast VerifyNotification.
  • Adyen: podpis jest w additionalData.hmacSignature elementu powiadomienia, nie w nagłówku. W panelu Adyen włącz podpis HMAC webhooka i skopiuj klucz do NotificationHmacKey.

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 w Rejection). Dotychczasowe Success, Ignored i ErrorMessage nadal działają.
  • CancellationToken jest 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.SlidingExpiration nie 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.

  • DateTimeProvider czyta czas z System.TimeProvider, więc w aplikacji jest jeden zegar.
  • Nowe: OffsetUtcNow i OffsetNow (DateTimeOffset) oraz rejestracja builder.Services.AddDateTimeProvider().
  • UtcTimeOfDaty (literówka) jest przestarzałe — użyj UtcTimeOfDay (usunięte w 3.0).
  • Zmiana zachowania: Now i Today raportują strefę czasową użytego TimeProvider (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: PagingAsync działa dla niepustych stron (w 1.x rzucało InvalidOperationException).
  • 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