Jak działa powiązanie parametrów w ASP.NET Core 8?

W ASP.NET Core 8, zarządzanie parametrami zapytań HTTP stało się bardziej elastyczne, ale i wymagające uwagi, jeśli chodzi o szczegóły implementacyjne. Istotnym zagadnieniem jest sposób, w jaki parametry są powiązywane z danymi przekazywanymi w żądaniach HTTP. Przykład, który ilustruje to zagadnienie, to kombinacja różnych źródeł danych, takich jak parametry trasy, dane formularzy, nagłówki HTTP oraz zapytania. Rozważmy, jak te mechanizmy działają w praktyce, z uwzględnieniem kilku kluczowych aspektów, które warto mieć na uwadze przy tworzeniu czystych, efektywnych i bezpiecznych API REST.

csharp
Copy code
app.MapPut("/Addresses/{addressId}", ([FromRoute] int addressId, [FromForm] Address address) => {   
    return Results.NoContent(); 
}).DisableAntiforgery();

Zauważmy, że parametry są jawnie oddzielone – jeden pochodzi z trasy, drugi z formularza. Jest to ważne, ponieważ pozwala uniknąć konfliktów przy wiązaniu danych, co może zdarzyć się, gdy próbuje się używać jednego obiektu do przekazania wielu źródeł danych. Równocześnie, dodanie metody DisableAntiforgery() zapewnia, że aplikacja nie będzie wymagała tokenów zabezpieczających przed atakami typu Cross-Site Request Forgery (CSRF), które są domyślnie włączone w ASP.NET Core, gdy używa się formularzy.

Innym ważnym elementem jest fakt, że jeśli spróbujemy połączyć różne źródła danych w tym samym obiekcie, z użyciem atrybutów wiązania na każdej z jego właściwości (jak w poniższym przykładzie), operacja zakończy się niepowodzeniem:

csharp
Copy code
public class Address {

    [FromRoute] public int AddressId { get; set; }

    [FromForm] public int StreetNumber { get; set; }

    [FromForm] public string StreetName { get; set; }

    [FromForm] public string StreetType { get; set; }

    [FromForm] public string City { get; set; }

    [FromForm] public string Country { get; set; }

    [FromForm] public int PostalCode { get; set; }
}

W takim przypadku tylko dane przekazywane przez jedno źródło, np. formularz lub ciało zapytania, będą prawidłowo powiązane, podczas gdy inne pozostaną niezwiązane, co można zobaczyć w odpowiednich widokach błędów.

W kontekście użycia parametrów zapytania i nagłówków w metodach GET warto zauważyć, jak można je efektywnie wykorzystać do filtrowania danych. Przykład z wykorzystaniem parametrów w nagłówkach oraz w zapytaniach wygląda następująco:

csharp
Copy code
app.MapGet("/Addresses", ([FromHeader] string coordinates, [FromQuery] int? limitCountSearch) => {

    return Results.Ok();
});

Parametry w zapytaniach są często opcjonalne, dlatego dobrym rozwiązaniem jest oznaczenie ich jako nullable (np. int? limitCountSearch), co zapewnia większą elastyczność w obsłudze żądań.

Jednym z interesujących przypadków jest także możliwość przesyłania tablic parametrów zarówno przez zapytania, jak i nagłówki. Oto przykład, jak przekazać tablicę identyfikatorów w zapytaniu:

csharp
Copy code
app.MapGet("/Ids", ([FromQuery] int[] id) => {
    return Results.Ok();
});

Dodatkowo, w przypadku nagłówków, możemy skonfigurować nazwę parametru:

csharp
Copy code
app.MapGet("/Languages", ([FromHeader(Name = "lng")] string[] lng) => {

    return Results.Ok();
});

Przykład ten pokazuje, jak ważne jest precyzyjne wskazywanie nazw parametrów w nagłówkach, szczególnie jeśli nie chcemy trzymać się domyślnych nazw.

Wszystkie powyższe techniki mają na celu umożliwienie efektywnego zarządzania różnymi źródłami danych w jednym zapytaniu HTTP, co pozwala na elastyczność przy tworzeniu RESTful API. Warto pamiętać, że niektóre aspekty, jak np. obsługa tokenów antywirusowych czy poprawne łączenie danych z różnych źródeł, mogą wymagać dodatkowej uwagi, szczególnie w przypadku bardziej złożonych aplikacji.

