Zwracamy wynik operacji do WebApi

Zwracamy wynik operacji do WebApi

Wstęp

To jest artykuł z cyklu „Kij w mrowisko” i jestem pewien, że duża część czytelników się ze mną nie zgodzi. I mają do tego prawo tak samo jak ja mam prawo do wyrażenia własnego zdania 😀

Zwracanie wyniku operacji z serwisu do kontrolera WebApi bywa czasem problematyczne. Zwłaszcza widzę to u młodych osób, ale nie tylko. W tym artykule przedstawię sposoby, które znam i sposób, który polecam.

ProblemDetails

Gwoli przypomnienia, od prawie 10 lat istnieje standard, który opisuje jak powinniśmy zwracać błędy z samego WebApi do klienta. To się nazywa ProblemDetails, o którym już pisałem w tym artykule. Ale ten tekst ma być o zwracaniu rezultatu z samego serwisu, a więc lećmy dalej.

Używanie wyjątków

To chyba sposób, który budzi najwięcej kontrowersji. Ja jestem mu zdecydowanie przeciwny, ale to też „zależy”. Zatem zobaczmy, jak mogłoby to wyglądać.

Spójrzmy na fragment przykładowego serwisu, gdzie dodajemy sobie do bazy danych jakiś TodoItem:

public async Task<ToDoItem> AddItem(string title, string description, DateTimeOffset expireDate)
{
    if(_timeProvider.GetUtcNow() > expireDate)
    {
        throw new ArgumentException("Expire Date nie może być w przeszłości!");
    }

    //dalej dodajemy do bazy danych i zwracamy utworzony obiekt
    return addedItem;
}

Od strony kontrolera mogłoby to wyglądać w skrócie tak:

public async Task<IActionResult> AddItem(ToDoDto item)
{
  try
  {
      var result = await _service.AddItem(item.Title, item.Description, item.ExpireDate);
      return Created(result);
  }catch(ArgumentException ex)
  {
      return ProblemDetails(ex.Message);
  }
}

Zwracam uwagę jeszcze na to, że zamiast rzucać i łapać ArgumentException, moglibyśmy stworzyć sobie jakiś ServiceException i łapać go na poziomie middleware zamiast bezpośrednio w kontrolerze. Takie podejście zdecydowanie jest ładniejsze, czystsze i dużo bardziej użyteczne. Natomiast chodzi tutaj o samo rzucanie wyjątków.

Czy wyjątki są wyjątkowe?

Tutaj wielu czytelników się ze mną nie zgodzi. Natomiast wyjątki powinny być stosowane do obsługi wyjątkowych sytuacji. Co to jest „wyjątkowa sytuacja”? Problem, którego nie jesteśmy w stanie przewidzieć albo jesteśmy w stanie przewidzieć, ale jego wystąpienie powoduje, że dalsze działanie aplikacji (czy też konkretnej akcji) nie może zostać ukończone ani w żaden sposób poprawione.

To teraz sobie odpowiedzmy na pytanie – czy nieprawidłowe dane podane przez użytkownika to jest wyjątkowa sytuacja? Zdecydowanie nie. To jest naturalne, że użytkownik poda nieprawidłowe dane (albo przypadkiem, albo ze względu na brak walidacji na froncie, albo po prostu próbuje atakować nasz system). Nie jest to zatem sytuacja wyjątkowa i w mojej ocenie nie powinna być obsługiwana za pomocą wyjątków.

Wyjątkową sytuacją w takim systemie mógłby być problem z dobiciem się do zewnętrznego API (jeśli używamy), problem z połączeniem z bazą danych, brak pamięci na dysku/w systemie itp. Sytuacje, w których nie możemy nic zrobić, żeby system zadziałał. Nie mamy na nie w ogóle wpływu.

A jeśli użytkownik podaje nieprawidłowe dane? Możemy go poprosić o prawidłowe.

Problemy z wyjątkami

To nie jest tylko kwestia „widzi mi się”. Nie raz słyszeliśmy, że obsługa wyjątków jest wolna. Owszem, pewnie w większości przypadków w normalnym użyciu systemu nikt z nas nie zauważy tego spowolnienia. Jednak tutaj problemem może być jeszcze jedna rzecz.

Wyjątki są wolne. Co oznacza, że w specyficznych sytuacjach mogą nam dać podatność na atak DDoS. Jeśli system jest publiczny (każdy może z niego korzystać za darmo lub za opłatą), wtedy rodzi się pewne niebezpieczeństwo, że ktoś będzie chciał nas hackować. A używanie wyjątków w celu walidacji danych daje hackerowi dodatkowe możliwości.

Kiedy używać?

Oczywiście tutaj też trzeba podejść do sprawy zdroworozsądkowo. Bo jednak użycie wyjątków w takiej sytuacji jest niesamowicie wygodne. Jeśli tworzysz system tylko do użytku wewnętrznego lub jest to coś niezbyt wartego uwagi, to śmiało. Nic złego raczej się nie stanie.

Jeśli jednak to system publiczny, a nie daj Boże jakiś SaaS, to zalecam jednak unikać takiego wykorzystania wyjątków. Możesz się tu ze mną kłócić. Historia nas oceni 😉

Używanie tupli

Innym często spotykanym rozwiązaniem jest użycie prostej tupli. Powyższy kod mógłby wyglądać tak (serwis):

public async Task<(ToDoItem? Result, string? Error)> AddItem(string title, string description, DateTimeOffset expireDate)
{
    if(_timeProvider.GetUtcNow() > expireDate)
    {
        return new(null, "Expire Date nie może być w przeszłości!");
    }

    //dalej dodajemy do bazy danych i zwracamy utworzony obiekt
    return new(addedItem, string.Empty);
}

A od strony kontrolera:

public async Task<IActionResult> AddItem(ToDoDto item)
{
      var result = await _service.AddItem(item.Title, item.Description, item.ExpireDate);
      if(string.IsNullOrEmpty(result.Error))
          return Created(result.Result);
      else
          return ProblemDetails(result.Error);
}

Jest to proste rozwiązanie. Gdy idę w tym kierunku, zawsze jednak staram się tą Tuple zamieniać na zwykły rekord:

public record AddItemResult(ToDoItem? Item, string? Error);

Jest to nieco czystszym rozwiązaniem.

I o ile tutaj nie ma żadnych pozornych problemów, to nie radziłbym tego używać w większych systemach. Takie zwracanie rezultatu nie jest po prostu uniwersalne. Jednak w małych systemach działa całkiem elegancko.

Jeśli masz system, gdzie masz tylko kilka endpointów i to się nie będzie rozrastać jakoś szybko, to zdecydowanie jest to szybkie i skuteczne rozwiązanie. Ale można lepiej…

FluentResult

FluentResult to bardzo fajna biblioteka open source dostępna na Nuget. Pozwala zwrócić zarówno błędy (w liczbie mnogiej) jak i sam rezultat operacji. Jej użycie w systemie może być bardzo uniwersalne, eleganckie i wygodne.

W każdym razie powyższy kod mógłby wyglądać tak (serwis):

public async Task<Result<ToDoItem>> AddItem(string title, string description, DateTimeOffset expireDate)
{
    if(_timeProvider.GetUtcNow() > expireDate)
    {
        return Result.Fail("Expire Date nie może być w przeszłości!");
    }

    //dalej dodajemy do bazy danych i zwracamy utworzony obiekt
    return addedItem; //klasa Result sama ogarnie konwersję
}

No i od strony kontrolera:

public async Task<IActionResult> AddItem(ToDoDto item)
{
      var result = await _service.AddItem(item.Title, item.Description, item.ExpireDate);
      if(result.IsFailed)
          return ProblemDetails(result.Reasons[0].Message);
      else
        return Created(result.Value);
}

FluentResult obsługuje zarówno wyjątki, jak i obiekty implementujące jego interfejs IError. Przykład, który widzisz wyżej (Result.Fail(„błąd”)) tak naprawdę pod spodem tworzy obiekt klasy Error (która implementuje IError) i przepisuje ten błąd do niej. Potem możesz to sobie odczytać.

FluentResult ma wiele użytecznych rzeczy out-of-the-box. Potrzebujesz błąd razem z jakimś jednoznacznym kodem?

Error err = new Error("Expire Date nie może być w przeszłości!")
    .WithMetadata("ErrorCode", ValidationError);

return Result.Fail(err);

Przy czym ValidationError to object, czyli może być czymkolwiek. Intem, stringiem, kotkiem, czym sobie chcesz.

Po stronie kontrolera też to możesz odczytać na różne sposoby. Nie chcę się za bardzo rozpisywać na temat tej biblioteki, ponieważ dokumentacja jest wystarczająca.

Podsumuję tylko, że ja jej bardzo chętnie używam, a tam gdzie potrzebuję większej uniwersalności (np. konwersja błędów na ProblemDetails) wystarczy jedna mała extension method. Super też się sprawdza podczas testów jednostkowych.

To jest właśnie ten sposób, który ja polecam i sam używam.


A Wy czego używacie? Używacie wyjątków? Sprawiły Wam kiedykolwiek jakieś problemy? A może macie zupełnie inny sposób? Koniecznie podzielcie się w komentarzu.

Dzięki za przeczytanie artykułu. Jeśli coś jest niejasne albo znalazłeś gdzieś jakiś błąd, daj znać w komentarzu.

Obrazek wyróżniający: Obraz autorstwa freepik

Podziel się artykułem na:
MemoryCache i jego pułapki

MemoryCache i jego pułapki

Wstęp

IMemoryCache to jeden z mechanizmów pamięci podręcznej (cache) jakie mamy dostępne w .NET. Wykorzystujemy go w sytuacji, kiedy nasza aplikacja działa tylko na jednej maszynie (nie jest skalowana).

Jednakże domyślna implementacja tego interfejsu może czasem odnieść odwrotny skutek lub przyprawić nas o dziwne problemy. Chyba że poznamy jej zawiłości. I o tym jest ten artykuł.

IMemoryCache czyli najprostsze cachowanie w pamięci

IMemoryCache domyślnie jest zaimplementowany przez… niesamowite… MemoryCache. A, żeby móc tego użyć, wystarczy zarejestrować sobie ten cache podczas rejestracji usług:

builder.Services.AddMemoryCache();

To rejestruje nam klasę MemoryCache jako singleton z ewentualnymi opcjami. Żeby potem użyć tego w swoim serwisie, wystarczy wstrzyknąć IMemoryCache.

Pobieranie i dodawanie danych

I tutaj zaczyna się ciekawie. Najpierw powiedzmy sobie o ICacheEntry.

ICacheEntry

To właśnie obiekty implementujące ICacheEntry mogą być elementami IMemoryCache. ICacheEntry trzyma w sobie kilka przydatnych dla mechanizmu informacji. Poza oczywiście wartością, którą trzymamy w cache, posiada jeszcze informacje na temat długości swojego życia, priorytetu itd. Dojdziemy do szczegółów później.

Domyślnie ICacheEntry jest implementowany przez wewnętrzną klasę CacheEntry. Wewnętrzną (internal), a więc nie możemy utworzyć sami jej obiektu.

Dodawanie elementu do cache

IMemoryCache ma kilka metod do dodawania i pobierania danych, które jednak potrafią nam dołożyć kilku siwych włosów. Zacznijmy bez extensionów, od zupełnej podstawy

{
    using var entry = memoryCache.CreateEntry(city);
    entry.Value = new WeatherForecast();
}

Żeby lepiej to uwidocznić, to:

var entry = memoryCache.CreateEntry(city);
entry.Value = new WeatherForecast();
entry.Dispose();

W powyższych kodach city to po prostu miasto dla którego chcemy zapamiętać pogodę, a więc KLUCZ, pod którym zapisujemy konkretną wartość.

Tak, żeby dodać wartość do cache, musimy:

  • utworzyć CacheEntry za pomocą metody CreateEntry z IMemoryCache – inaczej się nie da, bo CacheEntry jest tylko internal, nie możemy sami utworzyć jego instancji,
  • przypisać wartość do CacheEntry – bez tego nie zadziała
  • wywołać Dispose na rzecz tego CacheEntry – albo jawnie, albo tak jak wyżej za pomocą using – bez tego nie zadziała.

Jak widać, musimy zrobić z tym CacheEntry zrobić dwie rzeczy:

  • dodać wartość (Value)
  • wywołać Dispose()

Dyskusji na temat tego Dispose() było już kilka, m.in. tu: https://github.com/dotnet/runtime/pull/42355 i tu: https://github.com/dotnet/runtime/issues/36392.

Nie jest to naturalne użycie, ponieważ po tym jak wywołamy Dispose(), to CacheEntry dopiero jest wrzucane do MemoryCache i tam wykorzystywane (sic!). Nie mniej jednak MS tłumaczy, że zrobienie tego inaczej byłoby breaking changem (prawda) i nie przyniosłoby wartości (zasadniczo też prawda). Więc… „jest jak jest”. I trzeba o tym pamiętać.

Musimy ten Dispose() potraktować bardziej jako „koniec konfiguracji CacheEntry” niż koniec jego życia.

Dodawanie za pomocą rozszerzenia

Dodawanie CacheEntry za pomocą metody rozszerzeń jest zdecydowanie bardziej naturalne dla nas. Rozszerzenie już samo w sobie pamięta o wykonaniu Dispose(), więc my się tym nie musimy przejmować. Wystarczy:

memoryCache.Set(city, new WeatherForecast());

Jak widać, takie dodawanie jest zdecydowanie bardziej naturalne. Musimy jednak być świadomi, że Set jest tu metodą rozszerzenia (extension method).

Używając powyższych rozwiązań musimy zrobić dwie rzeczy, żeby cache zadziałał. Spójrz na poniższy kod:

public async Task<WeatherForecast?> GetWeatherFor(string city)
{
    if (memoryCache.TryGetValue<WeatherForecast>(city, out var weather))
    {
        return weather!;
    }

    return memoryCache.Set(city, new WeatherForecast());
}

Jeśli mamy w serwisie metodą GetWeatherFor, która w parametrze przyjmuje nazwę miasta, dla którego chcemy zwrócić prognozę pogody, to żeby to wszystko elegancko zadziałało z cachem, musimy:

  • sprawdzić, czy mamy taką wartość już w cache zapisaną, jeśli tak, zwrócić ją stamtąd
  • jeśli wartości nie ma w cache, musimy ją w jakiś sposób zdobyć (np. poprzez zewnętrzne API – nie jest to pokazane w kodzie) i dopiero potem zapisać w cache i zwrócić. Metoda Set na szczęście zwraca nam wartość, którą przekazaliśmy w parametrze, więc możemy po prostu zrobić return z niej.

To jest taka opcja „krok po kroku”, która zasadniczo nie powinna rodzić pytań. Wszyscy się spodziewamy, że cache właśnie tak działa. Ale jest inna fajna metoda rozszerzenia:

public async Task<WeatherForecast?> GetWeatherFor(string city)
{
    return await memoryCache.GetOrCreateAsync(city.ToString(), async (entry) =>
    {
        await Task.Delay(1000); //kwestia poglądowa, symulacja długiej operacji

        var result = new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = "Sunny"
        };

        entry.SetValue(result);
        return result;
    });
}

GetOrCreateAsync. Co to robi? W pierwszej kolejności próbuje zwrócić z cache istniejącą wartość na podstawie przekazanego klucza. Jeśli jest, to super, zwraca i tyle. Jeśli jednak takiej wartości nie ma, to ta metoda odpala naszą funkcję, którą podaliśmy w drugim parametrze – to jest to miejsce do pobrania wartości i SKONFIGUROWANIA CacheEntry.

Co się dzieje w tej lambdzie?

Na początku robię jakiś Task.Delay, ale tylko jako kwestia poglądowa, że tu może mieć miejsce jakaś długotrwała operacja (np. pobranie danych z zewnętrznego API).

Dalej w jakiś sposób pozyskuję WeatherForecast, ustawiam go jako wartość w entry i zwracam.

Parametr entry, który otrzymujemy w parametrze naszej funkcji to jest właśnie utworzony CacheEntry. Dlatego w naszej funkcji musimy go skonfigurować.

Którą opcję wybierzesz do dodawania elementu do cache jest Twoją indywidualną sprawą. Wszystkie te metody zasadniczo robią to samo, tylko w nieco inny sposób. No i oczywiście GetOrCreateAsync jest na tyle uniwersalne, że daje nam jakby 100% użyteczności całego cache.

Typ klucza

Każda wartość w cache musi mieć swój klucz. Inaczej nie wiedzielibyśmy co dodajemy lub pobieramy. I mimo, że parametr klucz jest zawsze typu object, to tak naprawdę może być czystym stringiem. Ważne, żeby klucz miał dobrze zaprogramowaną metodęy GetHashCode i Equals.

To może być szczegół implementacyjny, ale pod spodem mamy dwa słowniki, które przechowują nasze wartości. A konkretniej dwa ConcurrentDictionary (ale nie daj się zwieść, że MemoryCache jest thread safe – o tym później). Jeden z tych słowników przechowuje wartości z kluczem object, a drugi ze stringiem. I po prostu mechanizm sam rozpoznaje, czy podaliśmy w kluczu string, czy nie (if key is string...). Następnie dodaje wartość do odpowiedniego słownika.

Dlaczego tak? To jest tak naprawdę zależne od wersji .NET. Domyślny hash stringów kiedyś pozwalał na atak Hash Collision Atack. Natomiast teraz używany jest przy stringach „Marvin Hash”, który jest odporny na te ataki, czyli mamy zwiększone bezpieczeństwo.

Jednak trzeba pamiętać, że stringi są porównywane w zależności od wielkości znaków. Czyli klucze „Łódź” i „łódź” będą innymi kluczami.

Ustawienia CacheEntry

CacheEntry, jak i całe MemoryCache ma swoje ustawienia, które KONIECZNIE powinniśmy uwzględnić. Albo podczas dodawania (konfiguracji tak naprawdę) CacheEntry do cache, albo podczas rejestracji usług.

Co jest problemem, jeśli tego nie zrobimy? Cache jest przechowywany w pamięci RAM. Domyślnie wszelkie wartości jakie wrzucamy, nigdy nie giną. No, dopóki aplikacja żyje oczywiście 🙂

Co nam to daje? Pewnie się domyślasz. Ciągle tylko dokładamy do RAMu nowe dane, co w końcu doprowadzi do Out Of Memory.

Zatem musimy koniecznie zatroszczyć się o odpowiedni czas przechowywania danych w cache. Co to znaczy „odpowiedni”? To oczywiście zależy od konkretnej aplikacji. Bo czasem wartości mogą żyć dłużej (jak w przypadku prognozy pogody), czasem powinny nieco krócej, a w specyficznych aplikacjach używanie cache w ogóle nie ma sensu. Dlatego sam musisz odpowiedzieć na pytanie – jak długo ta dana może leżeć w cache.

Czas życia CacheEntry

Mamy kilka metod, żeby określić czas życia konkretnej danej w cache:

  • AbsoluteExpiration – gdzie podajemy konkretną datę i czas, do której wartość ma żyć (np. do 5 stycznia 2026 roku, do godziny 17:03)
  • AbsoluteExpirationRelativeToNow – zdecydowanie bardziej użyteczna, gdzie podajemy po prostu ile czasu ma żyć jako TimeSpan. Czyli konkretnie: 10 minut, 1 dzień itd.
  • SlidingExpiration – analogicznie jak AbsoluteExpirationRelativeToNow z tą różnicą, że ten czas odświeża się zawsze po pobraniu danej.
  • ExpirationToken – o tym niżej.

Czyli jeśli aktualnie mamy godzinę 17:00:00 i ustawimy AbsoluteExpirationRelativeToNow na 10 minut, to niezależnie od tego, ile razy w ciągu tych 10 minut będziemy pobierać daną z cache, to o 17:10:00 skończy się jej życie i zostanie usunięta.

Jeśli jednak użyjemy SlidingExpiration, to te 10 minut będzie liczone od nowa po każdym pobraniu danej. Czyli jeśli daną pobierzemy o 17:05, to życie skończy się jej dopiero o 17:15. Ale jeśli pobierzemy ją znowu o 17:07, to wydłuży jej życie do 17:17. Właściwość SlidingExpiration możesz znać z mechanizmu ciastek, gdzie działa dokładnie w taki sam sposób.

Ale uwaga, tutaj jest kolejna pułapka. Mechanizm odpowiedzialny za usuwanie danych z cache, bo ich czas się skończył, nie obsługuje żadnego timera. Czas ich życia jest sprawdzany po prostu przy każdej operacji z nimi związanej, czyli dodawanie nowej wartości, odczyt itd. Więc w bardzo specyficznych warunkach (raz dodamy daną do cache i nigdy nic więcej z tym cachem nie zrobimy) wartość może żyć wiecznie 🙂 Ale to raczej warunki niespotykane.

ExpirationToken

Mamy w .NET taki interfejs jak IChangeToken. Służy on do implementacji klas, które „monitorują” jakieś zdarzenia. Ustawienie ExpirationToken spowoduje usunięcie wartości z cache, gdy dane zdarzenie wystąpi. A co to może być za zdarzenie? Jakiekolwiek. Zmiana zawartości pliku na dysku, event związany z bazą danych albo cokolwiek sobie wymyślimy. Weźmy pod uwagę przykładowo zmianę zawartości pliku na dysku.

Scenariusz jest taki, że trzymamy dane z pliku w cache i monitorujemy zmianę tego pliku. Można by to ogarnąć w taki sposób:

Najpierw rejestrujemy odpowiedniego FileProvidera:

builder.Services.AddSingleton<IFileProvider>(new PhysicalFileProvider(@"C:\temp"));

A teraz możemy już pobrać token, który powie nam, czy plik się zmienił i dodać go do CacheEntry:

public class WeatherService(IMemoryCache memoryCache, 
    IFileProvider _fileProvider) : IWeatherService
{
    public async Task<WeatherForecast?> GetWeatherFor(string city)
    {
        return await memoryCache.GetOrCreateAsync(city.ToString(), async (entry) =>
        {
            // zaczynamy plik obserwować
            IChangeToken changeToken = _fileProvider.Watch("data.txt");

            // pobieramy dane z pliku
            var data = await File.ReadAllTextAsync(@"C:\temp\data.txt");

            // dodajemy token zmiany do pamięci podręcznej
            entry.AddExpirationToken(changeToken);

            // zapisujemy dane do pamięci podręcznej
            entry.SetValue(data);

            return JsonSerializer.Deserialize<WeatherForecast>(data);
        });
    }
}

Tylko UWAGA!

Tutaj za czas życia wartości w cache odpowiada ten token, a nie czas. Natomiast zasada sprawdzania, czy czas życia danej w cache się skończył jest dokładnie taka sama jak w poprzednim przypadku. Czyli mechanizm sprawdza tylko przy jakiejś operacji na danych (dodawanie, odczyt, usuwanie).

