W pierwszej części artykułu opisałem podstawy mieszania języków – C# i C++. Skupiliśmy się tam nieco bardziej na stringach, które nie są tak oczywiste i czasem sporo z nimi zabawy. Dzisiaj będzie coś jeszcze mniej oczywistego – struktury. Jeśli jednak nie ogarniasz podstaw, koniecznie przeczytaj pierwszą część artykułu.
Język C++ jest tylko przykładowy. Za każdy razem, gdy piszę o funkcji lub strukturze C++, mam na myśli funkcję / strukturę pisaną w dowolnym języku niskiego poziomu (niezarządzanego) typu C, C++, Pascal.
Przypominam, że cykl jest dość zaawansowany. Wymaga trochę wiedzy na temat pamięci i wskaźników. Co nieco pisałem w tym artykule. Ale jeśli czegoś nie rozumiesz, to koniecznie daj znać w komentarzu.
Przykładowy projekt
Przygotowałem prostą solucję, którą możesz pobrać z GitHuba. To są dwa projekty – jeden C++, drugi C#. Projekt C++ to prosta biblioteka DLL, którą będziemy używać w C#. Nie ma żadnego konkretnego sensu. Napisałem ją tylko na potrzeby tego artykułu. Na dzień pisania artykułu (lipiec 2024) biblioteka nie jest w pełni ukończona. Będę dodawał jej funkcjonalność przy kolejnych częściach artykułu. Niemniej jednak, projekty się budują i działają w obrębie tego artykułu jak i jego pierwszej części.
Jeśli masz problem z uruchomieniem solucji, jest to dokładnie opisane w pierwszej części artkułu.
Struktury w pamięci
Niestety struktury zarządzane i niezarządzane są nieco inaczej rozłożone w pamięci. Dlatego też trzeba zastosować kilka dodatkowych środków, żeby to ładnie pożenić. Ale od początku.
Co ciekawe, nazwy struktur nie mają tutaj żadnego znaczenia. Po stronie C++ możesz mieć strukturę nazwaną UserInfo, natomiast po stronie C# to może być AdditionalUserData. Nie ma to żadnego znaczenia.
To, co faktycznie ma znaczenie, to pola w tych strukturach. Muszą być zdefiniowane dokładnie w takiej samej kolejności i muszą zajmować dokładnie tylko samo bajtów w pamięci:
ta sama kolejność pól
pola tej samej długości
Niestety nie ma opcji, żeby w czasie kompilacji sprawdzić to. Po prostu jeśli zrobisz coś źle, to aplikacja się wywali w runtime. Z tego wychodzi pierwsze niebezpieczeństwo, które wiele lat temu (gdy na muchy mówiłem jeszcze „ptapty”) pozbawiło mnie kilku dni życia. I wcale to nie jest takie oczywiste.
Atrybut StructLayoutAttribute
W C#, ze względów wydajnościowych, pola w strukturze czasami są zamieniane miejscami. I zupełnie inaczej wyglądają w pamięci niż w kodzie. Dlaczego? Bo procesor najłatwiej i najszybciej odczytuje bloki po 4/8 bajtów w pamięci. Dochodzi do tego jeszcze padding.
Czym jest padding?
Jak już pisałem, procesor najlepiej radzi sobie (najbardziej optymalnie) z blokami po 4/8 bajtów w pamięci. Zatem ile miejsca w pamięci zajmie taka struktura?
struct MyStruct
{
public bool b;
public int i;
}
Odpowiedź może Cię zdziwić. Pomimo, że zmienne typu bool potrzebują 1 bajta w pamięci, a int 4 bajtów, to taka struktura zajmie 8 bajtów, a nie 5. Dlaczego? Właśnie przez optymalizację. Gdy kompilator zobaczy zmienną typu bool, będzie chciał dokonać wyrównania (alignment), czyli zarezerwuje jej pamięć tak, żeby zmienna znajdowała się w 4 bajtowym bloku. Czyli dopełni do 4 bajtów. To dopełnienie nazywa się paddingiem. Int zajmuje już 4 bajty, czyli tutaj nic się nie stanie. Dokładniej rzecz biorąc nie chodzi konkretnie o 4 bajty, tylko o największy składnik w strukturze. Ale to już naprawdę głębokie szczegóły.
Zobacz, jak ta struktura wygląda w pamięci:
MyStruct mstr;
mstr.b = true;
mstr.i = 10;
Jeśli będziesz mieć taką strukturę:
struct MyStruct
{
public bool b;
public bool c;
public int i;
}
to ona też zajmie 8 bajtów. Kompilator zobaczy, że dwie pierwsze zmienne mają 2 bajty, więc dopełni je do 4. Czyli w tym przypadku nie ma różnicy, czy masz jedno pole typu bool, czy 4.
struct MyStruct
{
public bool b;
public int i;
public bool c;
}
Prawdę mówiąc, nie jestem w stanie odpowiedzieć na to pytanie. Różne ustawienia i wersje kompilatora mogą doprowadzić do różnych wyników. Jednym z nich jest zarezerwowanie 12 bajtów w pamięci (b + 3 bajty paddingu, i, c + 4 bajty paddingu). Innym jest pomieszanie pól w taki sposób, żeby uzyskać strukturę jak z poprzedniego kodu – czyli 2 zmienne bool będą w pamięci obok siebie.
Tylklo dla dociekliwych
Załóżmy, że mamy taką strukturę:
struct MyStruct
{
public bool b;
public bool c;
public int i;
}
Domyślna wielkość paddingu to 4 bajty. W związku z tym, że 2 pierwsze elementy zajmują dwa bajty, kompilator doda kolejne 2 bajty przed zmienną int. Dzięki czemu mamy 2 bloki po 4 bajty.
Jednak jeśli ustawiłbyś jawnie padding na wielkość 2 bajtów – żaden padding nie zostanie dodany – w tym konkretnym przypadku. Dwa pierwsze pola zajmują już 2 bajty. Czyli mamy tutaj blok o określonej wielkości.
A jeśli ustawimy padding na 8 bajtów? Też nic się nie stanie. I dlaczego do cholery? Dlaczego? Ponieważ obliczając wielkość wyrównania, kompilator bierze pod uwagę nie tylko tą żądaną wielkość, lecz również wielkość największego pola w strukturze. A skoro tutaj największym polem jest int – 4 bajty, zatem do tych 4 bajtów będzie dokładane dopełnienie. Oczywiście, jeśli struktura posiadałaby pole typu long (8 bajtów), wtedy zastosowany będzie padding 8 bajtów. W jaki sposób?
struct MyStruct
{
public bool b;
public bool c;
public int i;
public long l;
}
Pierwsze dwa pola zajmą 8 bajtów – każde z nich będzie dopełnione do 4. Kolejne pole – int zajmie 8 bajtów – zostanie dopełnione do 8, No i long ma już 8 bajtów.
A co się stanie, jeśli padding ustawimy na 1?
Żaden padding nie zostanie zastosowany i pola nie będą dopełniane. Ale o tym za chwilę.
I jak to się ma z tym, co wcześniej napisałem? Że struktury w C++ i w C# muszą mieć pola o tej samej wielkości i w tym samym porządku?
Po stronie C# służy do tego wspomniany atrybut StructLayout.
Jak używać StructLayout?
Atrybut StructLayout mówi kompilatorowi w jaki sposób ma potraktować daną strukturę w pamięci. Atrybut posiada 4 parametry:
LayoutKind
CharSet
Pack
Size
LayoutKind
Możemy tutaj ustawić 3 wartości:
Sequential – pola w strukturze będą ustawione dokładnie w takiej samej kolejności, w jakiej napisaliśmy w kodzie. Powinieneś użyć jeszcze parametru Pack, żeby określić dokładnie padding. I wtedy możesz przekazywać taką strukturę między światem niezarządzanym i zarządzanym.
[StructLayout(LayoutKind.Sequential, Pack = 1)] //Pack ustawiony na 1 zabrania dokonywania jakiegokolwiek paddingu
struct MyStruct
{
public byte b;
public byte b2;
public int i;
}
Explicit – pola w strukturze są tak ustawione, jak je określisz za pomocą atrybutów FieldOffset. To znaczy, że możesz dokładnie i jawnie (explicitly) podać w którym miejscu w pamięci ma się zacząć konkretne pole.
[StructLayout(LayoutKind.Explicit)]
struct MyStruct
{
[FieldOffset(0)] public byte b; //w bajcie 0
[FieldOffset(1)] public byte b2; //w bajcie 1
[FieldOffset(2)] public int i; //w bajcie 2
}
W tej sytuacji pole b będzie na początku struktury. b2 zacznie się w pierwszym bajcie, a i w drugim. Oczywiście musisz na to uważać, bo możesz zrobić głupotę:
[StructLayout(LayoutKind.Explicit)]
struct MyStruct
{
[FieldOffset(0)] public byte b;
[FieldOffset(2)] public byte b2
[FieldOffset(1)] public int i;
}
Pamiętaj, że pole int zajmie 4 bajty. Byte zajmie 1 bajt. I co się stanie teraz? Pole int przesłoni pole byte. I w zależności od tego, co przypiszesz jako ostatnie, będą różne dziwne wyniki. Więc jeśli stosujesz layout typu explicit, to uważaj na to.
Auto – domyślny układ – czyli pola mogą być w różnym miejscu z paddingiem.
Pack
Parametr Pack określa wielkość paddingu. Opisałem to w akapicie dla dociekliwych, więc nie będę tutaj się powtarzał. Wartość 0 jest domyślna, natomiast jeśli w ogóle nie chcesz paddingu, daj tam wartość 1.
Size
Określić tym możesz wynikowy rozmiar CAŁEJ struktury. Jeśli jednak podasz zbyt małą liczbę, to spokojnie. Struktura i tak zajmie swoją minimalną wymaganą przestrzeń.
Padding po stronie C++
Po stronie C++ też należy określić padding dla struktury. Tam stosujesz dyrektywę pragma pack:
Pobierzemy sobie wreszcie jakieś dane z C++. Na razie spójrzmy na struktury z polami kopiowalnymi (blitable). Jeśli nie pamiętasz, czym są takie pola, to jest to opisane w pierwszej części artykułu.
I teraz uwaga – jeśli w strukturze chcesz mieć jakieś metody – w niczym to nie przeszkadza. Dane przejdą normalnie.
Ten sam padding
Wcześniej pisałem, że procesor działa najbardziej optymalnie, gdy odczytuje bloki o odpowiedniej długości. Ustawiając padding na 1, wyłączamy go w ogóle i powodujemy, że kod nie jest super optymalny. Oczywiście w standardowych przypadkach to pewnie będzie niezauważalne.
Ale chcę żebyś miał świadomość, że to nie chodzi o to, żeby tego paddingu nie było w ogóle, tylko żeby był taki sam po stronie natywnej i .NET.
Czyli równie dobrze nasze struktury mogłyby wyglądać tak:
To po prostu nazwa pliku i rozmiar pliku. Istotne tutaj jest, że nazwa pliku jest przedstawiona jako statyczna tablica – tzn. tablica o stałej długości. W C# powinniśmy tę strukturę zadeklarować tak:
[StructLayout(LayoutKind.Sequential, Pack = 1, CharSet = CharSet.Unicode)]
public struct CppFileInfo
{
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)]
public string fileName;
public long fileSize;
}
Użycie StructLayout już znasz. Dodatkowo, w związku z tym, że w strukturze występują stringi, musimy w struct layout zaznaczyć, że te stringi są unicodowe. A są unicodowe, bo po stronie C++ mamy tablicę wchar_t, a nie char.
Ale druga rzecz jest taka, że w związku z tym, że łapiemy zwykłego stringa po stronie C#, musimy zrobić na nim Marshaling. W marshalingu zaznaczamy, że jest to string. Po stronie C++ mamy string w najczystszej postaci, więc musimy powiedzieć .NETowi, że właśnie tak ma traktować ten fragment pamięci. Rozmiar tego stringu ustawiamy na 260, bo taką wartość ma stała MAX_PATH.
I teraz możemy już wywołać funkcję, która zwróci nam informacje o jakimś pliku. Po stronie C++:
Zauważ, że tutaj CharSet też ustawiamy, ale on odnosi się do zmiennej, którą przekazujemy do C++, a nie do tej ze struktury.
Podsumowując, ze stringami w strukturach radzimy sobie dokładnie tak samo, jak ze zwykłymi stringami – opisanymi w poprzednim artykule. Wszystko dotyczące stringów jest prawdą i tutaj.
Tylko różnica jest taka, że odpowiedni Marshaling musimy ogarnąć na poziomie pola w strukturze, a nie na poziomie definicji funkcji.
To wszystko jeśli chodzi o przekazywanie struktur. W kolejnej części zajmiemy się klasami i wskaźnikami. Będzie zabawa 🙂
Jeśli znalazłeś błąd w artykule lub czegoś nie rozumiesz, koniecznie daj znać w komentarzu.
Czas akcji: 10 – 11.06.2024 Miejsce akcji: ICE Kraków (ul. Marii Konopnickiej 17, Kraków)
Gotowy na Code Europe — największy festiwal technologiczny w Polsce? 🎆
Hej, tegoroczna edycja Code Europe odbędzie się już w czerwcu w Krakowie. Tym razem będą to dwa dni konferencji, a więc warto sobie zabukować jakiś hotel. Jest to prawdopodobnie największa tego typu impreza w Polsce.
Byłem na Code Europe dwa lata temu ostatnim razem i potwierdzam, że było ciekawie. Niestety w tym roku nie będę mógł dołączyć, a szkoda, bo agenda wygląda całkiem fajnie, co możecie zobaczyć na oficjalnej stronie wydarzenia: https://www.codeeurope.pl/pl/
Prelegenci
Lista jest jak zwykle długa, ale możemy się spodziewać między innymi takich postaci jak:
Kenneth Rohde Christiansen – Intel
Ekaterina Sirazitdinova – NVidia, ekspertka od AI, która rozwijała m.in. analizy medyczne oparte na obrazach
Michelle Sandford – ewangelistka z Microsoftu
Shaundai Person – Netflix
dr Robert Gentleman – Harvard Medical School – współtworzył język R, mocno związany z biomedycyną
i inni.
Czemu warto?
/akapit organizatora/
Code Europe to nie tylko zwykłe wydarzenie IT — to miejsce, gdzie najlepsi eksperci z całego świata gromadzą się, by dzielić się wiedzą, wymieniać doświadczeniami i przekraczać granice technologii, a to wszystko w otoczce festiwalowej zabawy!
To Twoja szansa, by odkryć najnowsze trendy i nawiązać kontakty, które mogą kształtować Twoją przyszłość zawodową w branży technologicznej. Z ponad 15 000 już zaangażowanych uczestników, możesz być pewien, że każda chwila spędzona na Code Europe będzie wartościowa i zdecydowanie nie chcesz tego przegapić!
Code Europe zabłyśnie na ICE Kraków 10-11 czerwca 2024 r. Festiwal jest dla wszystkich entuzjastów technologii, deweloperów, architektów oprogramowania, specjalistów DevOps, zapaleńców bezpieczeństwa, profesjonalistów ds. produktu, specjalistów ds. danych i pasjonatów QA, którzy chcą dzielić się wiedzą i razem ją zdobywać!
Dlaczego warto być częścią Code Europe?
🚀 Unikalne spojrzenie: ucz się od najlepszych prelegentów, którzy dzielą się najświeższymi spojrzeniami i doświadczeniami z branży technologicznej.
🤝 Networking: poznaj innych entuzjastów technologii, współpracuj nad pomysłami i nawiąż kontakty, które mogą wpłynąć na Twoją dalszą ścieżkę kariery.
💼 Paliwo karierowe: odkryj możliwości, połącz się z gigantami branży i zdobądź wgląd w najgorętsze trendy i możliwości w branży IT i technologii.
🎤 Najlepsi prelegenci: przygotuj się na prelekcje z liderami technologicznymi takimi jak Venkat Subramaniam, José Valim, Sébastien Chopin, Sven Peters, Michelle Sandford i wielu, wielu innych!
UWAGA! Zniżka!
CodeEurope jest oczywiście płatnym eventem. Jednak moi subskrybenci dostają 20% zniżki na bilety. Zniżka już poleciała do Was w osobnym mailu 🙂
Jeśli jeszcze nie subskrybujesz, koniecznie zapisz się na newsletter, a też dostaniesz kod zniżkowy 🙂
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:
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):
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
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.
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:
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:
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:
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:
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/");
});
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ć:
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ą?
Czy Twoja webówka działa? A jaką masz pewność? Musiałbyś co chwilę klikać i sprawdzać. Ale są też inne, lepsze metody. Możesz na przykład posłużyć się rozwiązaniem chmurowym, które cyklicznie będzie badać stan Twojej aplikacji. Co więcej, jest opcja, że nawet wyśle Ci maila albo SMSa, jeśli coś będzie nie tak.
Ten artykuł nie opowiada jednak o chmurowej części rozwiązania (jeśli chcesz taki materiał, daj znać w komentarzu), a o aplikacyjnej części. Czyli o healthcheck.
Czym jest Healthcheck?
Healthcheck jest sprawdzeniem stanu Twojej aplikacji. Czy działa wszystko ok, ewentualnie co nie działa. I oczywiście mógłbyś napisać sobie własny kontroler z odpowiednimi endpointami, w których to wszystko sprawdzasz, ale w .NET mamy już taki mechanizm w standardzie. I działa całkiem przyzwoicie.
Po co to właściwie?
Dzisiaj utrzymanie niezawodności i ciągłości działania aplikacji jest priorytetem. Stworzenie skutecznego mechanizmu healthcheck pozwala na szybką reakcję w razie wystąpienia jakiś problemów z jednym z kluczowych elementów systemu.
Jak już pisałem wcześniej, można to nawet spiąć z chmurą i spodziewać się maila albo nawet SMS gdy tylko coś niedobrego zacznie się dziać w Twojej aplikacji.
Przykładowa apka
Do tego artykułu stworzyłem przykładową aplikację, którą możesz pobrać z GitHuba. Po jej pobraniu, koniecznie uruchom migracje Entity Framework.
Niech nasza aplikacja zwraca różne dane pogodowe. Jeśli chodzi o prognozy, będą pobierane z zewnętrznego serwisu, a jeśli chodzi o dane archiwalne (prognoza z przeszłości), będą pobierane z naszej bazy danych.
Zewnętrzny serwis to oczywiście jakiś mock, który będzie udawał połączenie z zewnętrznym API.
Konfiguracja healthcheck
Podstawowa konfiguracja jest zabójczo prosta, bo sprowadza się tylko do rejestracji odpowiednich serwisów i dodania middleware. Czyli mamy coś takiego:
builder.Services.AddControllers();
//healthcheck
builder.Services.AddHealthChecks();
var app = builder.Build();
// Configure the HTTP request pipeline.
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapHealthChecks("/_health");
app.MapControllers();
app.Run();
Jeśli chodzi o linię 4 – to dodajemy do dependency injection serwisy do sprawdzenia stanu zdrowia. Co się tyczy linii 13, to mapujemy te healthchecki do konkretnego endpointa. W parametrze przekazujemy, pod jakim adresem ma być ten healthcheck. W tej sytuacji to będzie https://localhost:pppp/_health, gdzie pppp to oczywiście numer portu na środowisku lokalnym.
Teraz jeśli uruchomimy aplikację i sprawdzimy ten healthcheck, dostaniemy zwrotkę ze StatusCode 200 OK i wartością:
Healthy
Przyznasz jednak, że takie sprawdzenie niewiele nam daje. No właśnie, domyślny mechanizm właściwie niczego nie sprawdza. Jeśli aplikacja chodzi, to zawsze zwróci Healthy. A my chcemy sprawdzić przynajmniej dwie rzeczy:
czy działa połączenie z bazą danych
czy działa połączenie z zewnętrznym serwisem
Możemy wszystko napisać ręcznie, ale jest lepsza metoda. Nudesy…eeee Nugetsy 😉 O tym za chwilę.
Jak działa mechanizm healthcheck?
Metoda AddHealthChecks zwraca nam interfejs IHealthChecksBuilder, dodając jednocześnie domyślny serwis do sprawdzenia HealthChecków, który wszystkim zarządza. I tak naprawdę możemy sobie stworzyć listę healthchecków, jakie chcemy mieć. To wszystko sprowadza się do dodania do tego buildera klasy, która implementuje odpowiedni interfejs (o tym też będzie za chwilę).
Potem ten domyślny serwis bierze sobie te wszystkie klasy, tworzy je i wywołuje po kolei metodę sprawdzającą. Ot, cała magia. Dzięki czemu możemy tworzyć sobie właściwie nieograniczone sprawdzenia stanu zdrowia apki.
Badanie standardowych serwisów
Jeśli wejdziesz sobie do managera nugetów i zaczniesz wpisywać AspNetCore.Healthchecks, oczom Twym ukaże się całkiem pokaźna lista z już oprogramowanymi sprawdzeniami do konkretnych serwisów:
To nie są w prawdzie oficjalne Microsoftowe paczki, jednak społeczność która za tym stoi, to (w momencie pisania artykułu) ponad 150 osób. Jeśli używasz jakiegoś standardowego serwisu, to jest duża szansa, że sprawdzenie healthcheka do niego już istnieje.
Sprawdzanie bazy danych
Oczywiście możemy sobie sprawdzić różne bazy danych, w tym MSSQL, Postgre, MySQL, Redis itd. – używając bibliotek z powyższej listy. Możemy też użyć oficjalnej paczki Microsoft.Extensions.Diagnostics.Healthcheck, która umożliwia testowanie całego kontekstu bazy danych (EFCore). A jak używać tych wszystkich bibliotek?
Metoda AddHealthChecks zwraca nam interfejs IHealthChecksBuilder i wszystkie rozszerzenia jakie mamy dostępne są rozszerzeniami właśnie tego interfejsu. A prostymi słowami:
//healthcheck
builder.Services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>(); //rozszerzenie z Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
W taki sposób możemy dodać sprawdzenie, czy baza danych działa. Domyślnie, sprawdzane jest połączenie z bazą danych za pomocą metody dbContext.Database.CanConnectAsync(cancellationToken);
Jednak niech nie zwiedzie Cię ta pozorna prostota. Jeśli chodzi o bazę MSSQL, to ta metoda faktycznie próbuje połączyć się z bazą danych, a potem wysyła zapytanie SELECT 1.
Oczywiście można zrobić więcej – wystarczy dodać jakieś parametry, np.:
W tym momencie domyślne sprawdzenie zostanie zamienione na nasze. Czyli podczas sprawdzenia stanu zdrowia bazy danych, baza zostanie odpytana o ilość rekordów w tabeli WeatherArchives – którą mamy zdefiniowaną w naszym AppDbContext. Parametr CustomTestQuery to po prostu funkcja, która przyjmuje w parametrze nasz kontekst bazy danych i CancellationToken, a zwraca jakiś bool.
I co najważniejsze – ten kod wystarczy. Nie trzeba tutaj stosować żadnych try..catch’y, ponieważ cała nasza funkcja i tak jest wywoływana w kontekście try..catch. Więc jeśli wystąpi jakiś exception, mechanizm healthcheck zwróci nam odpowiednią informację.
Niemniej jednak przy standardowych zastosowaniach, standardowy mechanizm sprawdzania bazy danych jest w zupełności wystarczający.
Sprawdzanie niestandardowe
Jednak nasz przykładowy serwis ForecastService, który ma imitować klienta jakiegoś zewnętrznego API, jest niestandardowym serwisem i nie znajdziemy biblioteki dla niego. Mechanizm HealthCheck pozwala jednak na napisanie własnego HealthChecka – dokładnie w taki sam sposób w jaki powstają te biblioteki wyżej pokazane.
Utworzenie klasy do sprawdzenia zdrowia
W pierwszej kolejności musimy utworzyć klasę, która implementuje interfejs IHealthCheck. Interfejs ma tylko jedną metodę, którą musimy napisać.
Teraz załóżmy, że nasz serwis, który udaje klienta API do pobierania prognozy pogody wygląda tak:
public class ForecastService(RandomHelper _randomHelper)
{
public async Task<WeatherData> GetForecastFor(string city, DateOnly date)
{
await Task.Delay(500);
return new WeatherData
{
City = city,
Date = date,
TemperatureC = _randomHelper.GetRandomTemperature()
};
}
public async Task<bool> IsServiceHealthy()
{
await Task.Delay(500);
return true;
}
Czyli sprawdzenie stanu zdrowia tego serwisu będzie wymagało tylko wywołania metody IsServiceHealthy, którą nam daje nasz oszukany klient. A jak to zrobić? No oczywiście w klasie implementującej IHealthCheck:
public class ForecastServiceHealthCheck(ForecastService _forecastService) : IHealthCheck
{
public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context,
CancellationToken cancellationToken = default)
{
var result = await _forecastService.IsServiceHealthy();
if (result)
return HealthCheckResult.Healthy();
else
return HealthCheckResult.Unhealthy();
}
}
W metodzie CheckHealthAsync musimy teraz zwrócić HealthCheckResult – rezultat, który mówi, czy testowany podsystem jest zdrowy, czy nie. Domyślne stany Healthy i Unhealthy zazwyczaj wystarczą.
Oczywiście w klasie implementującej IHealthCheck możesz zrobić dowolny kod. Jeśli masz faktyczne zewnętrzne API, do którego się łączysz, możesz mieć tutaj po prostu HttpClienta, za pomocą którego wyślesz jakiś request.
I tak jak pisałem wcześniej – takich klas możesz sobie utworzyć tyle, ile potrzebujesz.
Czyli wywołujemy metodę AddCheck. W parametrze generycznym przekazujemy typ klasy, w której zaimplementowaliśmy sprawdzenie, a w parametrze Name przekazujemy jakąś nazwę dla tego sprawdzenia. W tym wypadku: "Forecast service", bo sprawdzamy działanie właśnie tego serwisu.
Pokazywanie większej ilości informacji
W tym momencie, jeśli strzelimy na końcówkę z healthcheckiem dostaniemy odpowiedź w formie czystego stringa – Healthy albo Unhealthy. Ale możemy to zmienić w dość łatwy sposób. Najprościej pobrać sobie Nugeta: AspNetCore.Healthchecks.UI.Client i podczas dodawania healthchecków do middleware dodać opcje:
app.MapHealthChecks("/_health", new HealthCheckOptions
{
ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse //UIResponseWriter pochodzi z ww. Nugeta
});
I teraz dostaniemy dużo więcej informacji. Np. przy działającej aplikacji:
Zwróć uwagę, że otrzymujemy główny status apki i statusy poszczególnych serwisów, które sprawdzamy. AppDbContext to oczywiście sprawdzenie bazy danych. A Forecast service – to jest to, co sami pisaliśmy. Przy błędzie możemy uzyskać coś takiego:
Generalnie właściwość ResponseWriter przy mapowaniu tych healthchecków daje nam opcje takiego stworzenia odpowiedzi jaką chcemy. Jeśli ta domyślna z Nugeta daje za mało info albo trochę za dużo, sami możemy coś pokombinować, np.:
ResponseWriter to po prostu funkcja, która dostaje w parametrze HttpContext i HealthReport, a zwraca Task. Jej zadaniem jest wypisanie do responsa tego, co chcemy zobaczyć w odpowiedzi na ten endpoint.
Więc możemy sobie tutaj skonstruować odpowiedź jaka nam się tylko podoba. Możemy np. napisać sobie funkcje, która zwróci nam informacje o wersji albo co sobie tam wymyślimy.
Dodatkowe możliwości
Jeśli przyjrzysz się metodzie AddCheck z IHealthCheckBuilder, zobaczysz że ma ona dodatkowe parametry, które możesz przekazać. Wszystkie parametry trafią później do HealthCheckStatus – parametr w metodzie, w której tworzysz sprawdzenie – jak robiliśmy wyżej z ForecastServiceHealthCheck.
Dodatkowo możesz umieścić tam np. timeout. Mechanizm healthcheck mierzy czas wykonania każdego sprawdzenia. Jeśli przekażesz timeout i ten czas zostanie przekroczony, no to też dostaniesz odpowiednią informację.
Jeśli chodzi o listę tags, to możesz sobie wrzucić tam jakieś dodatkowe informacje, które są Ci potrzebne. O tym będzie jeszcze niżej.
Zabezpieczenie healthchecka – uwierzytelnianie
Zastanów się, czy każdy powinien mieć dostęp do Twojego healthchecka. Być może po drugiej stronie siedzi gdzieś ciemny typ, który próbuje hackować Twój system i zastanawia się jak po różnych krokach wygląda healthcheck. Jeśli dojdziesz do wniosku, że tylko niektóre osoby (maszyny) powinny mieć do tego dostęp, łatwo to ogarnąć.
W momencie, w którym mapujesz końcówkę healthchecka możesz dodać zabezpieczenia:
Po takiej konfiguracji, będzie można dobić się do healthchecka tylko z domeny localhost. Próba dojścia z innej da po prostu zwrotkę 404 Not Found. Możesz też pokombinować mocniej. Np. wymusić konkretny port z dowolnego hosta:
Takich metod Require* mamy kilka, których możemy używać do różnych ograniczeń.
RequireCors – będzie wymagało odpowiedniej polityki CORS. O CORSach pisałem tutaj,
RequireAuthorization – będzie wymagało uwierzytelnionego użytkownika. Jak to zrobisz, to już jest Twoja sprawa. W tej metodzie możesz podać politykę autoryzacyjną, możesz też role, schematy. Jeśli nie podasz niczego, będzie użyty domyślny schematy uwierzytelniania,
RequireRateLimiting – da Ci rate limiting na tej końcówce 🙂 Po krótce, jest to mechanizm, który pozwala uderzyć w dane miejsce nie częściej niż ileś tam razy. Czyli np. możesz sobie ustawić raz na minutę.
Te ograniczenia możesz ze sobą również łączyć. Nic nie stoi na przeszkodzie, żeby mógł dobić się tylko uwierzytelniony użytkownik z konkretnego hosta i to nie częściej niż co jakiś czas:
Z jakiegoś powodu możesz chcieć uruchamiać tylko niektóre sprawdzenia. Domyślny mechanizm uruchamia wszystkie zarejestrowane HealthChecki. Ale możesz stworzyć filtrować te serwisy i pozwalać na uruchamianie tylko niektórych. Ponadto, możesz mieć więcej końcówek dla różnych sprawdzeń. Na przykład:
app.MapHealthChecks("/_health", new HealthCheckOptions
{
ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
});
app.MapHealthChecks("/_health_db", new HealthCheckOptions
{
Predicate = healthCheck => healthCheck.Tags.Contains("db")
});
Tutaj stworzyłem dwie końcówki:
_health – sprawdzi wszystkie zarejestrowane healthchecki i zwróci rezultat w JSON (tak jak pokazywałem wyżej)
_health_db – sprawdzi tylko te healthchecki, które zwróci Predicate – w tym wypadku te, które mają w swoich tagach słowo "db". I rezultat będzie zwrócony w standardowy sposób, czyli dostaniesz tylko informację Healthy lub Unhealthy (w tej końcówce nie posługujemy się ResponseWriterem).
A skąd ten filtr ma wiedzieć, że tag „db” oznacza bazę danych? Na szczęście to nie jest żadna magia i sam musisz zadbać o to, żeby do odpowiednich serwisów dodać odpowiednie tagi. Robisz to podczas ich rejestracji, np. tak:
//healthcheck
builder.Services.AddHealthChecks()
.AddDbContextCheck<AppDbContext>(tags: new string[] { "db" })
.AddCheck<ForecastServiceHealthCheck>("Forecast service");
Zwróć uwagę, jak w trzeciej linijce dodałem tagi do serwisu badającego bazę danych.
Dodanie endpointa do Swaggera
Skoro to czytasz, to zapewne zauważyłeś, że tak stworzony endpoint dla healthcheck nie jest dodawany do Swaggera. I przy obecnej technologii, gdzie możemy używać Postmana i requestów prosto z VisualStudio (plik *.http) nie widzę w tym większego sensu, ale się da. Wystarczy stworzyć i zarejestrować swój własny DocumentFilter.
IDocumentFilter to interfejs, który dostarcza informacji o dodatkowych operacjach. Standardowo Swagger szuka po prostu kontrolerów i akcji w nich i na tej podstawie (używając refleksji) tworzy swoją dokumentację. Oczywiście można mu dodać operacje, które nie są obsługiwane przez kontrolery. Wystarczy zaimplementować ten interfejs IDocumentFilter:
public class HealthCheckDocumentFilter : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
var healthCheckOp = CreateHealthcheckOperation("_health", true);
var dbHealthCheckOp = CreateHealthcheckOperation("_health_db", false);
var healthPathItem = new OpenApiPathItem();
healthPathItem.AddOperation(OperationType.Get, healthCheckOp);
var dbHealthCheckPathItem = new OpenApiPathItem();
dbHealthCheckPathItem.AddOperation(OperationType.Get, dbHealthCheckOp);
swaggerDoc.Paths.Add("/_health", healthPathItem);
swaggerDoc.Paths.Add("/_health_db", dbHealthCheckPathItem);
}
private OpenApiOperation CreateHealthcheckOperation(string endpoint, bool returnsJson)
{
var result = new OpenApiOperation();
result.OperationId = $"{endpoint}OperationId";
var mediaType = returnsJson ? "application/json" : "text/plain";
var objType = returnsJson ? "object" : "string";
var schema = new OpenApiSchema
{
Type = objType
};
var response = new OpenApiResponse
{
Description = "Success"
};
response.Content.Add(mediaType, new OpenApiMediaType { Schema = schema });
result.Responses.Add("200", response);
return result;
}
}
No i musimy go zarejestrować podczas rejestracji Swaggera:
Nie będę omawiał tego kodu, bo nie ma nic wspólnego z healthcheckiem, tylko z dodawaniem operacji do Swaggera. Jest dość prosty i intuicyjny. Po prostu musimy dodać konkretne operacje (OpenApiOperation) do konkretnych endpointów (swaggerDoc.Paths.Add) i tyle. A każda operacja może składać się z różnych opisów, zwrotek itd. To wszystko co tutaj podasz, będzie potem widoczne w odpowiednich opisach na stronie Twojej dokumentacji.
To tyle na dzisiaj. Dzięki za przeczytanie tego artykułu. Jeśli czegoś nie rozumiesz lub znalazłeś jakiś błąd, koniecznie daj znać w komentarzu. Jeśli chciałbyś jakąś dodatkową wiedzę na temat healthchecków, to też daj znać. No i koniecznie podziel się tekstem z osobami, którym się przyda 🙂
Wraz z wersją ósmą .NET, o której pisałem w tym artykule, dostaliśmy też wersję 12 języka C#. Dzisiaj opiszę Ci wszystkie nowości i zmiany w tej wersji. Lecimy.
Główne konstruktory – Primary constructors
Do tej pory mogliśmy ich używać tylko w recordach. Od C#12 mamy je dostępne również w klasach i strukturach. Działają jednak troszkę inaczej. O co chodzi?
Spójrz na ten POPRAWNY w C#12 kod:
class Person(string name, int age)
{
public string Name { get; } = name;
public int Age { get; } = age;
}
Obok nazwy klasy znalazły się nawiasy z parametrami. To jest właśnie coś, co nazywamy primary constructor. Zwróć uwagę, że te parametry: name i age są dostępne w całym ciele klasy. Można je odczytywać, zmieniać i robić wszystko to, co robiłbyś z prywatnymi polami. No właśnie… prywatnymi. Nie możesz się do nich dobrać z zewnątrz, dlatego też powyżej widzisz utworzone właściwości, które zwracają ich wartości.
Tak samo to działa w strukturach. I to jest ta różnica między klasą/strukturą, a rekordem:
record MyRecord(int X, int Y)
{
public bool IsNegative()
{
return X < 0 || Y < 0
}
}
Jeśli używasz primary constructor w rekordach, kompilator automatycznie stworzy właściwości ( { get; init; } ) dla każdego takiego parametru. Dzięki czemu możesz się normalnie do nich odwoływać na rzecz obiektu.
Wróćmy jednak do naszej klasy:
class Person(string name, int age)
{
public string Name { get; } = name;
public int Age { get; } = age;
}
To, co tutaj widzisz to tak naprawdę cukier składniowy. Kompilator wygeneruje do tego kod, który będzie wyglądał mniej więcej tak:
class Person
{
private string __unspeakable_name;
private int __unspeakable_age;
public string Name => __unspeakable_name;
public Person(string name, int age)
{
__unspeakable_name = name;
__unspeakable_age = age;
}
}
Primary constructor z innymi konstruktorami
Jeśli chciałbyś mieć dodatkowe konstruktory, to musisz w nich wywołać ten primary constructor. Robi się to za pomocą słówka this:
class Person(string name, int age)
{
public string Name { get; } = name;
public Person(string name, DateTime birthday)
: this(name, DateTime.Now.Year - birthday.Year)
{
}
}
Dependency injection
Primary constructors wspierają również mechanizm dependency injection, co wydaje się całkiem interesującym rozwiązaniem. Prawdę mówiąc, to chyba jedyny powód, dla których chciałbym ich używać. No bo popatrz na standardowy kod:
class MyService
{
private readonly MyOtherService _service;
public MyService(MyOtherService service)
{
_service = service;
}
}
Używając primary constructors możemy go skrócić do takiego zapisu:
class MyService(MyOtherService service)
{
}
Jest kompresja.
Operacje na parametrach
No dobra, a jak poradzić sobie z sytuacją, gdzie w konstruktorze musimy zrobić jakieś sprawdzenia, czy coś w ten deseń? Czyli po staremu:
class Person
{
public Person(string name)
{
if (string.IsNullOrWhiteSpace(name))
throw new ArgumentException("Person must have a name");
}
}
Po prostu możemy użyć statycznej metody:
class Person(string name)
{
public string Name { get; } = ValidName(name) ? name : throw new ArgumentException("Person must have a name!");
private static bool ValidName(string name)
{
return !string.IsNullOrWhiteSpace(name);
}
}
Podczas tworzenia takiego obiektu, zostanie wywołana metoda ValidName. No i jeśli podamy niepoprawną wartość, wywali się. Czyli kod poniżej zadziała tak, jak się tego spodziewamy:
var person = new Person(""); //wywali się
Niemniej jednak nie podoba mi się to. Chociaż to pewnie głównie kwestia gustu. Natomiast uważam, że to czyni kod brzydkim, brudnym, a im więcej takich rzeczy, tym ciężej będzie się go debugować.
Tworzenie kolekcji – Collection expressions
Bardzo miłe ułatwienie. Do tej pory, żeby stworzyć tablicę, trzeba było napisać:
int[] tab = new int[] { 1, 2, 3 };
Stary, fajny, klasyczny kod. Collection expressions, które dostaliśmy w C#12 daje nam dużo prostszą i szybszą metodę:
int[] tab = [1, 2, 3];
Możemy to samo zrobić z listami, spanami i właściwie wszystkimi kolekcjami wspierającymi inicjalizatory:
List<int> list = [1, 2, 3];
IEnumerable<int> e = [1, 2, 3];
A teraz spójrz jeszcze na zaznaczoną powyżej linię. Widzisz, jak stworzyłem IEnumerable?
Ale jak to? Przecież IEnumerable to interfejs!
Azaliż. I tak naprawdę powstał obiekt klasy ReadOnlyArray<int>.
W taki sposób można tworzyć też wszystkie rodzaje tablic – wielowymiarowe, poszarpane (jagged arrays) itd.
Jak dla mnie, bardzo fajne rozwiązanie. Bardzo ułatwi pracę i zdecydowanie będę z niego korzystał.
Inline arrays
UWAGA! To jest dość zaawansowany temat. Jeśli nie bawiłeś się pamięcią i nie używałeś bibliotek z innych języków (np. C++, Pascal), prawdopodobnie ten akapit niczego Ci nie da.
Inline array to odpowiednio utworzona struktura. Jest odpowiednikiem fixed buffer w bezpiecznym kodzie (safe code). Spójrz w jaki sposób możesz utworzyć taką strukturę:
[InlineArray(3)]
struct InlineBuffer
{
public int element0;
}
Oznacza to, że tworzymy 3 elementową tablicę intów. Jedna rzecz jest istotna:
InlineBuffer buff = new InlineBuffer();
Teraz zmienna buff WSKAZUJE na pierwszy element tablicy – który jest jednocześnie polem element0. Czyli nie jest to referencja do tablicy, tylko sama tablica.
To jest przydatne, gdy walczymy bardzo o szybkość wykonywania kodu. Kompilator gwarantuje, że buff będzie po prostu ciągłą pamięcią o zadanej wielkości.
Ważne jest, że taka struktura nie może mieć żadnego layoutu i musi mieć jedno pole o typie, jakiego chcemy użyć w naszej tablicy.
Co istotne, to pole nie może być wskaźnikiem (w końcu to wskaźnik to niebezpieczny kontekst), ale może być każdym typem wartościowym i większością typów referencyjnych (w tym stringiem). A dobrać się możesz do konkretnych wartości tak samo jak w przypadku zwykłej tablicy – przez indekser. A także przez operator zakresu.
Domyślne parametry w wyrażeniach lambda
Nie ma się co rozpisywać. Po prostu w C#12 możemy używać domyślnych parametrów w wyrażeniach lambda. Wcześniej taki zapis w ogóle się nie kompilował. Obowiązują dokładnie te same reguły, co przy domyślnych parametrach metod:
var foo = (string s = "Siemma") => System.Console.WriteLine(s);
foo(); //wyświetli -> Siema
foo("Hej"); //wyświetli -> Hej
Modyfikator ref readonly
Do tej pory mieliśmy takie modyfikatory, którymi mogliśmy oznaczać parametry metody:
in
out
ref
W C#12 doszedł nowy: ref readonly.
W sumie, ref readonly robi dokładnie to samo, co in. Przyjrzałem się nawet kodowi generowanemu przez IL i te poniższe fragmenty C# tworzą dokładnie ten sam kod IL:
static void Main(string[] args)
{
int val = 10;
Show(val); //<-- pierwszy przypadek
Show2(ref val); //<-- drugi przypadek
Show2(in val); //<-- trzeci przypadek
}
public static void Show(in int value)
{
System.Console.WriteLine(value);
}
public static void Show2(ref readonly int value)
{
System.Console.WriteLine(value);
}
A kod IL też jest dość prosty, bo najpierw odkłada na stos ADRES zmiennej val, następnie wywołuje metodę, która ten adres ze stosu pobiera.
Jednak pewne, nieznaczne różnice są:
metoda przyjmująca parametr in nie potrzebuje, żeby kod wywołujący dawał o tym znać. Przy ref readonly bez jawnego określenia dostaniesz warning. Czyli:
//tu wszystko jest ok
Show(val);
public static void Show(in int value)
{
System.Console.WriteLine(value);
}
//tutaj dostaniesz warning, bo powinieneś wywołać metodę z modyfikatorem ref lub in (nie ma żadnego faktycznego znaczenia dla kodu):
Show(val); //<-- dostaniesz warning
//Show(ref val); //<-- bez warninga
//Show(in val); <-- bez warninga
public static void Show(ref readonly int value)
{
System.Console.WriteLine(value);
}
Zaznaczam – nie ma znaczenia, czy wywołasz metodę (ref readonly) z modyfikatorem ref, czy in. Kod w IL zostanie utworzony dokładnie ten sam.
jeśli przekażesz wartość (lub wyrażenie) do metody z modyfikatorem in, wszystko będzie ok; jeśli zrobisz to samo z metodą z modyfikatorem ref readonly – dostaniesz warning:
//tu wszystko jest ok
Show(10);
public static void Show(in int value)
{
System.Console.WriteLine(value);
}
//tutaj dostaniesz warning
Show(10); //<-- dostaniesz warning
public static void Show(ref readonly int value)
{
System.Console.WriteLine(value);
}
Jeśli jesteś ciekawy, co się wydarzy tutaj, to już mówię. Kompilator tak jakby stworzy za Ciebie zmienną, której przypisze wartość 10. Następnie adres tej zmiennej przekaże do metody.
Więc po co to ref readonly? Nie wiem. W specyfikacji czytam coś takiego:
W C# 7.2 wprowadzono parametry „in” jako sposób przekazywania referencji tylko do odczytu (w C++ nazywałoby się to stałą referencją – przyp. Adama). Parametry „in” dopuszczają zarówno lvalues jak i rvalues i można ich używać bez żadnej adnotacji podczas wywoływania.
Jednakże interfejsy API, które przechwytują lub zwracają referencje ze swoich parametrów chciałyby uniemożliwić rvalue a także wymusić pewne wskazanie w miejscu wywołania, że przechwytywana jest referencja.
Parametry ref readonly są idealne w takich przypadkach, ponieważ ostrzegają, jeśli zostaną użyte z rvalue lub bez żadnej adnotacji.
Także ma to na celu chyba tylko indykację, że metoda przyjmuje referencję.
Atrybut Experimental
C#12 daje nam nowy atrybut. System.Diagnostics.CodeAnalysis.ExperimentalAttribute. Możemy nim oznaczyć chyba wszystko. Od klasy, czy też enuma do pola, właściwości, czy zdarzenia.
Jeśli w kodzie użyjemy czegoś, co jest oznaczone atrybutem Experimental, kompilator wypluje ostrzeżenie, które zachowa się jak błąd. Trzeba jawnie oznaczyć to stłumić (suppress) to ostrzeżenie, żeby taki kod się zbudował.
Jeśli jednak wywołanie eksperymentalnego elementu będzie w innym eksperymentalnym elemencie, wtedy takie ostrzeżenie się nie pojawi. Czyli np.:
internal class MyClass
{
public static void Run()
{
Foo();
}
public static void Foo()
{
}
[Experimental("")]
public static void Bar()
{
}
}
Powyższy kod skompiluje się bez problemu. Poniższy też
public static void Run()
{
//Foo(); <-- wykomentowane wywołanie, czyli nie używamy metod eksperymentalnych
}
[Experimental("")]
public static void Foo()
{
Bar();
}
[Experimental("")]
public static void Bar()
{
}
Ale poniższy da już błąd:
public static void Run()
{
Foo(); //<-- użycie eksperymentalnej metody
}
[Experimental("")]
public static void Foo()
{
Bar();
}
Błąd mówi: Error CS9204 'Foo()' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
Więc, jeśli chcemy jednak używać metody eksperymentalnej, musimy to ostrzeżenie będące błędem wyłączyć:
Można też zmniejszyć poziom tego ostrzeżenia – dokładnie tak samo jak innych. Możemy też to zrobić oczywiście globalnie, ale tego bardzo nie polecam.
Po co ten atrybut?
Raczej dla twórców bibliotek. Jeśli wprowadzają jakieś działanie, które w przyszłości może się mocno zmienić lub w ogóle zostać wywalone, wtedy oznaczenie tego jako Experimental jest dobrym pomysłem. A czy używanie takiego eksperymentalnego kodu jest dobrym pomysłem? Na produkcji raczej nie. W swoich wewnętrznych testach można się pobawić.
Wyłączanie ostrzeżeń o konkretnych funkcjonalnościach
Atrybut Experimental ma ciekawą właściwość. Można mu przekazać coś w rodzaju Id danej funkcjonalności (DiagnosticId), a potem tym Id posługiwać się podczas wyłączania ostrzeżenia. Np.:
Co więcej, możesz przekazać więcej informacji w komunikacie błędu – a konkretnie adres strony, na której jest opisana ta funkcjonalność lub powód dlaczego klienci nie powinni tego używać:
Error DoingFoo 'Foo()' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. (https://example.com/DoingFoo)
Interceptory
W chwili pisania tego artykułu (styczeń 2024) interceptory są eksperymentalne, więc póki co, nie opisuję ich. Ale będę trzymał rękę na pulsie i jeśli wejdą do użycia, na pewno o nich napiszę. Żeby tego nie przegapić, koniecznie zapisz się na newsletter 🙂
Dzięki za przeczytanie tego artykułu. Widać coraz bardziej, że C# idzie w stronę minimalizacji pisanego kodu, co jest z jednej strony fajnym rozwiązaniem. Chociaż może być cięższe do zrozumienia dla początkujących programistów. Niemniej jednak uważam, że to dobry krok naprzód. I choć w tej wersji może nie było jakiś super wielkich zmian, to jednak miło że MS słucha community.
Jeśli czegoś nie rozumiesz lub zauważyłeś w tekście jakiś błąd, daj znać w komentarzu 🙂
Obsługujemy pliki cookies. Jeśli uważasz, że to jest ok, po prostu kliknij "Akceptuj wszystko". Możesz też wybrać, jakie chcesz ciasteczka, klikając "Ustawienia".
Przeczytaj naszą politykę cookie