Jak działają middleware w aplikacjach REST API i jak zarządzać przepływem danych?

W architekturze minimalnych aplikacji API, kontrolowanie przepływu danych i obsługi żądań odbywa się za pomocą tak zwanych middleware, czyli oprogramowania pośredniczącego, które umożliwia wprowadzenie dodatkowych kroków przetwarzania pomiędzy różnymi etapami obsługi żądania. Middleware może pełnić wiele różnych funkcji, od logowania, przez walidację danych, aż po autoryzację. Ważne jest, by zrozumieć, jak różne typy middleware wpływają na przepływ kontrolowany przez aplikację i jak można nimi manipulować, by osiągnąć pożądane rezultaty.

Zacznijmy od podstawowej zasady: nie każdy middleware wprowadza nową gałąź w głównym przepływie żądań. Na przykład middleware takie jak MapGet czy MapPost nie rozpoczynają nowej gałęzi; są one używane do mapowania żądań na konkretne endpointy. Jednak middleware MapWhen, który posiada dodatkową funkcję warunkową, może już inicjować nową gałąź w przypadku spełnienia określonych warunków.

Middleware typu Map działa w oparciu o określoną trasę i inicjuje nową gałąź, jeżeli ścieżka żądania pasuje do zdefiniowanej w aplikacji. Przykład można zobaczyć na poniższym kodzie, który ilustruje sytuację, w której middleware MapWhen jest wywoływane tylko wtedy, gdy w zapytaniu znajduje się parametr q. Jeśli warunek nie jest spełniony, żadne nowe gałęzie nie zostaną uruchomione, a przepływ będzie kontynuowany w głównym pipeline.

csharp
Copy code
app.MapWhen(ctx => !string.IsNullOrEmpty(ctx.Request.Query["q"].ToString()), builder => {

    builder.Use(async (context, next) => {
        app.Logger.LogInformation("Nowa gałąź pipeline została uruchomiona");
        await next();
    });
    builder.Run(async context => {
        app.Logger.LogInformation("Nowa gałąź pipeline zakończona");
        await Task.CompletedTask;
    });
});

Ważnym aspektem jest to, że takie middleware jak MapWhen różni się od zwykłych Map, ponieważ warunkowe wykonanie pozwala na bardziej elastyczne sterowanie tym, jakie ścieżki mogą uruchomić dodatkowe kroki przetwarzania. Jeśli parametr w zapytaniu jest obecny, proces przejdzie do nowej gałęzi, a standardowe middleware, jak MapGet, już nie będą miały wpływu.

W przypadku middleware typu UseWhen, kod wyglądałby następująco:

csharp
Copy code
app.UseWhen(ctx => !string.IsNullOrEmpty(ctx.Request.Query["p"].ToString()), builder => {
    builder.Use(async (context, next) => {
        app.Logger.LogInformation("Wykonano middleware z warunkiem");
        await next();
    });
    builder.Run(async context => {
        app.Logger.LogInformation("Kończenie pipeline w UseWhen");
        await Task.CompletedTask;
    });
});

Warto dodać, że middleware Run zawsze kończy proces przetwarzania, a więc jeśli zostanie wywołane w odpowiednim momencie w pipeline, nie pozwoli na dalsze przetwarzanie.

csharp
Copy code
app.MapGet("/test", () => {
    app.Logger.LogInformation("Endpoint GET /test został wywołany");
    return Results.Ok();
});

Główna różnica między Use, UseWhen a MapWhen polega na tym, że pierwszy zestaw middleware działa globalnie na wszystkie żądania, drugi – tylko na te, które spełniają określony warunek, a trzeci – wprowadza dodatkowe gałęzie, które zależą od ścieżek i parametrów.

Oprócz mechanizmów takich jak Map, Use i UseWhen, warto zwrócić uwagę na bardziej zorganizowane podejście do strukturyzowania middleware, np. używanie oddzielnych klas middleware. Dzięki temu aplikacja staje się bardziej czytelna i łatwiejsza do zarządzania. Przykładem może być middleware zewnętrzny, którego kod jest kapsułkowany w dedykowanej klasie, co zapewnia lepszą separację odpowiedzialności i umożliwia łatwiejsze zarządzanie logiką.

Przykład:

csharp
Copy code
namespace AspNetCore8MinimalApis.Middlewares;

public class LoggingMiddleware {
    private readonly RequestDelegate _next;
    private readonly ILogger _logger;
    public LoggingMiddleware(RequestDelegate next, ILogger logger) {
        _next = next;
        _logger = logger;
    }
    public async Task Invoke(HttpContext context) {
        _logger.LogInformation("Wykonano LoggingMiddleware");
        await _next(context);
    }
}

Takie podejście nie tylko ułatwia późniejsze testowanie i rozbudowę, ale także pomaga w utrzymaniu aplikacji w czystości, separując konkretne zadania i nie mieszając logiki przetwarzania żądań z innymi operacjami.

Podsumowując, kluczowe jest zrozumienie, w jaki sposób różne middleware wpływają na strukturę aplikacji, jak i na kontrolowanie przepływu danych w aplikacjach REST API. Różnice między Map, Use, UseWhen, MapWhen oraz Run mają istotne znaczenie przy projektowaniu bardziej elastycznych i skalowalnych systemów. Zrozumienie tego mechanizmu pomoże w budowie wydajnych aplikacji, które reagują na warunki dynamicznie i kontrolują, jak, kiedy i które operacje są wykonywane.

Jak efektywnie i bezpiecznie zarządzać danymi w aplikacji przy użyciu Entity Framework Core?

Współczesne aplikacje coraz częściej bazują na rozwiązaniach typu ORM (Object-Relational Mapping), a jednym z najpopularniejszych narzędzi w tym obszarze jest Entity Framework Core (EF Core). EF Core umożliwia programistom wygodne mapowanie obiektów na dane w relacyjnych bazach danych, umożliwiając tym samym łatwiejsze i bardziej zrozumiałe operacje na danych. Poniżej przedstawimy sposób, w jaki można efektywnie zarządzać danymi w bazie danych przy użyciu EF Core, korzystając z różnych metod asynchronicznych, które zapewniają lepszą wydajność i skalowalność aplikacji.

Asynchroniczność w EF Core

Kluczowym elementem współczesnych aplikacji jest wykorzystanie metod asynchronicznych, takich jak ExecuteUpdateAsync, ExecuteDeleteAsync, FirstOrDefaultAsync, czy SaveChangesAsync. Zastosowanie tych metod pozwala na bardziej płynne i responsywne działanie aplikacji. Oto kilka istotnych przykładów:

1. ExecuteUpdateAsync – Metoda ta pozwala na zaktualizowanie rekordów w bazie danych w sposób asynchroniczny. W przykładzie, gdzie mamy aktualizację danych kraju, polecenie:

   csharp
   Copy code
   return await _demoContext.Countries
   
       .Where(x => x.Id == countryEntity.Id)
       .ExecuteUpdateAsync(s => s
           .SetProperty(p => p.Description, countryEntity.Description)
           .SetProperty(p => p.FlagUri, countryEntity.FlagUri)
           .SetProperty(p => p.Name, countryEntity.Name));
   

   W tym przypadku aktualizujemy tylko te pola, które zostały zmienione, co jest bardziej efektywne niż aktualizowanie całego rekordu.

2. ExecuteDeleteAsync – Podobnie jak w przypadku aktualizacji, możemy asynchronicznie usuwać dane z bazy. Dzięki temu operacja usunięcia rekordu jest wykonywana w tle, co nie powoduje zablokowania aplikacji.

3. AsNoTracking – Warto zwrócić uwagę na metodę AsNoTracking, która wyłącza śledzenie zmian w danej encji. Dzięki temu zapytanie jest szybsze, ponieważ Entity Framework nie musi utrzymywać stanu obiektów. Jest to szczególnie przydatne w przypadkach, gdy dane są tylko odczytywane i nie planujemy ich modyfikacji.

4. FirstOrDefaultAsync – Metoda ta pozwala na asynchroniczne pobieranie pierwszego elementu, który spełnia warunek zapytania. Jest to przydatne, gdy oczekujemy tylko jednego wyniku, jak np. przy pobieraniu danych konkretnego kraju na podstawie jego identyfikatora.

Projektowanie zapytań z użyciem DTO

Innym interesującym aspektem jest wykorzystanie klasy DTO (Data Transfer Object) w zapytaniach. Zamiast pobierać wszystkie kolumny z bazy danych, Entity Framework Core pobiera tylko te, które zostały określone w projekcji. Na przykład:

csharp
Copy code
.Select(x => new CountryDto
{
    Id = x.Id,
    Name = x.Name,
    Description = x.Description,
    FlagUri = x.FlagUri
})

Takie podejście, zwane projekcją, ma znaczący wpływ na wydajność, ponieważ do aplikacji trafiają tylko dane, które są rzeczywiście potrzebne, a nie cała tabela.

Rola serwisów w architekturze aplikacji

W bardziej złożonych aplikacjach, zarządzanie danymi za pomocą repository pattern i serwisów jest uznawane za dobry sposób organizacji kodu. W przykładowej klasie CountryService mamy metody, które korzystają z repozytoriów do wykonania operacji na danych:

csharp
Copy code
public async Task DeleteAsync(int id)

{
    return await _countryRepository.DeleteAsync(id) > 0;
}
public async Task<CountryDto> RetrieveAsync(int id)
{
    return await _countryRepository.RetrieveAsync(id);
}

Wartością dodaną w tym podejściu jest oddzielenie logiki dostępu do danych od logiki biznesowej, co ułatwia utrzymanie kodu oraz testowanie aplikacji.

Zarządzanie wyjątkami i poprawność aplikacji

Co jeszcze warto wiedzieć?

Przy wdrażaniu asynchronicznych operacji na bazie danych za pomocą EF Core warto również pamiętać o kwestiach związanych z wydajnością, takich jak:

• Optymalizacja zapytań SQL generowanych przez EF Core, poprzez ograniczenie liczby pobieranych danych do minimum (np. tylko te kolumny, które są potrzebne).

• Skorzystanie z mechanizmu buforowania, gdy mamy do czynienia z danymi, które rzadko się zmieniają, a ich pobieranie z bazy danych jest kosztowne.

• Używanie paginacji w przypadku zapytań, które mogą zwrócić dużą liczbę rekordów, aby uniknąć problemów z wydajnością i pamięcią.

Efektywne zarządzanie danymi w bazie danych to nie tylko kwestia stosowania właściwych metod, ale również odpowiedniego projektowania aplikacji, uwzględniającego zarówno wymagania funkcjonalne, jak i te związane z wydajnością i skalowalnością. Implementując asynchroniczność oraz odpowiednie wzorce projektowe, możemy zapewnić, że aplikacja będzie działać szybko i bezpiecznie, nawet w przypadku dużych zbiorów danych.

Jak skonfigurować i wykorzystać HealthCheck w aplikacji ASP.NET Core?

W kontekście monitorowania stanu aplikacji, jednym z najważniejszych narzędzi jest tzw. HealthCheck. W ASP.NET Core HealthCheck jest mechanizmem, który pozwala na sprawdzenie, czy aplikacja działa poprawnie oraz czy jest gotowa do przyjmowania ruchu. W ramach tego mechanizmu wyróżnia się dwa główne typy sprawdzeń: Readiness HealthCheck oraz Liveness HealthCheck. Oba pełnią różne funkcje, które warto zrozumieć, aby właściwie skonfigurować aplikację do monitorowania jej stanu.

Liveness HealthCheck

Liveness HealthCheck odpowiada na pytanie, czy aplikacja w ogóle działa. Jest to najprostszy rodzaj HealthCheck, którego celem jest potwierdzenie, że aplikacja nie jest martwa i działa poprawnie. W przypadku aplikacji wykorzystującej bazę danych SQL Server, konfiguracja tego sprawdzenia polega na dodaniu odpowiedniego pakietu NuGet – AspNetCore.HealthChecks.SqlServer. Następnie w pliku Program.cs dodajemy metodę, która skonfiguruje połączenie z bazą danych oraz utworzy endpoint, który będzie odpowiadał na zapytania o stan aplikacji.

Oto przykładowa konfiguracja:

csharp
Copy code
var builder = WebApplication.CreateBuilder(args); 

var dbConnection = builder.Configuration.GetConnectionString("DemoDb");
builder.Services.AddHealthChecks()
    .AddSqlServer(connectionString: dbConnection);
var app = builder.Build(); 
app.MapHealthChecks("/health"); 
app.Run();

Ten fragment kodu tworzy endpoint /health, który zwróci odpowiedź „Healthy” lub „Unhealthy” w zależności od tego, czy połączenie z bazą danych jest aktywne.

Dla bardziej zaawansowanej konfiguracji, jeśli aplikacja korzysta z wielu baz danych, każdą z nich należy zidentyfikować nazwą, co pozwala na oddzielne monitorowanie stanu każdej z baz:

csharp
Copy code
builder.Services.AddHealthChecks()
    .AddSqlServer(name: "SQL1", connectionString: dbConnection1)
    .AddSqlServer(name: "SQL2", connectionString: dbConnection2);

W przypadku tego typu HealthCheck, aplikacja jest uznawana za „żywą”, jeśli wszystkie zależności, takie jak połączenia z bazami danych, są aktywne i dostępne.

Readiness HealthCheck

Readiness HealthCheck jest bardziej zaawansowanym mechanizmem, który sprawdza, czy aplikacja jest gotowa do przyjmowania ruchu użytkowników. Oznacza to, że aplikacja może być uruchomiona, ale nie jest jeszcze w pełni przygotowana do obsługi żądań, np. może wymagać zakończenia jakiejś operacji inicjalizacyjnej (np. ładowania danych do pamięci podręcznej). W takim przypadku aplikacja nie powinna być uznawana za gotową do użytku, dopóki te długotrwałe operacje nie zostaną zakończone.

W przykładzie poniżej, wprowadzono symulację długotrwałej operacji (10 sekund), która ustawia stan aplikacji jako gotową do pracy dopiero po jej zakończeniu:

csharp
Copy code
public static class Ready

{
    public static bool IsReady { get; set; } = false;
}

Aby wprowadzić mechanizm sprawdzania gotowości aplikacji, należy stworzyć klasę, która implementuje interfejs IHealthCheck:

csharp
Copy code
public class ReadyHealthCheck : IHealthCheck

{
    public Task CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var result = Ready.IsReady
            ? HealthCheckResult.Healthy()
            : HealthCheckResult.Unhealthy("Application not ready");
        return Task.FromResult(result);
    }
}

W tym przypadku, CheckHealthAsync sprawdza, czy aplikacja jest gotowa (czy zmienna IsReady ma wartość true). Jeśli nie, zwraca stan „Unhealthy”, a jeśli aplikacja jest gotowa, odpowiada „Healthy”.

Aby zasymulować długotrwałą operację, używamy następującego kodu:

csharp
Copy code
Task.Run(() => { Thread.Sleep(10000); Ready.IsReady = true; });

Na koniec, aby rozdzielić endpointy dla liveness i readiness, należy odpowiednio skonfigurować mapowanie tych sprawdzeń w aplikacji:

csharp
Copy code
app.MapHealthChecks("/ready", new HealthCheckOptions { Predicate = healthCheck => healthCheck.Tags.Contains("ready") });

app.MapHealthChecks("/live", new HealthCheckOptions { Predicate = healthCheck => healthCheck.Tags.Contains("live") });

Dzięki temu dostępne będą dwa oddzielne punkty końcowe /ready i /live, które będą odpowiadały na zapytania o stan gotowości i żywotności aplikacji. Warto zauważyć, że podczas testowania stanu gotowości przed zakończeniem długotrwałej operacji, endpoint /ready zwróci „Unhealthy”, a dopiero po jej zakończeniu – „Healthy”.

Monitoring i telemetryka

Zaleca się także, aby zainstalować i skonfigurować narzędzia do bardziej zaawansowanego monitorowania aplikacji, takie jak Jaeger czy Grafana, które zapewniają bardziej szczegółowe informacje o stanie aplikacji w czasie rzeczywistym oraz umożliwiają wizualizację danych.

Podsumowanie

Podstawowe zrozumienie i konfiguracja HealthCheck w aplikacji ASP.NET Core jest kluczowe, aby zapewnić jej wysoką dostępność i wydajność. Zarówno Liveness HealthCheck, jak i Readiness HealthCheck są niezbędnymi elementami każdej nowoczesnej aplikacji, pozwalającymi na monitorowanie stanu aplikacji oraz informowanie systemów zarządzania o jej gotowości do obsługi ruchu. Właściwe skonfigurowanie tych mechanizmów pozwala uniknąć wielu problemów związanych z niedostępnością aplikacji czy błędami w działaniu.