Możemy też jednocześnie ustawić konkretny czas życia (np. na 5 minut), jak również dodać token. Jednak nie łączmy ze sobą różnych form wygasania po czasie, bo to po prostu nie ma sensu.

A może by tak IDisposable?

A gdybyśmy chcieli trzymać obiekt implementujący IDisposable? Hmm. Stwórzmy sobie do tego celu czystą klasę implementującą IDisposable:

public class MyDisposable : IDisposable
{
    private bool disposedValue;

    protected virtual void Dispose(bool disposing)
    {
        if (!disposedValue)
        {
            disposedValue = true;
        }
    }

    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this);
    }
}

I teraz lekko zmienię metodę GetWeatherFor, żebyśmy mogli tę klasę wykorzystać:

public async Task<IDisposable?> GetWeatherFor(string city)
{
    return await memoryCache.GetOrCreateAsync(city.ToString(), async (entry) =>
    {
        var d = new MyDisposable();
        entry.SetValue(d);
        entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(10);
        return d;
    });
}

Tworzymy sobie nasz obiekt i dodajemy go do cache w taki sposób, żeby żył tylko 10 sekund. I co się okazuje? Klops, dupa zbita. Obiekt implementujący IDisposable nigdy nie jest zwalniany, co może doprowadzić do poważnych wycieków pamięci i w gruncie rzeczy do Out Of Memory.

Jak sobie z tym poradzić?

Na szczęście CacheEntry ma specjalną metodę, którą wywołuje w momencie gdy jest usuwany z cache. Czyli nasz kod, powinniśmy zmienić na taki:

public async Task<IDisposable?> GetWeatherFor(string city)
{
    return await memoryCache.GetOrCreateAsync(city.ToString(), async (entry) =>
    {
        var d = new MyDisposable();
        entry.SetValue(d);
        entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(10);
        entry.RegisterPostEvictionCallback((key, value, reason, state) =>
        {
            if (value is IDisposable disposable)
            {
                disposable.Dispose();
            }
        });
        return d;
    });
}

Metoda rozszerzenia RegisterPostEvictionCallback rejestruje nam w prosty sposób właśnie taki callback, który zostanie wywołany, gdy z jakiegoś powodu wartość będzie usuwana z cache. To może być po prostu koniec życia albo po prostu zwykłe usunięcie przez użytkownika. To jest to miejsce, gdzie możemy po sobie posprzątać.

A kiedy wybuchnie?

Niestety trzymanie w cache obiektu implementującego IDisposable niesie za sobą jeszcze jedno niebezpieczeństwo. Mianowicie możemy ten obiekt zdisposować w innym miejscu.

Wtedy w cache będziemy przetrzymywać obiekt, który… no jest trupem. Takie „zombie”. Jeśli teraz pobierzemy takie zombie i będziemy chcieli użyć, no to BUM!

Zatem rada jest taka:

Nie przechowuj w cache obiektów implementujących IDisposable

A jak z wielowątkowością?

Memory cache NIE JEST thread safe

W związku z tym, że MemoryCache pod spodem używa ConcurrentDictionary, uważa się, że jest wątkowo bezpieczny. Ale nie jest tak do końca.

Fakt – MemoryCache jest bezpieczny pod kątem samego dodawania lub pobierania wartości (w końcu mamy Concurrent Dictionary). Ale problemem jest to, co dzieje się na zewnętrz tego cache – w naszym kodzie.

Możemy doświadczyć race condition i innych problemów z wątkami. Przykładowo callback zarejestrowany w CacheEntry może przyjść z zupełnie innego wątku, niż ten, w którym utworzyliśmy i dodaliśmy obiekt do cache. To może być istotne w pewnych sytuacjach. A co do race condition… Spójrz na ten prosty kodzik:

if (!cache.TryGetValue("key", out var value))
{
    // <- w tym momencie inny wątek może już dodać wartość
    value = LoadFromDb();
    cache.Set("key", value);
}

Co się może zadziać w tym przypadku?

  • wątek A robi TryGetValue – dostaje false, bo w cache nie ma jeszcze takiej wartości
  • wątek B robi TryGetValue – dostaje false, bo w cache nie ma jeszcze takiej wartości
  • oba wątki pobierają dane z bazy
  • oba wątki dodają wartość do cache

W efekcie:

  • powielamy zapytanie do bazy danych (co może być kosztowną operacją)
  • jeden wpis nadpisuje drugi

Ale jeszcze ciekawszy przypadek, który może pomóc zobrazować skalę problemu:

int data = 0;

Parallel.For(0, 10, _ =>
{
    var cachedItem = memoryCache.GetOrCreate<int>("data", _ => Interlocked.Increment(ref data));
    Console.WriteLine($"Cached Item: {cachedItem}");
});

Co tu chcemy osiągnąć?

Robimy równoległą pętlę, która ma 10 iteracji. W każdej iteracji pętli pobieramy z cache wartość pod kluczem „data” lub dodajemy, jeśli takiej nie ma. W efekcie chcielibyśmy otrzymać na konsoli dziesięć jedynek – ponieważ na początku dodaliśmy wartość 1 pod kluczem data. A co otrzymujemy? U mnie to było:

Cached Item: 3
Cached Item: 5
Cached Item: 6
Cached Item: 2
Cached Item: 1
Cached Item: 4
Cached Item: 4
Cached Item: 4
Cached Item: 4
Cached Item: 7

U Ciebie będą pewnie nieco inne wyniki, natomiast nie uzyskamy tego, czego się spodziewamy. Ponieważ operujemy na MemoryCache z różnych wątków.

Zatem mimo wątkowo bezpiecznych mechanizmów w środku, MemoryCache nie jest wątkowo bezpieczny.

Jak temu zaradzić? Mamy dwie opcje:

  • używać podwójnych locków (podobnie jak przy klasycznym singletonie)
  • używać biblioteki LazyCache.

Biblioteka LazyCache gwarantuje nam już jednorazową inicjalizację cache nawet z wielu wątków. Nie jest jednak spójna z interfejsem IMemoryCache, bo służy do trochę innych rzeczy. Ale to nie jest artykuł o tej bibliotece.

Usuwanie danych

Pomówmy sobie jeszcze o usuwaniu danych. Mamy do tego właściwie trzy możliwości:

  • automatyczne usuwanie danych na podstawie czasu ich życia lub tokenu,
  • usunięcie danych ręcznie,
  • usuwanie danych, gdy cache przekroczy ustawiony limit.

O pierwszym sposobie już pisałem wyżej. Drugi – no to po prostu wywołanie metody Remove, więc nie ma o czym gadać. Natomiast dość ciekawy jest trzeci sposób.

Limitowanie wielkości cache

Jak już pisałem wyżej, domyślnie MemoryCache nie ma żadnych ograniczeń. Więc jeśli nie ustawiamy czasu życia poszczególnych elementów, możemy dojść do OutOfMemory.

Ale jest dodatkowa opcja limitowania cache, którą warto rozważyć. A mianowicie ustawianie limitu wielkości cache. Robimy to podczas tworzenia cache lub jego rejestracji:

builder.Services.AddMemoryCache(o =>
{
    o.SizeLimit = 100;
    o.CompactionPercentage = 0.2f;
});

I co tu się zadziało?

Ustawiliśmy limit cache na 100. Teraz pytanie – czym jest to 100. To jest jednostka wybrana przez Ciebie. Sam decydujesz o tym, ile to jest 1. Tu nie chodzi o bajty, megabajty ani inne takie. Programista sam sobie ustala jednostkę, a potem musi się jej trzymać.

To teraz drugie pytanie – skąd cache ma wiedzieć, kiedy doszedł do limitu pamięci?

Ponieważ, gdy ustawiasz limit pamięci, to każdemu elementowi, który wkładasz do cache, musisz ustawić rozmiar, jaki zajmuje w TWOJEJ JEDNOSTCE (jeśli tego nie ustawisz, apka się wywali).

Np.:

memoryCache.Set("test", 200, new MemoryCacheEntryOptions
{ 
    Size = 1
});

Dodaję wartość 200 do cache. Dodatkowo podaję, ile przestrzeni zajmuje w moich jednostkach. W moim przypadku wartość 200 zajmuje 1.

Takie zarządzanie ma swoje plusy i minusy. Z jednej strony, przy moim pierwszym spotkaniu z tym limitem byłem przekonany, że wszędzie są po prostu bajty. A to oczywiście bzdura. Dajmy na to, jeśli w cache umieszczasz stringi, sam określasz ich długość. Czy to jest JEDEN string, czy ten string zajmuje przestrzeń równą ilości znaków.

Czyli sam sobie ustalasz tę jednostkę i musisz się jej spójnie trzymać w systemie.

To teraz kolejne pytanie – czym jest CompactionPercentage?

To jest informacja, o ile procent ma się zmniejszyć cache w momencie przekroczenia limitu.

Czyszczenie cache po przekroczeniu limitu

Weźmy pod uwagę taki kodzik:

for (int i = 0; i < 200; i++)
{
    memoryCache.Set("test" + i, i, new MemoryCacheEntryOptions
    { 
        Size = 1
    });
}

Wcześniej ustawiłem rozmiar cache na 100. Tutaj każdy element ma rozmiar 1. To znaczy, że w cache mogę mieć 100 takich elementów. W momencie, gdy będę chciał dodać kolejny, mechanizm się jorgnie, że cache przekroczyłby swój limit, zatem robi „kompakt”. A więc usuwa inne elementy. Ile? Tyle procent, ile ma określone w CompactionPercentage. Określiłem to na 20%, więc w tym wypadku usunie 20 elementów (bo każdy z nich ma rozmiar 1). A skąd wie, co ma usunąć?

Najpierw usuwa elementy, którym skończył się czas życia (jeśli w ogóle takie są).

Jeśli nadal musi usuwać elementy, to usuwa elementy względem nadanego im priorytetu:

  • Niski – CacheItemPriority.Low
  • Normalny (domyślny priorytet dla CacheEntry) – CacheItemPriority.Normal
  • Wysoki – CacheItemPriority.High

Z każdej tej listy usuwa elementy zgodnie z polityką LRU – Least Recently Used. To znaczy, że zaczyna usuwać najpierw te elementy, które były najdłużej nieużywane.

Mechanizm cache po każdym pobraniu elementu zmienia czas jego ostatniego użycia. To znaczy, że jeśli długo nie odczytujesz jakiegoś elementu, to ostatnio był używany „dawno temu”. Dla cache to informacja, że możliwe że już nie będzie używany.

Więc usuwa te elementy w konkretnej kolejności – od najdłużej nieużywanego (czas ostatniego dostępu najmniejszy).

Rzecz jasna po usunięciu każdego elementu sprawdza, ile odzyskał miejsca. Jeśli dojdzie do tej wartości określonej w CompactionPercentage przestaje usuwać dalej.


Chyba nie ma więcej problemów związanych z tym mechanizmem, jednak jeśli mi coś umknęło koniecznie daj znać w komentarzu.

Dzięki za przeczytanie tego artykułu. Jeśli coś nie jest jasne lub zauważyłeś gdzieś błąd, koniecznie daj znać. A może chcecie więcej artykułów o cache? W sumie i tak zamierzam je napisać 😀

Podziel się artykułem na:
Jak trzymać tokeny w SPA, czyli Backend For Frontend

Jak trzymać tokeny w SPA, czyli Backend For Frontend

Wstęp

Gdy łączymy aplikację frontową (typu SPA) z jakąś formą autoryzacji, np. OAuth, bardzo chętnie trzymamy sobie tokeny autoryzacyjne gdzieś na froncie. Spora ilość odpowiedzi na pytanie „gdzie trzymać tokeny” sugeruje, że to powinien być local storage. A niektóre, że ciastko. Ale odpowiedź jest jedna:

Nigdy nie trzymaj tokenów autoryzacyjnych na froncie.

W tym artykule pokażę jak to zrobić poprawnie – i będziemy mimo wszystko robić tylko backend. Artykuł nie ma nic wspólnego z OAuth, jest bardziej ogólny, ale to co tutaj zrobimy bez problemu nadaje się do zaadaptowania w systemie, w którym dostajemy jakiś token autoryzacyjny.

Przygotowałem też na GitHub prostą implementację tego, co tu robimy. Uwaga! Potraktuj ten kod jako wyznacznik, a nie jako gotową implementację. Ten kod raczej obrazuje jak takie BFF zrobić i należy go dostosować do własnych wymagań. Pobierz go stąd.

NuGet gotowy do użytku

Jeśli chcesz użyć gotowego NuGeta, który zapewnia Ci funkcjonalność BFF, to stworzyłem coś specjalnie na tą okazję. Do pobrania:

dotnet add package Nerdolando.Bff.AspNetCore

No i do poczytania na GitHub: https://github.com/Nerdolando/Nerdolando.Bff

To jest jednocześnie mój pierwszy taki OpenSource, więc zachęcam do współpracy 🙂

Dlaczego nie mogę trzymać tokenu na froncie?

Odpowiedź na to pytanie jest szalenie prosta. Nigdy nie wiesz, jaki kod działa na froncie. I to właściwie tyle. Token autoryzacyjny może zostać wykradziony. Wtedy dupa zbita. Konto może zostać przejęte.

I już widzę te słowa oburzenia: „Jak to nie wiem, jaki kod działa na froncie? W końcu sam go pisałem!”.

Jesteś pewien, że jeśli tworzysz front to sam piszesz kod? 🙂

Przy Blazor jest trochę lepiej, ale jeśli piszesz w JavaScript, używasz różnych bibliotek, które też mają swoje zależności, a te zależności mają inne zależności. Niestety mało kto zwraca uwagę na bezpieczeństwo na etapie zależności bibliotek, chociaż npm ma do tego jakieś narzędzia.

I co w związku z tym? Na jakimś etapie możesz niejawnie wykorzystywać bibliotekę, która jest podatna na różne ataki.

Ale ok, załóżmy że masz super restrykcyjną politykę bezpieczeństwa i każda zależność każdej zależności dla każdej biblioteki którą używasz jest sprawdzana i walidowana. I tu wchodzi rola użytkownika 😉

Użytkownik może mieć zainstalowany w przeglądarce złośliwy lub podatny dodatek. No i sorry – na to już żadnego wpływu nie masz.

Czyli – nigdy nie wiesz, jaki kod jest wykonywany na froncie. A jeśli kod Twojej aplikacji ma dostęp do tokenu, to każdy kod, który działa na Twoim froncie też ma do niego dostęp.

No to gdzie mam trzymać tokeny?

Nigdzie. Jeśli tworzysz aplikację typu SPA nigdy nie trzymaj tokenu. Istnieją dwie inne opcje, którymi możesz się posłużyć.

Service Worker

Service Worker to stosunkowo młody byt. To w gruncie rzeczy jakiś fragment funkcjonalności, który pełni rolę reverse proxy. Ale jeśli chciałbyś prawilnie i bezpiecznie używać np. OAuth (albo innego systemu autoryzacji), to musiałbyś całą funkcjonalność z tym związaną przenieść do Service Workera, co jednak nie jest tak prostym i trywialnym zadaniem.

Nie będziemy się zagłębiać w ten temat, bo jest to blog jednak backendowy, ale jeśli chcesz poczytać więcej na ten temat, to masz tutaj dokumentację: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API

BFF, czyli Backend For Frontend

No i teraz dochodzimy do sedna. BFF to zwykła aplikacja backendowa, która w całym systemie pełni rolę prostego reverse proxy. Zasada jest taka, że to BFF otrzymuje tokeny autoryzacyjne. Co więcej, to BFF komunikuje się z WebApi, które gdzieś tam jest pod spodem, a nie aplikacja frontowa. Podsumowując:

  • BFF to proste reverse proxy
  • Front komunikuje się TYLKO z BFF
  • BFF komunikuje się z serwerem autoryzacyjnym i WebApi
  • BFF przechowuje i/lub szyfruje tokeny
  • Front NIGDY nie komunikuje się z WebApi bezpośrednio

Jeśli weźmiemy sobie pod uwagę autoryzację OAuth, to uwzględniając BFF będzie to wyglądało tak:

Oczywiście istotne jest, że jeśli używamy OAuth, to musimy w tym momencie przestać używać przestarzałego Implicit flow, a zamiast tego użyć prawilnego Authorization Code flow i nasze BFF wtedy przejmuje rolę klienta, a nie apka frontowa.

Po lewej stronie mamy aplikację SPA, po środku nasze BFF, na górze „fabryka” reprezentuje serwer autoryzacyjny, a na niebiesko po prawej stronie przedstawione jest nasze API, do którego dobijamy się tokenem.

I teraz tak:

  1. Aplikacja SPA strzela do serwera autoryzacyjnego po Authorization Code
  2. Serwer autoryzacyjny oddaje SPA authorization code
  3. Aplikacja SPA przekazuje Authorization Code do BFF i BFF rozpoczyna już prawilną sesję logowania
  4. BFF otrzymuje w końcu od serwera autoryzacyjnego Access Token i opcjonalny Refresh Token
  5. BFF albo to sobie gdzieś zapisuje albo szyfruje i następnie tą informację wysyła do frontu jako HTTP Only, Secure cookie.
  6. Aplikacja z każdym żądaniem do BFF dołącza to cookie
  7. BFF odczytuje sobie dane z cookie i pobiera / odszyfrowuje tokeny
  8. BFF dołącza tokeny do requestu wysyłanego do WebApi
  9. BFF wysyła request do WebApi

Jak niby aplikacja SPA ma dołączyć ciastko, które jest HttpOnly?

No to tak. Ciastko HttpOnly to takie ciastko, którego żaden JavaScript nie będzie w stanie odczytać. To jasne – tu jesteśmy bezpieczni. Nie dość, że jeśli access token jest w ciastku, to jest też tak zaszyfrowany, że tylko BFF potrafi go odszyfrować. No i fajnie, bo Access Tokeny nie są przewidziane do używania na froncie. Czyli jesteśmy podwójnie chronieni nawet jeśli ten token jest zapisany w ciastku.

Ale, ale. Na froncie są metody, żeby dołączyć takie ciastko do wysyłanego żądania. Niezależnie od tego, czy używasz fetcha, axiosa, czy czegoś innego, każda z tych bibliotek ma (albo mieć powinna) taką opcję jak credentials, withCredentials, includeCredentials itp. W zależności od biblioteki. Przy takim ustawieniu HttpOnly cookie zostanie dołączone do requesta.

Jedziemy z implementacją

Implementacja tego cuda jest zasadniczo prosta. Istnieją jakieś biblioteki, które nam w tym pomagają (np. Duende coś ma, no i oczywiście moja darmowa wyżej wspomniana: https://github.com/Nerdolando/Nerdolando.Bff), ale polecam napisać własny fragment kodu, który będzie stosowany tylko w naszej apce. Dzięki temu możesz poznać mechanizm bardzo głęboko. Niemniej jednak będziemy posługiwać się biblioteką Yarp.ReverseProxy. (w moim NuGet nie stosujemy całego Yarpa, tylko jakąś jego część).

A więc w pierwszej kolejności utwórz sobie nowy projekt WebApi, z którego zrobimy BFF i zainstaluj ReverseProxy:

dotnet add package Yarp.ReverseProxy

Jeśli nie posługiwałeś się wcześniej tą biblioteką, możesz sobie poczytać więcej w dokumentacji.

W każdym razie takie ReverseProxy trzeba wstępnie skonfigurować, można to zrobić albo przez appsettings albo w kodzie. Ja Ci pokażę to na przykładzie appsettings, żeby nie zaciemniać obrazu.

Konfiguracja proxy

Zrobimy podstawową konfigurację w pliku appsettings.json. Można oczywiście zrobić konfigurację w odpowiednich klasach w runtime, ale na potrzeby prostego BFF taka konfiguracja jest wystarczająca.

"ProxyConfig": {
  "Routes": {
    "ApiRoute": {
      "ClusterId": "ApiCluster",
      "Match": {
        "Path": "/api/{**catch-all}"
      }
    }
  },
  "Clusters": {
    "ApiCluster": {
      "Destinations": {
        "ApiDestination": {
          "Address": "https://localhost:7034/"
        }
      }
    }
  }
}

Co się dzieje w tej konfiguracji?

To najprostsza chyba konfiguracja Reverse Proxy. Czyli: „gdy przyjdzie żądanie na Route o danym adresie (Match/Path), prześlij je na Cluster o danym Id (ClusterId)”.

U nas wszystkie żądania jakie przyjdą do BFF na adres /api/* zostaną przesłane dalej na adres odpowiedniego klastra, czyli w tym przypadku – klaster o Id ApiCluster, który ma zdefiniowany adres: https://localhost:7034. W rzeczywistej aplikacji to będzie adres Twojego WebApi.

Teraz trzeba dodać sobie Proxy do naszej apki. Po zainstalowaniu pakietu Yarp.ReverseProxy, nasz plik Program.cs może wyglądać tak:

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddReverseProxy()
            .LoadFromConfig(builder.Configuration.GetSection("ProxyConfig"));

        var app = builder.Build();

        // Configure the HTTP request pipeline.

        app.UseHttpsRedirection();

        app.MapReverseProxy();

        app.Run();
    }
}

Dodajemy sobie serwisy odpowiedzialne za działanie Reverse Proxy (linia 7) wraz z konfiguracją (linia 8) i wpinamy proxy do pipeline (linia 16) – bo tak trzeba.

W tym momencie mamy już działające proxy. Ale to jeszcze nie jest BFF, to jest samo właściwie proxy, które nie robi niczego poza przekazywaniem żądania dalej.

Dodajemy CORSy

Kolejny krokiem jest obsługa CORS. Jeśli nie wiesz, czym jest CORS, miałem o tym artykuł: Ten cholerny CORS dogłębnie.

Teraz metoda Main może wyglądać tak:

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    // Add services to the container.

    builder.Services.AddReverseProxy()
        .LoadFromConfig(builder.Configuration.GetSection("ProxyConfig"));

    var corsOrigins = builder.Configuration.GetSection("CorsOrigins").Get<string[]>()!;
    var corsExposedHeaders = builder.Configuration.GetSection("CorsExposedHeaders").Get<string[]>()!;
    builder.Services.AddCors(o =>
    {
        o.AddDefaultPolicy(builder =>
        {
            builder.AllowAnyMethod()
                .AllowAnyHeader()
                .WithOrigins(corsOrigins)
                .AllowCredentials()
                .WithExposedHeaders(corsExposedHeaders);
        });
    });

    var app = builder.Build();

    // Configure the HTTP request pipeline.

    app.UseHttpsRedirection();
    app.UseCors();

    app.MapReverseProxy();

    app.Run();
}

ZAKŁADAJĄC, że w konfiguracji mamy dozwolone originy, z których przychodzą żądania (sekcja CorsOrigins), musimy je dodać do metody WithOrigins (linia 18). Analogicznie z nagłówkami. Jeśli nasze PROXY może emitować niestandardowe nagłówki, musimy je dodać do WithExposedHeaders.

Tutaj cholernie ważna jest metoda AllowCredentials. Bez tego nie otrzymamy z frontu ciastka HttpOnly. A właściwie żądanie z takim ciastkiem zostanie zablokowane przez politykę CORS, więc zakończy się failem. Dlatego AllowCredentials musi tutaj być.

Przypominam – nie wiesz dokładnie co to CORS? To przeczytaj tutaj.

Transformacje – czyli serce BFF

Ok, mamy już reverse proxy, mamy politykę CORS, ale brakuje nam ostatniej rzeczy.

Jakoś tokeny autoryzacyjne musimy zapisać i jakoś je musimy odczytać. Do tego służą transformacje, które są częścią Yarp.ReverseProxy.

Czym jest transformacja? Generalnie możemy w jakiś sposób zmienić request, który do nas przychodzi (np. z frontu) przed przesłaniem go do WebApi, ale też możemy zmienić odpowiedź, która do nas przychodzi np. z WebApi zanim zostanie przekazana na front.

W związku z tym mamy jakby dwa rodzaje transformacji:

  • RequestTransform
  • ResponseTransform

Weźmy się najpierw za RequestTransform, czyli transformacja, gdzie działamy na danych pochodzących z frontu.

Request Transform

Najpierw musimy stworzyć sobie klasę dziedziczącą po RequestTransform. Pusta wygląda tak:

internal class AccessTokenRequestTransform : RequestTransform
{
    public override async ValueTask ApplyAsync(RequestTransformContext context)
    {
        
    }
}

Metoda ApplyAsync zostanie wywołana, gdy przyjdzie do nas żądanie z frontu, zanim zostanie przekazane dalej. W parametrze context mamy wszystko, co potrzebujemy, żeby bawić się żądaniem.

I w gruncie rzeczy to, jak powinna wyglądać ta metoda dokładnie, to już zależy od konkretnego systemu. Ja Ci podam tylko przykład, który wydaje się być w miarę uniwersalny.

UWAGA! W moim przykładzie trzymam zaszyfrowane tokeny w ciastku. Można też to zrobić inaczej. W ciastku trzymać jakieś Id (zaszyfrowane najlepiej), które doprowadzi do tokenu zapisanego w jakiejś bazie danych (chociażby Redis).

Tutaj scenariusz jest taki, że BFF po otrzymaniu tokenów szyfruje je, wrzuca w ciastko i wysyła na front.

Gdy front chce wysłać żądanie do API, przesyła z nim to ciastko (oczywiście HttpOnly, Secure) i BFF je odczytuje, a więc bardzo abstrakcyjnie:

internal class AccessTokenRequestTransform(IAuthCookieService _authCookieService, 
    IAccessTokenEncoder _tokenEncoder) : RequestTransform
{
    public override async ValueTask ApplyAsync(RequestTransformContext context)
    {
        var cookieValue = _authCookieService.ReadFromRequest(context);
        if (string.IsNullOrEmpty(cookieValue))
            return;

        var tokens = _tokenEncoder.DecodeTokens(cookieValue!);
        if (tokens != null)
            tokens = await RefreshTokensIfNeeded(context, tokens);

        if (tokens != null)
            AddAuthHeader(context, tokens.AccessToken);

        _authCookieService.RemoveAuthenticationCookie(context);
    }

    private Task<AuthTokenModel> RefreshTokensIfNeeded(RequestTransformContext context, AuthTokenModel tokens)
    {
        tokens.ValidTo = tokens.ValidTo.AddMinutes(15); //duży skrót myślowy, tu powinno być prawilne odświeżenie
        return Task.FromResult(tokens);
    }

    private void AddAuthHeader(RequestTransformContext context, string accessToken)
    {
        context.ProxyRequest.Headers.Add("Authorization", $"Bearer {accessToken}");
    }
}

Zadziało się sporo, ale już wszystko tłumaczę.

Na początku wstrzykujemy sobie dwa HIPOTETYCZNE serwisy, których zadaniem jest:

  • IAuthCookieService – odczyt danych z konkretnego ciasteczka
  • IAccessTokenEncoder – szyfrowanie i deszyfrowanie tokenów

Podstawowa implementacja tych serwisów jest zrobiona na GitHub. Nie ma tam niczego ciekawego, więc się tym nie zajmujemy.

I teraz metoda ApplyAsync:

  1. Pobieramy wartość z otrzymanego ciasteczka (powinien tam być zaszyfrowany token).
  2. Jeśli wartości nie ma (nie ma ciasteczka) nie robimy transformacji. Request jest po prostu przekazywany dalej bez żadnych zmian.
  3. Jeśli wartość była, to ją odszyfrowujemy. Po odszyfrowaniu powinniśmy otrzymać jakiś obiekt, który przechowuje token i informacje o nim.
  4. Sprawdzamy, czy token należy odświeżyć. W tym przykładowym systemie token powinniśmy odświeżyć jeśli wygaśnie w ciągu 5 minut. Pamiętaj, że to jest tylko przykład. W Twoim systemie wymaganie może być zupełnie inne. Zwróć też uwagę na metodę RefreshTokensIfNeeded – gdzie pokazałem zupełnie niepoprawne odświeżanie tokenów. Jednak przykładowy kod nie ma żadnego miejsca, które tokeny wydaje, więc potraktuj metodę RefreshTokensIfNeeded jako duży skrót myślowy.
  5. Dalej mamy metodę AddAuthHeader, która dodaje AccessToken do nagłówka autoryzacyjnego. Tutaj to też jest tylko przykład. Ale w prawdziwym systemie tokeny będą pewnie dodawane do jakiegoś nagłówka.
  6. No i na koniec USUWAMY ciasteczko z requestu, bo nie chcemy go przesyłać do WebApi.

Response Transform

W znakomitej większości przypadków nie będziesz potrzebował tej transformacji. Tutaj wchodzi żądanie z WebApi i przekazywane jest na front.

Jednak tokeny autoryzacyjne przeważnie będziesz otrzymywał z innego źródła. Jednak jeśli Twoje WebApi wystawia taki token, w takim przypadku powinieneś utworzyć taką transformację. Tutaj też tylko zarys, bo zasada jest dokładnie taka sama jak wyżej:

internal class AccessTokenResponseTransform(IAccessTokenEncoder _tokenEncoder,
    IAuthCookieService _authCookieService) : ResponseTransform
{
    public override async ValueTask ApplyAsync(ResponseTransformContext context)
    {
        var tokenModel = await ReadTokenModelFromBody(context) ?? context.HttpContext.GetTokens();
        if (tokenModel == null)
            return;

        var cookieValue = _tokenEncoder.EncodeTokens(tokenModel);
        _authCookieService.AddAuthCookieToResponse(context, cookieValue);
    }


    private async Task<AuthTokenModel?> ReadTokenModelFromBody(ResponseTransformContext context)
    {
        if (context.ProxyResponse == null)
            return null;

        if (!context.ProxyResponse.Headers.HasAuthToken())
            return null;

        var result = await context.ProxyResponse.Content.ReadFromJsonAsync<AuthTokenModel>();
        context.SuppressResponseBody = true;
        return result;
    }
}

Przyjrzyjmy się od razu metodzie ApplyAsync.

Ona w jakiś sposób pobiera sobie token, wygenerowany przez WebApi. Taki token może siedzieć albo w BODY, albo w jakimś nagłówku. Stąd najpierw jest próba pobrania go z BODY, a potem z nagłówka.

To teraz spójrz na metodę ReadTokenModelFromBody. Tu się dzieje jedna istotna rzecz.

Odczytujemy dane z BODY. To jest ważne – ODCZYTUJEMY DANE Z BODY. Po takim odczycie koniecznie trzeba przypisać TRUE do SupressResponseBody w kontekście. Jeśli to jest ustawione na TRUE, proxy podczas przesyłania requestu dalej, nie bierze pod uwagę zawartości BODY.

Niestety odczytujemy tutaj całe body, czyli niejako pobieramy je z oryginalnego żądania. Kradniemy je z niego. W oryginalnym żądaniu nie ma już tego body po naszym odczycie, jednak cały czas jest ustawiony nagłówek Content-Length, który mówi o tym, jak długie jest Body. W efekcie wszystko wybuchnie 🙂

To jest pewna pułapka biblioteki Yarp.ReverseProxy. Jeśli musisz odczytać body, żeby przykładowo pobrać jakąś wartość, ale chcesz żeby body było później przesłane dalej, to musisz je na nowo zapisać.

W przypadku tego kodu nie ma takiej potrzeby. Odczytujemy Body i jesteśmy z tym ok, że dalej nie pójdzie. Bo w MOIM systemie ja wiem, że jeśli metoda z linii 26: context.ProxyResponse.Headers.HasAuthToken() zwróci mi TRUE, to znaczy, że w body mam TYLKO tokeny autoryzacyjne.

Oczywiście to jest domena TYLKO I WYŁĄCZNIE mojej aplikacji i moich założeń. A czym jest metoda HasAuthToken? To jakieś rozszerzenie, które może sprawdzać, czy istnieje jakiś nagłówek w żądaniu. Czyli coś w stylu: „Jeśli w żądaniu występuje nagłówek MOJA-APKA-MAM-TOKEN, to znaczy, że w body znajduje się token autoryzacyjny. Chcę, żeby to dobrze wybrzmiało.

To teraz wróćmy do głównej metody – ApplyAsync:

    public override async ValueTask ApplyAsync(ResponseTransformContext context)
    {
        var tokenModel = await ReadTokenModelFromBody(context) ?? context.HttpContext.GetTokens();
        if (tokenModel == null)
            return;

        var cookieValue = _tokenEncoder.EncodeTokens(tokenModel);
        _authCookieService.AddAuthCookieToResponse(context, cookieValue);
    }

Co tu się konkretnie dzieje?

  1. Pobieramy sobie token z body lub jakiegoś nagłówka.
  2. Jeśli istnieje, to szyfrujemy go.
  3. Tworzymy ciasteczko z tym zaszyfrowanym tokenem i dodajemy je do żądania, które jest dalej przesyłane na front.

I to w zasadzie tyle.

Rejestracja transformacji

Rejestracja transformacji nie jest taka oczywista w Yarp.ReverseProxy. Można to zrobić na kilka sposobów. Ale jeśli używamy dependency injection w naszych transformacjach, powinniśmy stworzyć sobie jeszcze jedną klasę: TransformProvider:

internal class TransformProvider : ITransformProvider
{
    public void Apply(TransformBuilderContext context)
    {
        var requestTransform = context.Services.GetRequiredService<AccessTokenRequestTransform>();
        var responseTransform = context.Services.GetRequiredService<AccessTokenResponseTransform>();
        context.RequestTransforms.Add(requestTransform);
        context.ResponseTransforms.Add(responseTransform);
    }

    public void ValidateCluster(TransformClusterValidationContext context)
    {

    }

    public void ValidateRoute(TransformRouteValidationContext context)
    {

    }
}

Wystarczy zaimplementować interfejs ITransformProvider i wypełnić metodę Apply. Potem tworzymy nasze transformacje (w tym przypadku pobieramy z dependency injection) i dodajemy je do odpowiednich kolekcji. Bo transformacji możemy mieć wiele – zarówno dla requestu jak i dla responsu.

Na koniec trzeba to porejestrować:

builder.Services.AddSingleton<AccessTokenRequestTransform>();
builder.Services.AddSingleton<AccessTokenResponseTransform>();
builder.Services.AddReverseProxy()
    .AddTransforms<TransformProvider>()
    .LoadFromConfig(builder.Configuration.GetSection("ProxyConfig"));

W przykładowej solucji na GitHub są dwa projekty, które muszą zostać uruchomione razem – BFF i WebApi. W projekcie BFF w pliku BFF.http jest napisane podstawowe żądanie, które możesz uruchomić, żeby zobaczyć sobie jak to wszystko działa.

Zachęcam Cię do pobrania sobie tego „szkieletu” i pobawienie się trochę nim.


Jeśli pracujesz (albo jesteś częścią teamu) nad aplikacją SPA i jest tam jakaś forma autoryzacji z tokenami, to BFF jest poprawną drogą. Jest to również oficjalne zalecenie w OAuth, żeby używać BFF przy aplikacji typu SPA.

Dzięki za przeczytanie tego artykułu. Jeśli czegoś nie zrozumiałeś lub zauważyłeś gdzieś błąd, koniecznie daj znać w komentarzu 🙂

Jeśli masz dodatkowe pytania – też napisz. Z chęcią odpowiem.

Podziel się artykułem na:
Przegląd typów kolekcji – ściąga

Przegląd typów kolekcji – ściąga

Wstęp

Pomijam fakt, że większość osób, którym robiłem techniczne review, jedyne typy kolekcji jakie znała to List<T>, Dictionary<K, V> i to właściwie wszystko (czasem jeszcze HashSet), to jest jeszcze jeden problem. Różne typy kolekcji są lepsze w niektórych przypadkach, a gorsze w innych. Głównie chodzi tutaj o performance. Ja wiem… Nie optymalizujemy za wcześnie. Niemniej jednak warto wiedzieć, które kolekcje sprawdzają się lepiej w konkretnych sytuacjach.

U jednego ze swoich klientów, zmieniając tylko typy niektórych kolekcji, udało mi się zauważalnie skrócić czas głównej operacji.

W tym artykule robię zatem krótki przegląd większości kolekcji, jakie mamy do dyspozycji.

Dla maruderów

Nie opisuję tutaj rzeczy takich jak BitArray (i podobnych) ani kolekcji niegenerycznych. Niektóre klasy są wysoko wyspecjalizowane do konkretnych zadań (jak np. BitArray), a kolekcji niegenerycznych… po prostu nie powinniśmy raczej używać.

Jakie mamy kolekcje?

Pierwszy podział będzie ze względu na „thread safety”.

Kolekcje dla scenariuszy jednowątkowych

List<T>

To zdecydowanie najbardziej znana kolekcja w C#. Lista to po prostu tablica na sterydach i nic więcej. Elementy listy zajmują ciągły obszar w pamięci. Lista na dzień dobry rezerwuje sobie pewien obszar o wielkości określonej w Capacity (capacity to ilość elementów, jakie chcemy mieć, a nie wielkość wyrażona w bajtach). Gdy dodajemy nowe elementy i Capacity się kończy, wtedy lista rezerwuje nowy obszar w pamięci o rozmiarze Capacity * 2 (szczegół implementacyjny) i kopiuje tam swoje elementy. Itd. To oznacza, że dodawanie elementów do listy w pewnych sytuacjach może być kosztowne. Niemniej jednak jest najpopularniejszą kolekcją. Dostęp do elementu mamy przez jego indeks.

W skrócie:

  • kolejność elementów zachowana
  • elementy umieszczone w ciągłym miejscu w pamięci
  • może zawierać duplikaty
  • łatwy dostęp do poszczególnych elementów za pomocą indeksu

SortedList<K, V>

Lista sortowana. Coś w stylu połączenia List<V> z SortedDictionary<K, V>, chociaż nieco bliżej jej do słownika niż do listy. Elementy znajdują się wciąż w tablicach, czyli zajmują ciągłe miejsce w pamięci. Ale uwaga, kolekcja tak naprawdę zawiera dwie tablice – jedna trzyma klucze, druga wartości. Oczywiście wszystko ze sobą jest sprytnie zsynchronizowane. Uważam to jednak za szczegół implementacyjny, który być może kiedyś ulegnie zmianie.

Elementy są sortowane za pomocą klucza, czyli klucz powinien implementować interfejs IComparable<K>.

W skrócie:

  • elementy sortowane na podstawie klucza
  • elementy zajmują ciągłe miejsce w pamięci (osobne tablice dla kluczy i wartości)
  • nie może zawierać duplikatów
  • łatwy dostęp do poszczególnych elementów za pomocą indeksu

LinkedList<T>

To jest prawilna lista dwukierunkowa (kłaniają się struktury danych :)). Składa się z elementów (LinkedListNode<T>), które oprócz konkretnej wartości trzymają jeszcze referencje do następnego i poprzedniego elementu. Przez co pobieranie konkretnego elementu, np. 5tego może być nieco problematyczne, bo tak naprawdę wymaga przejścia przez wszystkie poprzednie elementy, aby uzyskać ten nas interesujący.

W skrócie:

  • kolejność elementów zachowana
  • elementy umieszczone w różnych miejscach w pamięci
  • może zawierać duplikaty
  • dostęp do poszczególnych elementów jest łatwy, ale może być wolniejszy

ObservableCollection<T>

To bardzo dobrze znają osoby piszące w WPF. Ta kolekcja po prostu daje Ci znać, kiedy coś się w niej zmieni. Tzn. element zostanie dodany, usunięty lub zamieniony. Pod spodem jest zwykła lista.

Queue<T>, Stack<T>

To po prostu typowa kolejka FIFO (queue) i stos LIFO (stack). Przydają się wtedy, kiedy chcemy się pozbyć elementu po zdjęciu go z kolekcji i chcemy mieć zapewniony konkretny porządek.

W skrócie:

  • queue to kolejka FIFO, a stack to stos LIFO
  • elementy umieszczone w ciągłym miejscu w pamięci
  • może zawierać duplikaty
  • element jest automatycznie zdejmowany po odczytaniu go z kolejki (stosu)

PriorityQueue<T, P>

Kolejka priorytetowa. Zawiera elementy typu T i priorytet typu P. Przydatna kiedy chcemy niektóre elementy w kolejce traktować priorytetowo.

W skrócie:

  • kolejka z priorytetem
  • brak kolejności elementów
  • może zawierać duplikaty
  • element jest automatycznie usuwany po odczytaniu go z kolejki

Dictionary<K, T>

Słownik to kolekcja, która przetrzymuje obiekty na podstawie jakiegoś klucza. Klucz jest obliczany za pomocą metody GetHashCode z obiektu typu K. A wartości to typy T. Wyróżnia się szybkim dostępem do danych. Oczywiście to jeszcze zależy jak napiszesz swoją metodę GetHashCode, ale trzymając się standardowych podejść, wszystko powinno być dobrze 🙂

Słownik może mieć tylko jeden wpis z danym kluczem. Jeśli spróbujemy dodać kolejny z kluczem, który już istnieje w słowniku, rzucony będzie wyjątek.

UWAGA! NIGDY nie przechowuj wartości zwracanej z GetHashCode między uruchomieniami aplikacji. Po zmianie wersji .NET (nawet minor albo build) może okazać się, że GetHashCode zwraca inne wartości. Microsoft nie daje gwarancji, że tak nie będzie. A i ja się miałem okazję kiedyś przekonać o tym, że nie można na tym polegać. GetHashCode jest użyteczne tylko w tej samej wersji frameworka.

W skrócie:

  • brak kolejności elementów
  • elementy umieszczone w różnych miejscach w pamięci
  • nie może zawierać duplikatów
  • szybki dostęp do elementu po kluczu

ReadOnlyDictionary<K, T>

Daję go w sumie jako ciekawostkę. To słownik tylko do odczytu. Każda zmiana elementów po utworzeniu tego słownika kończy się rzuceniem wyjątku. Ja zdecydowanie wolę posługiwanie się odpowiednim interfejsem (np. IReadOnlyDictionary) niż tym słownikiem.

SortedDictionary<K, T>

To po prostu słownik, który jest posortowany. Każdy element w słowniku jest sortowany na podstawie klucza. Jeśli klucz implementuje interfejs IComparable<K>, wtedy ten właśnie komparator jest używany do porównania wartości. Sortowanie odbywa się automatycznie po zmianie na liście elementów. Natomiast klucz musi być niezmienny.

Potrzebuje nieco więcej pamięci niż SortedList, za to operacje dodawania i usuwania elementów są szybsze.

W skrócie:

  • elementy są posortowane względem klucza
  • elementy umieszczone w różnych miejscach w pamięci
  • nie może zawierać duplikatów
  • szybki dostęp do elementu po kluczu

FrozenDictionary<K, V>

To jest nowość w .NET 8. Pisałem już o tym w tym artykule. Generalnie jest to słownik tylko do odczytu, który jest zoptymalizowany pod kątem szukania elementów. I naprawdę daje radę. Zresztą zobacz sobie porównanie w moim artykule o nowościach w .NET 8.

W skrócie:

  • brak kolejności elementów
  • elementy umieszczone w różnych miejscach w pamięci
  • nie może zawierać duplikatów
  • szybki dostęp do elementów po kluczu (szybszy niż w Dictionary<K, V>)
  • TYLKO DO ODCZYTU

HashSet<T>

To jest zbiór niepowtarzalnych elementów o typie T. „Powtarzalność” jest sprawdzana na podstawie metody GetHashCode. Można go uznać za coś w rodzaju słownika bez wartości.

W skrócie:

  • brak kolejności elementów
  • elementy umieszczone w różnych miejscach w pamięci
  • nie może zawierać duplikatów
  • szybki dostęp po kluczu

SortedSet<T>

To, podobnie jak HashSet, też jest formą zbioru. Ale SortedSet to struktura drzewa binarnego (czerwono-czarne drzewo binarne). Elementy są posortowane zgodnie z przekazanym w konstruktorze Comparerem (lub domyślnym, jeśli nie przekazano).

Utrzymuje porządek sortowania bez dodatkowego narzutu podczas dodawania lub usuwania elementów. Nie daje jednak bezpośredniego dostępu do konkretnego elementu. Są oczywiście rozszerzenia, które to umożliwiają, np. IEnumerable.ElementAt, jednak związane jest to z przechodzeniem przez drzewo. Zatem używaj tylko wtedy, jeśli potrzebujesz mieć posortowane elementy, gdzie dodawanie i usuwanie nie daje dodatkowego narzutu.

  • elementy posortowane według przekazanego lub domyślnego Comparera
  • elementy umieszczone w różnych miejscach w pamięci
  • nie może zawierać duplikatów
  • brak bezpośredniego dostępu do konkretnego elementu
  • struktura drzewiasta

FrozenSet<T>

Analogicznie jak FrozenDictionary. Tylko reprezentuje HashSet zoptymalizowany do odczytu.

W skrócie:

  • brak kolejności elementów
  • elementy umieszczone w różnych miejscach w pamięci
  • nie może zawierać duplikatów
  • szybki dostęp do elementów po kluczu (szybszy niż w HashSet<T>)
  • TYLKO DO ODCZYTU

Immutable*<T>

Jest do tego kilka kolekcji niezmienialnych, które są oparte dokładnie na tych wymienionych wyżej. Jednak… nie można ich zmienić. To znaczy, że jeśli np. umożliwiają dodawanie lub usuwanie elementów, to tworzą i zwracają tym samym zupełnie nową kolekcję, a oryginalna pozostaje bez zmian. Czyli przy każdym dodaniu/usunięciu, cała kolekcja jest kopiowana.

Kolekcje dla scenariuszy wielowątkowych

Tutaj najpierw słowo wstępu. Istnieje namespace System.Collections.Concurrent i to klasami z tego namespace powinniśmy się posługiwać jeśli chodzi o wielowątkowość. Są jeszcze inne kolekcje w innych namespace’ach (starszych), jak np. SynchronizedCollection opisane niżej. Ale tych raczej powinniśmy unikać, chyba że naprawdę z jakiegoś powodu musimy tego użyć.

SynchronizedCollection<T>

Czuję się trochę w obowiązku wspomnieć o tym starym tworze. TEORETYCZNIE to coś w rodzaju Listy do scenariuszy wielowątkowych. Jednak jego „thread-safe” ogranicza się tylko do tego, że każda operacja jest zamknięta w instrukcji lock. A blokowany jest obiekt dostępny przez SyncRoot.

Ostatecznie może to prowadzić do problemów w sytuacjach wielowątkowych, ponieważ operacje nie są atomowe. Czyli jeśli przykładowo próbujesz wykonać dwie operacje, które zasadniczo logicznie są jedną, wtedy może to prowadzić do poważnych problemów. Przykład?

if(!collection.Contains(element))
    collection.Add(element);

Tutaj po wywołaniu metody Contains, wątek może się przełączyć i ostatecznie możesz skończyć z kilkoma takimi samymi elementami w kolekcji.

ConcurrentBag<T>

O, to chyba zasługuje na osobny artykuł. Ale krótko mówiąc, to taka kolejka, która działa najlepiej we wzorcu Producer-Consumer. Słowo „kolejka” jest tutaj bardzo dobrym wyznacznikiem, bo ConcurrentBag to kolejka. Tyle że to nie jest to ani LIFO, ani FIFO – ot taka kolejka o nieokreślonej kolejności 🙂

Kilka wątków (A, B, C) może wkładać do niej elementy. Kolejka ma swoją własną listę elementów dla każdego wątku. Jeśli teraz pobieramy z niej elementy w wątku A, a ConcurrentBag nie ma elementów dla wątku A, wtedy „kradnie” element z puli innego wątku. Tak to mniej więcej można opisać. Więc najlepiej sprawdza się, gdy wątek często obsługuje własne zadania. Wtedy jest najbardziej efektywny.

W skrócie:

  • brak zachowania kolejności elementów
  • elementy umieszczone w różnych miejscach w pamięci
  • może zawierać duplikaty
  • brak dostępu do konkretnego elementu, można jedynie pobrać kolejny element z kolejki

ConcurrentStack<T>, ConcurrentQueue<T>

To zasadniczo są odpowiedniki zwykłego Stack i Queue, tyle że wątkowo bezpieczne. Tzn., że różne wątki mogą zapisywać i odczytywać elementy z kolejek w tym samym czasie. Oczywiście elementy będą zdejmowanie zgodnie z porządkiem kolejki.

W skrócie:

  • queue to kolejka FIFO, a stack to stos LIFO
  • elementy umieszczone w różnych miejscach w pamięci – w przeciwieństwie do jednowątkowych odpowiedników
  • może zawierać duplikaty
  • element jest automatycznie zdejmowany po odczytaniu go z kolejki (stosu)

BlockingCollection<T>

To też jest rodzaj kolejki, ale nie musi. W swojej domyślnej postaci, w środku ma ConcurrentQueue<T>. Podczas tworzenia można jej podać maksymalną ilość elementów. Wtedy, jeśli jakiś wątek będzie chciał dodać kolejny element (gdy już cała kolekcja jest zapełniona), wątek zostanie wstrzymany aż inny pobierze coś z kolekcji i zwolni miejsce. W drugą stronę zadziała to podobnie – jeśli wątek będzie chciał pobrać coś z pustej kolekcji, to będzie czekał.

Podczas tworzenia kolekcji można podać dowolny „kontener” dla itemów, który implementuje interfejs IProducerConsumerCollection<T>.

W skrócie:

  • elementy mogą być różnie umieszczone w zależności od przekazanego wewnętrznego kontenera – domyślnie jest to ConcurrentQueue
  • może zawierać duplikaty (jeśli wewnętrzny kontener na to pozwala)
  • brak dostępu do dowolnego elementu – można tylko ściągnąć aktualny element

UWAGA! Tutaj występuje jeszcze taka metoda jak CompleteAdding(). Wywołanie jej mówi kolekcji: „Słuchaj misiu, już nikt Ci nigdy niczego nie doda, a jeśli będzie próbował, zdziel go w twarz wyjątkiem”. To kwestia optymalizacyjna. Jeśli kolekcja jest oznaczona w ten sposób, wtedy wątek, który próbuje coś pobrać przy pustej kolekcji, nie będzie czekał, bo wie, że już nic nie zostanie dodane.

ConcurrentDictionary<K, T>

Nie ma co tu dużo mówić. To po prostu zwykły słownik przeznaczony do scenariuszy wielowątkowych. Różne wątki mogą jednocześnie zapisywać i odczytywać elementy. Poza tym niczym szczególnym nie różni się od zwykłego Dictionary<K, T>.


To tyle jeśli chodzi o standardowe kolekcje, których możemy używać. Dzięki za przeczytanie artykułu. Jeśli czegoś nie zrozumiałeś albo znalazłeś w tekście jakiś błąd, koniecznie daj znać w komentarzu.

A, no i koniecznie podziel się tym artykułem z osobami, które znają jedynie listę i słownik 😉

Podziel się artykułem na:
Czym jest ten Span<T>?

Czym jest ten Span<T>?

Wstęp

W pewnym momencie powstał (a właściwie „został odkryty”) typ Span<T>. Nagle Microsoft zaczął go wszędzie używać, twierdząc że jest zajebisty. No dobra, ale czym tak naprawdę jest ten Span? I czy faktycznie jest taki zajebisty? Zobaczmy.

Jedno jest pewne. Używasz go, być może nawet o tym nie wiedząc (jest rozlany wszędzie we Frameworku).

Czym jest Span<T>?

Żeby była jasność. Span to NIE JEST kontener.

W zasadzie Span<T> to takie oczko, które gapi się na przekazany fragment pamięci:

I właściwie mógłbym na tym artykuł skończyć, bo obrazek powyżej idealnie oddaje sens i działanie Spanu. Ale ok, jeśli chcesz więcej, to czytaj dalej 🙂

Przede wszystkim musisz zrozumieć różnice między stosem i stertą. Jeśli nie jesteś pewien, koniecznie przeczytaj ten artykuł, w którym nieco nakreślam sytuację.

Span jako wskaźnik

Span<T> jest w pewnym sensie wskaźnikiem w świecie zarządzanym. Wskazuje na pewien obszar pamięci na stercie (zarządzanej i niezarządzanej). Ale może też wskazywać na pamięć na stosie. Pamiętaj, że jako wskaźnik, sam Span jest alokowany na stosie i zasadniczo składa się z dwóch elementów:

  • adresu miejsca, na który wskazuje
  • wielkości tego miejsca

Można by powiedzieć, że Span<T> wygląda mniej więcej tak:

public readonly ref struct Span<T>
{
    private readonly ref T _pointer;
    private readonly int _length;
}

Tak, mniej więcej taka jest zawartość spanu (+ do tego kilka prostych metod i rozszerzeń). Z tego wynika pierwsza rzecz:

  • Span jest niemutowalny (immutable) – raz utworzonego Spanu nie można zmienić. Tzn., że raz utworzony Span zawsze będzie wskazywał na to samo miejsce w pamięci.

W pamięci może to wyglądać mniej więcej tak:

Na stosie mamy dwie wartości, które składają się na Span. Pointer, jak to pointer, wskazuje na jakiś obszar w pamięci na stercie, natomiast length posiada wielkość tego obszaru. A co to za obszar? Ten, który wskażesz przy tworzeniu Spana.

Uniwersalność tworzenia

Utworzyć Spana możemy właściwie ze wszystkiego. Z tablicy, z listy, z Enumerable, a nawet ze zwykłego niskopoziomowego wskaźnika. To jest jego główna moc i jeden z powodów jego powstania.

I, powtarzam – Span to NIE JEST żadna kolekcja. To NIE JEST tablica. Span nie służy do przechowywania danych, tylko pokazuje Ci fragment pamięci z tymi danymi, które zostały zaalokowane gdzieś wcześniej.

A po co to?

Wyobraź sobie teraz, że masz listę intów, której elementy chcesz zsumować. Możesz przecież zrobić coś takiego:

static void Main(string[] args)
{
    List<int> list = [1, 2, 3];
    var value = Sum(list);
}

private static int Sum(List<int> source)
{
    var sum = 0;
    foreach (var item in source)
    {
        sum += item;
    }

    return sum;
}

I to zadziała super. Masz metodę, która sumuje jakieś dane.

Ok, a teraz załóżmy, że w pewnym momencie ktoś zamiast listy chce dać Ci tablicę. I czym to się kończy? Czymś takim:

static void Main(string[] args)
{
    int[] arr = [1, 2, 3];
    var value = Sum(arr.ToList());
}

private static int Sum(List<int> source)
{
    var sum = 0;
    foreach (var item in source)
    {
        sum += item;
    }

    return sum;
}

Czy to jest w porządku?

Spójrz co się dzieje w linii 4. TWORZYSZ listę. W sensie dosłownym – tworzysz zupełnie nowy obiekt (wywołując ToList()). Wszystkie wartości tablicy są kopiowane i jest tworzona nowa lista, która będzie obserwowana przez Garbage Collector na stercie zarządzanej.

Czyli masz już dwa obiekty obserwowane na tej stercie – tablicę i listę. Pamiętaj, że tworzenie obiektów na stercie jest stosunkowo kosztowne. Poza tym, gdy pracuje Garbage Collector, Twoja aplikacja NIE pracuje, tylko czeka.

I teraz z pomocą przychodzi Span:

static void Main(string[] args)
{
    int[] arr = [1, 2, 3];
    var span = new Span<int>(arr);
    var value = Sum(span);
}

private static int Sum(Span<int> source)
{
    var sum = 0;
    foreach (var item in source)
    {
        sum += item;
    }

    return sum;
}

Co się dzieje w tym kodzie? Przede wszystkim zwróć uwagę, że metoda Sum w ogóle się nie zmieniła (poza typem argumentu, który przyjmuje). Span daje Ci możliwość iterowania bez żadnych przeszkód.

To, co zostało zmienione, to zamiast Listy na stercie, utworzony został Span. A gdzie? Na STOSIE! Ponieważ, jak pisałem na początku – Span to STRUKTURA i jako taka jest tworzona na stosie. Nie ma też narzutu związanego z kopiowaniem danych i tworzeniem obiektu na stercie.

Dlaczego nie ma narzutu związanego z kopiowaniem danych? Bo nic nie jest kopiowane – powtarzam – Span to wskaźnik – on wskazuje na obszar zajmowany przez dane w tablicy arr. I to jest też mega ważne – wskazuje na konkretne dane, a nie na cały obiekt. Innymi słowy, wskazuje na miejsce arr[0]. I to jest właśnie druga główna supermoc Spana (tak samo wskaże na początek danych listy itd).

Porównanie

Zróbmy sobie teraz małe porównanie. Span idealnie działa ze stringami, gdzie widać jego moc już na pierwszy rzut oka. Więc napiszmy sobie prostą apkę, która zwróci ze stringa jakieś obiekty. String będzie w tej postaci:

string data = "firstname=John;lastname=Smith";

Stwórzmy też wynikową klasę:

class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

Aby wykonać to zadanie bez użycia Spana, napisalibyśmy kod mniej więcej taki:

private static Person ProcessDataUsingString(string data)
{
    var values = data.Split(";"); //alokacja dwóch nowych stringów i tablicy
    var firstName = values[0].Substring(values[0].IndexOf('=') + 1); //alokacja nowego stringu
    var lastName = values[1].Substring(values[1].IndexOf('=') + 1); //alokacja nowego stringu

    return new Person
    {
        FirstName = firstName,
        LastName = lastName
    };
}

Natomiast ze Spanem mogłoby to wyglądać tak:

private static Person ProcessDataUsingSpan(string data)
{
    var span = data.AsSpan();

    var fNameValues = span.Slice(0, span.IndexOf(';'));
    var lNameValues = span.Slice(span.IndexOf(';') + 1);

    var firstName = fNameValues.Slice(fNameValues.IndexOf('=') + 1);
    var lastName = lNameValues.Slice(lNameValues.IndexOf('=') + 1);

    return new Person
    {
        FirstName = firstName.ToString(), //alokacja nowego stringu
        LastName = lastName.ToString() //alokacja nowego stringu
    };
}

Zrobiłem Benchmark dla jednego takiego rekordu:

MethodMeanErrorStdDevRatioGen0AllocatedAlloc Ratio
ProcessWithString48.81 ns0.231 ns0.193 ns1.000.0421264 B1.00
ProcessWithSpan26.69 ns0.534 ns0.525 ns0.550.0179112 B0.42

Jak widać Span jest zdecydowanie bardziej wydajny. Nie tylko pod względem czasu wykonania, ale i alokacji pamięci. Właściwie jedyne alokacje, jakie się tu odbyły są już podczas tworzenia nowego obiektu Person – gdy przypisywane są konkretne nowe stringi do obiektu.

Span tylko do odczytu

Zwykły Span pozwala na zmianę konkretnych danych w pamięci. A jeśli jednak chciałbyś użyć jego bezpieczniejszej wersji, to możesz ReadOnlySpan. Działa dokładnie tak samo, tylko nie umożliwia zmiany danych.

I ta właśnie wersja jest zwracana przez stringa – czyli wciąż nie możesz zmienić raz utworzonego stringa (bez użycia kodu unsafe i niskopoziomowych wskaźników).

Możesz mieć tu teraz mały mindfuck – jak to span jest niemutowalny, ale można zmienić mu dane?

Span jest niemutowalny pod tym względem, że raz utworzony zawsze będzie wskazywał na ten sam fragment pamięci. Ale to, co jest w tej pamięci możesz zmienić (chyba że masz ReadOnlySpan). Zobaczysz to dalej w artykule.

Na co nie pozwala?

Nie można zmienić stringu

Jak już pisałem, Span nie pozwala na zmianę elementów stringu. String jest zawsze niemutowalny i nic na to nie poradzisz (poza niskopoziomowymi wskaźnikami).

Nie może być częścią klasy

Z tego powodu, że Span MUSI BYĆ alokowany na stosie, nie może być elementem klasy. W sensie właściwością, czy polem. Elementy klasy mogą być alokowane na stercie, a Span nie może, bo ma to zabronione. Za to Span może być częścią ref struct. Ale w takiej sytuacji musisz uważać.

Musisz używać go mądrze

Pamiętasz jak pisałem, że raz utworzony Span zawsze będzie wskazywał dokładnie to samo miejce w pamięci? Musisz wiedzieć, co masz w tym miejscu, żeby nie doszło do wykrzaczenia:

byte[] arr = [1, 2, 3];
var span = new Span<byte>(arr);
arr = null!;

GC.Collect();

span[0] = 10;

Spójrz, najpierw alokujemy pamięć na tablicę. Na stosie znajduje się adres do elementów tej tablicy (czyli zmienna arr). Tworzymy sobie Span dla tej tablicy – Span teraz wskazuje na elementy tablicy na stercie.

Następnie usuwamy naszą tablicę – w efekcie nic tego miejsca już nie używa. Garbage Collector w pewnym momencie może je wyczyścić albo mogą zostać tam zaalokowane inne rzeczy. Natomiast Span cały czas wskazuje na tę pamięć. I przypisując jakąś wartość możesz doprowadzić do Access Violation.

Więc pod tym względem musisz być uważny.

Nie możesz go używać w asynchronicznych operacjach

Jako, że każdy wątek ma swój oddzielny stos, a Stack jest alokowany na stosie, to nie może być używany w operacjach asynchronicznych. Jeśli potrzebujesz czegoś takiego, użyj Memory<T>. O tym może też coś napiszę.

Czy Span jest zajebisty?

To w sumie tylko narzędzie. Odpowiednio użyte może sprawdzić, że aplikacje w C# będą naprawdę wydajne. Niemniej jednak cieszę się, że coś takiego powstało, ponieważ to jest jedna z rzeczy, których brakowało mi trochę, a które używałem w innych językach. Czyli wskaźniki. I to bez użycia kodu unsafe 🙂


Dzięki za przeczytanie artykułu. Jeśli czegoś nie rozumiesz lub znalazłeś jakiś błąd, koniecznie daj znać w komentarzu 🙂

Podziel się artykułem na:
Kiedy i jak ponawiać żądania HTTP? Najlepsze praktyki

Kiedy i jak ponawiać żądania HTTP? Najlepsze praktyki

Wstęp

Jeśli Twoja apka używa WebAPI, warto zatroszczyć się o ponawianie żądań HTTP właśnie do tych API. Stosuje się to z kilku powodów, o których piszę niżej.

W tym artykule przedstawię Ci najlepsze praktyki, jakie możesz wykorzystać.

O tworzeniu własnego klienta WebAPI i różnych uproszczeniach, które możemy zastosować, pisałem już w tym artykule. Ten, który czytasz, potraktuj jako rozszerzenie i coś, co warto zastosować w prawdziwym kodzie.

Jeśli jesteś zainteresowany tylko konkretnym rozwiązaniem, rozwiń poniższy akapit:

Na szybko

  1. Pobierz Nuget: Microsoft.Extensions.Http.Polly
  2. Przy rejestracji klienta Http dodaj kod:
builder.Services.AddHttpClient<IndexModel>((client) =>
{
    client.BaseAddress = new Uri("https://example/com/");
}).AddTransientHttpErrorPolicy(policy => 
        policy.OrResult(x => x.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(Backoff.DecorrelatedJitterBackoffV2(TimeSpan.FromSeconds(1), 3)));

Teraz możesz już używać HttpClienta otrzymanego z dependency injection w standardowy sposób. Wszystko załatwia pobrana biblioteka i metoda AddTransientHttpErrorPolicy.

Jeśli chcesz wiedzieć więcej, przeczytaj cały artykuł.

Po co ponawiać żądania?

Jeśli pobierasz jakieś dane z WebApi możesz spotkać się z kilkoma odpowiedziami poza poprawną. Wtedy masz dwie opcje – pokazać użytkownikowi błąd. No i cześć. Albo spróbować ponowić żądanie, może za drugim razem się uda, a doświadczenie użytkownika z Twoją aplikacją będzie lepsze.

Odpowiedzi, po których warto ponowić żądanie to na przykład:

Wewnętrzny błąd serwera

Czyli kody odpowiedzi 5xx.

Oznacza to, że serwer ma aktualnie problem ze sobą. Mamy nadzieję, że chwilowy. W najgorszym wypadku, programiści czegoś nie przewidzieli i kod po prostu się wywala. Jeśli jednak jest to chwilowy problem, warto spróbować ponowić żądanie. Być może problem za chwilę zniknie.

Throttling

Kod 429: Too Many Requests.

Ten problem oznacza, że klient (Twoja aplikacja) zbyt często odpytuje serwer. Serwer ma ustawiony jakiś rate limit, co oznacza że możemy do niego strzelić określoną ilość razy w określonym czasie. To może być też ograniczone do ilości przesłanych danych. Więc jeśli otrzymasz odpowiedź 429 oznacza to, że za jakiś czas powinieneś ponowić żądanie i będzie git.

A co przy braku szukanego zasobu, skoro został utworzony?

Stare, dobre 404.

No… tutaj ponawianie ma sens tylko w jednej sytuacji. Kiedy wcześniej próbowałeś stworzyć zasób, ale to chwilę może zająć. A samo WebApi jest asynchroniczne. O asynchronicznych WebApi pisałem w tym artykule. W innym wypadku powtarzanie żądania przy tym kodzie nie ma żadnego sensu. Czyli zasadniczo nie powinieneś dostać takiej sytuacji, jeśli poprawnie obsługujesz asynchroniczne WebApi.

Ponawianie żądania – z czym to się je?

Zasadniczo sytuacja jest ciekawa. Bo nie ma innej opcji jak tylko ponawianie żądania w jakiejś pętli. Jednakże można to robić zarówno źle jak i dobrze. I źle to np. samemu tworzyć takie mechanizmy.

I możesz napisać sobie coś najprostszego w stylu (tylko fragment kodu):

HttpResponseMessage response;
try
{
    response = await _httpClient.GetAsync("api/get-data");
    switch(response.StatusCode)
    {
        case ....
        //jakoś zrób retry
    }
}catch(HttpRequestException ex)
{
    switch(ex.StatusCode)
    {
        case ...
        //jakoś zrób retry
    }
}

To oczywiście nie dość, że ciężko jest reużyć, to jest brzydkie. Nie dość, że jest brzydkie, to sam musisz oprogramować jakieś standardowe zachowania. Sam musisz:

  • napisać kolejne mechanizmy do ponawiania requestu,
  • pilnować, czy nie ponawiasz requestu nieskończoną ilość razy,
  • pilnować, czy ponawiasz go dostatecznie długo, ale nie za długo,
  • napisać coś, co pozwoli Ci ponawiać request po jakimś delayu, a nie od razu,
  • i pewnie mnóstwo innych rzeczy.

Wpadasz w dużą ilość pułapek, zaczynasz trafiać na mnóstwo zduplikowanego kodu i koniec końców okazuje się, że tworzysz jakiś skomplikowany mechanizm albo nawet cały projekt, którego jedynym zadaniem jest tak naprawdę ponowienie requestu w pewnych warunkach… Zamiast skupić się na faktycznej robocie.

Co jaki czas ponawiać request?

Na to pytanie będziesz musiał odpowiedzieć sobie tak, czy inaczej. Nie możesz ponawiać requestu bez żadnej przerwy, np. tak

public async Task<HttpResponseMessage> SendRequest()
{
    HttpResponseMessage response;
    try
    {
        return await _httpClient.GetAsync("api/get-data");
    }catch(HttpRequestException ex)
    {
        return await SendRequest();
    }
}

Weź pod uwagę kilka rzeczy:

  • ten kod jest pozbawiony kluczowych elementów (np. sprawdzania kodu odpowiedzi)
  • zakładamy, że posiadamy tutaj ochronę przed nieskończoną rekukrencją

Tutaj będziesz ponawiał requesty jeden za drugim bez żadnej przerwy. Nie jest to dobre podejście, bo bombardujesz zupełnie bez sensu API. No i nie dajesz odetchnąć procesorowi.

Lepiej zrobić chociażby coś takiego:

public async Task<HttpResponseMessage> SendRequest()
{
    HttpResponseMessage response;
    try
    {
        return await _httpClient.GetAsync("api/get-data");
    }catch(HttpRequestException ex)
    {
        await Task.Delay(1000);
        return await SendRequest();
    }
}

Requestów wyjdzie od Ciebie duuużo mniej i będą dużo bardziej sensowne. No bo jeśli uzyskałeś odpowiedź 429, to mało prawdopodobne, że od razu w następnym requeście otrzymasz poprawną. Odczekaj chwilę – dokładnie to mówi ten błąd: „Wstrzymaj konie kowboju, daj odetchnąć… albo wykup wyższy pakiet dostępu”.

To samo tyczy się innych kodów, które warto ponawiać.

Takie „stałe” (co jedną sekundę) ponawianie pewnie jakoś wygląda i pomaga. Natomiast można to zrobić duuuużo lepiej.

Jitter

Jitter (możesz wyszukać w necie pod hasłem „retry with jitter”) to pewna zmienna, która pomaga lepiej ustalić ten czas. To może być jakaś losowość, czyli raz czekasz sekundę, raz czekasz dwie, raz czekasz pół.

Ale to może być też exponential backoff.

Exponential backoff

Zapamiętaj to pojęcie dobrze, bo może pojawiać się na pytaniach rekrutacyjnych 😉

Exponential backoff to ogólnie przyjęta strategia do obliczania czasu, jaki musi minąć pomiędzy ponawianiem konkretnego żądania. Polega na tym, że pierwsze ponowienia są dość szybko, a kolejne mają coraz większą przerwę. Zobacz ten prosty przykład ponawiania requestu w pseudokodzie:

Request();
Czekaj(1000);
Request();
Czekaj(2000);
Request();
Czekaj(4000);
Request();
Czekaj(8000);

Jeśli pierwszy request trzeba ponowić, odczekaj sekundę.

Jeśli i to nie poszło, odczekaj 2 sekundy.

Jeśli nadal nie działa, odczekaj 4 sekundy… (to jest potęgowanie) Itd.

Jest to dość eleganckie rozwiązanie i szeroko stosowane.

Oczywiście nie musisz tego wszystkiego robić sam. W .NET jest paczka, która całą tą czarną robotę z ponawianiem requestów robi za Ciebie. I to jest prawidłowy mechanizm i bardzo dobra praktyka.

Przywitaj Polly

Jest taki Nuget:

Użycie tej paczki bardzo ułatwia całą pracę, co za chwilę zobaczysz, ale można jeszcze prościej (co zobaczysz później).

Polly przedstawia mechanizm AsyncPolicy, w którym po prostu budujesz sobie politykę ponawiania requestów. Oczywiście politykę możesz zbudować raz i używać ją wszędzie albo możesz też mieć różne polityki. Zbudujmy swoją pierwszą polityke:

private readonly IAsyncPolicy<HttpResponseMessage> _retryPolicy =
    Policy<HttpResponseMessage>
        .Handle<HttpRequestException>()
        .OrResult(x => (int)x.StatusCode >= 500 || x.StatusCode == HttpStatusCode.TooManyRequests)
        .RetryAsync(3);

//wywołanie requestu nieco się teraz zmienia:
public async Task<HttpResponseMessage> SendRequest()
{
   return await _retryPolicy.ExecuteAsync(() => _httpClient.GetAsync("api/get-data"));
}

W pierwszych linijkach stworzyliśmy politykę ponawiania requestów. To jest bardzo prosty builder i ma oczywiście dużo więcej możliwości niż tylko to, co pokazałem. Ale nie chcę w tym artykule pisać dokumentacji Polly, którą znajdziesz tutaj 🙂

Generalnie to mówi tyle:

  • IAsyncPolicy<HttpResponseMessage> – stwórz politykę dla typu zwracanego HttpResponseMessage
  • Handle<HttpRequestException> – użyj, jeśli pójdzie exception typu HttpRequestException (handle exception)
  • OrResult…. – lub rezultatem będzie – i tu przekazany delegat
  • RetryAsync(3) – ponów taki request 3 razy

I zobacz teraz co się stało w metodzie SendRequest. Została tylko jedna linijka, a mamy załatwione ponawianie requestu dla konkretnych StatusCode’ów i dla exceptiona, który może być rzucony. Wszystko się dzieje wewnątrz metody ExecuteAsync. My tylko musimy przekazać jej funkcję, która ma zostać wykonana – czyli konkretny strzał do API.

ExecuteAsync zwróci HttpResponseMessage, ponieważ z takim typem została zadeklarowana nasza polityka.

Jednak tak stworzona polityka nie jest idealna, bo będzie ponawiała request za requestem bez żadnej przerwy. Czy możemy dodać jakiś delay? Oczywiście, że tak:

private readonly IAsyncPolicy<HttpResponseMessage> _retryPolicy =
    Policy<HttpResponseMessage>
        .Handle<HttpRequestException>()
        .OrResult(x => (int)x.StatusCode >= 500 || x.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(3, retryCount => TimeSpan.FromSeconds(Math.Pow(2, retryCount)));

Tutaj metodę RetryAsync zamieniliśmy na WaitAndRetryAsync. Ta metoda w pierwszym parametrze przyjmuje ilość żądanych powtórzeń – tak jak RetryAsync, natomiast w drugim podajesz czas jaki ma upłynąć przed kolejnymi powtórzeniami.

Drugim parametrem jest oczywiście funkcja, która ten czas oblicza. W parametrze funkcji dostajesz zmienną int – retryCount, która Ci mówi, które powtórzenie aktualnie się odbywa. Za pomocą tej informacji w bardzo łatwy sposób możemy stworzyć swój exponential backoff, co zostało zrobione w tym kodzie.

Wygląda skomplikowanie? Jasne, że można prościej.

Rozszerzenia do Polly

W Nuget znajdziesz różne rozszerzenia do Polly, między innymi Polly.Contrib.WaitAndRetry. Celem tego rozszerzenia jest dostarczenie Ci już gotowych mechanizmów „backoff”, czyli tych do obliczania czasu między powtórzeniami żądania. I powyższy kod może być zamieniony na taki:

private readonly IAsyncPolicy<HttpResponseMessage> _retryPolicy =
    Policy<HttpResponseMessage>
        .Handle<HttpRequestException>()
        .OrResult(x => (int)x.StatusCode >= 500 || x.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(Backoff.ExponentialBackoff(TimeSpan.FromSeconds(1), 3));

W rozszerzeniu Polly.Contrib.WaitAndRetry dostaliśmy klasę Backoff i metodę ExponentialBackoff, której przekazaliśmy dwa parametry:

  • jaki czas musi upłynąć przed PIERWSZYM ponowieniem (tutaj sekunda)
  • ile razy ponawiać

Jest jeszcze lepsza metoda – do exponential backoff można dodać element losowości. Czyli przerwy nie będą idealnymi potęgami dwójki, ale będą trwały trochę mniej lub trochę więcej:

private readonly IAsyncPolicy<HttpResponseMessage> _retryPolicy =
    Policy<HttpResponseMessage>
        .Handle<HttpRequestException>()
        .OrResult(x => (int)x.StatusCode >= 500 || x.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(Backoff.DecorrelatedJitterBackoffV2(TimeSpan.FromSeconds(1), 3));

Jak widzisz, w bardzo łatwy sposób możesz zmieniać sobie strategie liczenia czasu.

Ale można jeszcze prościej… 😉

Integracja .NET z Polly

Microsoft w całej swojej dobroci zrobił już integrację z Polly, dzięki czemu możemy używać tego mechanizmu właściwie bez większych zmian w kodzie. Wszystko jest wpięte do HttpClientFactory, o którym pisałem trochę w artykule jak używać HttpClient.

Przede wszystkim pobierz sobie NuGeta: Microsoft.Extensions.Http.Polly. On ma już wszystkie zależeności.

Teraz, gdy rejestrujesz swojego klienta Http:

builder.Services.AddHttpClient<IndexModel>((client) =>
{
    client.BaseAddress = new Uri("https://example/com/");
});

możesz dodać swoją politykę Polly:

builder.Services.AddHttpClient<IndexModel>((client) =>
{
    client.BaseAddress = new Uri("https://example/com/");
})
    .AddPolicyHandler(Policy<HttpResponseMessage>
        .Handle<HttpRequestException>()
        .OrResult(x => (int)x.StatusCode >= 500 || x.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(Backoff.DecorrelatedJitterBackoffV2(TimeSpan.FromSeconds(1), 3)));

Zwróć uwagę, że dodałem dokładnie tą samą politykę, co w kodzie wyżej, bo to jest dokładnie takie samo działanie.

Oczywiście swoje polityki możesz trzymać w różnych miejscach (i zmiennych) i mieć je bardziej scentralizowane, jeśli tego chcesz.

Teraz już możesz HttpClienta uzywać w sposób klasyczny:

public class IndexModel : PageModel
{
    private readonly HttpClient _httpClient;

    public IndexModel(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task<HttpResponseMessage> SendRequest()
    {
       return await _httpClient.GetAsync("api/get-data");
    }
}

Jeśli jeszcze nie wiesz, czemu akurat w taki sposób używamy HttpClient (przez dependency injection), KONIECZNIE przeczytaj ten artykuł.

Można jeszcze prościej

Ludzie, trzymajcie mnie, bo można jeszcze prościej:

builder.Services.AddHttpClient<IndexModel>((client) =>
{
    client.BaseAddress = new Uri("https://example/com/");
}).AddTransientHttpErrorPolicy(policy => policy.WaitAndRetryAsync(Backoff.DecorrelatedJitterBackoffV2(TimeSpan.FromSeconds(1), 3)));

Powtarzanie requestu w konkretnych warunkach jest na tyle pospolite, że Microsoft zrobił dodatkowe rozszerzenie do tego. Metoda AddTransientHttpErrorPolicy dodaje politykę domyślnie ustawioną na:

  • obsługę exceptiona typu HttpRequestException,
  • obsługę rezultatu, gdy status >= 500
  • obsługę timeout.

Musimy dodać tylko backoff jaki chcemy mieć (czyli ten delay pomiędzy powtórzeniami).

Ale uwaga. Uważny czytelnik zorientował się, że metoda AddTransientHttpErrorPolicy nie dodaje do polityki statusu kodu 429 Too may requests. Zgadza się. Jeśli chcemy to mieć, musimy sami to dodać:

builder.Services.AddHttpClient<IndexModel>((client) =>
{
    client.BaseAddress = new Uri("https://example/com/");
}).AddTransientHttpErrorPolicy(policy => 
        policy.OrResult(x => x.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(Backoff.DecorrelatedJitterBackoffV2(TimeSpan.FromSeconds(1), 3)));

Przyznasz jednak, że rozwiązanie jest duuużo bardziej czytelne i dużo lepsze niż mechanizmy, które tworzyłbyś sam, prawda? W zasadzie cały ten mechanizm ograniczył się do wywołania trzech metod przy konfiguracji. Piękna sprawa.


To tyle. Dzięki za przeczytanie artykułu. Jak zwykle, jeśli czegoś nie rozumiesz lub znalazłeś błąd w tekście, koniecznie daj mi znać w komentarzu.

A i sprawdź swoje apki, gdzie używasz zewnętrznych Api. Czy w którejś z nich masz czasem problem z dostępnością?

Podziel się artykułem na:
Asynchroniczne REST Api – jak i po co?

Asynchroniczne REST Api – jak i po co?

W tym artykule wyjaśnię Ci, czym jest asynchroniczne REST API, czemu i kiedy takie tworzyć. Poza tym powiem Ci jak sobie poradzić z synchronicznym REST API, żeby bez dostępu do kodu uzyskać wersję asynchroniczną. Takie czary 🙂

W międzyczasie ubrudzimy sobie trochę ręce. Przykładowe kody umieściłem na GitHubie. No to jedziemy.

Jak działa REST API?

REST Api możemy podzielić na dwie wersje – synchroniczne i asynchroniczne. Jeśli chodzi o synchroniczne, to sprawa jest dość prosta. Wysyłasz żądanie i czekasz na odpowiedź:

public async Task GenerateReport(string jsonData)
{
    var result = await _httpClient.PostAsJsonAsync("orders/report", jsonData);
}

Kod jest prosty i całe flow też. Zobaczmy jak to wygląda w żądaniach HTTP:

  • klient wysyła żądanie do serwera o wygenerowanie jakiegoś raportu, np.:
POST https://example.com/orders/report
{
  "startDate": "2023-01-01",
  "endDate": "2023-01-31"
}
  • serwer odpowiada kodem 400, jeśli przekazane dane są błędne lub 200 OK:
HTTP/1.1 200 OK
Content-Type: application/json
{
 "data": &lt;data>
}

Tutaj oczywiście dane raportu mogą pojawić się w BODY lub też dostaniesz adres do pobrania pliku z raportem – w zależności od API.

Gorzej, gdy operacja na serwerze trwa długo. Kilkadziesiąt sekund lub kilka minut. Wtedy taka robota może zakończyć się kilkoma problemami:

  • możesz otrzymać time-out (brak odpowiedzi z serwera)
  • tak, czy inaczej używasz wątku, który czeka (na odpowiedź). Może to powodować problemy w wydajności aplikacji, szybsze jej skalowanie w górę i wzrost kosztów związany z chwilowym zwiększonym zapotrzebowaniem na zasoby (zwłaszcza jeśli ruch jest duży).
  • podatność na atak DDoS

Asynchroniczne REST Api

Jeśli operacja może trwać nieco dłużej niż kilka sekund, lepiej rozważyć jest zrobienie asynchronicznego API. Możesz je zaprojektować na kilka sposobów. Klient może odpytywać serwer co jakiś czas o status operacji lub klient może przekazać webhooka, na który serwer da znać, gdy operacja się zakończy. Prześledźmy obie możliwości:

Odpytywanie serwera

  • klient wysyła żądanie do serwera, np.:
POST https://example.com/orders/report
{
  "startDate": "2023-01-01",
  "endDate": "2023-01-31"
}
  • serwer odpowiada kodem 202 Accepted, dodając nagłówek Location, który wskazuje na endpoint, którym możesz odpytywać o status operacji
HTTP/1.1 202 Accepted
Location: orders/report/status/&lt;id>
Retry-After: 60
  • serwer rozpoczyna operację (lub częściej – przekazuje ją dalej do wykonania)
  • co jakiś czas (Retry-After) pytasz o stan operacji, wysyłając żądanie na końcówkę otrzymaną w kroku 2
GET https://example.com/orders/report/status/&lt;id>
  • możesz dostać odpowiedź 200 OK, wraz z opisem statusu lub 303 See Other ze wskazaniem miejsca, z którego pobierasz rezultat. Przy czym kod 303 oznacza, że operacja się zakończyła.

Przykładowa odpowiedź na operację, która jest w toku:

HTTP/1.1 200 OK
Content-Type: application/json
Retry-After: 60
{
 "status" : "InProgress"
}

Przykładowa odpowiedź na zakończoną operację:

HTTP/1.1 303 See Other
Location: orders/report/&lt;id>
  • wysyłasz żądanie po rezultat na końcówkę z nagłówka Location
GET https://example.com/orders/report/&lt;id>

W tym momencie żaden wątek klienta nie był zblokowany i nie czekał aż operacja się wykona. Co więcej, jeśli serwer przekazał operację do wykonania dalej, żaden wątek serwera też nie został zblokowany. Po prostu klient zlecił jakieś zadanie i co jakiś czas odpytywał, czy jest już zrobione (jak to bywa w życiu ;)).

Oczywiście serwer może odpowiedzieć na różne sposoby. W pewnym momencie może się coś wywalić i wtedy pytając o status klient powinien otrzymać informację o błędzie.

Jeśli klient przesyła niepoprawne dane w pierwszym żądaniu, serwer powinien odpowiedzieć kodem 400 Bad Request zamiast 202 Accepted – jak w przypadku synchronicznej wersji.

A niech to serwer… odpowie

Czasem nie chcesz, żeby klient pytał co jakiś czas o stan zadania i wychodzisz z założenia: „Panie, będzie to będzie”. Tak też można. Tutaj sprawa jest nieco prostsza.

  • klient wysyła żądanie wraz z adresem, na który serwer ma dać odpowiedź
POST https://example.com/orders/report
{
  "startDate": "2023-01-01",
  "endDate": "2023-01-31",
  "callbackUrl": "https://application.com/callback"
}
  • serwer odpowiada 202 Accepted (lub 400, jeśli dane w żądaniu są nieprawidłowe). Zauważ, że nie podaje tutaj już końcówki do sprawdzania stanu – nagłówka Location. Po prostu – „będzie zrobione, jak się zrobi”
HTTP/1.1 202 Accepted
  • no i jak już się zrobiło, to tym razem SERWER wysyła żądanie do klienta na wcześniej przekazany callback
POST https://application.com/callback
{
  "status" : "Completed",
  "links" : [{
    "rel" : "reports",
    "href" : "orders/reports/&lt;id>"
  }]
}

Na koniec klient powinien zapytać się o konkretny raport, strzelając na podany endpoint. Oczywiście w zależności od API, serwer też może już w callbacku wysłać wynikowe dane.

Jak to wygląda w praktyce

Zazwyczaj, żeby móc korzystać z czyjegoś API, musisz zarejestrować swojego klienta (swoją aplikację, która będzie to API wykorzystywać). Często podczas rejestracji można podać od razu adres callback, na który serwer ma dawać znać o zakończonym zadaniu lub po prostu wysyłać do Ciebie różne komunikaty – to już zależy od konkretnego API.

Jednak często jest też możliwe wysłanie adresu callbacka w żądaniu, jak to było zrobione w tym przykładzie.

API, po skończonym zadaniu, może od razu wysłać Ci rezultat zamiast odpowiedzi o zakończonym statusie (tak jak w powyższym przykładzie).

Piszemy asynchroniczny serwer

Teraz napiszemy sobie przykładowy asynchroniczny serwer. Zauważ kilka rzeczy:

  • to jest przykład – dość prosty, acz użyteczny
  • nie ma tutaj mechanizmu autoryzacji, który powinien być w prawdziwym rozwiązaniu
  • nie ma tutaj wykonywania prawdziwej operacji, w rzeczywistym przypadku to może być robione na różne sposoby
  • nie ma tutaj żadnej abstrakcji, piszemy najprościej jak się da, jednak staram się stosować zasady czystego kodu

UWAGA! Ta wersja kodu jest wersją prostą. Bez użycia Azure (albo innej chmury). Weź pod uwagę, że to nie jest do końca asynchroniczne rozwiązanie, jednak jeśli nie znasz Azure, to ta wersja dużo bardziej ułatwi Ci zrozumienie o co w tym chodzi. Wersja wykorzystująca Azure jest opisana niżej.

Na początek stwórzmy sobie standardowe WebApi z kontrolerem do pogody, który za chwilę zmienimy. Do tego stwórzmy serwis WeatherForecastService, który na początek będzie pusty:

public class WeatherForecastService
{
    public Task GetForecast(Guid requestId, DateOnly date)
    {
        return Task.CompletedTask;
    }
}

Serwis zarejestrujemy jako Scoped:

builder.Services.AddScoped<WeatherForecastService>();

I wstrzykniemy go do naszego lekko zmienionego kontrolera:

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private WeatherForecastService _service;

    public WeatherForecastController(WeatherForecastService service)
    {
        _service = service;
    }

    [HttpGet(Name = "GetWeatherForecast/{date}")]
    public async Task<IActionResult> Get(DateOnly date)
    {
        Guid requestId = Guid.NewGuid();
        _ = _service.GetForecast(requestId, date);

        return await Task.FromResult(Accepted($"WeatherForecast/Status/{requestId}"));
    }
}

Do tej pory wszystko powinno być jasne. Użytkownik pyta o pogodę na dany dzień. Kontroler wywołuje metodę w serwisie. Dodatkowo kontroler tworzy ID dla tego żądania, które zwraca użytkownikowi. Tutaj ważne jest, że nie czekamy na to aż wykona się Task GetForecast. Nie ma tutaj wywołania z await. To znaczy, że kontroler może zakończyć swoją pracę od razu, a Task będzie działał w tle.

Na koniec kontroler zwraca odpowiednią odpowiedź – 202 Accepted. Zwróć uwagę, że kontroler nie czeka na wykonanie operacji przez serwis. Co to oznacza? W tym momencie nigdy nie dowiemy się, czy operacja się wykonała i jaki jest jej wynik. Dlatego też ten wynik trzeba gdzieś zapisać…

Baza danych

Tak, takie operacje zapisuje się w bazie danych. Stwórzmy więc prosty model bazodanowy i banalną bazę danych – opakowany słownik (weź pod uwagę, że w rzeczywistości powinna być to prawilna baza, ten kod poniżej jest tylko ze względu na prostotę):

public enum OperationStatus
{
    NotStarted,
    InProgress,
    Finished
}
public class WeatherDatabaseItem
{
    public Guid RequestId { get; set; }
    public OperationStatus Status { get; set; }
    public WeatherForecast Data { get; set; }
}

A teraz nasza baza danych:

public class Database
{
    private Dictionary<Guid, WeatherDatabaseItem> _weatherForecasts = new();

    public void UpsertForecast(Guid id, OperationStatus status, WeatherForecast forecast)
    {
        WeatherDatabaseItem item = GetOrCreate(id);
        item.Status = status;
        item.Data = forecast;

        _weatherForecasts[id] = item;
    }

    private WeatherDatabaseItem GetOrCreate(Guid id)
    {
        WeatherDatabaseItem result = null;

        if (!_weatherForecasts.TryGetValue(id, out result))
            return new WeatherDatabaseItem { RequestId = id };

        return result;
    }
}

Żeby taka „baza” miał sens, musimy klasę Database zarejestrować jako singleton:

builder.Services.AddSingleton<Database>();

Serwis

OK, mając bazę danych i kontroler, możemy teraz zrobić jakąś prawdziwą robotę – sprawdzić/wyliczyć prognozę pogody w serwisie. Wstrzyknijmy mu bazę danych i dajmy nieco ciałka:

public class WeatherForecastService
{
    private readonly Database _database;

    public WeatherForecastService(Database database)
    {
        _database = database;
    }

    public async Task GetForecast(Guid requestId, DateOnly date)
    {
        _database.UpsertForecast(requestId, OperationStatus.InProgress, null);

        await Task.Delay(30000); //symulacja długiej operacji

        var result = new WeatherForecast
        {
            Date = date,
            Summary = "Sunny",
            TemperatureC = 25
        };

        _database.UpsertForecast(requestId, OperationStatus.Finished, result);
    }
}

Zwróć uwagę na dwie rzeczy. Po pierwsze na początku (linia 12) dodajemy pusty rekord do bazy z uzyskanym ID i statusem ustawionym na InProgress. To znaczy, że obliczenia są w trakcie.

Następnie mamy jakiś Delay, który ma tylko symulować długotrwałą operację.

Na koniec dodajemy do bazy gotową prognozę pogody. W międzyczasie klienci mogą pytać się o status operacji i dostaną odpowiedź InProgress.

Zatem musimy jeszcze zrobić dwa endpointy w kontrolerze:

  • sprawdzanie statusu operacji
  • pobieranie wyników

Sprawdzanie statusu operacji

Najpierw w bazie danych dodajmy metodę do pobierania odpowiedniego rekordu:

public class Database
{
    private Dictionary<Guid, DatabaseItem> _weatherForecasts = new();

    public void UpsertForecast(Guid id, OperationStatus status, WeatherForecast forecast)
    {
        DatabaseItem item = GetOrCreate(id);
        item.Status = status;
        item.Data = forecast;

        _weatherForecasts[id] = item;
    }

    public DatabaseItem GetById(Guid id)
    {
        DatabaseItem result = null;
        _weatherForecasts.TryGetValue(id, out result);
        return result;
    }

    private DatabaseItem GetOrCreate(Guid id)
    {
        DatabaseItem result = null;

        if (!_weatherForecasts.TryGetValue(id, out result))
            return new DatabaseItem { RequestId = id };

        return result;
    }
}

Teraz w serwisie powinna znaleźć się metoda do pobierania statusu:

public class WeatherForecastService
{
    private readonly Database _database;

    public WeatherForecastService(Database database)
    {
        _database = database;
    }

    public async Task GetForecast(Guid requestId, DateOnly date)
    {
        _database.UpsertForecast(requestId, OperationStatus.InProgress, null);

        await Task.Delay(30000);

        var result = new WeatherForecast
        {
            Date = date,
            Summary = "Sunny",
            TemperatureC = 25
        };

        _database.UpsertForecast(requestId, OperationStatus.Finished, result);
        return Task.CompletedTask;
    }

    public async Task<OperationStatus> GetRequestStatus(Guid requestId)
    {
        var status = await Task.Run(() =>
        {
            var item = _database.GetById(requestId);
            if (item == null)
                return OperationStatus.NotStarted;
            else
                return item.Status;
        });

        return status;
    }
}

Możesz się czepić o to, że metoda GetRequestStatus jest oznaczona jako asynchroniczna, bo w tym przypadku ta asynchroniczność niczego nie daje. Zrobiłem tak tylko po to, żeby utrzymać konwencję pobierania danych z bazy danych jako operację asynchroniczną.

No i na koniec endpoint w kontrolerze:

[HttpGet("Status/{requestId}")]
public async Task<IActionResult> GetStatus(Guid requestId)
{
    var status = await _service.GetRequestStatus(requestId);
    if(status == Models.OperationStatus.Finished)
    {
        Response.Headers.Add("Location", $"/WeatherForecast/{requestId}");
        return StatusCode(StatusCodes.Status303SeeOther);
    } else
    {
        var data = new
        {
            status = status
        };
        return Ok(data);
    }
}

Najpierw pobieramy status z serwisu i sprawdzamy go. Jeśli operacja jest zakończona, to odsyłamy klientowi odpowiedź 303 See Other wraz z linkiem do pobrania danych.

Jeśli jednak operacja jest w trakcie, to odsyłamy klientowi rezultat Ok z odpowiednimi danymi.

UWAGA!

Standardowi klienci (przeglądarki internetowe, Postman, a nawet klasa HttpClient) mają wbudowany mechanizm „follow redirects„, co oznacza że po odebraniu odpowiedzi 301, 302 lub 303 automatycznie przeniosą Cię na adres, który będzie w nagłówku Location.

Z jednej strony to fajnie, bo masz załatwioną część pracy. Z drugiej strony jeśli chcesz to przetestować krok po kroku np. Postmanem, to musisz mu wyłączyć opcję „Follow redirect” albo globalnie, albo na poziomie konkretnego requestu:

Niestety nie da się tego wyłączyć w Swaggerze.

Minusy takiego serwera

Oczywiście takie rozwiązanie (opisany serwer) ma swoje minusy, które w zależności od sytuacji można albo zaakceptować, albo nie.

Przede wszystkim tutaj serwer, mimo wszystko, odpowiada za przeprowadzenie długotrwałej operacji. Fakt, żadne wątki nie są blokowane, komunikacja z klientami jest szybka, natomiast jeśli uruchomimy kilka takich zadań, bo dostaniemy żądania od kilku klientów, wtedy nie skorzystamy za bardzo z asynchroniczności. Może się okazać, że aplikacja szybko będzie potrzebowała nowych zasobów i albo je dostanie (wzrost opłat za hosting), albo przestanie odpowiadać i się zblokuje. Daje to też możliwą podatność na atak DDoS.

Oczywiście, jeśli z apki korzysta kilkadziesiąt klientów raz na jakiś czas, to raczej nie ma to znaczenia. Ale już przy kilkuset czy kilku tysiącach, to jest nie do pomyślenia.

Jak zatem sobie z tym poradzić w rzeczywistości?

Odpowiedzią jest chmura.

Serwer asynchroniczny z użyciem chmurki

Pokażę Ci to na przykładzie Microsoft Azure. Jeśli nie wiesz, czym jest Azure, to ten akapit i następne nie dadzą Ci za wiele i na tym możesz skończyć czytanie. Jeśli jednak coś tam wiesz albo jesteś po prostu ciekawy, to czytaj dalej 🙂 Najpierw, z poczucia obowiązku, opiszę Ci bardzo ogólnie trzy usługi, z których będziemy korzystać.

Zakładam że posiadasz subskrypcję Azure’ową i wiesz jak rejestrować podstawowe usługi.

Poniższy przykład nie ma nic wspólnego z bezpieczeństwem. Ze względu na prostotę, wszystkie klucze i hasła będą przekazywane aplikacji w jawny sposób. Nie używamy tutaj KeyVaulta, żeby nie zaciemniać obrazu.

Usługi

Zauważ, że metod na rozwiązanie tego problemu jest zapewne kilka. Ja przedstawię Ci tylko jedną z nich. Oto usługi, z jakich będziemy korzystać:

  • Storage Queue
  • Azure Functions
  • CosmosDb

Oględny opis usług

Storage Queue

StorageQueue to usługa, która daje Ci kolejkę. Możesz kłaść do niej wiadomości, odczytywać je, a także zdejmować je z kolejki.

Azure Functions

Są to funkcje, które mogą być „serverless„, tzn. nie potrzebujesz do ich utrzymywania żadnego serwera. Ma to swoje plusy i minusy. Plusem zdecydowanie są (bardzo) małe koszty.

Potraktuj AzureFunction jak zwykłą funkcję lub metodę. Możesz ją napisać na kilka sposobów i w różnych językach. My się skupimy tutaj na kompilowanej wersji C#.

Dodatkowo funkcje Azurowe mają tzw. triggery – czyli coś, co je uruchamia. Jest wiele wbudowanych triggerów i one właściwie wystarczają. Jednym z nich jest np. wywołanie HTTP, innym – którego będziemy używać – dodanie nowej wiadomości do kolejki Storage Queue.

CosmosDB

CosmosDb to baza danych typu NoSQL. Na Azure znajduje się jej wersja „serverless”, dzięki czemu w prostych zastosowaniach koszty takiej bazy są naprawdę mikroskopijne.

W tej bazie będziemy trzymać dane dotyczące naszych prognoz.

Jeśli nie chcesz tworzyć usług ręcznie, w przykładowym kodzie są pliki BICEP, które utworzą infrastrukturę (o tym jak to zrobić piszę niżej).

Jak utworzyć usługi automatem?

W przykładowych kodach znajdują się pliki BICEP z opisaną strukturą usług. Teraz musisz się upewnić, że masz zainstalowane narzędzie az bicep:

az bicep version

lub je zainstalować:

az bicep install

Następnie za pomocą az musisz zalogować się do swojej subskrypcji na Azure i stworzyć grupę zasobów (dajmy na to: rg-rest-api).

Teraz, mając odpowiednią grupę, możesz uruchomić tworzenie usług. Przejdź w konsoli do katalogu deployment w przykładowych kodach, a następnie:

az deployment group create --resource-group "rg-rest-api" --template-file .\main.bicep

Po chwili wszystkie wymagane usługi będą utworzone w twojej resource grupie.

Tworzymy bazę danych

Na początek utwórzmy bazę danych CosmosDb (For NoSQL).

Tak naprawdę potrzebujemy tylko jednego kontenera. Nazwijmy go operations, a partitionKey ustawmy na requestId. W tym kontenerze będziemy trzymać wszystkie informacje.

Tworzymy kolejkę

Teraz stwórzmy kolejkę (Blob Storage Queue). Nowe wiadomości wpadające do tej kolejki będą odpalać Azurową funkcję, która będzie robiła całą robotę. W tym celu musimy utworzyć StorageAccount.

Jak widzisz, ja utworzyłem storage account o nazwie masterbranchweatherst, a w środku kolejkę o nazwie weather-requests-queue.

Super, została teraz już tylko logika do zrobienia. A to wymaga utworzenia funkcji Azurowej.

Tworzymy funkcję Azurową

Funkcja będzie uruchamiana wcześniej utworzoną kolejką. To znaczy, że jeśli w kolejce znajdzie się jakaś wiadomość, to to zdarzenie uruchomi funkcję i przekaże do niej konkretną wiadomość.

Oczywiście, jeśli w kolejce będzie 100 wiadomości, to jest szansa, że uruchomi się 100 funkcji równolegle. To jednak zależy od kilku czynników, którymi nie będziemy się zajmować w tym artykule. To co jest ważne, to to, że jeśli funkcje Azurowe nie będą w stanie obrobić wszystkich wiadomości od razu, te wiadomości będą po prostu czekać na swoją… kolej. Jak to w kolejce 🙂 Dzięki temu system wciąż będzie wydolny i nie zobaczymy żadnego przeciążenia. Po prostu niektóre wyniki będą nieco później dostępne.

Taka funkcja w najprostszej postaci może wyglądać jak w przykładzie:

public class AnalyzeWeather
{
    private readonly ILogger<AnalyzeWeather> _logger;
    private readonly WeatherRepository _weatherRepository;
    private readonly Randomizer _randomizer;

    public AnalyzeWeather(ILogger<AnalyzeWeather> logger, 
        WeatherRepository weatherRepository, 
        Randomizer randomizer)
    {
        _logger = logger;
        _weatherRepository = weatherRepository;
        _randomizer = randomizer;
    }

    [Function(nameof(AnalyzeWeather))]
    public async Task Run([QueueTrigger("weather-requests-queue", Connection = "QueueConnectionString")] QueueMessage message)
    {
        _logger.LogInformation("Weather analyzing started");

        WeatherQueueItem msgItem = message.Body.ToObjectFromJson<WeatherQueueItem>();

        WeatherDatabaseItem dbItem = new WeatherDatabaseItem();
        dbItem.Status = OperationStatus.InProgress;
        dbItem.RequestId = msgItem.Data.RequestId;
        dbItem.Data = msgItem.Data.Data;

        await _weatherRepository.UpsertWeatherOperation(dbItem);

        //symulacja
        await Task.Delay(30000);

        dbItem.Data.Summary = "Warm";
        dbItem.Data.TemperatureC = _randomizer.GetInt(20, 29);
        dbItem.Status = OperationStatus.Finished;

        await _weatherRepository.UpsertWeatherOperation(dbItem);            
    }
}

Nie omawiam tutaj, jak działają funkcje Azurowe i czym są, zakładam że wiesz to. Ale jeśli chciałbyś przeczytać o tym artykuł daj znać w komentarzu.

Tutaj sprawa jest prosta. Do funkcji trafia wiadomość z kolejki (parametr message). Wiadomość ma właściwość Body, w której znajdzie się json, którego wcześniej wysyłamy (o tym za chwilę).

To, co robimy w linii 22, to deserializujemy tego JSONa do konkretnego obiektu. Następnie (w linii 29) zapisujemy stan naszej operacji w bazie danych – zauważ, że ze statusem InProgress.

Potem symulujemy jakąś długą analizę, na koniec aktualizujemy nasz rekord w bazie danych częściowo losowymi danymi (to tak dla picu, żeby się działo :))

Wszystkie kody zobaczysz w przykładzie, nie jest celem tego artykułu opisywanie ich, bo byłby straaasznie długi. A to zwykła obsługa funkcji azurowej i CosmosDb.

OK, skoro już mamy funkcję azurową uruchamianą przez kolejkę, to teraz trzeba coś do tej kolejki dodać. I tu jest właśnie przeniesienie pracy i rozdzielenie naszej aplikacji na mniejsze części.

Dodajemy wiadomość do kolejki.

Tutaj sprawa jest prosta. To ma działać tak:

  • klient wysyła żądanie z pytaniem o prognozę pogody
  • jego żądanie jest wrzucane do kolejki
  • zwracamy mu odpowiedź 202 Accepted wraz z linkiem do pobierania informacji o statusie jego żądania

Najpierw pokażę Ci klasę, którą napisałem do wrzucenia żądania do kolejki:

public class StorageQueueService
{
    private readonly QueueOptions _queueOptions;

    public StorageQueueService(IOptions<QueueOptions> queueOptions)
    {
        _queueOptions = queueOptions.Value;
    }
    public async Task SendWeatherRequest(WeatherDatabaseItem item)
    {
        QueueClientOptions clientOptions = new QueueClientOptions
        {
            MessageEncoding = QueueMessageEncoding.Base64
        };

        var client = new QueueClient(_queueOptions.ConnectionString, 
            _queueOptions.WeatherQueueName, clientOptions);
        
        WeatherQueueItem queueItem = new WeatherQueueItem
        {
            Data = item
        };

        var serializedData = JsonSerializer.Serialize(queueItem);
        await client.SendMessageAsync(serializedData);
    }
}

Klasa jest dość prymitywna. Tworzymy ją z opcjami QueueOptions – to jest zwykła klasa trzymająca opcje, które pozwalają na połączenie się z kolejką:

public class QueueOptions
{
    public string ConnectionString {  get; set; }
    public string WeatherQueueName { get; set; }
}

Czyli mamy tutaj connection string do kolejki (w dokładniej do AzureBlobStorage), a także nazwę kolejki, do której chcemy wrzucać te żądania. Więcej o opcjach w .NET pisałem w tym artykule.

Następnie mamy tylko jedną metodę: SendWeatherRequest, która jest odpowiedzialna właśnie za wrzucenie konkretnego żądania na kolejkę. Wrzucamy to w postaci JSON, później otrzymamy to jako wiadomość w naszej funkcji Azure.

WeatherQueueItem to zwykła klasa, którą wykorzystuję dla danych wysyłanych do kolejki. Równie dobrze mógłbym posłużyć się WeatherDatabaseItem, jednak uznałem że tak będzie bardziej prawilnie. Ostatecznie ta wiadomość w kolejce może mieć jakieś dodatkowe dane. Natomiast, jak widzisz, WeatherDatabaseItem jest składnikiem WeatherQueueItem:

public class WeatherQueueItem
{
    public WeatherDatabaseItem Data {  get; set; }
}

StorageQueueService rejestrujemy jako Scoped (przy okazji konfigurujące opcje):

builder.Services.AddScoped<StorageQueueService>();
builder.Services.Configure<QueueOptions>(builder.Configuration.GetSection("StorageQueueOptions"));

Aktualizujemy WeatherForecastService

Teraz tylko zaktualizujemy sobie WeatherForecastService, bo kontroler będzie korzystał z niego:

public class WeatherForecastService
{
    private readonly Database _database;
    private readonly StorageQueueService _queueService;

    public WeatherForecastService(Database database, 
        StorageQueueService queueService)
    {
        _database = database;
        _queueService = queueService;
    }

    public async Task SetForecastRequestToQueue(Guid requestId, DateOnly date)
    {
        WeatherForecast forecast = new WeatherForecast
        {
            Date = date
        };

        WeatherDatabaseItem dbItem = new WeatherDatabaseItem
        {
            RequestId = requestId,
            Data = forecast,
            Status = OperationStatus.NotStarted,
        };

        await _queueService.SendWeatherRequest(dbItem);
    }
    //reszta bez zmian
}

No i na koniec dodajmy nowy endpoint do kontrolera:

[HttpGet(Name = "GetWeatherForecast/{date}")]
public async Task<IActionResult> Get(DateOnly date)
{
    Guid requestId = Guid.NewGuid();
    _ = _service.GetForecast(requestId, date);

    return await Task.FromResult(Accepted($"/WeatherForecast/Status/{requestId}"));
}

[HttpPost("GetAsyncWeatherForecast/{date}")]
public async Task<IActionResult> GetByQueue(DateOnly date)
{
    Guid requestId = Guid.NewGuid();
    await _service.SetForecastRequestToQueue(requestId, date);

    return Accepted($"/AsyncWeatherForecast/Status/{requestId}");
}

Podsumowanie

Ok, mamy prawie działający serwer asynchroniczny. Prawie, ponieważ nie ma tutaj końcówki do pobierania stanu ani wyniku. To będzie po prostu pobranie danych z CosmosDb, a działanie analogiczne do wersji serwera bez chmury.

Teraz, gdy wywołasz końcówkę GetByQueue, do kolejki zostanie dodana odpowiednia wiadomość. Dodanie tej wiadomości uruchomi funkcję Azurową. Funkcja odczyta tę wiadomość i zrobi odpowiednie wpisy w CosmosDb. To tyle.

Tworzenie asynchroniczności przy API synchronicznym

Może się zdarzyć taka sytuacja, że używasz API, które jest synchroniczne, jednak poszczególne żądania działają zbyt długo jak na Twoje wymagania.

W takiej sytuacji również możesz posłużyć się mechanizmem jak wyżej. I nie ma żadnego znaczenia, że nie masz dostępu do kodów API.

Musisz po prostu stworzyć jakąś kolejkę, funkcję Azure’ową i jakąś bazę danych. Teraz zamiast wysyłać żądanie do docelowego API, po prostu umieścisz odpowiedni komunikat w kolejce. Kolejka uruchomi funkcję Azurową, która strzeli do docelowego API. Po tym jak praca się skończy, funkcja Azure’owa może albo wysłać Ci powiadomienie (callback), albo po prostu zmienić dane w bazie, żebyś wiedział, że zadanie zostało zakończone.

Diagram takiej pracy może wyglądać w taki sposób (worker to docelowe API):


To tyle jeśli chodzi o asynchroniczne API. Nie przeczę, że temat może być zawiły zwłaszcza dla osób nie znających chmury lub juniorów. Jeśli czegoś nie zrozumiałeś lub znalazłeś w artykule błąd, koniecznie daj znać w komentarzu.

Podziel się artykułem na:
Jak zrobić własny mechanizm uwierzytelniania – na przykładzie API key i BasicAuth

Jak zrobić własny mechanizm uwierzytelniania – na przykładzie API key i BasicAuth

Wstęp

Hej, mimo że .NET daje Ci kilka gotowych mechanizmów (schematów) uwierzytelniania, to jednak czasem trzeba napisać coś swojego. Takimi przykładami mogą być Basic Authentication albo chociażby Api Key Authentication. Api Key będziesz używał wtedy, kiedy masz swoje API dostępne dla innych programistów, jednak chcesz uwierzytelnić w jakiś sposób każdego klienta, który z Twojego API korzysta.

W tym artykule pokażę Ci jak skonstruować swój własny mechanizm uwierzytelniania. Co więcej – pokażę jak wybrać dynamicznie odpowiedni schemat w zależności od przekazanego żądania. No to jedziemy.

Do artykułu przygotowałem przykładowe kody, które możesz pobrać z GitHub.

Czym jest uwierzytelnienie

Co nieco pisałem już na ten temat w artykule o uwierzytelnianiu i o tym, czym jest ClaimsPrincipal.

Generalnie proces uwierzytelnienia polega na tym, żeby sprawdzić dane identyfikacyjne, które przychodzą od użytkownika (np. w żądaniu HTTP) i wystawić na ich podstawie ClaimsPrincipal.

Najprostszym przykładem będzie właśnie klucz API. Załóżmy, że gdy klient korzysta z Twojego API, powinien w żądaniu wysłać nagłówek X-API-KEY. Jeśli go nie ma, taka osoba jest anonimowa (nie jest uwierzytelniona). Jeśli jest, to sprawdzasz, czy ten klucz jest gdzieś u Ciebie zarejestrowany. Jeśli tak, to na tej podstawie możesz stworzyć odpowiedni obiekt ClaimsPrincipal. Na tym właśnie polega cały proces – uwierzytelnij klienta, czyli zwróć informację na temat KIM ON JEST.

Później ten ClaimsPrincipal jest używany przez mechanizm autoryzacji, który sprawdza, co dany użytkownik może zrobić. No i ten ClaimsPrincipal jest dostępny w kontrolerach w HttpContext.User.

Czym tak naprawdę jest API Key?

Jeśli wystawiasz dla świata jakieś API, to to API może być publiczne (dostęp dla każdego), niepubliczne (dostęp tylko dla zarejestrowanych klientów) lub mieszane, przy czym zarejestrowani klienci mogą więcej.

Jeśli ktoś rejestruje u Ciebie klienta do Twojego API, powinieneś wydać mu tzw. API Key – klucz jednoznacznie identyfikujący takiego klienta. To może być w najprostszej postaci GUID. Po prawdzie klient też powinien dostać od Ciebie API Secret – czyli coś w rodzaju hasła.

Gdy klient chce wykonać jakąś operację na API, powinien się uwierzytelnić, wysyłając w żądaniu co najmniej Api Key. W taki sposób możesz logować operacje tego klienta lub w ogóle nie dopuścić go do używania API. Klient może się też uwierzytelnić za pomocą różnych mechanizmów jak OpenId Connect, ale ten artykuł nie jest o tym.

Dzisiaj pokazuję jak stworzyć taki mechanizm uwierzytelniania w .NET.

Jak działa mechanizm uwierzytelniania w .NET?

Tworząc swój własny mechanizm uwierzytelniania, tak naprawdę tworzysz własny „schemat”. Schemat to nic innego jak nazwa (np. „ApiKey”) połączona z Twoją klasą do uwierzytelniania (handler).

Wszystko sprowadza się ostatecznie do trzech kroków:

  • stwórz swój handler do uwierzytelniania (klasa dziedzicząca po AuthenticationHandler)
  • stwórz w nim obiekt ClaimsPrincipal
  • zarejestruj swój schemat

AuthenticationHandler

Całą obsługę uwierzytelniania robimy w klasie, która dziedziczy po AuthenticationHandler (bądź implementuje interfejs IAuthenticationHandler, co jest nieco trudniejsze). To na początek może wyglądać nieco skomplikowanie, ale jest proste.

Opcje

Klasa abstrakcyjna AuthenticationHandler jest klasą generyczną. Przyjmuje w parametrze typ, w którym trzymamy opcje naszego schematu uwierzytelnienia. Przy czym te opcje muszą dziedziczyć po klasie AuthenticationSchemeOptions i mogą być zupełnie puste, np.:

public class ApiKeyAuthenticationOptions: AuthenticationSchemeOptions
{

}

W tych opcjach możemy mieć wszystko, co nam się podoba. Przykładem może być uwierzytelnianie za pomocą Bearer Token, gdzie w opcjach masz czas życia takiego tokena, wystawcę itd. Żeby zademonstrować całość, zrobimy sobie ograniczenie do długości klucza API. Nie ma to w prawdzie żadnego zastosowania praktycznego. Po prostu pokazuję, jak wykorzystać te opcje:

public class ApiKeyAuthenticationOptions: AuthenticationSchemeOptions
{
    public int ApiKeyLength { get; set; }
    public bool CheckApiKeyLength { get; set; }
}

Handler

Teraz musimy napisać klasę, która będzie całym sercem uwierzytelniania – ta, która dziedziczy po AuthenticationHandler:

public class ApiKeyAuthenticationHandler : AuthenticationHandler<ApiKeyAuthenticationOptions>
{
    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        throw new NotImplementedException();
    }
}

Jak widzisz, wystarczy przesłonić metodę HandleAuthenticateAsync lub jej synchroniczną odpowiedniczkę.

Metoda musi zwrócić AuthenticationResult. Ten AuthenticationResult może przyjąć 3 stany:

  • sukces,
  • niepowodzenie,
  • brak wyniku.

Sukces

Jeśli rezultat kończy się sukcesem, musimy do niego przekazać „bilet” – ticket. Jest to taki mały obiekt, który trzyma informacje o schemacie uwierzytelnienia, ClaimsPrincipal i może zawierać jakieś dodatkowe dane (AuthenticationProperties). W swojej minimalnej postaci wystarczy mu nazwa schematu i ClaimsPrincipal.

Oczywiście „sukces” oznacza, że nasz mechanizm poprawnie uwierzytelnił danego klienta / użytkownika.

Niepowodzenie

Jeśli rezultat zakończy się niepowodzeniem (Fail) oznacza to, że nie dość, że użytkownik nie został uwierzytelniony przez nasz mechanizm, to jeszcze wszystkie inne ewentualne handlery już go nie mogą próbować uwierzytelnić.

Brak wyniku

Jeśli jednak rezultat zakończy się brakiem wyniku (NoResult) oznacza to, że użytkownik nie jest uwierzytelniony TYM SCHEMATEM, jednak inne ewentualne handlery mogą próbować go dalej uwierzytelniać.

Kiedy to stosujemy? Załóżmy, że mamy dwa schematy – ApiKey i Login + Hasło. Każdy handler jest uruchamiany po kolei przez Framework (chyba, że któryś handler zwróci sukces lub niepowodzenie – wtedy kolejne nie są już uruchamiane).

I teraz jeśli handler do ApiKey nie znajdzie klucza tam, gdzie powinien on być (np. w nagłówku żądania), może chcieć przekazać proces uwierzytelnienia kolejnym handlerom. Gdzieś tam wystartuje taki, który spodziewa się loginu i hasła.

Cały proces można by przedstawić w postaci prostego algorytmu:

UWAGA! W rzeczywistym świecie ta odpowiedź ma sens tylko, gdy w mechanizmie AUTORYZACJI wybrano kilka schematów uwierzytelnienia dla jakiejś końcówki. A, że to jak najbardziej jest możliwe, trzeba stosować tę wartość.

Podczas zwykłej operacji uwierzytelnienia (bez autoryzacji) zawsze w grę wchodzi tylko jeden schemat.

Konstruktor

Klasa AuthenticationHandler wymaga pewnych obiektów przekazanych w konstruktorze. Dlatego też minimalny konstruktor musi je przyjąć. Na szczęście wszystko ogarnia Dependency Injection. Teraz całość wygląda tak:

public class ApiKeyAuthenticationHandler : AuthenticationHandler<ApiKeyAuthenticationOptions>
{
    public ApiKeyAuthenticationHandler(IOptionsMonitor<ApiKeyAuthenticationOptions> options, 
        ILoggerFactory logger, 
        UrlEncoder encoder, 
        ISystemClock clock) : base(options, logger, encoder, clock)
    {
    }

    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        throw new NotImplementedException();
    }
}

Jak widzisz, jedną z tych wymaganych rzeczy jest IOptionsMonitor. Jeśli nie wiesz, czym to jest, pisałem o tym w artykule o opcjach.

Piszemy handlera

Napiszmy sobie teraz jakąś oszukaną klasę, która zwróci dane użytkownika, dla którego jest zarejestrowany dany ApiKey. Ta klasa pełni rolę „bazy danych”. Równie dobrze możesz tutaj użyć EfCore, czy czegokolwiek sobie życzysz:

public class ApiKeyClientProvider
{
    private Dictionary<string, ApiKeyClient> _clients = new Dictionary<string, ApiKeyClient>();
    public ApiKeyClientProvider()
    {
        AddClients();
    }

    public ApiKeyClient GetClient(string key)
    {
        ApiKeyClient result; ;

        if (_clients.TryGetValue(key, out result))
            return result;
        else
            return null;
    }

    private void AddClients()
    {
        var client = new ApiKeyClient()
        {
            ApiKey = "klucz-1",
            Email = "client1@example.com",
            Id = 1,
            Name = "Klient 1"
        };

        _clients[client.ApiKey] = client;

        var client2 = new ApiKeyClient()
        {
            ApiKey = "klucz-2",
            Email = "client2@example.com",
            Id = 2,
            Name = "Klient 2"
        };

        _clients[client2.ApiKey] = client2;
    }
}

W kolejnym kroku możemy zaimplementować ostatecznie nasz schemat uwierzytelniania:

public class ApiKeyAuthenticationHandler : AuthenticationHandler<ApiKeyAuthenticationOptions>
{
    private readonly ApiKeyClientProvider _clientProvider;
    public ApiKeyAuthenticationHandler(
        ApiKeyClientProvider clientProvider, //wstrzykujemy naszą oszukaną bazę danych
        IOptionsMonitor<ApiKeyAuthenticationOptions> options, 
        ILoggerFactory logger, 
        UrlEncoder encoder, 
        ISystemClock clock) : base(options, logger, encoder, clock)
    {
        _clientProvider = clientProvider;
    }

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        var apiKey = GetApiKey();
        if (string.IsNullOrWhiteSpace(apiKey))
            return AuthenticateResult.Fail("No API key provided");

        var client = _clientProvider.GetClient(apiKey);
        if (client == null)
            return AuthenticateResult.Fail("Invalid API key");

        var principal = CreatePrincipal(client);

        AuthenticationTicket ticket = new AuthenticationTicket(principal, "ApiKey");
        return AuthenticateResult.Success(ticket);
    }

    private string GetApiKey()
    {
        StringValues keyValue;
        if (!Context.Request.Headers.TryGetValue("X-API-KEY", out keyValue))
            return null;

        if (!keyValue.Any())
            return null;

        return keyValue.ElementAt(0);
    }

    private ClaimsPrincipal CreatePrincipal(ApiKeyClient client)
    {
        ClaimsIdentity identity = new ClaimsIdentity("ApiKey");
        identity.AddClaim(new Claim(ClaimTypes.Email, client.Email));
        identity.AddClaim(new Claim(ClaimTypes.NameIdentifier, client.Id.ToString()));
        identity.AddClaim(new Claim(ClaimTypes.Name, client.Name));

        return new ClaimsPrincipal(identity);
    }
}

Przejdźmy ją fragmentami.

Na samym dole jest metoda CreatePrincipal. Ona tworzy obiekt ClaimsPrincipal na podstawie przekazanego rekordu klienta z naszej bazy.

Tworzenie ClaimsPrincipal polega w sumie na utworzeniu odpowiednich ClaimsIdentity wraz z Claimsami. ApiKey, które widzisz podczas tworzenia ClaimsIdentity to po prostu nazwa naszego schematu. Dzięki temu wiesz – aha, ten ClaimsIdentity powstał ze schematu ApiKey.

Jeśli nie wiesz, czym jest ten ClaimsPrincipal i Claimsy, przeczytaj ten artykuł.

Ok, dalej mamy metodę GetApiKey. Ona po prostu pobiera wartość odpowiedniego nagłówka żądania. Jak widzisz, klasa AuthenticationHandler daje nam bezpośredni dostęp do kontekstu HTTP przez właściwość Context.

No i najważniejsza metoda – HandleAuthenticateAsync. Przyjrzyjmy się jej jeszcze raz:

protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
{
    var apiKey = GetApiKey();
    if (string.IsNullOrWhiteSpace(apiKey))
        return AuthenticateResult.NoResult;

    var client = _clientProvider.GetClient(apiKey);
    if (client == null)
        return AuthenticateResult.Fail("Invalid API key");

    var principal = CreatePrincipal(client);

    AuthenticationTicket ticket = new AuthenticationTicket(principal, "ApiKey");
    return AuthenticateResult.Success(ticket);
}

Na początku pobieramy klucz API z nagłówka żądania. Jeśli jest pusty, to znaczy że nie można uwierzytelnić takiego klienta TYM SCHEMATEM. Klient po prostu nie dodał klucza do żądania. Zwracamy błąd uwierzytelnienia. Być może inny schemat będzie w stanie go zidentyfikować.

Jeśli jednak ten klucz jest, pobieramy użytkownika przypisanego do niego z naszej bazy. I znowu – jeśli taki użytkownik nie istnieje, to znaczy że klucz API nie jest prawidłowy.

Na koniec jeśli użytkownik istnieje, tworzymy na jego podstawie ClaimsPrincipal. Na koniec wydajemy mu „bilecik” z jego danymi i zwracamy sukces uwierzytelnienia.

Używamy opcji

Jak widzisz, nie dorobiliśmy jeszcze sprawdzenia, czy nasz klucz API ma odpowiednią długość. Ale wszystko mamy wstrzyknięte w konstruktorze. IOptionsMonitor daje nam te opcje. Wykorzystajmy więc go. Jeśli nie wiesz, czym jest IOptionsMonitor i jak z niego korzystać, przeczytaj ten artykuł.

protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
{
    var apiKey = GetApiKey();
    if (string.IsNullOrWhiteSpace(apiKey))
        return AuthenticateResult.Fail("No API key provided");

    if (Options.CheckApiKeyLength)
    {
        if (apiKey.Length != Options.ApiKeyLength)
            return AuthenticateResult.Fail("Invalid API key");
    }

    var client = _clientProvider.GetClient(apiKey);
    if (client == null)
        return AuthenticateResult.Fail("Invalid API key");

    var principal = CreatePrincipal(client);

    AuthenticationTicket ticket = new AuthenticationTicket(principal, "ApiKey");
    return AuthenticateResult.Success(ticket);
}

Jak widzisz, dostęp do opcji uwierzytelniania masz przez właściwość Options z klasy bazowej. Teraz tylko musimy zarejestrować nasz schemat.

Rejestracja

Pamiętaj o rejestracji naszej „bazy danych”:

builder.Services.AddScoped<ApiKeyClientProvider>();

No i sam schemat:

builder.Services.AddAuthentication("ApiKey")
    .AddScheme<ApiKeyAuthenticationOptions, ApiKeyAuthenticationHandler>("ApiKey", o =>
    {
        o.ApiKeyLength = 7;
        o.CheckApiKeyLength = true;
    });

Wszystko rozbija się o rejestrację AddAuthentication. W parametrze podajemy domyślny schemat uwierzytelniania. Następnie dodajemy nasz schemat przez metodę AddScheme. Jeśli nie używasz opcji, to w drugim parametrze możesz dać po prostu null. Drugi parametr to delegat, który ustawia nasze opcje. Oczywiście w prawdziwym programie te wartości byłyby pobierane z konfiguracji.

Pamiętaj też o middleware. Musisz dodać przed UseAuthorization():

app.UseAuthentication();
app.UseAuthorization();

Challenge

Challenge (authentication challenge) to mechanizm, który jest uruchamiany przez .NET, gdy użytkownika nie można uwierzytelnić. Efektem tego może być przejście na stronę logowania albo po prostu dodanie jakiejś informacji w odpowiedzi na żądanie. Domyślny Challenge zwraca po prostu błąd 401.

Aby zrobić coś swojego, wystarczy przeciążyć metodę HandleChallengeAsync w naszej klasie. Można to zrobić tak:

protected override Task HandleChallengeAsync(AuthenticationProperties properties)
{
    Response.Headers.WWWAuthenticate = new StringValues("X-API-KEY");
    return Task.CompletedTask;
}

Podczas wywoływania HandleChallengeAsync przez .Net możemy korzystać z Response – czyli możemy modyfikować sobie odpowiedź do klienta. Standardowym podejściem w takim przypadku jest umieszczenie nagłówka www-authenticate z nazwą schematu lub jakimiś wskazówkami, jak uwierzytelniać się w naszym systemie.

To jest opcjonalne, Domyślny mechanizm, jak mówiłem, zwraca po prostu błąd 401.

Jeśli spróbujesz teraz pobrać dane przez Postmana, oczywiście nie zobaczysz ich, ale zostanie zwrócony Ci właśnie ten nagłówek. Zwróć też uwagę na to, że zwrócony kod operacji (200) oznacza operację zakończoną sukcesem:

ForwardChallenge

Jeśli przyjrzysz się klasie bazowej do opcji uwierzytelniania, zobaczysz taką właściwość jak ForwardChallenge. Możesz tutaj przypisać nazwę schematu, który będzie użyty do Challengowania. Jeśli więc podczas konfiguracji naszego schematu, przypisałbyś takie opcje:

builder.Services.AddAuthentication("ApiKey")
    .AddScheme<ApiKeyAuthenticationOptions, ApiKeyAuthenticationHandler>("ApiKey", o =>
    {
        o.ApiKeyLength = 7;
        o.CheckApiKeyLength = true;
        o.ForwardChallenge = "Bearer";
    });

To wtedy, jeśli Twój schemat nie uwierzytelni użytkownika, Challenge zostanie przekazany do schematu o nazwie Bearer. Oczywiście, jeśli taki schemat nie został zarejestrowany, program się wysypie.

Forbid

To jest metoda, która wykona się, gdy dostęp do zasobu nie został udzielony dla Twojego schematu uwierzytelniania. Inaczej mówiąc, załóżmy że masz dwa schematy uwierzytelniania:

  • Użytkownik podaje login i hasło
  • Klient API podaje klucz API

Teraz, niektóre końcówki mogą wymagać konkretnego schematu uwierzytelniania. Załóżmy, że mamy jakieś końcówki administracyjne, na które nie można się dobić za pomocą uwierzytelniania przez klucz API. One wymagają uwierzytelnienia za pomocą loginu i hasła. Można to w kontrolerze zablokować przekazując po prostu nazwę schematu, który oczekujemy, np:

[Authorize(AuthenticationSchemes = "LoginAndPass")]

I teraz załóżmy taką sytuację. Jakiś klient API został uwierzytelniony przez nasze ApiKeyAuthorizationHandler. Natomiast końcówka wymaga uwierzytelnienia przez jakiś schemat LoginAndPass. W tym momencie zostanie wywołana metoda Forbid w naszym handlerze (ponieważ to nasz handler go uwierzytelnił). Działa to analogicznie do metody Challenge. Domyślnie zwracany jest błąd 403.

Oczywiście tutaj też możemy przekazać Forbid do innego schematu, używając – analogicznie jak przy Challenge – ForwardForbid w opcjach uwierzytelniania.

Inne opcje

Jeśli chodzi o uwierzytelnianie klientów API, istnieje inna opcja, w której właściwie nie musisz pisać tego kodu. Jest to usługa Azure’owa o nazwie Azure API Management, która załatwia to wszystko za Ciebie. Możesz też ustawić limity czasowe/ilościowe dla konkretnych klientów. Czego dusza zapragnie. Usługa daje Ci duuużo więcej (wraz z portalem dla Twoich klientów). Nie jest jednak darmowa.

Basic Authentication

Basic Authentication to standardowy mechanizm uwierzytelniania. Polega on na obecności odpowiedniej wartości w nagłówku Authentication.

A ta wartość to po prostu: Base64(<login>:<hasło>).

Czyli dajesz login i hasło przedzielone dwukropkiem, a następnie konwertujesz to na Base64. Taką wartość umieszcza się w nagłówku Authentication. Jak zapewne się domyślasz, nie jest to zbyt dobra metoda, jednak jest używana. W związku z tym, że przekazywane jest jawnie login i hasło, konieczne jest użycie SSL przy tej formie.

Napiszemy sobie teraz prosty mechanizm uwierzytelniania używający właśnie Basic Authentication. To będzie zrobione analogicznie do tego, co robiliśmy wyżej. Więc możesz po prostu przejrzeć sobie kod:

public class BasicAuthenticationOptions: AuthenticationSchemeOptions
{
}
public class BasicAuthenticationHandler : AuthenticationHandler<BasicAuthenticationOptions>
{
    private readonly UserProvider _userProvider;
    private record UserCredentials(string login, string password);
    
    public BasicAuthenticationHandler(
        UserProvider userProvider,
        IOptionsMonitor<BasicAuthenticationOptions> options, 
        ILoggerFactory logger, 
        UrlEncoder encoder, 
        ISystemClock clock) : base(options, logger, encoder, clock)
    {
        _userProvider = userProvider;
    }

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        var creds = RetrieveCredentials();
        if (creds == null)
            return AuthenticateResult.Fail("No credentials");

        var userData = _userProvider.GetUser(creds.login, creds.password);
        if (userData == null)
            return AuthenticateResult.Fail("No such user");

        if (userData.Password != creds.password)
            return AuthenticateResult.Fail("Invalid password");

        var principal = CreatePrincipal(userData);
        var ticket = new AuthenticationTicket(principal, "Basic");

        return AuthenticateResult.Success(ticket);
    }

  private UserCredentials RetrieveCredentials()
  {
      if (Context.Request.Headers.Authorization.Count == 0)
          return null;

      var basedValue = Context.Request.Headers.Authorization[0];
      if (basedValue.StartsWith("Basic "))
          basedValue = basedValue.Remove(0, "Basic ".Length);
      else
          return null;

      var byteData = Convert.FromBase64String(basedValue);
      var credsData = Encoding.UTF8.GetString(byteData);

      var credValues = credsData.Split(':');
      if (credValues == null || credValues.Length != 2)
          return null;

      return new UserCredentials(credValues[0], credValues[1]);
  }

    private ClaimsPrincipal CreatePrincipal(UserData user)
    {
        ClaimsIdentity identity = new ClaimsIdentity("Basic");
        identity.AddClaim(new Claim(ClaimTypes.Email, user.Email));
        identity.AddClaim(new Claim(ClaimTypes.NameIdentifier, user.Id.ToString()));
        identity.AddClaim(new Claim(ClaimTypes.Name, user.UserName));

        return new ClaimsPrincipal(identity);
    }
}

Jedyne, czego tu nie widać, to klasa UserProvider, która wygląda bardzo podobnie jak ApiKeyClientProvider. Możesz zobaczyć całość na GitHub. Wszystko działa tutaj analogicznie.

Dodałem tę metodę, żeby pokazać Ci teraz, w jaki sposób możesz dynamicznie wybrać sobie schemat uwierzytelniania.

Dynamiczny wybór schematu uwierzytelniania

Żeby móc dynamicznie wybrać schemat, musimy dodatkowo dodać politykę. To nie wymaga dużo wysiłku, spójrz na ten kod:

builder.Services.AddAuthentication("ApiKeyOrBasic")
    .AddScheme<ApiKeyAuthenticationOptions, ApiKeyAuthenticationHandler>("ApiKey", o =>
    {
        o.ApiKeyLength = 7;
        o.CheckApiKeyLength = true;
    })
    .AddScheme<BasicAuthenticationOptions, BasicAuthenticationHandler>("Basic", null)
    .AddPolicyScheme("ApiKeyOrBasic", null, o =>
    {
        o.ForwardDefaultSelector = context =>
        {
            if (context.Request.Headers.ContainsKey("X-API-KEY"))
                return "ApiKey";
            else
                return "Basic";
        };
    });

Gdy rejestrujemy mechanizmy uwierzytelniania przez AddAuthentication, zobacz że jako domyślny schemat podajemy nazwę ApiKeyOrBasic – czyli nazwę naszej polityki do wyboru schematu.

Teraz, wykonując AddPolicyScheme, rejestrujemy właśnie taką politykę.

W rezultacie, wywołany zostanie domyślny schemat uwierzytelniania – czyli nasza polityka, która po prostu sprawdzi, czy w żądaniu znajduje się odpowiedni nagłówek. Następnie zwraca nazwę schematu, którym to żądanie powinno być uwierzytelnione. Nazwa trafia do ForwardDefaultSelector.

.NET w kolejnym kroku uruchomi właśnie ten schemat.

Czym jest domyślna nazwa schematu?

W .NET możesz m.in. przy kontrolerach wymagać uwierzytelnienia użytkownika konkretnym schematem. Czyli przykładowo: „Jeśli użytkownik chce wykonać tę operację, MUSI być zalogowany schematem login i hasło„.

Jeśli tego nie podasz jawnie, wtedy do gry wejdzie domyślny schemat uwierzytelniania. Dlatego ważne jest, żeby zawsze go podać.

Dobre praktyki

Kod, który pokazałem nie zawiera dobrych praktyk. Ale dzięki temu jest bardziej czytelny.

W prawdziwym kodzie upewnij się, że stosujesz te dobre praktyki, czyli:

  • Nazwy nagłówków – jeśli wprowadzasz jakieś własne nazwy nagłówków, upewnij się, że NIE zaczynają się od X-. Jest to przestarzała forma, która jest już odradzana przez konsorcjum. Zamiast tego powinieneś w jakiś jednoznaczny sposób nazwać swój nagłówek, np.: MOJ-PROGRAM-API-KEY.
  • Nazwy schematów w gołych stringach – no coś takiego w prawdziwym kodzie woła o pomstę do nieba. Powinieneś stworzyć jakieś stałe w stylu:
class ApiKeyAuthenticationDefaults
{
    public const string SchemeName = "ApiKey";
}

i posługiwać się tymi stałymi.

  • Nazwy nagłówków w gołych stringach – tutaj tak samo. Wszystko powinno iść przez stałe.

Dzięki za przeczytanie tego artykułu. Jeśli czegoś nie rozumiesz lub znalazłeś błąd, koniecznie daj znać w komentarzu. No i udostępnij go osobom, którym się przyda 🙂

Obrazek wyróżniający: Obraz autorstwa macrovector na Freepik

Podziel się artykułem na:
Walidacja opcji

Walidacja opcji

Wstęp

Kiedy tworzysz opcje do swojego programu, warto dodatkowo je walidować. Pewnie, że nie wszystkie. Jednak daje to większe poczucie spokoju, zwłaszcza kiedy aplikacja chodzi na różnych środowiskach (chociażby produkcyjne i deweloperskie). Jeśli ktoś przez pomyłkę źle skonfiguruje system, to nie będzie on działał poprawnie. Co więcej, przez długi czas możesz się o tym nie dowiedzieć. Niepoprawne opcje mogą przez dłuższy czas nie dawać o sobie znaku. Walidacja ich od razu może rozwalić program. Od razu będzie wiadomo, że coś jest nie tak.

W tym artykule pokażę Ci jak możesz walidować swoje opcje zarówno za pomocą adnotacji, jak i fluent validation.

Jeśli nie wiesz jak konfigurować opcje w .NET, koniecznie przeczytaj ten artykuł: Konfiguracja i opcje programu w .NET.

Przykładowy projekt

Do tego artykułu przygotowałem przykładowy projekt, który możesz pobrać z GitHuba: https://github.com/AdamJachocki/OptionsValidation/tree/master

Podstawy walidacji

.NET umożliwia Ci walidację opcji na kilka różnych sposobów. Możesz sprawdzać typowymi adnotacjami (DataAnnotations) w klasie modelu opcji. Pisałem już o tym w artykule o walidacji.

Załóżmy więc, że mamy taki prosty model opcji:

public class SimpleOptions
{
    [EmailAddress]
    public string SenderEmail { get; set; }
    [Required]
    public string SmtpAddress { get; set; }
}

Jak widać, walidujemy tutaj za pomocą adnotacji. Pole SenderEmail musi być adresem e-mail, natomiast pole SmtpAddress jest wymagane.

Teraz, żeby uruchomić walidację, trzeba nieco inaczej skonfigurować te opcje niż w sposób domyślny opisany w tym artykule. Teraz zamiast metody Configure, użyjemy AddOptions, które zwraca obiekt klasy OptionBuilder, który z kolei umożliwia walidacje:

services.AddOptions<SimpleOptions>()
	.Bind(Configuration.GetSection("SimpleOptions"))
	.ValidateDataAnnotations();

Zauważ, że używając OptionBuildera, trzeba użyć metody Bind do powiązania tych opcji i na koniec ValidateDataAnnotations, co uruchomi walidację tych opcji, używając adnotacji. Tylko adnotacji. Pamiętaj o tym.

Teraz, jeśli jakieś opcje nie będą spełniały założeń, podczas ich wstrzykiwania pójdzie wyjątek. Np. spójrz na taki appsettings.json:

 {
   "SimpleOptions": {
    "SenderEmail": "admin@example.com"
  }
}

Jak widzisz, nie ma tutaj w ogóle pola SmtpAddress, które jest wymagane w naszym modelu. Teraz, jeśli chcielibyśmy takie opcje odczytać np.:

[Route("api/[controller]")]
[ApiController]
public class TestController : ControllerBase
{
    private readonly SimpleOptions _simpleOptions;
    public TestController(IOptions<SimpleOptions> simpleOptions)
    {
        _simpleOptions = simpleOptions.Value;
    }
}

to w linijce 8 dostaniemy wyjątek. Takich opcji nie można pobrać, bo nie spełniają warunków.

Problemem jest to, że program musi dojść do tego miejsca, żeby opcje zostały zwalidowane. Na szczęście w .NET6 można sprawdzić konkretne opcje już podczas uruchamiania aplikacji, co jest naprawdę mega użyteczne. Piszę o tym później.

Oczywiście sam możesz pisać własne atrybuty walidacyjne, o czym pisałem tutaj. Wystarczy napisać klasę dziedziczącą po ValidationAttribute.

To prosta walidacja. Nie można za jej pomocą zrobić bardziej wyrafinowanych sprawdzeń. A jeśli można to jest to uciążliwe. Dlatego dla takich scenariuszy przychodzi kolejna możliwość…

Własny walidator

Wystarczy stworzyć własny walidator – klasę, która implementuje interfejs IValidateOptions. Nic nie stoi na przeszkodzie, żeby Twój model ten interfejs implementował, jednak z punktu widzenia czystości kodu, to nie jest dobre rozwiązanie. Pamiętaj o tym.

Stworzę zatem osobną klasę, która będzie walidować taki model:

public class ApiOptions
{
    public string ClientId { get; set; }
    public string ClientSecret { get; set; }
    public string ClientUri { get; set; }
}

Te przykładowe opcje pozwalają się łączyć z hipotetycznym API. Założenie jest takie, że albo podajemy ClientId i ClientSecret (który musi być odpowiedniej długości), albo podajemy ClientUri. Napiszmy teraz walidator do tego. Zacznijmy od pustego:

public class ApiOptionsValidator : IValidateOptions<ApiOptions>
{
    public ValidateOptionsResult Validate(string? name, ApiOptions options)
    {
        
    }
}

Jak widzisz, interfejs IValidateOptions posiada tylko jedną metodę do implementacji. W parametrze name dostaniesz nazwę tych opcji, jeśli używasz named options. Natomiast w parametrze options otrzymasz cały model odczytany z konfiguracji. I teraz możesz go sprawdzić np. w taki najprostszy sposób:

public class ApiOptionsValidator : IValidateOptions<ApiOptions>
{
    public ValidateOptionsResult Validate(string? name, ApiOptions options)
    {
        bool isIdAndSecret = IsIdAndSecret(options);
        bool isUri = IsUri(options);

        if (isIdAndSecret && isUri)
            return ValidateOptionsResult.Fail("Nie możesz jednocześnie podać ClientUri i sekretów");

        if (!isIdAndSecret && !isUri)
            return ValidateOptionsResult.Fail("Musisz podać jakieś dane do połączenia z API");

        if (isIdAndSecret && options.ClientSecret.Length < 5)
            return ValidateOptionsResult.Fail("Client secret jest za krótki");

        return ValidateOptionsResult.Success;
    }

    private bool IsIdAndSecret(ApiOptions options)
    {
        return !string.IsNullOrWhiteSpace(options.ClientId) && !string.IsNullOrWhiteSpace(options.ClientSecret);
    }

    private bool IsUri(ApiOptions options)
    {
        return !string.IsNullOrWhiteSpace(options.ClientUri);
    }
}

Po prostu wykonujemy kilka prostych sprawdzeń i albo zwracamy ValidateOptionsResult.Success, albo Fail. W przypadku, jeśli walidacja się nie powiedzie, zachowanie będzie identyczne jak przy walidacji adnotacjami. Program się wywali na próbie pobrania opcji.

Teraz tylko trzeba to zarejestrować w nieco inny sposób. Możemy posłużyć się zarówno OptionsBuilderem jak i konfiguracją, jednak trzeba dodatkowo zarejestrować takiego walidatora:

builder.Services.Configure<ApiOptions>(builder.Configuration.GetSection("ApiOptions"));
builder.Services.AddSingleton<IValidateOptions<ApiOptions>, ApiOptionsValidator>();

Nowość w .NET8

W .NET8 wprowadzono budowniczego ValidateOptionsResultBuilder, którym możesz sobie zbudować cały rezultat jeśli chcesz. Dzięki temu możesz zwrócić kilka błędów. Powyższy kod mógłby wyglądać tak:

public class ApiOptionsValidator : IValidateOptions<ApiOptions>
{
    public ValidateOptionsResult Validate(string? name, ApiOptions options)
    {
        bool isIdAndSecret = IsIdAndSecret(options);
        bool isUri = IsUri(options);

        ValidateOptionsResultBuilder builder = new();

        if (isIdAndSecret && isUri)
            builder.AddError("Nie możesz jednocześnie podać ClientUri i sekretów");

        if (!isIdAndSecret && !isUri)
            builder.AddError("Musisz podać jakieś dane do połączenia z API");

        if (isIdAndSecret && options.ClientSecret.Length < 5)
            builder.AddResult(ValidateOptionsResult.Fail("Client secret jest za krótki"));

        return builder.Build();
    }

    private bool IsIdAndSecret(ApiOptions options)
    {
        return !string.IsNullOrWhiteSpace(options.ClientId) && !string.IsNullOrWhiteSpace(options.ClientSecret);
    }

    private bool IsUri(ApiOptions options)
    {
        return !string.IsNullOrWhiteSpace(options.ClientUri);
    }
}

Zaznaczyłem znaczące linie. Jak widzisz, możesz do buildera dodawać zarówno errory jak i całe obiekty ValidateOptionsResult.

Dzięki temu możesz pokazać wszystkie problemy związane z opcjami, a nie tylko jeden.

Walidacja w OptionsBuilderze

Ten sposób walidacji zostawiam raczej jako ciekawostkę. W małych systemach pewnie się sprawdzi, natomiast w większych lepiej go unikać.

Można napisać kod walidacyjny podczas rejestrowania opcji:

builder.Services.AddOptions<ApiOptions>()
    .Bind(builder.Configuration.GetSection("ApiOptions"))
    .Validate(options =>
    {
        if (string.IsNullOrWhiteSpace(options.ClientUri)
            && string.IsNullOrWhiteSpace(options.ClientId)
            && string.IsNullOrWhiteSpace(options.ClientSecret))
            return false;

        return true;
    });

To tylko fragment wcześniejszej walidacji. Musiałbym napisać resztę przypadków, ale to nie ma sensu (bo to tylko przykład). Tutaj metoda Validate przyjmuje delegat – funkcję, która zwraca bool, a w parametrze ma model opcji.

Dlaczego to nie ma sensu? To chyba widać. W przypadku większej ilości opcji lub bardziej wyrafinowanych walidacji w kodzie po prostu zrobi się burdel i całość stanie się mało czytelna.

Tak jak mówiłem wcześniej – w małych, szybkich projektach to się może sprawdzić. Natomiast w większych raczej nie.

Walidacja przy starcie systemu

Domyślny mechanizm będzie walidował opcje dopiero w momencie próby ich pobrania: var myOptions = options.Value. Natomiast możesz sobie życzyć, żeby opcje były sprawdzane podczas uruchamiania programu. Plusem tego jest to, że od razu dowiesz się, że coś jest nie tak, bo apka wywali się podczas uruchamiania. Minus? Aplikacja będzie potrzebować nieco więcej czasu, żeby się uruchomić, ponieważ będzie sprawdzać opcje, które wskażesz. Myślę jednak, że warto to zrobić, bo od razu dostajesz wiedzę, że coś jest źle skonfigurowane.

Wystarczy, że wywołasz metodę ValidateOnStart z OptionsBuilder:

builder.Services.AddOptions<SimpleOptions>()
    .Bind(builder.Configuration.GetSection("SimpleOptions"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

Pamiętaj, że metoda ValidateOnStart doszła dopiero w .NET6. Dlatego jeśli masz projekt we wcześniejszej wersji przemyśl migrację do .NET6.

Walidacja typu FLUENT

Na koniec pokażę jak zaprząc do walidacji opcji znaną i lubianą bibliotekę open source – FluentValidation. Od razu zaznaczam, że ten artykuł nie jest kursem ani nawet nie muska działania tej biblioteki. Jeśli wiesz, co ona robi, ten akapit może Ci się przydać. W innym przypadku spróbuj się z nią najpierw zapoznać.

FluentValidation umożliwia walidacje w sposób „fluent” modeli. Jednak standardowo nie obsługuje opcji. Można to w dość prosty sposób zmienić.

Spójrzmy na przykładowy model opcji:

public class FluentApiOptions
{
    public string ClientId { get; set; }
    public string ClientSecret { get; set; }
    public string ClientUri { get; set; }
    public string ApiUrl { get; set; }
}

Założenia będą takie jak w poprzednim przykładzie, tzn. podajemy albo clientId i secret, albo clientUri. Jedno z dwóch. Dodatkowo zawsze musi być ApiUrl.

Walidator Fluenta

Napiszmy do tego standardowy walidator fluentowy:

public class FluentApiOptionsValidator: AbstractValidator<FluentApiOptions>
{
    public FluentApiOptionsValidator()
    {
        RuleFor(x => x.ApiUrl)
            .NotEmpty();

        RuleFor(x => x.ClientUri)
            .NotEmpty()
            .When(x => string.IsNullOrWhiteSpace(x.ClientId) && string.IsNullOrWhiteSpace(x.ClientSecret))
            .WithMessage("Jeśli nie podajesz clientId i sekretu, musisz podać ClientUri")
            .MinimumLength(5)
            .WithMessage("ClientUri jest za krótkie");

        RuleFor(x => x.ClientId)
            .NotEmpty()
            .When(x => string.IsNullOrWhiteSpace(x.ClientUri))
            .WithMessage("Musisz podać ClientId i sekret, jeśli nie podajesz ClientUri");

        RuleFor(x => x.ClientSecret)
            .NotEmpty()
            .When(x => !string.IsNullOrWhiteSpace(x.ClientId))
            .WithMessage("Brak client secret");
    }
}

I dopiero teraz zacznie się zabawa.

Mając już walidator do konkretnego modelu, musimy teraz stworzyć swój własny walidator opcji – ten, implementujący interfejs IValidateOptions. Dlaczego?

Integracja z opcjami

Jak już mówiłem, FluentValidation nie jest domyślnie zintegrowany z mechanizmem opcji w .NET. A szkoda, bo mógłby być. Zatem sami musimy sobie taką integrację zapewnić. I tutaj przychodzi z pomocą IValidateOptions. Utworzymy generyczny walidator, żeby można go było używać z każdym typem opcji. To w najprostszej postaci może wyglądać tak:

public class GenericFluentValidator<TOptions> : IValidateOptions<TOptions>
    where TOptions : class
{
    private readonly IServiceProvider _serviceProvider;
    private readonly string _name;

    public GenericFluentValidator(string name, IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
        _name = name;
    }

    public ValidateOptionsResult Validate(string? name, TOptions options)
    {
        if (_name != null && _name != name)
            return ValidateOptionsResult.Skip;

        using var scope = _serviceProvider.CreateScope();
        var validator = scope.ServiceProvider.GetRequiredService<IValidator<TOptions>>();

        ValidationResult res = validator.Validate(options);
        if (res.IsValid)
            return ValidateOptionsResult.Success;

        var errorArray = res.Errors.Select(e => e.ErrorMessage).ToArray();
        var msg = string.Join(Environment.NewLine, errorArray);

        return ValidateOptionsResult.Fail(msg);              
    }
}

To na pierwszy rzut oka może okazać się zawiłe, ale jest naprawdę bardzo proste.

Pomińmy na razie konstruktor – w jakiś sposób dostaniemy IServiceProvider i nazwę (jeśli używamy named options). Przejdźmy od razu do metody Validate.

Najpierw sprawdzamy, czy używamy named options i czy to odpowiedni do tego walidator. Jeśli nie, to olewamy.

Następnie tworzymy sobie scope’a, żeby pobrać z niego serwis implementujący IValidator<TOptions>. A teraz pytanie – co to takiego? Interfejs IValidator<T> pochodzi z FluentValidation. Wszystkie walidatory ten interfejs implementują. A więc po prostu szukamy walidatora dla konkretnego typu.

Gdy już mamy go, to w linijce 21 uruchamiamy walidację. Jeśli się udała, zwracamy sukces. Jeśli nie, zwracamy listę błędów z tego walidatora w postaci jednego stringa.

Rejestracja

Teraz, jak już wiesz, trzeba zarejestrować ten GenericFluentValidator:

builder.Services.AddSingleton<IValidateOptions<FluentApiOptions>>(sp =>
{
    return new GenericFluentValidator<FluentApiOptions>("", sp);
});

Po prostu dodajemy go tak jak w poprzednich przykładach, tyle że z wykorzystaniem fabryki – dzięki czemu możemy przekazać IServiceProvidera. Parametrem name na razie się nie przejmuj, zajmiemy się nim później.

Na koniec wystarczy zarejestrować konkretny walidator modelu:

builder.Services.AddSingleton<IValidator<FluentApiOptions>, FluentApiOptionsValidator>();

No i wszystko śmiga. Ale przyznasz, że żeby ogarnąć jeden model w taki sposób, trzeba się sporo napisać. Właściwie upierdliwe są te rejestracje. Ale jest na to metoda…

Upraszczamy rejestracje

Posłużymy się extensioniem, żeby ułatwić sobie pracę. Całą rejestrację przeniesiemy do extensiona. Przy okazji załatwi nam to problem named options:

public static class OptionsBuilderExtensions
{
    public static OptionsBuilder<TOptions> ValidateFluentValidation<TOptions, TValidator>(this OptionsBuilder<TOptions> builder)
        where TOptions : class
        where TValidator: class, IValidator<TOptions> 
    {
        builder.Services.AddSingleton<IValidateOptions<TOptions>>(sp =>
        {
            return new GenericFluentValidator<TOptions>(builder.Name, sp);
        });

        builder.Services.AddSingleton<IValidator<TOptions>, TValidator>();

        return builder;
    }
}

Dzięki takiemu rozwiązaniu, model opcji możemy zarejestrować w taki sposób:

builder.Services.AddOptions<FluentApiOptions>()
    .BindConfiguration("FluentApiOptions")
    .ValidateFluentValidation<FluentApiOptions, FluentApiOptionsValidator>()
    .ValidateOnStart();

Jeśli uważasz, że to wciąż kupa roboty, można to upraszczać dalej.

FluentValidation ma oficjalne rozszerzenie do DependencyInjection. Jeśli używasz FV, to pewnie tego rozszerzenia też:

dotnet add package FluentValidation.DependencyInjectionExtensions

W tym pakiecie znajdują się metody, które automatycznie rejestrują wszystkie walidatory ze wskazanego assembly. Więc teraz wystarczy uprościć nasze rozszerzenie i wywalić z niego rejestrację walidatora:

public static class OptionsBuilderExtensions
{
    public static OptionsBuilder<TOptions> ValidateFluentValidation<TOptions>(this OptionsBuilder<TOptions> builder)
        where TOptions : class
    {
        builder.Services.AddSingleton<IValidateOptions<TOptions>>(sp =>
        {
            return new GenericFluentValidator<TOptions>(builder.Name, sp);
        });

        return builder;
    }
}

A na koniec zarejestrować opcje:

builder.Services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());
builder.Services.AddOptions<FluentApiOptions>()
    .BindConfiguration("FluentApiOptions")
    .ValidateFluentValidation()
    .ValidateOnStart();

Teraz jest łatwo, miło i prosto.

I tutaj rodzi się pytanie, czy walidowanie opcji za pomocą FluentValidation ma sens i czy nie jest to przerost formy nad treścią. Jak zwykle – to zależy. Jeśli szybciej/lepiej pracuje Ci się z FluentValidation i widzisz zysk w takim sprawdzaniu, zamiast pisać własny kod walidujący, to na pewno ma to sens, a czas włożony w konfigurację tego ustrojstwa szybko się zwróci. Zwłaszcza, że jest już sporo gotowych walidatorów na „dzień dobry”. A jak widzisz, konfiguracja nie jest aż taka straszna.

Nowości w .NET8

Walidacja opcji bez użycia refleksji – zgodność z AOT

.NET8 przynosi pewną, małą nowość. Kod, który używa refleksji (na przykład ten standardowy sposób walidacji powyżej), nie jest zgodny z AOT. Dlatego też nie moglibyśmy używać walidacji opcji w kompilacji AOT.

Możemy napisać częściowego walidatora, którego kod zostanie wygenerowany automagicznie i ten kod nie będzie już używał refleksji.

Brzmi jak kupa roboty? Może i tak, ale spójrz na to:

public class MyAppConfig
{
    [EmailAddress]
    [Required]
    public string SmtpAdress {  get; set; }
    [Range(1, 10)]
    public int TraceLevel { get; set; }
}

To jest model, który będziemy walidować. A walidator będzie wyglądał tak:

[OptionsValidator]
public partial class MyAppConfigValidator: IValidateOptions<MyAppConfig>
{

}

I to jest dokładnie tyle. Dobrze widzisz. Tutaj są istotne dwie rzeczy:

  • klasa musi być oznaczona jako partial
  • klasa musi posiadać atrybut [OptionsValidator]

W innym wypadku po prostu się nawet nie skompiluje.

W ostatnim kroku musimy ją jeszcze zarejestrować:

builder.Services.AddSingleton<IValidateOptions<MyAppConfig>, MyAppConfigValidator>();

W efekcie zostanie wygenerowany kod dla klasy MyAppConfigValidator, który będzie miał zaszytą całą logikę walidacji w sobie. I to wszystko zadzieje się bez wykorzystania refleksji. Dzięki temu możesz tego używać w kompilacjach AOT.

Bindowanie opcji bez użycia refleksji – zgodność z AOT

Jeśli chodzi o rejestracje opcji, tj. Configure(TOptions), Bind i Get, to standardowo była do tego wykorzystywana refleksja. W .NET8 w aplikacjach internetowych domyślnie konfiguracja jest realizowana przez generator kodu. Czyli jest to zgodne z AOT i nie wymaga żadnych zmian.

Jeśli jednak chcesz być zgodny z AOT i nie tworzysz aplikacji webowej, musisz na takie działanie jawnie wyrazić zgodę. Wystarczy dodać ustawienie w projekcie:

<PropertyGroup>
    <EnableConfigurationBindingGenerator>true</EnableConfigurationBindingGenerator>
</PropertyGroup>

A czy ty walidujesz swoje opcje? Daj znać w komentarzu 🙂


Dziękuję Ci za przeczytanie tego artykułu. Wierzę, że walidacja opcji stała się dla Ciebie jasna i będziesz jej używać. Jeśli znalazłeś w artykule jakiś błąd lub czegoś nie rozumiesz, koniecznie daj znać w komentarzu.

No i podziel się tym artykułem z kimś, komu uważasz że się przyda 🙂

Podziel się artykułem na:
Controller MVC i/lub API w osobnej bibliotece Class Library

Controller MVC i/lub API w osobnej bibliotece Class Library

Wstęp

Dodawanie kontrolera do osobnej biblioteki może być użyteczne w przypadku, gdy na przykład tworzysz plugin lub system, który korzysta z pluginów. Lub z jakiegoś jeszcze innego powodu chcesz wydzielić część kontrolerów do innego projektu. W .NET robi się to bardzo prosto.

Krok po kroku

Zakładam, że masz już istniejącą solucję z kontrolerami API, czy też MVC.

  1. Dodaj kolejny projekt Class Library do solucji, jeśli jeszcze go nie masz.
  2. Doinstaluj do niego paczkę NuGet: Microsoft.AspNetCore.App
  3. Podczas rejestracji serwisów dodaj:
services.AddMvc().AddApplicationPart(assembly);

Zmienna assembly to oczywiście Twoje assembly z ClassLibrary, w którym masz kontrolery. Możesz to pobrać na kilka sposobów. Jeśli taką rejestrację przeprowadzasz z jakiejś extension method w swojej ClassLibrary, np:

public static class ServiceCollectionExtensions
{
    public static IServiceCollection(this IServiceCollection services)
    {
         services.AddMvc().AddApplicationPart(Assembly.GetExecutingAssembly());
    }
}

Jeśli jednak rejestrację przeprowadzasz z jakiegoś powodu z głównej aplikacji, to najprościej pobrać Assembly po konkretnej klasie.

Załóżmy, że Twój kontroler mieści się w takiej klasie:

namespace API.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class AccountController : ControllerBase
    {
        //
    }
}

Wtedy wystarczy pobrać assembly z tej właśnie klasy:

var assembly = typeof(API.Controllers.AccountController).Assembly;
services.AddMvc().AddApplicationPart(assembly);

To wszystko. Ta prosta „sztuczka” może sprawić, że Twój projekt stanie się bardziej czytelny i bardziej modularny.

Dzięki za przeczytanie artykułu. Jeśli znalazłeś jakiś błąd albo czegoś nie rozumiesz, koniecznie daj znać w komentarzu. Jeśli uważasz, że ta „sztuczka” jest super przydatna i ma też inne zastosowania, to też się podziel 🙂

Podziel się artykułem na: