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.
.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:
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:
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:
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:
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:
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:
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:
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;
}
}
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 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:
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 🙂
Witaj podróżniku. Skoro już tu jesteś, prawdopodobnie wiesz czym jest EntityFramework. Jeśli jednak nie, to przeczytaj kolejny akapit. W tym artykule postaram szybko wprowadzić Cię w jego świat, żebyś w ciągu kilku minut był w stanie zacząć z nim wspólną przygodę.
Czym jest Entity Framework? – rozwiń jeśli nie wiesz
EntityFramework Core zwany również EfCore to narzędzie typu ORM – Object Relational Mapper. Prostymi słowami to mechanizm, który umie zamienić (mapować) rekordy znajdujące się w bazie danych, na obiekty modelowe. Po co to? To jest zwykły „pomagacz”. Bo oczywiście możesz napisać w starym dobrym ADO.NET kod w stylu:
//pseudokod
var resultList = new List<Employee>();
string sql = "SELECT * from employees";
var reader = _db.OpenQuery(sql);
while(reader.Read())
{
var employee = new Employee();
employee.Id = reader.GetGuid("id");
employee.Name = reader.GetString("name");
employee.Salary = reader.GetDecimal("salary");
resultList.Add(employee);
reader.Next();
}
return resultList;
ale ostatecznie większość programistów, pisząc w ADO.NET i tak kończyła z jakąś ubogą formą własnego ORMa.
Dlatego powstały właśnie takie narzędzia, żeby ułatwić pracę. Programista wie jak ma pobrać dane i wie jaki obiekt chce zwrócić. Nie musi się zajmować czarną robotą w stylu mapowania tak jak wyżej.
Jest sporo różnych ORMów na rynku. Myślę, że najpopularniejsze z nich (przynajmniej w mojej subiektywnej ocenie) to Dapper, nHibernate i właśnie EfCore. Przy czym Dapper zalicza się do grupy tzw. micro orm. Dlatego, że nie potrafi tyle, co EfCore, czy nHibernate. Wciąż musisz pisać własnego SQLa, ale za to dostajesz obiekt już elegancko zmapowany. No i Dapper jest zdecydowanie szybszy.
Kwestia nazwy
Pewnie zobaczysz nie raz obok siebie nazwy w stylu „Entity Framework”, „EfCore”, „Entity Framework Core”. Czy to jest ten sam produkt? Nie do końca. Jeśli chodzi o „Entity Framework” jest on używany w .NET Framework (czyli w tej starszej technologii przed .NET Core). Natomiast „EfCore”, czy po prostu „Entity Framework Core” to wersja dla .Net Core i nowszych. Czasem możesz widzieć te nazwy zamiennie. W tym artykule, pisząc „Ef”, „Entity Framework” zawsze będę miał na myśli „EfCore”.
Kwestia prędkości
Oczywiście, że ORMy są wolniejsze niż ręczne mapowanie. Jednak to zwolnienie w większości przypadków jest niezauważalne. Jeśli jednak faktycznie w niektórych miejscach potrzebujesz większej szybkości, możesz tylko te miejsca traktować inaczej – bez ORMa.
Instalacja narzędzi EfCore
Na początek sprawdź, czy masz już zainstalowane narzędzia do EF. Wklep taką komendę do command line’a:
dotnet ef --version
Jeśli Ci się wykrzaczyło, znaczy że nie masz. W takim przypadku zainstaluj:
dotnet tool install --global dotnet-ef
Powyższe polecenie zainstaluje globalnie narzędzia do EF, a poniższe zaktualizuje do najnowszej wersji:
dotnet tool update --global dotnet-ef
Przykładowa aplikacja
Jak zwykle, przygotowałem małą przykładową aplikację do tego artykułu. Możesz ją pobrać z GitHuba.
Aplikacja to prosty programik w stylu ToDoList. W ramach ćwiczeń polecam Ci go wykończyć.
Wymagane NuGety:
EfCore nie jest standardową biblioteką. Musisz pobrać sobie minimum dwa NuGety:
Microsoft.EntityFrameworkCore – cały silnik dla EfCore
Microsoft.EntityFrameworkCore.Design – to jest zestaw narzędzi potrzebny programiście podczas „projektowania” aplikacji. Są to narzędzia, które np. pomagają utworzyć migracje (o tym później). Nie są jednak dostępne w czasie działania aplikacji (runtime). Więc jeśli nie będziesz robił migracji, nie musisz tego instalować. Ale lepiej mieć, niż nie mieć.
Biblioteka do obsługi konkretnego typu bazy danych (DBMS) – inna jest dla MSSQL, inna dla Sqlite, inna dla Oracle itd. Ich nazwy określają do jakiej bazy danych się odnoszą, np: Microsoft.EntityFrameworkCore.SqlServer – do obsługi MSSQL.
Modele bazodanowe
Na początek stwórzmy sobie podstawowy model bazodanowy do aplikacji.
public enum ToDoItemStatus
{
NotStarted,
Running,
Done
}
public class ToDoItem: BaseDbItem
{
public DateTimeOffset? StartDate { get; set; }
public ToDoItemStatus Status { get; set; } = ToDoItemStatus.NotStarted;
public DateTimeOffset? EndDate { get; set; }
public string Title { get; set; }
public string Description { get; set; }
}
Mamy tutaj zwykły ToDoItem, który może być w 3 stanach:
Nierozpoczęty (NotRunning)
Rozpoczęty (Running)
Zakończony (Done)
Zauważysz też, że mój model dziedziczy po BaseDbItem. To zwykła klasa abstrakcyjna, która zawiera Id:
public abstract class BaseDbItem
{
public Guid Id { get; set; }
}
Oczywiście nie musisz jej tworzyć i możesz umieścić w każdym modelu pole Id. Ja jednak wolę to zrobić, bo to pomaga i może uprościć wiele rzeczy w późniejszym utrzymaniu takiego systemu. Dlatego też zachęcam Cię, żebyś stosował taką klasę bazową.
Kontekst bazy danych
To jest najważniejszy element EfCore. Technicznie to klasa, która dziedziczy po DbContext. Odzwierciedla całą zawartość bazy danych – wszystkie tabele, które chcesz mieć. Dlatego też musisz napisać taką klasę. W swojej najprostszej i NIEWYSTARCZAJĄCEJ postaci może wyglądać tak:
public class ApplicationDbContext: DbContext
{
public DbSet<ToDoItem> ToDoItems { get; set; }
}
Właściwie to zbiór właściwości typu DbSet. DbSet odnosi się do tabeli w bazie danych. Dlatego też dla każdej tabeli będziesz miał osobne właściwości DbSet. Stwórzmy zatem drugi model – użytkownik. Dodamy też od razu go do kontekstu:
public class User: BaseDbItem
{
public string Name { get; set; }
}
//dodajmy go też jako właściciela konkretnego ToDoItem:
public class ToDoItem: BaseDbItem
{
public User Owner { get; set; }
public DateTimeOffset? StartDate { get; set; }
public ToDoItemStatus Status { get; set; } = ToDoItemStatus.NotStarted;
public DateTimeOffset? EndDate { get; set; }
public string Title { get; set; }
public string Description { get; set; }
}
//no i do kontekstu:
public class ApplicationDbContext: DbContext
{
public DbSet<ToDoItem> ToDoItems { get; set; }
public DbSet<User> Users { get; set; }
}
Połączenie z bazą danych
Mając stworzony DbContext, możemy teraz utworzyć połączenie do bazy danych. Sprowadza się to do trzech kroków:
Przechowywanie ConnectionString
ConnectionString do bazy będzie przechowywany oczywiście w ustawieniach – appsettings. Ja trzymam w głównym pliku: appsettings.json zamiast appsettings.Development.json, ponieważ jest mi prościej (za chwilę dowiesz się dlaczego).
Pamiętaj, że ten plik ląduje w repozytorium na serwerze, więc jeśli umieszczasz tam jakieś hasło, to pamiętaj, że to zła praktyka i powinieneś posłużyć się sekretami. W przeciwnym razie każdy z dostępem do repozytorium zobaczy Twoje hasło.
To teraz jak utworzyć ConnectionString do bazy lokalnej? Bardzo prosto. Najpierw otwórz sobie okienko SQL Server Object Explorer:
To okienko pozwala Ci zarządzać lokalnymi bazami. Teraz odnajdź bazę master na lokalnym serwerze i wejdź w jej właściwości (ważne, żebyś rozwinął bazę master. Jeśli jej nie rozwiniesz, nie zobaczysz connection stringa):
Z właściwości możesz odczytać connection stringa:
Skopiuj go i wklej do ustawień w pliku appsettings.json lub w secrets.json:
Teraz zwróć uwagę, że w connection string jest zaszyta nazwa bazy – master. Dlatego też powinieneś ją zmienić na swoją docelową bazę. Ta baza nie musi istnieć, EfCore sam ją sobie utworzy, ale zmień tą nazwę. Nigdy nie pracuj na bazie master (traktuj ją tylko jako do odczytu):
Musimy teraz w jakiś sposób powiedzieć EfCore’owi z jaką bazą chcemy się łączyć. Robimy to poprzez kontekst bazy danych. Wystarczy oprogramować konkretną wersję konstruktora w taki sposób:
public class ApplicationDbContext: DbContext
{
public DbSet<ToDoItem> ToDoItems { get; set; }
public DbSet<User> Users { get; set; }
public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
: base(options)
{
}
}
I to w zasadzie wystarczy. Oczywiście nic Ci nie broni, żebyś w tym konstruktorze posiadał jakiś kod. Ale to w domyślnym mechanizmie wystarczy.
Pamiętaj tylko, że jeśli używasz EfCore z dependency injection, stwórz konstruktor z generyczną wersją DbContextOptions – tak jak wyżej: DbContextOptions<ApplicationDbContext> zamiast samego DbContextOptions.
Dlaczego? Jeśli masz w aplikacji jeden DbContext, to nie ma żadnej różnicy. Jednak, jeśli masz ich kilka, to użycie generycznej wersji DbContextOptions<T> zapewni, że do odpowiednich kontekstów zawsze trafią odpowiednie opcje. W przeciwnym razie dependency injection może coś pochrzanić.
Więc lepiej wyrób sobie taki nawyk.
Teraz dwa słowa wyjaśnienia. EfCore działa w taki sposób, że to kontekst bazy danych musi wiedzieć z jaką bazą się łączy. I ten connection string przekazuje się w konstruktorze. Jednak nie możesz go tam zahardkodować, bo to zła praktyka z punktu widzenia bezpieczeństwa i utrzymania takiego kodu.
Oczywiście mógłbyś posłużyć się mechanizmem konfiguracji i wstrzyknąć tutaj jakieś IOptions. Ale to już jest domyślnie. Ten domyślny sposób korzysta z tego przeciążenia konstruktora – wstrzykuje do kontekstu odpowiednie opcje.
Podczas rejestracji kontekstu, rejestrowane są też jego opcje (DbContextOptions), w którym connection string jest już obecny. Jeśli dobrze zarejestrujemy 🙂
Rejestracja kontekstu bazy danych
Kontekst rejestrujemy tak jak każdy inny serwis, dodatkowo podając connection stringa i mówiąc mu, jakiej bazy chcemy użyć.
var config = builder.Configuration;
builder.Services.AddDbContext<ApplicationDbContext>(o =>
{
o.UseSqlServer(config.GetConnectionString("MainDbConnection"));
});
Uwaga! GetConnectionString to metoda pomocnicza, która pobiera sekcję z ustawień aplikacji o nazwie „ConnectionStrings”. Więc jeśli Twoja sekcja nazywa się inaczej lub w innym miejscu masz tego connection stringa, wtedy posłuż się standardowym wywołaniem w stylu config[„MojaSekcja:Connection”].
Pamiętaj, że UseSqlServer to extension method pochodzące z NuGet: Microsoft.EntityFrameworkCore.SqlServer. Jeśli zainstalujesz inny NuGet, np. do obsługi SQLite, wtedy będziesz używał metody UseSqlite. Analogicznie z innymi bazami danych.
Inne sposoby
Są też inne prawilne sposoby rejestracji takiego kontekstu. Np. za pomocą DbContextFactory, o którym za chwilę.
Czym są migracje w EfCore?
Nieodłącznym mechanizmem EfCore są migracje. EfCore jest w stanie sam utworzyć bazę danych. Co więcej, jest w stanie pilnować, żeby struktura bazy danych odpowiadała strukturze w Twoich modelach (choć pamiętaj, że świat relacyjny i obiektowy to zupełnie dwa różne miejsca). Co więcej, od jakiegoś czasu EfCore potrafi też stworzyć modele na podstawie tabel istniejących w bazie danych.
Na pewno spotkałeś się z pojęciami Code First i Database First. To właśnie opisuje sposób tworzenia bazy danych. Podejście Code First tworzy bazę danych z istniejących modeli obiektowych. Database First z kolei na odwrót – tworzy modele obiektowe na podstawie struktury bazy danych. W EfCore jeszcze do niedawna było możliwe użycie jedynie podejścia CodeFirst.
EfCore, aby to wszystko było możliwe, posługuje się migracjami. Z technicznego punktu widzenia, migracja to zwykła klasa, która posiada przepis na utworzenie konkretnej wersji bazy danych.
Gdy zmieniasz swój model i uznajesz go za pewną skończoną wersję, powinieneś zrobić migrację. Robi się to za pomocą narzędzi EfCore. Wystarczy, że w konsoli przejdziesz do folderu, w którym jest Twój projekt i wpiszesz tam takie polecenie:
dotnet ef migrations add "InitialDbCreate"
InitialDbCreate to oczywiście nazwa Twojej migracji. Ta jest standardową nazwą na pierwszą migrację. Poza tym przyjęło się, że nazwa migracji powinna mówić o tym, co migracja zawiera, np. „AddedClientName” albo „RemovedOwnerModel” itd.
Wykonanie tego polecenia stworzy folder Migrations i dwa pliki w środku. Pierwszy to migracja (klasa dziedzicząca po Migration), a drugi to snapshot aktualnej wersji – powstaje na podstawie migracji. Jeśli chcesz od nowa zbudować bazę danych, po prostu możesz usunąć cały folder i bazę danych.
Mając taką migrację, możesz teraz uaktualnić / stworzyć bazę danych poleceniem:
dotnet ef database update
To polecenie po pierwsze połączy się z bazą danych, a po drugie utworzy lub odczyta specjalną tabelę, w której są zapisane nazwy migracji, z których powstaje baza danych. Patrzy na ostatni wpis i wykonuje kolejną migrację – aktualizuje strukturę bazy danych.
Oczywiście dokładnie tak samo, jak tworzyłbyś skrypty SQL aktualizujące strukturę – tutaj też to może się nie udać. Przykładowo, jeśli istnieją rekordy i jakaś kolumna ma wartości NULL, a teraz chcesz zrobić, żeby ta kolumna nie mogła być NULLem, to się nie uda. Więc trzeba na takie rzeczy zwracać uwagę.
Jak to działa?
Zarówno tworzenie migracji jak i aktualizacja bazy uruchamia Twoją aplikację. Najpierw apka jest budowana (choć to można pominąć, dodając do polecenia argument --no-build, ale uważaj na to, bo może się okazać że migracja nie zostanie przeprowadzona), potem uruchamiana w specjalny sposób. I tutaj może pojawić się problem z odczytem connection stringa. W .NET6 narzędzia szukają connection stringa na produkcyjnej wersji środowiska (chyba że masz globalnie ustawioną zmienną środowiskową ASPNET_ENVIRONMENT z wartością Development) – dlatego wcześniej pisałem o tym, że dla ułatwienia connection string trzymany jest w głównym appsettings.json (lub secrets.json).
Pewnie można to jakoś zmienić, ale jeszcze nie rozkminiłem jak 🙂
Konfiguracja EfCore
EfCore jest na tyle „mądry”, że dużo potrafi wywnioskować na temat modeli będących w DbContext. I tak naprawdę jeśli w ogóle nie skonfigurujesz swoich modeli, to on i tak rozkimi, że pole o nazwie Id jest kluczem głównym; że pole OwnerId jest jakimś kluczem obcym. Co więcej nawet jak zobaczy właściwość wskazującą na inny obiekt, też stworzy z tego relację.
Jednak nie wszystko jest w stanie wydedukować. Poza tym mamy w naszym przypadku jeden poważny problem. Kolumna Status w tabeli ToDoItems domyślnie została utworzona jako int (EfCore tak domyślnie mapuje enumy). Czy to dobrze? Zdecydowanie nie. W tym momencie mamy możliwe 3 wartości:
public enum ToDoItemStatus
{
NotStarted,
Running,
Done
}
NotStarted zostało zmapowane do 0, Running to 1, a Done to 2. Fajnie. A jak ktoś dołoży kolejną?
public enum ToDoItemStatus
{
NotStarted,
Running,
Paused,
Done
}
Wtedy w bazie wszystko się pop…rzy. Bo nagle Paused przyjmie wartość 2, a Done 3. Z bazy będzie wynikało, że żadne zadanie nie zostało ukończone. Za to te, co były ukończone będą uważane za wstrzymane. Dlatego mimo wszystko lepiej enumy trzymać jako string.
To wszystko i wiele więcej możemy uzyskać dzięki konfiguracji modeli. Konfigurację można przeprowadzić na dwa sposoby:
za pomocą adnotacji
używając fluentowej konfiguracji
Osobiście jestem zwolennikiem tej drugiej, bo dzięki temu modele bazodanowe są czyste. Poza tym adnotacje nie pozwolą na wszystko.
Przykład konfiguracji za pomocą adnotacji może wyglądać tak:
public class ToDoItem: BaseDbItem
{
[Required]
public Guid OwnerId { get; set; }
[ForeignKey(nameof(OwnerId)]
public User Owner { get; set; }
public DateTimeOffset? StartDate { get; set; }
public ToDoItemStatus Status { get; set; } = ToDoItemStatus.NotStarted;
public DateTimeOffset? EndDate { get; set; }
[MaxLength(30)]
public string Title { get; set; }
public string Description { get; set; }
}
Tutaj mówimy do ORMa trzy rzeczy:
Pole OwnerId ma być wymagane (not null)
Owner to klucz obcy do tabeli Users, odpowiada mu właściwość OwnerId
Pole Title ma mieć maksymalnie 30 znaków
Tych adnotacji jest oczywiście więcej, ale moim skromnym zdaniem szkoda na nie czasu. Przejdźmy od razu do Fluent Configuration.
Konfiguracja typu Fluent
Możesz ją przeprowadzić na dwa sposoby. Czysto – tzn. oddzielne klasy odpowiadają za konfigurację konkretnych modeli lub brudno – wszystkie modele w jednej metodzie. Najpierw pokażę Ci tę „brudną” konfigurację.
Przejdźmy do naszego DbContext. Tam jest do przeciążenia taka metoda jak OnModelCreating, w której możemy te modele pokonfigurować. Ale zanim do tego dojdzie, zróbmy małą, ale cholernie istotną zmianę w modelu:
public class ToDoItem: BaseDbItem
{
public Guid OwnerId { get; set; }
public User Owner { get; set; }
public DateTimeOffset? StartDate { get; set; }
public ToDoItemStatus Status { get; set; } = ToDoItemStatus.NotStarted;
public DateTimeOffset? EndDate { get; set; }
public string Title { get; set; }
public string Description { get; set; }
}
Dodałem właściwość OwnerId. Dzięki temu będziemy mogli przeszukiwać tabelę ToDoItems pod kątem konkretnych użytkowników z użyciem Linq. Jednocześnie nie będziemy musieli robić joina z tabelą Users. Skonfigurujmy to teraz:
Ta konfiguracja fluentowa również sama się świetnie opisuje 🙂 Założę się, że bez tłumaczenia od razu widzisz jakie masz możliwości i co robi powyższy kod.
Generalnie, posługując się metodą Property, możemy ustawiać ograniczenia, konwertery itd. dla konkretnych właściwości.
Zwróć uwagę szczególnie na linijki 10 i 11, gdzie konwertujemy enum do stringa.
Czy warto bawić się w konfigurację, skoro EfCore robi dużo za nas? Moim zdaniem warto. Ja nie za bardzo lubię oddawać kontrolę nad kodem, są rzeczy które wolę jasno określić. Jednak, jeśli Ty jesteś bardziej otwarty lub nie potrzebujesz niektórych ograniczeń, możesz spróbować dać EfCore wolną wolę i zobaczyć co się stanie.
Ignorowanie właściwości
EfCore domyślnie umieszcza w bazie wszystkie właściwości z modelu (w przeciwieństwie do nHibernate). Tutaj też możemy mu powiedzieć jakie właściwości ma ominąć. Np. jeśli bym nie chciał, żeby do bazy trafiał czas zakończenia zadania, mógłbym to skonfigurować tak:
todoItemBuilder.Ignore(x => x.EndDate);
Jak widzisz sam konkretny builder danego modelu ma w sobie też różne ciekawe elementy. Pozwala między innymi na zmianę nazwy tabeli.
Klucze
Możesz ustawić dodatkowy klucz na jednym lub na kilku polach. Przy czym jeśli chodzi o klucz ustawiany na kilku polach, jest to możliwe tylko za pomocą fluent configuration. Nie można tego zrobić adnotacjami:
todoItemBuilder.HasKey(x => x.Status);
todoItemBuilder.HasKey(x => new {x.OwnerId, x.Status});
Tutaj utworzyłem dwa klucze – jeden na pole Status, drugi jest kluczem na dwóch polach – OwnerId i Status. Jak widzisz, jest to banalnie proste.
Relacje w EfCore
Relacje to dość ważny aspekt w bazach relacyjnych 😀 W EfCore konfiguruje się je bardzo prosto, trzeba pamiętać tylko o kilku rzeczach i pojęciach:
relację konfigurujemy tylko z jednej strony. Tzn. możemy ustawić, że ToDoItem ma jednego ownera albo User ma wiele ToDoItem'ów. Nie musimy konfigurować dwóch modeli. Tzn. nie musimy w User podawać, że ma wiele ToDoItem'ów i jednocześnie w ToDoItem, że ma jednego usera. Wystarczy, że skonfigiujemy to po jednej stronie
encja zależna (dependent entity) – to jest ta encja, która zawiera klucz obcy. Czyli w naszym przypadku encją zależną jest ToDoItem – ponieważ to w tej klasie zdefiniowaliśmy klucz obcy
encja główna (principal entity) – to jest ta encja, która jest „rodzicem” encji zależnej. W naszym wypadku będzie to User. No, jeśli usuniemy Usera, jego encje zależne też powinny zostać usunięte (czyli jego wszystkie zadania).
właściwość nawigacyjna (navigation property) – to jest właściwość w encji zależnej i/lub głównej, która wskazuje na tę drugą stronę. Bardziej po ludzku, w modelu ToDoItems naszym navigation property jest Owner – to ta właściwość wskazuje na konkretny model encji głównej. Możemy dodać takie navigation property również do modelu User, dodając np. listę todo itemów:
public class User: BaseDbItem
{
public string Name { get; set; }
public List<ToDoItem> Items { get; set; }
}
Generalnie navigation property może posiadać kilka typów:
kolekcję zależnych encji (jak wyżej właściwość Items)
właściwość wskazującą na jedną powiązaną encję (np. w naszym modelu ToDoItems jest to Owner)
Czasem mówimy też o inverse property. To jest zwykłe navigation property tyle, że po drugiej stronie relacji. Jakby to powiedzieć prościej… Jeśli nasza encja User miałaby listę Itemów jak w powyższym przykładzie, wtedy ta lista Itemów byłaby takim „inverse property”. Kiedy to się przydaje i po co?
Generalnie EfCore potrafi sam wykminić wiele rzeczy na podstawie konwencji nazewnictwa, zależności itd. Ale w pewnych sytuacjach nie ogranie. Czasem możesz dostać błąd, że nie może „wydedukować” rodzaju relacji. Wtedy, żeby mu ułatwić możesz zastosować ten inverse property. I konfiguracja takiej relacji wyglądałaby tak:
Mam tu na myśli taką konfigurację, że poszczególne klasy są konfigurowane w osobnych plikach – tak jak ma to miejsce przy nHibernate. Najpierw warto utworzyć sobie konfiguracyjną klasę bazową, np:
public abstract class BaseModelConfig<TModel> : IEntityTypeConfiguration<TModel>
where TModel : BaseDbItem
{
public virtual void Configure(EntityTypeBuilder<TModel> builder)
{
builder.Property(x => x.Id)
.IsRequired()
.ValueGeneratedOnAdd();
}
}
Zwróć uwagę, że nasza klasa bazowa implementuje interfejs IEntityTypeConfiguration. Tutaj właśnie przyda się też bazowy model, o czym pisałem wcześniej. Naprawdę warto go mieć.
Następnie konfiguracja pozostałych modeli polega na dziedziczeniu po klasie BaseModelConfig:
Oczywiście nie musisz tworzyć abstrakcyjnej klasy bazowej. Ważne, żeby konkretne konfiguracje implementowały interfejs IEntityTypeConfiguration. Jednak taka klasa bazowa dużo ułatwia.
Na koniec musisz jeszcze powiedzieć w kontekście, gdzie ma szukać konfiguracji. DbContext będzie szukał implementacji interfejsu IEntityTypeConfiguration w Assembly, które mu podasz. W tym przypadku wykorzystujemy aktualne, główne:
Przede wszystkim pamiętaj, że EfCore pełni rolę repozytorium. Dlatego nie twórz repozytorium (mówię tutaj o wzorcu projektowym), używając EfCore – to jest częsty błąd w tutorialach na YouTubie i zbyt wielu artykułach. Pamiętaj – EfCore to repozytorium.
Jeśli chodzi o programowanie webowe, to najczyściej jest używać EfCore w serwisach. Kontroler odwołuje się do serwisu, serwis ma wstrzyknięty DbContext. A teraz zobaczmy, w jaki sposób można dodać rekord. Spójrz na poniższy serwis:
public class UserService
{
private readonly ApplicationDbContext _dbContext;
public UserService(ApplicationDbContext dbContext)
{
_dbContext = dbContext;
}
public async Task AddOrUpdateUser(User data)
{
_dbContext.Users.Update(data);
await _dbContext.SaveChangesAsync();
}
}
Najpierw wstrzykujemy do konstruktora ApplicationDbContext. Następnie możemy się nim posługiwać tak jakbyśmy używali zwykłego wzorca repozytorium. A nawet lepiej, bo można używać Linq do pobierania danych.
Zwróć tylko uwagę na to, że dodawanie/modyfikacja danych w poszczególnych DbSet'ach jeszcze niczego nie zmienia. Na tym poziomie działa taki sprytny wewnętrzny mechanizm EfCore (change tracker), który oznacza odpowiednie rekordy w odpowiedni sposób (ten rekord będzie zmodyfikowany, ten trzeba dodać, a tu jest jakiś do usunięcia).
Faktyczne operacje do bazy danych pójdą dopiero po wywołaniu SaveChanges. I do tego pójdą w transakcji.
Czas życia DbContext – ważne
DbContext nie jest thread-safe. Nie powinien żyć długo. Domyślnie jest wstrzykiwany jako scope (choć to można zmienić podczas konfiguracji). Zalecam zostawić domyślne zachowanie, chyba że pojawiają się problemy, to wtedy można zmienić na transient:
Jeśli używasz zwykłego WebApplication albo WebApi, to takie konstrukcje ze wstrzykiwaniem DbContext są jak najbardziej poprawne. Ale problem pojawia się przy Blazor lub aplikacjach desktopowych.
Inaczej dla Blazor i aplikacji desktopowych
Dlaczego? Jak już mówiłem, DbContext jest standardowo wstrzykiwany jako scoped. Możesz też zmienić na transient. Jednak co to oznacza dla Blazor? Tam, jeśli masz serwis oznaczony jako scope, to właściwie zachowuje się to jak singleton. Dokładnie tak samo jest w aplikacjach desktopowych.
Nie oznacza to teraz, że w Blazor wszystkie serwisy korzystające pośrednio lub bezpośrednio z bazy danych, mają być wstrzykiwane jako transient. O nie. Jest lepszy sposób. Spójrzmy na fabrykę.
Fabryka DbContext
Zamiast rejestrować DbContext, możesz zarejestrować fabrykę:
Przyznasz, że wielkiej różnicy nie ma. Różnica pojawia się w momencie używania tego kontekstu. Teraz wstrzykujemy fabrykę do serwisu:
public class UserService
{
private readonly IDbContextFactory<ApplicationDbContext> _dbContextFactory;
public UserService(IDbContextFactory<ApplicationDbContext> dbContextFactory)
{
_dbContextFactory = dbContextFactory;
}
public async Task AddOrUpdateUser(User data)
{
using var dbContext = _dbContextFactory.CreateDbContext();
dbContext.Users.Update(data);
await dbContext.SaveChangesAsync();
}
}
Tutaj do dostępu do bazy danych wykorzystujemy fabrykę. Po prostu ona nam tworzy ten kontekst. Pamiętaj, że musisz tworzyć to przez using. DbContext implementuje interfejs IDisposable i jest cholernie ważne, żeby po sobie posprzątał.
Nie ma nic złego w takim tworzeniu kontekstu. Co więcej – to naturalny sposób w przypadku aplikacji desktopowych no i we wspomnianym Blazor.
Pamiętaj, że jeśli chodzi o WebApplication lub WebApi – gdzie każdy request tworzy i usuwa scope, to możesz posłużyć się tą wersją ze wstrzykiwaniem samego kontekstu.
Zapytania SELECT
Oczywiście jest to tak samo proste jak pobieranie danych ze zwykłej listy. Zwróć tylko uwagę na to, czym jest IQueryable. Spójrz na poniższy kod:
var data = dbContext.Users.Where(x => x.Name.Length > 3);
Tutaj pobieramy użytkowników, których imię ma więcej niż 3 znaki. Czy to zapytanie się wykona?
Nie wykona się. Dlatego, że metoda Where zwraca obiekt IQueryable. A to taki twór, który możesz uznać za zapytanie SQL. Możesz mu zatem dodać inne warunki, np:
var data = dbContext.Users.Where(x => x.Name.Length > 3);
data = data.Where(x => x.Name.Contains("A"));
A kiedy IQueryable zostanie wysłane do bazy danych? We wszystkich tych metodach, które zwracają coś innego niż IQueryable (a konkretnie nasz model lub jego listę), np:
var list = await data.ToListAsync();
var first = await data.FirstAsync();
var fod = await data.FirstOrDefaultAsync();
Itd. Generalnie zawsze spójrz na to, co zwraca konkretna metoda. Tam, gdzie masz IQueryable, to nie ma jeszcze żadnej pracy na bazie danych.
Join
A teraz spójrz na takie zapytanie:
using var ctx = _dbContextFactory.CreateDbContext();
var data = await ctx.ToDoItems.ToListAsync();
Co zostanie pobrane?
Same zadania. Bez ich właścicieli. To super wiadomość. EfCore domyślnie zwróci tylko te dane, o które pytamy. Nie jest to wprawdzie takie „lazy loading” jak w nHibernate (choć to też da się ustawić), jednak do bazy idą tylko najbardziej potrzebne zapytania.
Oczywiście możemy do tego zrobić joina, żeby uzyskać zadania wraz z właścicielami. Ale musimy to jasno powiedzieć. W taki sposób:
using var ctx = _dbContextFactory.CreateDbContext();
var data = await ctx.ToDoItems
.Include(x => x.Owner)
.ToListAsync();
Metoda Include powie EfCore’owi, że chcemy pobrać również właściciela zadania. Istnieje również metoda ThenInclude, która pobiera dane z kolejnej encji (w naszym przypadku byłby to User).
Uważaj na podwójny INSERT
Spójrz na tan kod:
public async Task AddOrUpdateTask(ToDoItem item)
{
User owner;
using var ctx = _dbContextFactory.CreateDbContext();
owner = await ctx.Users.FirstAsync();
item.Owner = owner;
ctx.ToDoItems.Add(item);
await ctx.SaveChangesAsync();
}
Tak naprawdę nie jest ważne skąd pochodzi owner, ważne jest że ten owner znajduje się już w bazie danych. Taki kod wybucha błędem o niepoprawnym kluczu. EfCore myśli, że skoro dodajemy nowy rekord (ToDoItem), to dodajemy go z całym inwentarzem, czyli chcemy też dodać jego ownera (technicznie – INSERT owner i INSERT todoItem). Ale User o takim id już istnieje w bazie danych.
Czemu tak się stało?
EfCore ma taki sprytny mechanizm, który nazywa się ChangeTracker. On po prostu sprawdza, co się zmieniło w encji podczas życia kontekstu bazy danych. Akurat ta encja (TodoItem) jest zupełnie nowa. Więc w ChangeTrackerze, który żyje razem z kontekstem bazy danych ma oznaczenie „New”. Wszystko co ma oznaczenie „New” musi zostać dodane do bazy przez INSERT. EfCore uznaje również, że wszystkie encje zależne też są nowe.
Ale to nie koniec niespodzianki. Jeśli stworzymy jeden DbContext i pobierzemy z niego TodoItem, następnie kontekst zostanie ubity, to po utworzeniu drugiego kontekstu ten TodoItem, który został pobrany też będzie widoczny jako nowy – w tym nowym DbContext. To jest pułapka, na którą często sam się łapałem i na którą zwracam Tobie szczególną uwagę.
Więc jak sobie z czymś takim poradzić? Po prostu:
public async Task AddOrUpdateTask(ToDoItem item)
{
User owner;
using var ctx = _dbContextFactory.CreateDbContext();
owner = await ctx.Users.FirstAsync();
item.OwnerId = owner.Id;
ctx.ToDoItems.Add(item);
await ctx.SaveChangesAsync();
}
Czyli zamiast obiektu, przypisuję Id. Czasem nawet będziesz musiał zrobić takie cudo:
Musisz znullować ownera jako obiekt, ale zostawiasz jego Id. To oczywiście dotyczy tej samej sytuacji, czyli jedna encja pochodzi z jednego kontekstu, a druga z drugiego. Może się tak zdarzyć chociażby przy WebApi. Dlatego też pomocne może okazać się przesyłanie między końcówkami modelu DTO, zamiast bazodanowego (i mocno Cię do tego zachęcam, żebyś nie przesyłał modeli bazodanowych).
Różne bazy danych, różne możliwości
Możliwości EfCore zależą trochę od rodzaju bazy danych, na jakiej pracujesz. Niektóre operacje nie będą dozwolone np. na Sqlite. Zazwyczaj pracujemy na jednym typie bazy. Ale nie zawsze. Czasem zdarza się, że potrzebujesz dwóch rodzajów. Dlatego ważne jest, żeby przetestować wszystkie funkcje na wszystkich DBMS, które wykorzystujesz.
Dziękuję Ci za przeczytanie tego artykułu. To oczywiście nie wyczerpuje tematu. To są podstawy podstaw jeśli chodzi o EfCore. Na tym blogu mam jeszcze kilka tekstów na ten temat, jeśli Cię zainteresowało, to polecam:
Jeśli czegoś nie rozumiesz lub znalazłeś błąd w artykule, koniecznie daj znać w komentarzu. No i oczywiście udostępnij artykuł osobom, które powinny wiedzieć jak podejść do EfCore.
Często zdarza się, że tworzymy własne modele, którymi przesyłamy błędy z API do klienta API. Osobiście często miałem z tym rozkminy, jak to zrobić uniwersalnie. Na szczęście w 2016 roku w życie wszedł standard RFC7807, który opisuje ProblemDetails – uniwersalny sposób przesyłania błędów.
Standard ProblemDetails
Po co powstał ten standard? Przede wszystkim REST ma być uniwersalny. Twórcy dostrzegli problem typu „każdy wuj na swój strój” – każdy robił własne modele i standardy przesyłania informacji o błędach. Chodziło też o usprawnienie automatyzacji.
Przykładowo, człowiek siedzący za monitorem często z kontekstu może wydedukować, czy błąd 404 jest związany z brakiem strony, czy może z brakiem szukanego rekordu w bazie danych. Automaty niekoniecznie.
Czym jest ProblemDetails?
Z punktu widzenia dokumentacji to jest ustandaryzowany model, który wygląda tak:
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"status": 400,
"instance": "/account/12345/msgs/abc",
}
Teraz omówię każde z tych pól:
Type
To pole jest wymagane i powinno posiadać adres do strony HTML na temat danego błędu. Informacje mają być w formie, w której człowiek może je przeczytać. Jeśli nie możesz dać żadnego adresu, daj domyślną wartość „about:blank”.
Klient API musi traktować to pole jako główne pole opisu błędu. Tzn. powinien wiedzieć, jak zareagować na przykładową wartość: https://www.rfc-editor.org/rfc/rfc7231#section-6.5.4.
Title
To ma być jakieś podsumowanie problemu czytelne dla człowieka. I tutaj uwaga – zawartość tego pola nie może się zmieniać. Tzn. że kilka „wywołań” tego samego problemu musi dać ten sam tytuł. Czyli nie zmieniaj tego w zależności od kontekstu.
Wyjątkiem od tej reguły może być lokalizowanie treści. Czyli inną możesz dać dla Niemca (po niemiecku), inną dla Polaka (po polsku).
Detail
Tutaj powinien znaleźć się opis konkretnej sytuacji czytelny dla człowieka. O ile pole title nie powinno się zmieniać w zależności od danych, to pole detail jak najbardziej może – tak jak widzisz w przykładzie. Pole jest opcjonalne.
Klient API nie powinien w żaden sposób parsować informacji zawartych w tym polu. Są inne możliwości, które pomagają w automatyzacji, o których piszę później (rozszerzenia).
Status
To pole jest opcjonalne. Jego wartością powinien być kod oryginalnego błędu. Powiesz – „ale po co, skoro kod błędu jest w odpowiedzi na żądanie?”. No niby jest. Ale niekoniecznie musi być oryginalny. Jeśli np. ruch przechodzi przez jakieś proxy albo w jakiś inny sposób jest modyfikowany, wtedy kod w odpowiedzi może być inny niż w oryginalnym wystąpieniu błędu. Dlatego w polu status zawsze podawaj oryginalny kod błędu.
Instance
Tutaj powinno znaleźć się miejsce, które spowodowało błąd. To też powinien być adres URI.
Rozszerzenia
Standard pozwala rozszerzać ProblemDetails. Tzn. możesz dodać do modelu inne właściwości. Teraz możesz powiedzieć: „I tu się kończy uniwersalność, dziękuję, do widzenia.”. I w pewnym sensie będziesz miał rację, ale tylko w pewnym sensie. Zauważ, że cały czas podstawowy model jest taki sam.
Przykład modelu z rozszerzeniem
{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"status": 400,
"invalid_params": [ {
"name": "age",
"reason": "must be a positive integer"
},
{
"name": "color",
"reason": "must be 'green', 'red' or 'blue'"}
]
}
Jak widzisz w przykładzie powyżej, doszło pole „invalid_params„. Takie rozszerzenia mogą być użyteczne dla klientów API lub po prostu posiadać dodatkowe informacje. Pamiętaj, że pole detail nie powinno być w żaden sposób parsowane. Więc, wracając do pierwszego przykładu, moglibyśmy dać dwa rozszerzenia, którymi klient API może się w jakiś sposób posłużyć:
{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"status": 400,
"instance": "/account/12345/msgs/abc",
"balance": 30,
"price": 50
}
Generalnie rozszerzenia umożliwiają przekazanie większej ilości informacji w sposób, w jaki chcesz.
Czy muszę używać ProblemDetails?
Nie musisz. Jeśli masz już swój mechanizm, który działa, to go zostaw. ProblemDetails nie ma zamieniać istniejących mechanizmów. Ma dawać uniwersalność i brak konieczności tworzenia własnych rozwiązań.
Jeśli jednak zwracasz jakiś konkretny model, zawsze masz opcję żeby zrobić z niego swój ProblemDetails. Po prostu potraktuj swój model jako rozszerzenie. Wystarczy, że dodasz pola wymagane i będzie git.
Ale powtarzam – jeśli masz już swój działający mechanizm, niczego nie musisz robić. Nie musisz tego implementować na siłę. Jednak w nowych projektach – doradzam używanie ProblemDetails.
ProblemDetails w .NET
Na szczęście .NET ma już ogarnięte ProblemDetails i w zasadzie nie musisz tworzyć własnego mechanizmu. Różnice występują między .NET6 i .NET7. Nie piszę o wcześniejszych wersjach jako że już nie są wspierane. Jeśli utrzymujesz jakieś apki poniżej .NET6, powinieneś zmigrować do nowszej wersji.
Zwracanie problemu
W .NET standardowo możesz zwracać Problem w kontrolerze:
[HttpGet]
public IActionResult ReturnProblem()
{
return Problem();
}
Oczywiście możesz przekazać mu wszystkie pola z modelu standardowego (jako parametry metody Problem). Jeśli tego nie zrobisz, .NET sam je uzupełni domyślnymi wartościami. Z powyższego przykładu uzyskasz taką zwrotkę:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
"title": "An error occurred while processing your request.",
"status": 500,
"traceId": "00-4139aae6364cb68d2235c576689bb359-88964c6328a1d834-00"
}
Zauważ, że:
type odnosi do opisu błędu 500 (bo taki jest domyślnie zwracany przy problemie)
title – to jakaś ogólna domyślna wartość
status – jak pisałem wyżej, zwraca oryginalny kod błędu
traceId – to jest rozszerzenie .NET, które ułatwia szukanie błędów w logach
Piszemy rozszerzenie
Tutaj wszystko sprowadza się do zwrócenia obiektu ProblemDetails zamiast wywołania metody Problem(). Niestety metoda Problem() nie umożliwia dodawania rozszerzeń. Ale nic się nie bój – nie musisz wszystkiego tworzyć sam. Jest dostępna fabryka, którą wykorzystamy. Musisz ją wstrzyknąć do kontrolera, a potem użyć jej, żeby stworzyć instancję ProblemDetails:
public class ProblemController : ControllerBase
{
private readonly ProblemDetailsFactory _problemDetailsFactory;
public ProblemController(ProblemDetailsFactory problemDetailsFactory)
{
_problemDetailsFactory = problemDetailsFactory;
}
[HttpGet]
public IActionResult ReturnProblem()
{
var result = _problemDetailsFactory.CreateProblemDetails(HttpContext);
var extObject = new
{
errorType = "LoginProblem",
systemCode = 10
};
result.Extensions["additionalData"] = extObject;
return Unauthorized(result);
}
}
Wszystko powinno być dość jasne. Tylko zwróć uwagę na jedną rzecz. Właściwość Extensions z klasy ProblemDetails to jest słownik. Zwykły Dictionary<string, object>. Co nam to daje? Kluczem musi być string (to będzie nazwa pola), ale za to wartością może być już cokolwiek. Może być string, liczba jakaś, a nawet cały obiekt – to, co zrobiliśmy tutaj.
Utworzyłem jakiś anonimowy obiekt i dodałem go jako rozszerzenie. W efekcie ten obiekt zostanie zserializowany (domyślnie do JSON).
Oczywiście na koniec musimy zwrócić problem posługując się jedną z metod w stylu BadRequest, NotFound, Unauthorized itd. Ja przykładowo wybrałem Unauthorized, ale pewnie w rzeczywistym projekcie, najchętniej użyjesz BadRequest.
Zwróć uwagę na jedną rzecz. W response będziesz miał kod 401 (bo zwróciliśmy Unauthorized), natomiast w modelu ProblemDetails masz 500 – bo z takim kodem jest tworzony domyślnie ProblemDetails. Oczywiście wypadałoby to ujednolicić, przekazując do fabryki odpowiedni kod błędu:
var result = _problemDetailsFactory.CreateProblemDetails(HttpContext, statusCode: (int)HttpStatusCode.Unauthorized);
Zobacz też, że nigdzie nie musisz podawać właściwości type. I super! .NET sam ma wszystko ładnie zmapowane do strony https://tools.ietf.org/html/rfc7231, na której są już opisane wszystkie błędy.
Właściwość type jest uzupełniana na podstawie przekazanego statusCode. Oczywiście, jeśli potrzebujesz, możesz dać swoje type w parametrze metody Problem() lub fabryki.
Obsługa błędów
Cały mechanizm umożliwia też elegancką obsługę błędów. Jeśli gdziekolwiek zostanie rzucony nieprzechwycony wyjątek, standardowe działanie jest takie, że zwracany jest błąd 500. Natomiast mechanizm ProblemDetails w .NET tworzy odpowiedź z użyciem tego standardu. Niestety… dopiero w .NET7. Tu jest ta różnica. W .NET7 jest to dostępne na „dzień dobry”, natomiast w .NET6 trzeba sobie samemu to dopisać. Chociaż istnieje NuGet Hellang.Middleware.ProblemDetails którego możesz użyć we wcześniejszych wersjach. Ja go nie używałem, więc tylko daję Ci znać, że jest.
Wyjątki i ProblemDetails w .NET6
W .NET6 musisz do tego napisać własny mechanizm (lub posłużyć się wspomnianym Nugetem). Możesz np. napisać middleware, który Ci to ogarnie. Taki middleware w najprostszej postaci mógłby wyglądać tak:
public class ProblemDetailsMiddleware : IMiddleware
{
public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
try
{
await next(context);
}
catch (Exception ex)
{
await HandleProblemDetails(context, ex);
}
}
private async Task HandleProblemDetails(HttpContext context, Exception ex)
{
var factory = context.RequestServices.GetRequiredService<ProblemDetailsFactory>();
var problem = factory.CreateProblemDetails(context,
title: "Unhandled exception",
detail: ex.GetType().ToString());
problem.Extensions["message"] = ex.Message;
if (IsDevelopement(context))
problem.Extensions["stackTrace"] = ex.StackTrace;
context.Response.StatusCode = problem.Status.Value;
await context.Response.WriteAsJsonAsync(problem, null, "application/problem+json");
}
private bool IsDevelopement(HttpContext context)
{
var hostEnv = context.RequestServices.GetRequiredService<IWebHostEnvironment>();
return hostEnv.IsDevelopment();
}
}
Jak widzisz, po prostu zapisuję problem do odpowiedzi. Sprawdzam też środowisko. Jeśli jest deweloperskie, to nie waham się pokazać stack trace 🙂 W innym przypadku – ze względów bezpieczeństwa lepiej tego nie robić. W takim przypadku musisz też uważać na to, jakie komunikaty dajesz, gdy rzucasz jakiś wyjątek – nie mogą być drogowskazem dla hackerów. Pisałem o tej „podatności” w książce „Zabezpieczanie aplikacji internetowych w .NET – podstawy„.
To jest najprostszy możliwy middleware. Dobrze byłoby również zalogować taki błąd.
Oczywiście musisz pamiętać o dodaniu tego middleware do pipeline:
builder.Services.AddScoped<ProblemDetailsMiddleware>();
var app = builder.Build();
app.UseMiddleware<ProblemDetailsMiddleware>();
Pamiętaj, że middleware’y obsługujące wyjątki powinny być uruchamiane jak najwcześniej w pipeline.
Wyjątki i ProblemDetails w .NET7
Jak już pisałem, w .NET7 to masz „out-of-the-box”. Wystarczy zrobić dwie rzeczy. Podczas rejestracji serwisów dodaj serwisy od ProblemDetails:
builder.Services.AddProblemDetails();
A przy konfiguracji middleware pipeline włóż obsługę wyjątków:
app.UseExceptionHandler();
A jeśli byś chciał dodać jakieś swoje rozszerzenie do ProblemDetails przy niezłapanym wyjątku, wystarczy dodać serwisy z odpowiednim przeciążeniem, np:
W tym przykładzie, do każdego ProblemDetails zostanie dołożone moje rozszerzenie; pole „user_logged„, mówiące czy użytkownik jest zalogowany, czy nie. W obiekcie ctx (ProblemDetailsContext) mamy do dyspozycji m.in. HttpContext z żądania. Więc jeśli potrzebujesz jakiś dodatkowych informacji, to proszę bardzo.
Bezpieczeństwo
Pamiętaj, że komunikat błędu może tworzyć jakiś drogowskaz dla hackerów. A tym bardziej cały stack trace. Na szczęście mechanizm ProblemDetails w .NET7 jest bezpieczny. Dopóki nie zrobisz niczego bardzo głupiego, to będzie dobrze. Stack Trace zostanie dołączone do modelu ProblemDetails tylko na środowisku Developerskim. Natomiast na każdym innym nie zobaczysz go. I to dobrze.
Dzięki za przeczytanie artykułu. To tyle jeśli chodzi o podstawy użycia ProblemDetails. Jeśli znalazłeś w artykule jakiś błąd albo czegoś nie rozumiesz, koniecznie daj znać w komentarzu.
W tym artykule przedstawię Ci mechanizm własnego wiązania obiektów, czyli po ludzku „Custom model binding” w .NET.
.NET w standardzie ma sporo wbudowanych binderów, których zadaniem jest po prostu utworzenie jakiegoś konkretnego obiektu na podstawie danych z żądania HTTP. W zasadzie rzadko zdarza się potrzeba napisania własnego bindera, bo te domyślne załatwiają prawie 100% potrzeb. Prawie.
Postaram przedstawić Ci ten cały mechanizm od zupełnego początku. Jeśli szukasz konkretnego rozwiązania przejdź na koniec artykułu.
Do artykułu powstał przykładowy projekt. Możesz go pobrać z GitHuba.
Czym jest binder?
Wyobraź sobie taki kod w kontrolerze:
[Route("api/[controller]")]
[ApiController]
public class UserController : ControllerBase
{
[HttpGet("{id}")]
public IActionResult GetById(int id)
{
}
}
Tutaj dzieje się dość sporo magii. Jak zapewne wiesz, żądanie HTTP to nic innego jak standaryzowany tekst wysłany z jednego komputera do drugiego.
W tym przypadku takie proste żądanie mogłoby wyglądać tak:
GET /api/user/5 HTTP/1.1
Host: localhost
Już pomijam w jaki sposób z czegoś takiego .NET umie wywołać konkretną metodę z konkretnej klasy. Ale spójrz, że w żądaniu masz ścieżkę /api/user/5. I tę piątkę dostaniesz w parametrze id w swojej metodzie GetById. Cały myk polega na tym, żeby Twoja nazwa parametru w procedurze (int id) była taka sama jak w atrybucie HttpGet ({id}).
Zanim wywołana zostanie metoda GetById, do roboty rusza specjalny binder, który patrzy i widzi:
„Aha, tutaj w atrybucie mam zmienną o nazwie id. W parametrze procedury też mam zmienną o nazwie id. To teraz wezmę sobie wartość z żądania („5”) i skonwertuję to na żądany typ (int) i zwrócę inta o odpowiedniej wartości (5)”.
Być może brzmi to nieco skomplikowanie, ale w rzeczywistości jest banalnie proste, ponieważ sam framework robi już dużo roboty za Ciebie. Spróbujmy napisać coś podobnego.
Binder działa dla konkretnego parametru. Spójrz na taki przykład:
[HttpPost("{id}")]
public IActionResult SaveData(int id, [FromBody]Author authorData)
{
}
Tutaj do pracy ruszą dwa różne bindery. Pierwszy – który powiąże id, drugi który odczyta jsona z ciała żądania i stworzy z niego obiekt Author.
Prosty binder
Opis zadania
Będziemy chcieli przesłać jakiś prosty rekord w żądaniu i po drugiej stronie odebrać to jako obiekt.
Model będzie wyglądał tak:
public class SimplePost
{
public int Id { get; set; }
public string Title { get; set; }
}
A metoda w kontrolerze:
[HttpPost("{post}")]
public IActionResult AddPost(SimplePost post)
{
}
Żądanie, które będzie wysłane to:
POST /api/posts/id:2;title:Tytuł postu
Weź pod uwagę, że to tylko przykład. W rzeczywistości prawdopodobnie przesłałbyś te dane po prostu jsonem. Ale chcę Ci pokazać, jak działa binder.
Zauważ, że tutaj analogicznie jak w pierwszym przykładzie, nazwa zmiennej w atrybucie jest taka sama jak nazwa zmiennej w parametrze metody. Do tej zmiennej dowiążemy te dane.
Wybór bindera
Musisz dać znać frameworkowi, jakiego bindera ma użyć dla konkretnego przypadku. Można to zrobić na dwa sposoby. Swój model możesz opatrzyć atrybutem ModelBinder, np:
[ModelBinder(typeof(SimplePostBinder))]
public class SimplePost
{
public int Id { get; set; }
public string Title { get; set; }
}
albo jeśli nie chcesz lub nie możesz posłużyć się atrybutem ModelBinder, zawsze możesz napisać swojego providera.
Provider dla bindera
UWAGA! SimplePostBinder przedstawiony w tym akapicie, to binder, którego piszemy w następnym akapicie 🙂
public class SimplePostBinderProvider : IModelBinderProvider
{
public IModelBinder GetBinder(ModelBinderProviderContext context)
{
if (context.Metadata.ModelType == typeof(SimplePost))
return new BinderTypeModelBinder(typeof(SimplePostBinder));
else
return null;
}
}
Teraz pewnie zachodzisz w głowę co to do cholery jest BinderTypeModelBinder i dlaczego nie możesz po prostu zrobić new SimplePostBinder().
Otóż możesz. Natomiast BinderTypeModelBinder to jest fabryka dla bindera. Umożliwia wykorzystanie dependency injection. Jeśli chciałbyś zwrócić swój obiekt: new SimplePostBinder, a konstruktor wymagałby różnych serwisów, no to wtedy mamy problem. Na szczęście BinderTypeModelBinder go rozwiązuje i sam się zatroszczy o wstrzyknięcie odpowiednich obiektów.
Na koniec musisz tego providera zarejestrować przy rejestracji kontrolerów:
builder.Services.AddControllers(options =>
{
options.ModelBinderProviders.Insert(0, new SimplePostBinderProvider());
});
UWAGA!
Providerzy są sprawdzani wg kolejności na liście ModelBinderProviders. Jest prawie pewne, że jeśli dodasz swojego providera na końcu (metodą Add), wtedy framework wybierze jakiegoś innego, zarejestrowanego wcześniej, który spełni swój warunek. Dlatego też zawsze dodawaj swojego bindera na początek listy – metodą Insert.
Jeśli otrzymujesz błędy w stylu 415: Unsupported media type lub widzisz że Twój binder nie chodzi, upewnij się w pierwszej kolejności, że dodałeś go na początek listy.
Piszemy bindera
W pierwszym kroku musisz stworzyć klasę, która implementuje interfejs IModelBinder. Interfejs ma tylko jedną metodę do napisania:
public class SimplePostBinder : IModelBinder
{
public Task BindModelAsync(ModelBindingContext bindingContext)
{
}
}
Pierwsza uwaga – pisząc własnego bindera, jak najbardziej możesz posługiwać się dependency injection. Możesz do konstruktora wrzucić sobie to, co potrzebujesz.
Parametr ModelBindingContext to jest klasa abstrakcyjna, której implementacja (DefaultModelBindingContext) daje Ci sporo informacji.
Przede wszystkim musimy pobrać nazwę modelu – czyli parametr z atrybutu HttpPost:
public Task BindModelAsync(ModelBindingContext bindingContext)
{
var paramName = bindingContext.ModelName;
return Task.CompletedTask;
}
BindingContext ma jeszcze jedną podobną właściwość: FieldName – to jest nazwa parametru w Twojej metodzie.
Mając nazwę parametru z atrybutu (pamiętaj – z atrybutu), możemy teraz pobrać jego wartość:
public Task BindModelAsync(ModelBindingContext bindingContext)
{
var paramName = bindingContext.ModelName;
ValueProviderResult value = bindingContext.ValueProvider.GetValue(paramName);
return Task.CompletedTask;
}
ValueProviderResult to w pewnym uproszczeniu tablica stringów. ValueProvider, jeśli zwróci jakąś wartość, to zawsze będą to stringi. I dopiero te stringi możemy konwertować na poszczególne typy.
Tutaj dostaniemy stringa: „id:2;title:Tytuł postu” i teraz musimy go skonwertować na nasz typ. Tu już jest prosto:
public Task BindModelAsync(ModelBindingContext bindingContext)
{
var paramName = bindingContext.ModelName;
ValueProviderResult value = bindingContext.ValueProvider.GetValue(paramName);
if(value == ValueProviderResult.None)
return Task.CompletedTask;
var strValue = value.First();
if(string.IsNullOrWhiteSpace(strValue))
return Task.CompletedTask;
SimplePost result = ConvertFromString(strValue);
bindingContext.Result = ModelBindingResult.Success(result);
return Task.CompletedTask;
}
Najpierw w linijce 6 upewniłem się, że faktycznie otrzymaliśmy jakąś wartość. Potem w linijce 10 upewniłem się, że wartość, którą mamy nie jest pustym stringiem. Na koniec konwertuję tego stringa do obiektu i zwracam za pomocą bindingContext.Result.
Domyślnie bindingContext.Result jest ustawiony na Failed, dlatego ustawiam go tylko, gdy konwersja się powiodła.
Jeśli z ciekawości chciałbyś zobaczyć metodę ConvertFromString, to może wyglądać tak:
W sytuacji, gdzie użytkownik przekazuje dane, wszystko może pójść nie tak. Tak samo w naszym przypadku. Dlatego zawsze warto jest zabezpieczyć się przed problemami.
Jeśli przekażemy złe dane, np.: „idik:2;title:Tytuł postu” – idik zamiast id, nie będziemy w stanie utworzyć obiektu. Po prostu metoda ConvertFromString się wykrzaczy. Najprościej poradzić sobie z tym w taki sposób:
try
{
SimplePost result = ConvertFromString(strValue);
bindingContext.Result = ModelBindingResult.Success(result);
}catch(Exception ex)
{
bindingContext.ModelState.AddModelError(paramName, $"Could not convert from specified data, error: {ex.Message}");
}
return Task.CompletedTask;
W aplikacji webowej np. RazorPages musisz teraz sprawdzić stan modelu w standardowy sposób:
if(!ModelState.IsValid)
return View()
W przypadku WebApi (klasa opatrzona atrybutem ApiController) stan modelu jest sprawdzany automatem przed uruchomieniem metody w kontrolerze. W naszym przykładzie po prostu dostaniesz taką zwrotkę:
400: BadRequest z przykładową zawartością:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-528c9aba1d62ac1e013a1b841d57c8b0-e13ad6c0c13efb6f-00",
"errors": {
"post": [
"Could not convert from specified data, error: The given key 'id' was not present in the dictionary."
]
}
}
Tak samo z automatu zadziała sprawdzenie pól, które mają dodatkowe wymagania np. za pomocą adnotacji. Przykładowo:
[Range(10, 1000)]
public int Id { get; set; }
Piszemy bindera dla Jsona w formularzu
To już właściwie formalność, bo poznałeś już zasadę działania bindera. I w tym punkcie będzie więcej zabawy refleksją niż binderem. Niemniej jednak uczulę Cię na jedną rzecz.
Jeśli chcesz przesłać plik wraz z jakimiś danymi w JSONie, prawdopodobnie chciałbyś mieć analogiczny model:
public class Data
{
public IEnumerable<IFormFile> Files { get; set; }
public Author AuthorData { get; set; }
}
Czyli plik i obiekt w jednej klasie. Da się to zrobić i pokażę Ci jak. Jednak uczulam Cię, że zdecydowanie lepiej jest mieć pliki i dane osobno. Dlaczego? Bo binder do pobierania plików już istnieje w standardzie i wcale nie jest taki oczywisty, jakby się mogło wydawać.
Model generyczny
Stworzymy model generyczny, który będzie mógł mieć dowolny obiekt, który będzie pochodził z JSONa. Model jest banalnie prosty:
[ModelBinder(typeof(FormJsonBinder))]
public class FormJsonData<T>
where T: class, new()
{
public T Model { get; set; }
}
Teraz przyjmiemy model i plik w osobnych parametrach:
public class Author
{
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public DateTimeOffset Birthday { get; set; }
public string Note { get; set; }
}
Jak już wiesz – binder działa na konkretnym parametrze. A więc w tym przypadku pliki z parametru files przyjdą ze standardowego bindera .NET. Więc zajmiemy się tylko FormJsonData.
Z PostMana można by wysłać takie żądanie:
Jak widzisz, wysyłamy formularz, gdzie w polu author mam JSONa z danymi autora, a w polu files mamy pliki. Zwróć uwagę, że te pola nazywają się tak samo jak parametry w naszej procedurze. To ważne, bo tak będziemy to wiązać.
Binder
Teraz napiszemy sobie bindera do tego FormJsonData. Początek już znasz:
public class FormJsonBinder : IModelBinder
{
public Task BindModelAsync(ModelBindingContext bindingContext)
{
var fieldName = bindingContext.FieldName;
var fieldValue = bindingContext.ValueProvider.GetValue(fieldName);
if (fieldValue == ValueProviderResult.None)
return Task.CompletedTask;
return Task.CompletedTask;
}
}
Teraz w fieldValue mamy całego przekazanego JSONa. Musimy stworzyć już tylko odpowiedni obiekt. No właśnie. Ale jaki? FormJsonData jest klasą generyczną. Dlatego musimy się nieco pobawić refleksją. Nie będę tego omawiał, bo to nie jest artykuł na ten temat:
public Task BindModelAsync(ModelBindingContext bindingContext)
{
var fieldName = bindingContext.FieldName;
var fieldValue = bindingContext.ValueProvider.GetValue(fieldName);
if (fieldValue == ValueProviderResult.None)
return Task.CompletedTask;
try
{
Type modelType = GetTypeForModel(bindingContext);
var result = ConvertFromJson(modelType, fieldValue.FirstValue);
bindingContext.Result = ModelBindingResult.Success(result);
}catch(Exception ex)
{
bindingContext.ModelState.AddModelError(fieldName, $"Could not convert from specified data, error: {ex.Message}");
}
return Task.CompletedTask;
}
private Type GetTypeForModel(ModelBindingContext context)
{
Type modelType = context.ModelType;
Type[] genericArgs = modelType.GenericTypeArguments;
if (genericArgs.Length == 0)
throw new InvalidOperationException("Invalid class! Expected generic type!");
return genericArgs[0];
}
private object ConvertFromJson(Type modelType, string jsonData)
{
Type outputType = typeof(FormJsonData<>).MakeGenericType(modelType);
JsonSerializerOptions opt = new JsonSerializerOptions
{
PropertyNameCaseInsensitive = true
};
var model = JsonSerializer.Deserialize(jsonData, modelType, opt);
var result = Activator.CreateInstance(outputType);
var modelProp = outputType.GetProperty("Model");
modelProp.SetValue(result, model);
return result;
}
Dzięki takiemu podejściu moglibyśmy mieć kilka różnych obiektów w jednym formularzu! W różnych polach formularza możesz umieścić różne Jsony i odbierać je w kontrolerze stosując odpowiednie nazwy parametrów.
Pobranie pliku w binderze
Tak naprawdę do pobierania plików w binderze służy… osobny binder. I ma on dużo więcej kodu niż, to co pokazuję Ci niżej:
private async Task GetFormFilesAsync(ModelBindingContext bindingContext,
ICollection<IFormFile> postedFiles)
{
var request = bindingContext.HttpContext.Request;
if (request.HasFormContentType)
{
var form = await request.ReadFormAsync();
foreach (var file in form.Files)
{
if (file.Length == 0 && string.IsNullOrEmpty(file.FileName))
continue;
postedFiles.Add(file);
}
}
}
Ten kod zadziała, ale zwracam uwagę po raz trzeci – binder do pobierania plików robi więcej rzeczy niż tylko to. Dlatego najlepiej pobieraj pliki osobnym parametrem, tak jak zrobiliśmy to wyżej.
Dzięki za przeczytanie tego artykułu. To tyle jeśli chodzi o custom model binding w .NET. Temat dość prosty i przyjemny, ale za to rzadko stosowany 🙂 Jeśli czegoś nie zrozumiałeś lub znalazłeś błąd w artykule, koniecznie daj znać w komentarzu.
W tym artykule pokazuję, jak przesyłać pliki między aplikacjami webowymi. Myślę, że wiedza tutaj zawarta jest kompletna i dużo obszerniejsza niż w innych artykułach. Zobaczysz tutaj kompletne mechanizmy do przesyłania plików pożądane w każdej aplikacji.
UWAGA! Ze względu na prostotę i czytelność, kody przedstawione w tym artykule nie są zbyt czyste. Miej to na uwadze.
Na GitHubie znajdują się przykładowe projekty. W pliku readme.md jest instrukcja, która pokazuje jak je poprawnie uruchamiać.
Jeśli szukasz informacji jak przesłać formularzem plik z danymi w JSON, przeczytaj ten artykuł.
Po stronie HTML posługujemy się zwykłym inputem o typie file. Atrybut accept pozwala ograniczyć typy plików tylko do tych, które chcemy zobaczyć w okienku do wyboru plików.
Ale ważna uwaga – pamiętaj że musisz ustawić atrybut enctype dla formularza na multipart/form-data. W innym przypadku plik po prostu nie przejdzie.
Teraz pytanie, jak odebrać plik po stronie serwera? Służy do tego specjalny interfejs IFormFile. Ten interfejs znajduje się w Nugecie: Microsoft.AspNetCore.Http, więc zainstaluj go najpierw.
Model
Napiszmy teraz klasę, która będzie modelem dla tego formularza i prześle plik wraz z jakimiś innymi danymi:
public class FormData
{
[Required(ErrorMessage = "Musisz wybrać plik")]
public IFormFile? FileToUpload { get; set; }
[Required(ErrorMessage = "Musisz wpisać wiadomość")]
public string? Message { get; set; }
}
Zwróć uwagę, że oba pola są oznaczone jako Required – będą wymagane. I tu mała dygresja.
Wszystkie pola, które nie są oznaczone jako nullable – znakiem zapytania (a nullable używane jest w projekcie) domyślnie są uznane za wymagane. Z tego wynika, że powyższy kod mógłbym zapisać tak:
public class FormData
{
public IFormFile FileToUpload { get; set; }
public string Message { get; set; }
}
Zauważ, że w drugim przykładzie przy typach pól nie ma znaku zapytania, który oznacza pole jako nullable. W tym momencie te pola są domyślnie wymagane. I jeśli któreś z nich nie będzie wypełnione, formularz nie przejdzie walidacji.
Przesyłanie
Jeśli nie wiesz co robią atrybuty Required i jak walidować formularz, koniecznie przeczytaj artykuł Walidacja danych w MVC.
To teraz dodamy ten model do strony i zaktualizujemy formularz:
index.cshtml.cs:
public class IndexModel : PageModel
{
[BindProperty]
public FormData Data { get; set; }
public async Task OnPostAsync()
{
}
}
Jeśli nie wiesz, czym jest atrybut asp-validation-for lub _ValidationScriptsPartial, koniecznie przeczytaj artykuł o walidacji. Krótko mówiąc – jeśli jakiś warunek walidacyjny nie zostanie spełniony (np. [Required]), to w tym spanie pojawi się komunikat błędu.
Pamiętaj też, że _ValidationScriptsPartial musisz umieścić na końcu strony. W przeciwnym razie mechanizm walidacji po stronie klienta może nie zadziałać poprawnie.
Odbieranie danych
Teraz już wystarczy tylko odebrać te dane. Robimy to w metodzie OnPostAsync.
public async Task<IActionResult> OnPostAsync()
{
if (!ModelState.IsValid)
return Page();
EnsureFilesDirExists();
var secureFileName = Path.GetFileName(Data.FileToUpload.FileName);
var filePath = Path.Combine("files", secureFileName);
using var stream = new FileStream(filePath, FileMode.CreateNew);
await Data.FileToUpload.CopyToAsync(stream);
return Page();
}
private void EnsureFilesDirExists()
{
if (!Directory.Exists("files"))
Directory.CreateDirectory("files");
}
Najpierw sprawdzam, czy stan modelu jest prawidłowy – po stronie serwera też musisz o to zadbać.
Następnie tworzę obiekt klasy FileStream, do którego wkopiowuję otrzymany plik. Plik za sprawą tego strumienia ląduje na dysku.
Jeśli przesyłane jest kilka plików, zamiast pojedynczej właściwości IFormFile użyj jakiejś formy kolekcji w swoim modelu, np. IEnumerable<IFormFile>, czy też List<IFormFile>.
Nazwa właściwości w modelu musi być taka sama jak wartość atrybutu name w elemencie input. Oczywiście, jeśli posługujesz się tylko RazorPages i domyślnym bindingiem, to masz to zagwarantowane.
Niebezpieczeństwa
Zapchanie pamięci i atak DoS
UWAGA! Nie używaj MemoryStream do łapania plików po stronie serwera. Pamiętaj, że wszystko co jest w MemoryStream znajduje się w pamięci. Jeśli na Twój serwer przesyłane są pliki, wtedy użycie MemoryStream może doprowadzić do wyczerpania pamięci i BUM! Wszystko wybuchnie. Stworzysz też podatność na atak Denial Of Service.
Dlatego też zawsze w takiej sytuacji używaj FileStream lub lepiej – jeśli masz taką możliwość – przesyłaj plik bezpośrednio na blob storage – o tym za chwilę.
Niebezpieczna nazwa pliku i przejęcie kontroli nad komputerem
Drugim zagrożeniem jest nazwa pliku. Zdziwiony? Nazwa pliku i plik mogą zostać tak spreparowane, żeby dobrać się do danych znajdujących się na serwerze. A nawet przejąć nad nim całkowitą kontrolę. Jeśli posłużysz się gołą nazwą pliku, która przychodzi w IFormFile.FileName stworzysz sobie podatność na atak Path Traversal. Piszę o tym więcej w swojej książce Zabezpieczanie aplikacji internetowych w .NET – podstawy. Jest tam wyjaśniony ten atak wraz z przykładem. A także kilka innych. Polecam zerknąć 🙂
Aby uniknąć podatności, zastosuj po prostu nazwę pliku, którą zwróci Ci Path.GetFileName().
Dobre praktyki
Poza tym, co opisałem wyżej, warto jeszcze sprawdzić rozmiar przesyłanego pliku. Ten rozmiar masz we właściwości IFormFile.Length. Daj jakieś maksimum na wielkość pliku. Jeśli przesłany plik jest za duży, to po prostu zwróć błąd.
Dobrze jest też uruchomić jakiś skaner antywirusowy na przesyłanym pliku, jeśli masz taką możliwość.
No i pamiętaj, żeby zawsze sprawdzać po stronie serwera co do Ciebie przychodzi, bo walidacje po stronie klienta można łatwo obejść.
Jeśli przesyłany plik jest naprawdę duży, to zapisuj go w osobnym tasku. Zwróć odpowiedź do klienta w stylu, że plik jest procesowany i wkrótce się pojawi.
Ochrona przed ponownym przesłaniem
Może się zdarzyć tak, że w przeglądarce ktoś zdąży zupełnym przypadkiem wcisnąć przycisk do wysyłania pliku dwa razy. Można się przed tym uchronić w prosty sposób. Wystarczy zablokować guzik po przesłaniu. Wymaga to jednak nieco JavaScriptu. W standardowym mechanizmie walidacji można to osiągnąć w taki sposób:
Tutaj nadałem ID formularzowi i przyciskowi do wysyłania. Dodatkowo dodałem obsługę zdarzenia onsubmit dla formularza. W tym handlerze najpierw sprawdzam, czy formularz jest poprawnie zwalidowany. Wywołanie form.validate().checkForm() nie powoduje kolejnej walidacji, tylko sprawdza, czy formularz jest zwalidowany. Jeśli nie jest (bo np. nie podałeś wszystkich wymaganych danych), wtedy zwracam false – formularz wtedy nie zostaje przesłany.
W przeciwnym razie blokuję guzik do wysyłania i zwracam true. Nie ma opcji podwójnego wciśnięcia tego przycisku. Taki mechanizm powinieneś stosować w każdym formularzu. Możesz też schować taki formularz i wyświetlić komunikat, że formularz jest wysyłany. Po prostu pokaż zamiast niego jakiegoś diva z taką informacją.
Walidacja rozmiaru pliku
Tak jak pisałem wyżej – warto dać jakiś maksymalny rozmiar pliku. Można to dość łatwo zwalidować zarówno po stronie klienta jak i serwera – wystarczy użyć własnego atrybutu walidacyjnego 🙂 Przede wszystkim muszę Cię odesłać do tego artykułu, w którym opisałem jak tworzyć własne atrybuty walidacyjne.
Nie będę tutaj powtarzał tej wiedzy, więc warto żebyś go przeczytał, jeśli czegoś nie rozumiesz. Tutaj dam Ci gotowe rozwiązanie.
Atrybut może wyglądać tak:
[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field,
AllowMultiple = false)]
public class MaxFileSizeAttribute : ValidationAttribute, IClientModelValidator
{
private readonly int _maxFileSize;
public MaxFileSizeAttribute(int maxFileSize)
{
_maxFileSize = maxFileSize;
}
public override bool IsValid(object value)
{
var file = value as IFormFile;
if (file == null)
return true;
return file.Length <= _maxFileSize;
}
public void AddValidation(ClientModelValidationContext context)
{
if (context == null)
{
throw new ArgumentNullException(nameof(context));
}
MergeAttribute(context.Attributes, "data-val", "true");
MergeAttribute(context.Attributes, "data-val-filesize", ErrorMessageString);
MergeAttribute(context.Attributes, "data-val-filesize-maxsize", _maxFileSize.ToString());
}
private static void MergeAttribute(IDictionary<string, string> attributes, string key, string value)
{
if (!attributes.ContainsKey(key))
{
attributes.Add(key, value);
}
}
}
Dodatkowo trzeba dodać walidację po stronie klienta. Ja robię to w pliku _ValidationScriptsPartial.cs. Cały plik może wyglądać tak:
<script src="~/lib/jquery-validation/dist/jquery.validate.min.js"></script>
<script src="~/lib/jquery-validation-unobtrusive/jquery.validate.unobtrusive.min.js"></script>
<script type="text/javascript">
$.validator.addMethod("filesize", function (value, element, param) {
if (element.type != "file")
return false;
for(let i = 0; i < element.files.length; i++)
if(element.files[i].size > param)
return false;
return true;
});
$.validator.unobtrusive.adapters.addSingleVal("filesize", "maxsize");
</script>
Teraz wystarczy już tylko użyć tego w modelu:
public class FormData
{
[Required(ErrorMessage = "Musisz wybrać plik")]
[MaxFileSize(1024 * 1024, ErrorMessage = "Plik jest za duży, maksymalna wielkość pliku to 1 MB")]
public IFormFile? FileToUpload { get; set; }
[Required(ErrorMessage = "Musisz wpisać wiadomość")]
public string? Message { get; set; }
}
Ważne! Pamiętaj że żeby walidacja działała, model na stronie musi być opatrzony atrybutem BindProperty:
public class IndexModel : PageModel
{
[BindProperty]
public FormData Data { get; set; } = new();
public async Task<IActionResult> OnPostAsync()
{
}
}
Jeśli tego nie będzie, formularz może zadziałać poprawnie i przesłać dane, ale walidacja nie zostanie uruchomiona.
Przesyłanie pliku bezpośrednio na blob storage
BlobStorage jest to usługa Azure’owa do przechowywania plików. Czasem lepiej/łatwiej umieścić pewne pliki właśnie tam niż u siebie na serwerze. To nie jest artykuł o tym, więc nie piszę tutaj więcej w szczególności jak obsługować i tworzyć taki storage. Jeśli wiesz o co chodzi, to ten akapit może Ci się przydać. Jeśli nie – pewnego dnia na pewno to opiszę.
Generalnie wszystko sprowadza się do wywołania odpowiedniego przeciążenia metody UploadBlobAsync z BlobContainerClient:
W takiej sytuacji plik ląduje bezpośrednio na Twoim blob storage.
Przesyłanie pliku w Blazor
Tutaj sprawa wygląda nieco inaczej. Generalnie mamy gotowy komponent do pobrania pliku: InputFile. Co więcej, ten komponent nie musi być częścią formularza. To jednak nieco zmienia sposób podejścia do zadania. Zacznijmy od tego jak w ogóle działa przesyłanie plików w Blazor:
<InputFile OnChange="FileChangeHandler" accept=".jpg" />
@code{
private async Task FileChangeHandler(InputFileChangeEventArgs args)
{
using var stream = args.File.OpenReadStream();
}
}
Po pierwsze mamy komponent InputFile, którego kluczowym zdarzeniem jest OnChange. Trzeba tutaj podać handlera, który dostanie przekazany plik.
Parametr metody posiada pole File (typu IBrowserFile). Znajduje się tam pierwszy dostępny plik. Jeśli pozwoliłeś na dodanie kilku plików, wtedy możesz je odczytać z metody GetMultipleFiles, która zwraca Ci listę IBrowserFile. To wszystko znajduje się w klasie InputFileChangeEventArgs w przesłanym parametrze.
Interfejs IBrowserFile zawiera metodę OpenReadStream, która zwraca strumień z danymi pliku. I teraz uwaga nr 1. OpenReadStream przyjmuje w parametrze maksymalny rozmiar pliku, który może przekazać. Domyślnie ten parametr wskazuje 512 KB. Jeśli plik w strumieniu będzie większy, wtedy metoda wybuchnie wyjątkiem.
UWAGA! Blazor WASM pracuje tylko po stronie klienta – w jego przeglądarce. Nie ma tutaj żadnego serwera. Daje nam to pewne ograniczenie – nie możesz zapisać pobranego pliku – Blazor nie ma dostępu do systemu plików. Dlatego też w przypadku Blazor nie możesz posłużyć się FileStream, jak to było wyżej. Tutaj musisz po prostu przechować plik albo w tablicy bajtów, albo w MemoryStream.
Zobaczmy teraz w jaki sposób można zrobić pobieranie pliku z progress barem.
Przesyłanie pliku z progress barem
<InputFile OnChange="FileChangeHandler" accept=".jpg" />
@if(ReadingFile)
{
<div>
<progress value="@DataRead" max="@FileSize" />
</div>
}
@code{
private long FileSize { get; set; }
private long DataRead { get; set; }
private bool ReadingFile { get; set; } = false;
private async Task FileChangeHandler(InputFileChangeEventArgs args)
{
try
{
FileSize = args.File.Size;
DataRead = 0;
ReadingFile = true;
byte[] buffer = System.Buffers.ArrayPool<byte>.Shared.Rent(1024); //pobranie buforu min. 1024 bajty
using var stream = args.File.OpenReadStream(1024 * 1024); //ograniczenie wielkości pliku do 1 MB
using MemoryStream fileContent = new MemoryStream();
while(await stream.ReadAsync(buffer) is int read && read > 0)
{
DataRead += read;
fileContent.Write(buffer);
StateHasChanged();
}
}finally
{
ReadingFile = false;
}
}
}
Wszystko rozbija się o odczyt pliku w porcjach po 1024 bajty. Kolejne części pliku są zapisywane w strumieniu fileContent. Przy każdym zapisywanym fragmencie aktualizuję ilość odczytanych danych (DataRead), która jest aktualną wartością w progress barze. Aby progress bar się odświeżył, trzeba zawołać StateHasChanged.
Na koniec odczytu cały plik będzie w strumieniu fileContent.
Pokazanie pobranego obrazka
W związku z tym, że Blazor pracuje po stronie klienta, nie możemy pliku zapisać gdzieś i go pokazać. Najprościej zatem pokazać taki obrazek w postaci zakodowanej do Base64. Robi się to w taki sposób, że odczytujemy dane obrazka (np. przekazujemy go do MemoryStream lub tablicy bajtów), następnie zamieniamy na Base64, a na koniec do tagu IMG przekazujemy ten obrazek w takiej postaci:
<img src="data:image/jpeg;base64,==data==" />
Ten tajemniczy ciąg w atrybucie src możemy rozbić na poszczególne elementy:
data:image/jpeg;base64,==data==
data – to określenie, że obrazek będzie w formie danych, a nie ścieżki do pliku
image/jpeg – to określenie typu tych danych
base64 – format danych i dane
Zwróć uwagę na różne separatory konkretnych elementów – po data jest dwukropek, po content-type jest średnik, a po base64 jest przecinek. Jasne, prawda? 🙂 Jeśli nie widzisz faktycznego obrazka tylko ikonkę zastępczą, sprawdź te separatory w pierwszej kolejności.
Zwróć uwagę, że content type przekazywanego pliku wziąłem z parametru InputFileChangeEventArgs. Mógłbym go wpisać na sztywno, ale wtedy byłby problem jeśli użytkownik wybrałby inny typ pliku. Png, svg, czy chociażby bmp.
Walidacja pliku po stronie klienta
W związku z tym, że plik nie musi być w Blazor częścią formularza i tak naprawdę nie ma żadnej walidacji, musimy posłużyć się małym mykiem.
Tak jak w kodzie powyżej, odczytamy plik do jakiejś zmiennej i będziemy walidować tę zmienną. To oznacza, że trzeba zmienić model widoku dla Blazor:
public class FormDataViewModel
{
[Required(AllowEmptyStrings = false, ErrorMessage = "Wybierz plik")]
[MinLength(1, ErrorMessage = "Plik nie może być pusty")]
[MaxLength(1024 * 1024, ErrorMessage = "Plik jest za duży")]
public byte[]? FileContent { get; set; }
[Required(ErrorMessage = "Musisz wpisać wiadomość")]
public string? Message { get; set; }
}
I zasadniczo taka walidacja jest prawie dobra. Problem w tym, że jeśli przekażemy zbyt duży plik, to nie będzie o tym informacji. Dlaczego? Przypomnij sobie, jak odczytujemy plik:
var stream = args.File.OpenReadStream(1024 * 1024);
Jeśli będzie większy niż 1MB, to wtedy OpenReadStream rzuci wyjątek. Dlatego też powinniśmy sprawdzić w tym miejscu, czy plik nie jest za duży.
Zgłoszenie błędu można zrobić na kilka sposobów. Najprostszym z nich jest po prostu pokazanie jakiegoś spana przy InputFile z odpowiednim tekstem. Np.:
To jest najprostsze rozwiązanie, które pewnie sprawdzi się w większości przypadków. Jednak można to też zrobić inaczej, za pomocą ValidationMessage. Wymaga to jednak zmiany sposobu walidacji formularza i wykracza poza ramy tego artykułu. Obiecuję, że napiszę osobny artykuł o dodatkowej walidacji w Blazor.
Przesyłanie pliku na serwer do WebApi
Skoro mamy już fajny przykład w Blazorze, wykorzystamy go do przesłania pliku do WebApi. A właściwie całego modelu. Pokażę Ci jak przesłać dane wraz z plikiem.
Przede wszystkim musisz pamiętać, że tak jak w przypadku MVC / Razor Pages, plik jest wysyłany formularzem. Zasadniczo – przesyłanie pliku na serwer zawsze sprowadza się do umieszczenia go w formularzu i wysłaniu tego formularza.
Odczyt po stronie Api
Na początek stwórzmy projekt WebApi. Następnie dodajmy model, który będzie wyglądał tak:
public class WebApiFormData
{
public IFormFile File { get; set; }
public string Message { get; set; }
}
Zwróć uwagę na starego znajomego – IFormFile.
Teraz najlepsze, jedyne co musimy zrobić w kontrolerze w WebApi to:
[Route("api/[controller]")]
[ApiController]
public class FormController : ControllerBase
{
[HttpPost]
public IActionResult PostHandler([FromForm]WebApiFormData data)
{
if (!ModelState.IsValid)
return BadRequest();
return Ok();
}
}
I to wystarczy, żeby WebApi odpowiednio odebrało dane! Po tej stronie już niczego nie musimy robić. Czy to nie jest piękne?
UWAGA! Jeśli podczas wysyłania danych do WebApi otrzymujesz błąd 415 (Unsupported Media Type) sprawdź, czy na pewno pobierasz w WebApi dane z formularza – atrybut FromForm.
Wysyłanie do API
Rejestracja HttpClientFactory
Teraz musimy te dane wysłać formularzem za pomocą HttpClient. Zrobimy to z aplikacji Blazor, która była tworzona wyżej w tym artykule. Zacznijmy od rejestracji fabryki dla HttpClient przy rejestracji serwisów:
builder.Services.AddHttpClient("api", client =>
{
client.BaseAddress = new Uri("https://localhost:7144/");
});
Tego klienta pobierzemy sobie w metodzie, która jest wywoływana po poprawnym przesłaniu formularza w Blazor:
[Inject]
public IHttpClientFactory HttpClientFactory { get; set; }
private async Task ValidSumbitHandler(EditContext ctx)
{
var client = HttpClientFactory.CreateClient("api");
}
Teraz musimy utworzyć całe ciało wiadomości, którą będziemy wysyłać. Będzie to formularz złożony z części.
Każda część to tzw. content. C# daje nam różne takie klasy jak np. StreamContent, do którego możemy wrzucić strumień, ByteArrayContent, do którego możemy podać tablicę, StringContent, do którego wrzucamy stringa.
I tutaj uwaga. Pojedyncze żądanie może mieć tylko jeden content. Ale jest specjalny typ – MultipartFormDataContent, który składa się z innych contentów. Ostatecznie wszystko jest przesyłane oczywiście jako strumień bajtów. A skąd wiadomo gdzie kończy się jedna zawartość a zaczyna druga?
Istnieje coś takiego jak Boundary. Jest to string, który oddziela poszczególne części między sobą. Jest ustawiany automatycznie, ale sam też go możesz podać. Pamiętaj tylko, że taki string powinien być unikalny.
Najpierw stwórzmy i dodajmy zawartość pliku. Posłużymy się tutaj ByteArrayContent, ponieważ trzymamy plik w tablicy bajtów:
var request = new HttpRequestMessage(HttpMethod.Post, "api/form");
var form = new MultipartFormDataContent();
var fileContent = new ByteArrayContent(Data.FileContent);
form.Add(fileContent, nameof(WebApiFormData.File), "uploaded.jpg");
Na początku utworzyłem HttpRequestMessage, który ostatecznie zostanie wysłany. To on będzie miał zawarty w sobie formularz.
Potem tworzę formularz, do którego będą dodawane poszczególne zawartości.
I tak tworzymy fileContent z zawartością pliku, który został odczytany. Podczas dodawania tego contentu (form.Add) ważne jest wszystko – nazwa tego contentu – file – taka sama jak w modelu, który będzie przyjmowany przez WebApi. No i nazwa pliku – „uploaded.jpg”. Nazwa pliku musi być dodana w przypadku przesyłania pliku. Tak naprawdę powinieneś dodać prawdziwe rozszerzenie. Ja tylko z czystego lenistwa i prostoty wpisałem na sztywno „jpg”. Pamiętaj, żeby dodawać faktyczne rozszerzenie.
To teraz zajmiemy się pozostałymi właściwościami:
var msgContent = new StringContent(Data.Message, new MediaTypeHeaderValue("text/plain"));
form.Add(msgContent, nameof(WebApiFormData.Message));
Tutaj wszystko wygląda analogicznie, z tym że posługuję się StringContent zamiast ByteArrayContent.
I tutaj istotna uwaga. Zawsze dobrze jest podać media-type dla stringa, który przesyłasz. Może to być czysty tekst (text/plain), może to być string z json’em (application/json), cokolwiek. Może być też tak, że WebApi nie chce mieć przekazanego żadnego mime-type albo wręcz przeciwnie – jakiś konkretny. W takim przypadku zastosuj to, co jest napisane w dokumentacji konkretnego WebApi.
Teraz można już dodać nasz formularz do żądania i wysłać je:
Często trzeba przesłać większą ilość danych wraz z plikiem. Napisałem osobny artykuł o tym jak przesłać dane w JSON razem z plikiem. Zachęcam do przeczytania, bo mówię też tam o mechanizmie bindingu.
Dzięki za przeczytanie tego artykułu. Mam nadzieję, że wszystko jest jasne. Jeśli jednak znalazłeś jakiś błąd lub czegoś nie rozumiesz, koniecznie daj znać w komentarzu.
Pewnie nie raz spotkałeś się z sytuacją, gdzie próba wywołania API z Blazor albo JavaScript zakończyła się radosnym błędem
XMLHttpRequest cannot load http://…. No ‘Access-Control-Allow-Origin’ header is present on the requested resource. Origin ‘http://…’ is therefore not allowed access.
Czym jest CORS, dlaczego jest potrzebne i jak się z nim zaprzyjaźnić? O tym dzisiaj.
Co to CORS
Cross Origin Request Sharing to mechanizm bezpieczeństwa wspierający politykę same-origin. Same-origin polega na tym, że JavaScript z jednej domeny (a konkretnie origin) nie może komunikować się z serwerem z innej domeny (origin).
Innymi słowy, jeśli masz stronę pod adresem: https://example.com i chciałbyś z niej wywołać za pomocą JavaScript coś ze strony https://mysite.com, to musisz mieć na to specjalne pozwolenie wydane przez mysite.com.
Czyli jeśli u siebie lokalnie z końcówki https://localhost:3000 będziesz chciał zawołać jakieś API z końcówki: https://localhost:5001, to też się to nie uda bez specjalnego pozwolenia. Tym wszystkim zarządza przeglądarka.
Czym jest ORIGIN
Już wiemy, że żeby nie było problemów, obydwie strony żądania muszą należeć do tego samego originu. Czym jest zatem origin?
To połączenie: protocol + host + port, czyli np:
https://example.com i https://example.com:443 – należą do tego samego originu. Pomimo, że w pierwszym przypadku nie podaliśmy jawnie portu, to jednak protokół https domyślnie działa na porcie 443. A więc został tam dodany niejawnie.
http://example.com i https://example.com – nie należą już do tego samego originu. Różnią się protokołem i portem (przypominam, że https działa domyślnie na porcie 443, a http na 80).
https://example.com:5000 i https://example.com:5001 – też nie należą do tego samego originiu, ponieważ różnią się portem.
https://api.example.com i https://example.com – też nie należą do tego samego originu, bo różnią się hostem. Zasadniczo origin definiuje aplikację internetową.
Polityka same-origin
Jak już pisałem wcześniej, polityka same-origin zakazuje jednej aplikacji korzystać z elementów innej aplikacji. Skryptów js, arkuszy css i innych… Ale…
No, ale jak to? A CDN? A linkowanie bootstrapa itd?
No właśnie. Przede wszystkim przeglądarki nie są zbyt rygorystyczne pod tym względem. Głównie ze względu na kompatybilność wsteczną. Pół Internetu przestałoby działać. Jednak to „rozluźnienie” niesie za sobą pewne zagrożenia. Np. może dawać podatność na atak XSS lub CSRF (pisałem o Cross Site Request Forgery w książce o podstawach zabezpieczania aplikacji internetowych).
Wyjątki polityki same-origin
Skoro przeglądarki niezbyt rygorystycznie podchodzą do polityki same-origin, to znaczy że są pewne luźniejsze jej elementy. Oczywiście, że tak. Przeglądarki pozwalają ogólnie na:
zamieszczanie obrazków z innych originów
wysyłanie formularzy do innych originów
zamieszczanie skryptów z innych originów – choć tutaj są już pewne ograniczenia
Na co same-origin nie pozwoli
Przede wszystkim nie pozwoli Ci na dostęp do innych originów w nowych technologiach takich jak chociażby AJAX. Czyli strzały HTTP za pomocą JavaScriptu. Co to oznacza? Zacznijmy od najmniejszego problemu – jeśli piszesz aplikację typu SPA w JavaScript lub Blazor, to chcesz się odwoływać do jakiegoś API. W momencie tworzenia aplikacji prawdopodobnie serwer stoi na innym originie niż front. Na produkcji może być podobnie. W takiej sytuacji bez obsługi CORS po stronie serwera, nie połączysz się z API.
Idąc dalej, jeśli chcesz na swojej stronie udostępnić dane pobierane z innego źródła – np. pobierasz AJAXem kursy walut – to też może nie zadziałać. W prawdzie użyłem tych kursów walut jako być może nieszczęśliwy przykład. Jeśli to działa to tylko ze względu na luźną politykę CORS. W przeciwnym razie musiałbyś się kontaktować z dostawcą danych, żeby pozwolił Ci na ich pobieranie. I tak też często się dzieje. I on może to zrobić właśnie dzięki CORS.
Więc jak działa ten CORS?
Pobierz sobie przykładową solucję, którą przygotowałem na GitHub. Jest kam kilka projektów:
WebApiWithoutCors – api, które w żaden sposób nie reaguje na CORS – domyślnie uniemożliwi wszystko
WebApiWithCors – api z obsługą CORS
ClientApiConfig – podstawowy klient, który chciałby pobrać dane i zrobić POST
DeletableClient – klient, któremu polityka CORS pozwala jedynie na zrobienie DELETE
BadClient – klient, któremu żadne API na nic nie pozwala
Każdy projekt pracuje w HTTP (nie ma SSL/TLS) specjalnie, żeby umożliwić w łatwy sposób podsłuchiwanie pakietów w snifferze.
Przede wszystkim działanie CORS (Cross Origin Request Sharing) jest domeną przeglądarki. Jeśli uruchomisz teraz przykładowe projekty: ClientApp (aplikacja SPA pisana w Blazor) i WebApiWithoutCors i wciśniesz guzik Pobierz dane, to zobaczysz taki komunikat:
A teraz wywołaj tę samą końcówkę z PostMan, to zobaczysz że dane zostały pobrane:
Co więcej, jeśli posłużysz się snifferem, np. WireShark, zobaczysz że te dane do przeglądarki przyszły:
To znaczy, że to ta małpa przeglądarka Ci ich nie dała. Co więcej, wywaliła się wyjątkiem HttpRequestException przy pobieraniu danych:
var client = HttpClientFactory.CreateClient("api");
try
{
var response = await client.GetAsync("weatherforecast");
if (!response.IsSuccessStatusCode)
ErrorMsg = $"Nie można było pobrać danych, błąd: {response.StatusCode}";
else
{
var data = await response.Content.ReadAsStringAsync();
WeatherData = new(JsonSerializer.Deserialize<WeatherForecast[]>(data));
}
}catch(HttpRequestException ex)
{
ErrorMsg = $"Nie można było pobrać danych, błąd: {ex.Message}";
}
Co z tą przeglądarką nie tak?
Przeglądarka odebrała odpowiedź z serwera, ale Ci jej nie pokazała. Dlaczego? Ponieważ nie dostała z serwera odpowiedniej informacji. A konkretnie nagłówka Access-Control-Allow-Origin, o czym informuje w konsoli:
XMLHttpRequest cannot load http://.... No ‘Access-Control-Allow-Origin’ header is present on the requested resource. Origin ‘http://...’ is therefore not allowed access.
To poniekąd serwer zdecydował, że nie chce klientowi danych pokazywać. A dokładniej – serwer nie zrobił niczego, żeby te dane pokazać. Po prostu na dzień dobry obsługa CORS na serwerze jest wyłączona. Można powiedzieć, że jest zaimplementowana jedynie w przeglądarce.
Niemniej jednak przeglądarka wysłała do serwera zapytanie GET, które odpowiednie dane pobrało i zwróciło. Czyli jakaś operacja na serwerze się wykonała. Pamiętaj, że zapytanie GET nie powinno mieć żadnych skutków ubocznych. Czyli nie powinno zmieniać żadnych danych. Powinno dane jedynie pobierać. A więc teoretycznie nic złego nie może się stać.
A gdyby tak przeglądarka wysłała POST? Zadziała czy nie? No właśnie nie w każdej sytuacji.
Jeśli teraz w przykładowej aplikacji uruchomisz narzędzia dewelopera (Shift + Ctrl + i) i wciśniesz guzik Wywołaj POST, to zobaczysz coś takiego:
Zanim przeglądarka wyśle to żądanie, najpierw wykona specjalne zapytanie, tzw. preflight. Czyli niejako zapyta się serwera: „Hej serwer, jestem z takiego originu i chciałbym wysłać do Ciebie POST z takimi nagłówkami. Mogę?”
To specjalne żądanie wysyłane jest na adres, na który chcesz rzucić POSTem. Z tym że tutaj metodą jest OPTIONS. Poza tym w nagłówkach są zaszyte informacje:
Access-Control-Request-Headers – lista nagłówków z jakimi chcesz wysłać POST
Access-Control-Request-Method – metoda, jaką chcesz wywołać (POST, DELETE itd)
Origin – origin, z którego żądanie będzie wysłane
Możesz to podejrzeć zarówno w narzędziach dewelopera jak i w Wireshark:
A co zrobił serwer? Zwrócił błąd: 405 - Method not allowed. Co znaczy, że pod takim endpointem serwer nie obsługuje zapytań typu OPTIONS. Co dla przeglądarki daje jasny komunikat: „Nie wysyłaj mi tego, nie obsługuję CORS”. Przeglądarka więc zaniecha i nie wyśle takiego zapytania.
Wyjątkowe formularze
Jak już pisałem wcześniej, formularze są pewnym wyjątkiem. Przeglądarka i tak je wyśle. To kwestia kompatybilności wstecznej. Jeśli będziesz chciał wysłać metodę POST z Content-Type ustawionym na multipart/form-data, to takie zapytanie zostanie wykonane bez żadnego preflight'u. Takich wyjątków jest więcej i są bardzo dobrze opisane na stronie Sekuraka, więc nie będę tego powielał. Jeśli masz ochotę zgłębić temat, to polecam.
Obsługa CORS w .NET
Skoro już wiesz z grubsza czym jest CORS i, że to serwer ostatecznie musi dać jawnie znać, że zgadza się na konkretne zapytanie, to teraz zaimplementujmy ten mechanizm po jego stronie. Spójrz na projekt WebApiWithCors z załączonej solucji.
Jeśli pracujesz na .NET < 6, to pewnie będziesz musiał dorzucić Nugeta: Microsoft.AspNetCore.Cors.
Przede wszystkim musisz dodać serwisy obsługujące CORS podczas rejestracji serwisów:
builder.Services.AddCors();
a także wpiąć obsługę CORS w middleware pipeline. Jeśli nie wiesz, czym jest middleware pipeline, przeczytaj ten artykuł.
Pamiętaj, że UseCors musi zostać wpięte po UseRouting, ale przed UseAuthorization.
Takie dodanie jednak niczego nie załatwi. CORS do odpowiedniego funkcjonowania potrzebuje polityki. I musimy mu tę politykę ustawić.
Polityka CORS
CORS Policy mówi jakich dokładnie klientów i żądania możesz obsłużyć. Składa się z trzech części:
origin – obsługuj klientów z tych originów
method – obsługuj takie metody (POST, GET, DELETE itd…)
header – obsługuj takie nagłówki
To znaczy, że klient aby się dobić do serwera musi spełnić wszystkie trzy warunki – pochodzić ze wskazanego originu, wywołać wskazaną metodę i posiadać wskazany nagłówek.
Wyjątkiem jest tu POST. Co wynika z wyjątkowości formularzy. Jeśli będziesz chciał wysłać POST, przeglądarka zapyta się o to jedynie w przypadku, gdy Content-Type jest odpowiedni (np. nie wskazuje na formularz). Co to dalej oznacza? Jeśli stworzysz na serwerze politykę, która nie dopuszcza POST, ale dopuszcza wszystkie nagłówki (AllowAnyHeader), to ten POST i tak zostanie wysłany. Kwestia kompatybilności wstecznej.
Ona zezwala na połączenia z dowolnego originu, wykonanie dowolnej metody z dowolnymi nagłówkami. Czy to dobrze? To zależy od projektu.
Co więcej, metoda AddDefaultPolicy doda domyślną politykę. Wpięty w pipeline UseCors będzie używał tej domyślnej polityki do sprawdzenia, czy żądanie od klienta może pójść dalej.
Za pomocą metody AddPolicy możesz dodać politykę z jakąś nazwą. Tylko wtedy do UseCors musisz przekazać w parametrze nazwę polityki, której chcesz używać domyślnie. UseCors wywołany bez parametrów będzie używał polityki dodanej przez AddDefaultPolicy. Jeśli jej nie dodasz, wtedy CORS nie będzie obsługiwany.
Konkretna polityka
Oczywiście możesz w polityce wskazać konkretne wartości, np.:
To spowoduje, że polityka dopuści strzały tylko z originu http://localhost:5001 z jakąkolwiek metodą i dozwolonym nagłówkiem X-API-KEY.
I tutaj dwie uwagi. Po pierwsze – pamiętaj, żeby originu nie kończyć slashem: / . Jeśli tak wpiszesz http://localhost:5001/, wtedy origin się nie zgodzi i mechanizm CORS nie dopuści połączeń. Czyli – brak slasha na końcu originu. Idąc dalej, nie podawaj pełnych adresów w stylu: https://localhost:5001/myapp – to nie jest origin.
A teraz pytanie za milion punktów. Co się stanie, gdy mając taką politykę z poprawnego originu wywołasz:
var data = new WeatherForecast
{
Date = DateTime.Now,
Summary = "Cold",
TemperatureC = 5
};
var client = HttpClientFactory.CreateClient("api");
client.DefaultRequestHeaders.Add("X-API-KEY", "abc");
var response = await client.PostAsJsonAsync("weatherforecast", data);
Dodałeś nagłówek X-API-KEY do żądania i wysyłasz JSONa za pomocą post (dowolna metoda).
Zadziała?
Przemyśl to.
Jeśli powiedziałeś „nie”, to zgadza się. Gratulacje 🙂 A teraz pytanie dlaczego to nie zadziała. Spójrz jaki przeglądarka wysyła preflight:
O co pyta przeglądarka w tym żądaniu?
„Hej serwer, czy mogę ci wysłać POST z nagłówkami contenty-type i x-api-key? A co odpowiada serwer?
„Ja się mogę zgodzić co najwyżej na metodę POST i nagłówek X-API-KEY„.
Przeglądarka teraz patrzy na swoje żądanie i mówi: „Ojoj, to nie mogę ci wysłać content-type. Więc nie wysyłam”. To teraz pytanie skąd się wzięło to content type? Spójrz jeszcze raz na kod:
var response = await client.PostAsJsonAsync("weatherforecast", data);
Wysyłasz JSONa. A to znaczy, że gdzieś w metodzie PostAsJsonAsync został dodany nagłówek: Content-Type=application/json. Ponieważ w zawartości żądania (content) masz json (czyli typ application/json).
Uważaj na takie rzeczy, bo mogą doprowadzić do problemów, z którymi będziesz walczył przez kilka godzin. Ale w tym wypadku już powinieneś wiedzieć, jak zaktualizować politykę CORS:
Jeśli wydaje Ci się, że CORS powinien zadziałać, a nie działa, w pierwszej kolejności zawsze zobacz jaki preflight jest wysyłany, jakie nagłówki idą w żądaniu i czy są zgodne z polityką.
Pamiętaj też, że w żądaniu nie muszą znaleźć się wszystkie nagłówki. Jeśli nie będzie w tej sytuacji X-API-KEY nic złego się nie stanie. Analogicznie jak przy polityce dotyczącej metod. Możesz wysłać albo GET, albo POST, albo DELETE… Nie możesz wysłać kilku metod jednocześnie, prawda? 🙂
CORS tylko dla jednego endpointu
Corsy możesz włączyć tylko dla konkretnych endpointów. Możesz to zrobić za pomocą atrybutów. I to na dwa sposoby. Jeśli chcesz umożliwić większość operacji, możesz niektóre endpointy wyłączyć spod opieki CORS. Spójrz na kod kontrolera:
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
[HttpPost]
[DisableCors]
public IActionResult PostTest([FromBody]WeatherForecast data)
{
return Ok();
}
Atrybut DisableCors spowoduje, że mechanizm CORSów uniemożliwi wywołanie tej końcówki. Jeśli przeglądarka użyje preflight, wtedy serwer odpowie, ale nie pozwalając na nic.
Kilka polityk CORS
Skoro można zablokować CORS na pewnych końcówkach, to pewnie można też odblokować na innych. No i tak. Zgadza się. Zróbmy sobie takie dwie polityki:
Zwróć uwagę na to, że nie dodajemy teraz żadnej domyślnej polityki (AddDefaultPolicy), tylko dwie, które jakoś nazwaliśmy. Teraz każdy endpoint może mieć swoją własną politykę:
[HttpGet]
[EnableCors("get-policy")]
public IEnumerable<WeatherForecast> Get()
{
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = Random.Shared.Next(-20, 55),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray();
}
[HttpPost]
[EnableCors("set-policy")]
public IActionResult PostTest([FromBody]WeatherForecast data)
{
return Ok();
}
Każdy endpoint dostał swoją własną politykę za pomocą atrybutu EnableCors. Jako parametr przekazujemy nazwę polityki. Jeśli w takim przypadku nie podasz atrybutu EnableCors, to końcówka będzie zablokowana. Dlaczego? Spójrz na middleware:
app.UseCors();
Taki middleware po prostu będzie chciał użyć domyślnej polityki (AddDefaultPolicy), której jednak nie ma. Dlatego też zablokuje wszystko. Oczywiście możesz w tym momencie podać konkretną politykę, jaka ma być używana przez middleware:
app.UseCors("get-policy");
Wtedy każdy endpoint bez atrybutu [EnableCors] będzie używał tej polityki.
Dynamiczna polityka CORS
Czasem możesz potrzebować bardziej płynnej polityki, która może zależeć od konkretnego originu. Możesz chcieć wpuszczać tylko te originy, które są zarejestrowane w bazie albo dla różnych originów mieć różne polityki.
Wtedy sam musisz zadbać o to, żeby mechanizm CORS dostał odpowiednią politykę. Na szczęście w .NET6 jest to banalnie proste. Wystarczy zaimplementować interfejs ICorsPolicyProvider, np. w taki sposób:
public class OriginCorsPolicyProvider : ICorsPolicyProvider
{
private readonly CorsOptions _corsOptions;
public OriginCorsPolicyProvider(IOptions<CorsOptions> corsOptions)
{
_corsOptions = corsOptions.Value;
}
public Task<CorsPolicy?> GetPolicyAsync(HttpContext context, string? policyName)
{
var origin = context.Request.Headers.Origin;
var policy = _corsOptions.GetPolicy(origin);
if (policy == null)
policy = _corsOptions.GetPolicy(policyName ?? _corsOptions.DefaultPolicyName);
return Task.FromResult(policy);
}
}
Interfejs wymaga tylko jednej metody – GetPolicyAsync. Najpierw jednak zobacz w jaki sposób zarejestrowałem odpowiednie polityki podczas rejestracji serwisów CORS:
Nazwa polityki to po prostu origin, dla którego ta polityka jest utworzona. A teraz wróćmy do providera. Spójrz najpierw na metodę GetPolicyAsync.
Najpierw pobieram origin z requestu, następnie pobieram odpowiednią politykę. Metoda GetPolicy z obiektu _corsOptions zwraca politykę po nazwie. Te polityki są tam dodawane przez setup.AddPolicy. Gdzieś tam pod spodem są tworzone jako dodatkowe opcje, co widzisz w konstruktorze – w taki sposób możesz pobrać zarejestrowane polityki.
Oczywiście nic nie stoi na przeszkodzie, żebyś w swoim providerze połączył się z bazą danych i na podstawie jakiś wpisów sam utworzył odpowiednią politykę dynamicznie i ją zwrócił.
Teraz jeszcze tylko musimy zarejestrować tego providera:
Słowem zakończenia, pamiętaj żeby nie podawać w middleware kilka razy UseCors, bo to nie ma sensu. Pierwszy UseCors albo przepuści żądanie dalej w middleware albo je sterminuje.
To tyle jeśli chodzi o CORSy. Dzięki za przeczytanie artykułu. Mam nadzieję, że teraz będziesz się poruszał po tym świecie z większą pewnością. Jeśli znalazłeś błąd w artykule albo czegoś nie rozumiesz, koniecznie daj znać w komentarzu.
W poprzednim artykule pokazałem jak tworzyć klasyczny szablon projektów dla Visual Studio. Natomiast z tego artykułu dowiesz się jak stworzyć szablon dla dotnet new. Taki szablon możesz zaimportować na każdym komputerze i systemie, w którym zainstalowany jest dotnet.
Klasyczne szablony (dla Visual Studio) są obsługiwane tylko przez VisualStudio dla Windows. Natomiast te nowe dla „dotnet new” już nie mają tego ograniczenia. Ponadto pozwalają duuużo prościej zrobić bardziej skomplikowane rzeczy. Minus? Nie da się tego wyklikać…jeszcze…
Pamiętaj, że ten artykuł to nie jest kompletny podręcznik szablonów. O nie! To jest dość duży temat. Artykuł pokazuje jak zacząć i jak zrobić coś trudniejszego niż „hello world”. Na koniec jednak daję Ci kilka linków, które uzupełniają artykuł. Jeśli czegoś tutaj nie znajdziesz, być może znajdziesz w oficjalnej dokumentacji (podlinkowanej na końcu).
Z czego składa się szablon
Są dwie rzeczy:
struktura projektu – wrzucasz tutaj dowolną zawartość (pliki, foldery, inne projekty), która ma się znaleźć na dzień dobry w projekcie wynikowym – od tego zaczynasz, po prostu stwórz nowy projekt, który będzie wyjściowym projektem dla Twojego szablonu
plik konfiguracyjny template.json – opisuje parametry szablonu
opcjonalne pliki np. do obsługi Wizarda, czy też ikonka
W przeciwieństwie do klasycznych szablonów pod VisualStudio, nie musisz stosować specjalnych tokenów w formie parametrów w swoich projektach. Nie ma też problemu z kompilowaniem ich – właśnie ze względu na brak tych tokenów.
Musisz jednak zapewnić odpowiednią strukturę katalogów, np. taką:
Jak widzisz, w katalogu z projektem musisz utworzyć folder .template.config, w którym umieścisz całą konfigurację swojego szablonu. Ja utworzyłem projekt WebApplication (RazorPages), jako projekt wyjściowy, któremu nadałem nazwę WebAppWithApiTemplate.
Tylko uwaga – będzie Cię korciło, żeby dodać folder .template.config do projektu w Visual Studio. Nie rób tego. Wszystko, co zrobisz z projektem będzie miało skutek w Twoim szablonie. W prawdzie można potem zastosować pewien mechanizm, żeby pozbyć się tego folderu w wynikowym projekcie, ale moim zdaniem można to zrobić lepiej…
Dodawanie plików konfiguracyjnych do solucji
To nie znaczy jednak, że nie możesz pracować na plikach konfiguracyjnych w Visualu. Byłoby to mocno uciążliwe. Utwórz zatem ręcznie katalog .template.config, a w nim plik o nazwie template.json. A następnie w Visual Studio kliknij prawym klawiszem myszy na solucję i wybierz Add -> New Solution Folder:
To utworzy Ci folder (tzw. „filtr”) na poziomie solucji. Jednak żaden folder na dysku nie powstanie. Ja swój „filtr” nazwałem template-files – to jak nazwiesz swój nie ma żadnego znaczenia.
Następnie kliknij go prawym klawiszem myszy i wybierz Add -> Existing Item:
W pickerze wybierz pliki konfiguracyjne szablonu, które utworzyłeś wcześniej. To doda je do solucji, ale nie zrobi żadnych zmian na poziomie projektów. Dzięki temu będziesz mógł pracować na plikach konfiguracyjnych w Visual Studio:
Plik template.json
To właściwie serce Twojego szablonu. Niestety na dzień dzisiejszy nie da się go wyklikać, ale dość łatwo się go tworzy. Zwłaszcza, jeśli wykorzystasz możliwości VisualStudio. Spójrz na okno z zawartością pliku:
Plik oczywiście jest pusty, ale w edytorze kodu widzisz combobox oznaczony jako Schema. Możesz w nim wybrać schemat pliku json, który chcesz tworzyć – dzięki temu cały Intellisense zadziała i będziesz mieć eleganckie podpowiedzi w kodzie. Odnajdź na tej liście https://json.schemastore.org/template.json – to jest opisany schemat szablonu.
UWAGA! Widoczny na powyższym screenie schemat to jakiś przykładowy pierwszy lepszy z listy. Pamiętaj, żeby odnaleźć tam konkretny: https://json.schemastore.org/template.json
VS dzięki temu opisowi może dawać Ci podpowiedzi. A teraz zacznijmy wypełniać plik template.json. Na początek trzeba mu wskazać wybrany schemat. Robimy to za pomocą właściwości $schema:
To są minimalne wymagane właściwości. Rozpoznasz je po tym, że w Intellisense są pogrubione. A teraz przelecimy je po kolei:
author – to oczywiście autor szablonu
classifications – to klasyfikuje szablon. Te wartości będą potem używane w filtrach np. Visual Studio. Podajesz tutaj tablicę wartości, które powinny kategoryzować Twój szablon. W VisualStudio to te właściwości podczas dodawania nowego projektu. W narzędziu dotnet new --list będą się pojawiały w rubryce tags.
identity – to jest coś w rodzaju ID Twojego szablonu. To musi być unikalne, dlatego daj tutaj jakąś unikalną wartość, ale niech to będzie coś opisowego a nie np. GUID – później się przyda
name – pełna nazwa Twojego szablonu (przykłady istniejących: „Console App”, „ASP.NET Core Web App”)
shortName – nazwa skrócona szablonu, której będziesz mógł używać, tworząc projekt na jego podstawie
tags – podstawowy opis szablonu – wskazujesz, że szablon odnosi się do projektu (type: project) i jaki jest główny język projektu. Szablon może być jeszcze dla całej solucji (kilka projektów) lub nowym item’em – czyli poszczególnym typem pliku.
Dość istotną właściwością jest sourceName. SourceName to ciąg znaków zarówno w zawartości plików jak i w ich nazwach, który podczas tworzenia projektu zostanie zastąpiony nazwą projektu, którą poda użytkownik. Przykładowo, jeśli mój kod wygląda tak:
I jeśli we właściwości sourceName podam: „WebAppWithApiTemplate” wtedy ten ciąg zostanie zamieniony na to, co wpisze użytkownik podając nazwę swojego projektu.
Czyli zarówno namespace’y, jak i nazwa projektu głównego zostaną zamienione na ten żądany przez użytkownika. A więc dodajmy to:
Pewnie są sytuacje, w których nie chciałbyś takiej podmiany. Wtedy po prostu tego nie stosujesz, gdyż nie jest to właściwość wymagana.
To jest już pełnoprawny projekt szablonu. Teraz musisz go tylko zapakować w nuget i zainstalować. O tym później. Najpierw zrobimy inne fajne rzeczy.
Parametry
Szablon często będzie zawierał jakieś parametry, które mogą być ustawione przez użytkownika. W pliku template.json lądują one we właściwości symbols. Parametry są jednym z typów symboli.
Parametr składa się z nazwy (ID), a także typu danych. Może zawierać wartość domyślną, a także ciąg, który będzie zamieniony na wartość parametru.
Jak to działa? Silnik szablonów analizuje plik template.json. Jeśli teraz znajdzie jakieś parametry (symbole) do podmiany, to każdy taki ciąg znaków w kodzie zamieni na konkretną wartość podaną przez użytkownika. Analogicznie do właściwości sourceName.
Dodajmy do naszego szablonu folder ApiClient, a nim prostą klasę:
I teraz chcę, żeby taka klasa znalazła się w katalogu ApiClient, ale to użytkownik będzie decydował o tym, jak ten klient ma się nazywać. Dlatego też posłużę się symbolem:
"symbols": {
"ApiClientName": { //nazwa parametru (jego ID)
"type": "parameter",
"datatype": "text",
"description": "Podaj nazwę klasy dla swojego klienta API",
"displayName": "Nazwa klasy dla Api Client",
"defaultValue": "MyApiClient",
"isRequired": true,
"replaces": "varApiClientName",
"fileRename": "varApiClientName"
}
}
Uznaj właściwość symbols za klasę, która posiada inne właściwości – konkretne symbole. I teraz tak. Każdy symbol ma swoją nazwę (ID). Tutaj to APIClientName. Nazwą symbolu możesz posługiwać się w kodzie swojego szablonu, o tym za chwilę.
Każdy symbol to też swego rodzaju klasa, która posiada konkretne właściwości:
type – typ symbolu. To może być parametr, generator itd. Na razie skupmy się na parametrach
datatype – typ danych, jakie ten parametr będzie przechowywał. Inne typy to np:
bool – true/false – na GUI równoznaczne z checkboxem (np. Use Https)
choice – lista wartości do wyboru – na GUI równoznaczne z combo (np. wybór Identity)
float, hex, int, text – no te wartości same się opisują. Przy czym text jest wartością domyślną
description – opis parametru. Pokaże się w konsoli w poleceniu dotnet new, ale też w VisualStudio jako dodatkowa informacja (chociaż dla IDE jest dodatkowy/osobny sposób pokazywania parametrów opisany niżej)
defaultValue – wartość domyślna
isRequired – czy parametr jest wymagany. Jeśli podczas tworzenia projektu przez polecenie dotnet new użytkownik nie poda tej wartości, to dotnet new zwróci błąd
replaces – to jest ten magiczny string w plikach, który zostanie zamieniony na wartość wprowadzoną przez użytkownika. U mnie to varApiClientName. Ten prefix „var” jest tylko pewnym udogodnieniem dla mnie. Nie ma tutaj żadnych wytycznych ani obostrzeń. Ale pamiętaj, że zostaną zamienione WSZYSTKIE STRINGI w kodzie. Łącznie z tymi w plikach projektów, komentarze, a nawet wszystkie wartości tekstowe. Jeśli więc miałbym w kodzie coś takiego:
public string Id { get; set; } = "varApiClientName";
to też będzie zamienione. Dlatego ja posługuję się tym przedrostkiem var. To trochę chroni przed zrobieniem głupoty.
fileRename – analogicznie jak replace z tą różnicą, że taki ciąg zostanie podmieniony w nazwach plików.
Stwórzmy teraz bardzo prostego i prymitywnego klienta dla API. To jest tylko bardzo prymitywny przykład. Jak fajnie zrobić takiego klienta pisałem w tym artykule. Nie chcę zaciemniać obrazu, dlatego zrobię najprościej jak się da. Ten klient powstał tylko dla przykładu. I naprawdę nie jest istotne, że nie ma większego sensu 😉
Sparametryzowany klient
Co chcemy uzyskać?
Użytkownik ma mieć opcję do podania nazwy klienta – to już nam załatwił parametr varApiClientName.
Użytkownik ma mieć możliwość wyłączenia lub włączenia rejestracji serwisów – czyli domyślnej konfiguracji klienta.
W przypadku włączenia rejestracji serwisów, użytkownik ma mieć możliwość podania BaseAddress dla API. Zarówno dla środowiska produkcyjnego jak i deweloperskiego.
Tworzenie pełnego kodu
Tak, czy inaczej musimy stworzyć cały kod. W pliku template.json nie możemy dodawać plików ani linijek kodu. Dlatego też musimy wyjść od pełnego obrazu.
Przede wszystkim jest klasa, która umożliwia wysyłanie żądań – prosty klient w pliku varApiClientName.cs:
namespace WebAppWithApiTemplate.ApiClient
{
public class varApiClientName
{
private readonly HttpClient _client;
public varApiClientName(HttpClient client)
{
_client = client;
}
public async Task<HttpResponseMessage> GetData(string endpoint)
{
return await _client.GetAsync(endpoint);
}
public async Task<HttpResponseMessage> PostData<TOut>(TOut data, string endpoint)
{
return await _client.PostAsJsonAsync(endpoint, data);
}
}
}
Do tego trzeba zrobić rejestrację HttpClienta. Dlaczego w taki sposób? Opisywałem to w tym artykule.
W folderze ApiClient dodałem plik ServiceCollectionsExtensions.cs:
public class varApiClientNameOptions
{
public const string CONFIG_SECTION = "varApiClientName";
public string BaseAddress { get; set; }
}
public static class ServiceCollectionExtensions
{
public static IServiceCollection AddvarApiClientNameIntegration(this IServiceCollection services,
IConfiguration config)
{
varApiClientNameOptions options = new varApiClientNameOptions();
config.Bind(varApiClientNameOptions.CONFIG_SECTION, options);
services.AddHttpClient<varApiClientName>(client =>
{
client.BaseAddress = new Uri(options.BaseAddress);
});
return services;
}
}
W tym kodzie po prostu rejestrujemy HttpClient dla naszego klienta. Jeśli nie wiesz co robi AddHttpClient, koniecznie przeczytaj ten artykuł.
Najpierw pobieramy ustawienia, w których będzie wpisany adres bazowy api. To nam zapewnia, że adres bazowy będzie pobrany w zależności od środowiska. Nasępnie konfigurujemy klienta.
Spójrz w jaki sposób przemycam wszędzie varApiClientName – te wszystkie miejsca zostaną zamienione na faktyczną nazwę klienta.
Na koniec wywołamy jeszcze tę metodę podczas rejestracji serwisów w pliku Program.cs:
using WebAppWithApiTemplate.ApiClient;
//...
builder.Services.AddRazorPages();
builder.Services.AddvarApiClientNameIntegration(builder.Configuration);
Dodawanie parametrów
W związku z tym, że chcemy aby użytkownik mógł podać adres bazowy dla API, musimy dodać takie parametry do template.json. Oczywiście dodajemy to dalej w sekcji symbols:
"ApiProdBaseAddress": {
"type": "parameter",
"datatype": "text",
"description": "Bazowy adres dla API dla środowiska produkcyjnego",
"replaces": "varApiProdBaseAddress",
"defaultValue": "https://api.example.com/"
},
"ApiDevBaseAddress": {
"type": "parameter",
"datatype": "text",
"description": "Bazowy adres dla API dla środowiska deweloperskiego",
"replaces": "varApiDevBaseAddress",
"defaultValue": "https://api.dev.example.com"
}
Dodałem dwa parametry – jeden to adres bazowy dla środowiska produkcyjnego, drugi dla deweloperskiego. Jeśli nie wiesz, czym jest appsettings.json, czym się różni od appsettings.Development.json i masz małe pojęcie o konfiguracji .NET, koniecznie przeczytaj ten artykuł.
Dodawanie ustawień w aplikacji
OK, możemy teraz te dane dodać do plików appsettings.
Spójrz w jaki sposób przemycam tutaj znów nazwy tego klienta i parametr z bazowym adresem dla API. Analogicznie zrobimy w pliku appsettings.Development.json:
OK, teraz mamy ogarnięte punkty 1 i 3 z naszych założeń. Czyli użytkownik może podać nazwę klienta, a także adresy bazowe do API. To teraz musimy się zatroszczyć o punkt 2 – użytkownik ma mieć możliwość wyłączenia jakiejkolwiek konfiguracji klienta.
Najpierw dodajmy taki parametr w pliku template.json:
"ConfigureApiClient": {
"type": "parameter",
"datatype": "bool",
"description": "Czy klient API ma być domyślnie skonfigurowany",
"defaultValue": "true"
}
Zauważ, że tutaj nie posługuję się właściwością replaces, ponieważ niczego nie będziemy podmieniać. Albo wykonamy fragment kodu, albo nie.
Zatem wytnijmy warunkowo fragment kodu, który wywołuje rejestrację klienta, czyli to:
using WebAppWithApiTemplate.ApiClient;
//...
builder.Services.AddRazorPages();
builder.Services.AddvarApiClientNameIntegration(builder.Configuration);
Robimy to w bardzo prosty sposób – dyrektywami kompilatora:
W taki sposób możesz sterować fragmentami kodu w plikach. Po prostu sprawdzasz, czy parametr o podanym ID ma wartość true.
Usuwanie plików
Jeśli chodzi jednak o plik ServiceCollectionExtensions.cs nie jest on w ogóle potrzebny, gdy użytkownik nie chce automatycznej konfiguracji. Nie ma sensu wycinać kodu w tym pliku, bo zostałby nam zupełnie pusty. Dlatego warunkowo możemy go usunąć. Z pomocą przychodzi nowa sekcja w pliku template.json – sources – w niej możemy stosować modyfikatory plików źródłowych.
Sekcja sources zawiera modyfikatory. Każdy modyfikator może mieć warunek lub wykonać się bezwarunkowo (zawsze). Napiszmy więc taki modyfikator, który usunie plik ServiceCollectionsExtensions.cs, gdy parametr ConfigureApiClient nie będzie ustawiony (jego wartość będzie na false):
Jak widzisz, żeby sprawdzić wartość jakiegoś parametru, po prostu wpisujemy jego nazwę w nawias. Możemy też go zanegować wykrzyknikiem. Czyli w tym przypadku, gdybyśmy chcieli ten warunek przepisać na kod, wyglądałoby to akoś tak:
Następnie musimy wskazać, co ma się zadziać, jeśli warunek będzie spełniony. A więc pozbywamy się pliku, wykluczamy go (exclude) z całości.
Teraz może pojawić się pytanie – skąd silnik template’ów wie, gdzie jest konkretny plik. Ścieżką wyjściową (bazową) dla silnika jest folder, w którym znajduje się folder .template.config.
I tutaj odnosimy się do folderu ApiClient i pliku, który się w nim znajduje. Możesz stosować tutaj symbole wieloznaczne, np: „**/*Extensions.cs” – usunęłoby wszystkie pliki z wszystkich podkatalogów, których nazwy kończą się na Extensions.cs.
Jeśli jednak chciałbyś wykluczyć większość plików, a zostawić tylko jeden, łatwiej będzie posłużyć się modyfikatorem include. Domyślnie include włącza wszystkie pliki, które znajdują się w projekcie (oczywiście poza katalogiem .template.config).
Możesz też chcieć warunkowo zmienić nazwy plików. Do tego możesz zastosować modyfikator rename.
Warunkowe zawartości plików
Pliki *.cs
Jak już pisałem wcześniej, w plikach cs możemy posługować się dyrektywami kompilatora, żeby warunkowo mieć jakąś zawartość, np:
Możesz stosować również dyrektywę #elif. A co jeśli chcesz jednak, żeby jakaś dyrektywa była widoczna na koniec w pliku? Np:
#if DEBUG
logger.LogWarning("UWAGA! Tryb deweloperski!");
#endif
Jest i na to sposób. Nazywa się to processing flag. To już jednak wygląda jak czary:
//-:cnd:noEmit
#if DEBUG
logger.LogWarning("UWAGA! Tryb deweloperski!");
#endif
//+:cnd:noEmit
No cóż… Grunt, że jest taka opcja 😉 Pamiętaj – „processing flag”.
Pliki JSON
Tutaj nie możemy się posłużyć bezczelnie dyrektywą, ale możemy posłużyć się specjalnym komentarzem. W plikach json komentarz jest rozpoczynany znakami // i trwa do końca linii. To wytnijmy teraz ustawienia związane z konfiguracją api clienta z plików appsettings:
To spowoduje dokładnie to, czego się spodziewasz – sekcja varApiClientName pojawi się w pliku appsettings tylko wtedy, gdy parametr ConfigureApiClient będzie miał wartość TRUE. Zrób analogiczną operację w pliku appsettings.Development.json.
Zmiany w plikach projektów i innych XMLach
Tutaj analogicznie posłużymy się komentarzami XMLowymi. Możesz bez problemu je stosować w plikach projektów. Dodajmy do naszych wymagań jeszcze jedno – niech użytkownik wybierze, czy chce korzystać z biblioteki System.Text.Json, czy ze starego dobrego Newtonsoft.Json. Na początek dodajmy taki parametr do pliku template.json. Niech to będzie combobox.
Jak widzisz, choices składa się z tablicy obiektów (choice, description, displayName). Ich właściwości same się opisują. I co ciekawe, przy choice też możesz stosować właściwość replaces, co później pokażę. Pamiętaj też, żeby wartością datatype było ustawione na choice.
To teraz zmieńmy plik projektu. Jak już wspomniałem robimy to specjalnym komentarzem:
Pomiędzy znakiem komentarza <!-- a hashem nie może być spacji. Inaczej silnik szablonów nie uzna tego za dyrektywę, tylko za zwykły komentarz.
Wartość, którą porównujesz musi być w apostrofach. Inaczej warunek nie zostanie uznany jako spełniony.
Można to zrobić jeszcze inaczej – bez porównywania konkretnych wartości. Przydać się to może w sytuacji, gdzie miałbyś do sprawdzenia kilka tych samych warunków w kilku miejscach. Ale o tym za chwilę.
Trochę magii – czyli czego nie powie Ci dokumentacja
Dokumentacje szablonów są całkiem nieźle opisane, ale mają miejscami sporo braków. Jak np. magiczny parametr Framework. Na jakimś video z Microsoftu słyszałem, że jest on zalecany, ale nigdzie nie jest opisany. Hurrra!
Generalnie parametr Framerowk daje wybór frameworka, na którym ma być stworzony projekt oparty na szablonie. Tworzy się go analogicznie jak inne parametry:
wartości w choice muszą być dokładnymi „monikerami” wersji .NET, np.:
net48 – .NetFramework 4.8
netstandard2.1
netcoreapp3.1
net5.0
net6.0
net7.0
Jeśli wrzucisz inne wartości, to magiczny mechanizm nie zadziała.
we właściwości replaces wstawiasz, jak to z innymi parametrami, string do podmiany. Pamiętaj, że to podmieni wszystkie znalezione stringi „net6.0” na wybraną przez użytkownika wartość – w szczególności w pliku projektu.
Zobacz, jak sprytnie Visual Studio rozkminił wersje
Symbole wyliczane
Innym typem symbolu są symbole wyliczane. To coś w rodzaju parametru. Tylko nie podaje go użytkownik, a wyliczamy go na jakiejś podstawie. Możesz to stosować gdy w kilku miejscach stosujesz jakieś warunki. Np:
Taki kodzik stworzy Ci coś w rodzaju zmiennej o nazwie IsLTS, która przyjmie odpowiednią wartość na podstawie innych parametrów. W tym konkretnym przypadku możesz sprawdzić, czy wybrana wersja .net jest długowieczną (long time support), czy też nie. Później na tej podstawie możesz zadecydować o czymś innym, stosując w innych warunkach zmienną IsLTS – dokładnie w taki sam sposób jak inne parametry. Np. możesz gdzieś w kodzie wpisać warning:
#if (!IsLTS)
#warning "Caution! Your framework is not LTS version!"
#endif
UWAGA! Symbole typu computed mogą przyjmować jedynie wartości typu bool.
Instalowanie szablonu
Właściwie wszystkie wytyczne mamy już ogarnięte. Teraz możemy zainstalować taki szablon. Oczywiście nie można zrobić z VisualStudio tego automatem… jeszcze… za to można to zrobić na kilka sposobów. Najpierw podam Ci sposób lokalny – to jest wystarczające jeśli tworzysz jakiś szablon dla siebie i raczej nie będziesz w nim już grzebał.
Uruchom terminal i przejdź do katalogu głównego Twojej aplikacji. Tam, gdzie masz katalog z projektem. U mnie plik projektu znajduje się w projekty\MasterBranch\SingleNewTemplate\src\WebAppWithApiTemplate\WebAppWithApiTemplate.csproj dlatego muszę ustawić się w katalogu src: projekty\MasterBranch\SingleNewTemplate\src\
Teraz wystarczy zainstalować szablon, wykonując polecenie:
dotnet new --install .\WebAppWithApiTemplate
czyli podajemy nazwę katalogu, w którym jest projekt z szablonem.
Następnie możemy przejrzeć sobie listę szablonów:
dotnet new --list
U mnie wygląda to tak:
Jak widzisz, mój szablon został zainstalowany.
Jeśli będziesz chciał go odinstalować, to dotnet new podpowie Ci dokładnie co zrobić, ale zasadniczo powinieneś podać pełną ścieżkę dostępu do katalogu z projektem szablonu, np.:
dotnet new --uninstall d:\projekty\MasterBranch\SingleNewTemplate\src\WebAppWithApiTemplate
Jeśli chciałbyś utworzyć sobie projekt na podstawie tego szablonu, to możesz to zrobić podając króką nazwę szablonu. A wywołując instrukcję help, dostaniesz pełną pomoc dla swojego szablonu:
dotnet new waapi --help
Jak widzisz, dotnet świetnie sobie poradził z Twoimi parametrami i pokazuje Ci dokładnie jak ich użyć. Przykładowe utworzenie projektu:
dotnet new waapi -J Default -A ExampleApiClient -o .\NewProject
Tutaj jednak pamiętaj, że parametry polecenia dotnet new mieszają się z Twoimi parametrami. Stąd np. -o (--output) – parametr dotnet new, który mówi gdzie stworzyć projekt.
Możesz też taki projekt stworzyć bezpośrednio z Visual Studio (zrestartuj Visual Studio po zainstalowaniu szablonu).
Instalowanie szablonu NuGetem
Ten sposób umożliwia Ci podzielenie się szablonem z innymi, a także łatwe jego wersjonowanie. Wymaga to utworzenia nugetowej paczki. Ale zadanie jest dość proste.
Utwórz gdzieś plik template.nuspec. Możesz to zrobić w katalogu .template.config, ale nie musisz. Utwórz go gdzieś, gdzie uznasz za słuszne. Jego przykładowa zawartość powinna wyglądać tak:
Ten plik sam się opisuje. Musisz pamiętać jedynie o tym, żeby sekcja files odnosiła się do konkretnych plików Twojego szablonu. Ja akurat plik nuspec umieściłem w .template.config – dlatego też w sekcji files idę po pliki „piętro wyżej”.
Następnie musisz wywołać na nim:
nuget pack template.nuspec
Jeśli wszystko jest ok, to otrzymałeś plik z rozszerzeniem nupkg. I to jest Twój pakiet, którym możesz się już dzielić. Żeby teraz zainstalować taki szablon, wystarczy:
dotnet new install .\twoj-plik.nupkg
Odinstalowanie jest analogiczne. Tyle, że podajesz tylko nazwę pakietu – bez ścieżki do niego.
Przygotowanie szablonu dla środowisk IDE
dotnetcli.host.json
Oprócz pliku template.json, który jest podstawą, możesz mieć jeszcze dodatkowe pliki, w których swój szablon możesz podkręcić. Najprostszym jest dotnetcli.host.json. Jego rolą jest ustawienie aliasów do parametrów w narzędziu dotnet new. Domyślnie są one tworzone jakoś automagicznie. Jeśli wyświetlisz pomoc dla swojego szablonu, zobaczysz taki mniej więcej opis:
Parametr na długą nazwę, np. --ApiClientName, ale może mieć też krótki alias, np: -a. Zauważ, że pełna nazwa parametru rozpoczyna się podwójnym myślnikiem [–], natomiast aliast pojedynczym [-]. Jest to naturalne zachowanie. Jak widzisz powyżej, dla każdego parametru istnieją jakieś domyślne aliasy. Ale możesz je sam utworzyć, stosując plik dotnetcli.host.json, np. tak:
Najpierw podajesz id symbolu takie jak w pliku template.json. Następnie masz parametry:
longName – długa nazwa – czyli ta prawilna cała nazwa parametru prefiksowana podwójnym myślnikiem
shortName – alias – krótka nazwa parametru. Jeśli podasz pusty string „”, wtedy parametr nie będzie miał aliasu.
isHidden – jeśli ustawisz na true, to ta opcja nie będzie widoczna z poziomu dotnet new --help. Jednak nadal będziesz mógł z niej korzystać (po prostu nie zobaczysz jej w podpowiedziach).
ide.host.json
Ten plik z kolei pomaga ogarnąć dodatkowe rzeczy w Visual Studio (i pewnie w innych IDE). We wcześniejszych wersjach (poniżej 2022) był wymagany. Teraz jest opcjonalny, jednak umożliwia dodatkowe czary mary.
Tutaj ustawiamy ikonkę dla szablonu. To zakłada, że w katalogu .template.config masz ikonkę o nazwie icon.png. Żeby ikonka była dobrze widoczna, powinna być w rozmiarze 32×32 piksele o głębokości 32 bitów.
UWAGA! Jeśli tego nie zrobisz, ale w katalogu .template.config będziesz miał ikonkę o nazwie icon.png, to VisualStudio od wersji 2022 też to ogarnie.
Parametry
Informacje o parametrach przechowywane są we właściwości symbolInfo. To po prostu tablica parametrów, mówiących VisualStudio jak ma je obsługiwać. Podobnie jak w template.json
Podstawowa budowa obiektu jest taka:
"symbolInfo": [
{
"id": "ApiClientName",
"name": {
"text": "Nazwa klienta API"
},
"description": {
"text": "Podaj nazwę klienta dla swojego API. Tak będzie nazywać się wygenerowana klasa."
},
"isVisible": true
}
]
Id to nazwa parametru z pliku template.json. Właściwości name i description pokażą się przy tym parametrze jako jego nazwa i opis, który będzie w hincie:
Jeśli nie wypełnisz właściwości name i description, zostanę one odczytane z pliku template.json.
Parametr isVisible określa, czy właściwość ma być widoczna.
Jeśli używasz pliku ide.host.json, to pamiętaj że domyślnie wszystkie parametry są UKRYTE. Stąd właściwość isVisible. Ustawiasz nią, które parametry mają być widoczne. Jeśli chcesz żeby wszystkie były widoczne, to jest od tego właściwość defaultSymbolVisibility, np:
Ten kod sprawi, że wszystkie parametry z template.json będą widoczne podczas tworzenia nowego projektu w Visual Studio. Czyli zasadniczo w VisualStudio 2022 równie dobrze ten plik (ide.host.json) mógłby nie istnieć.
Plik ide.host.json ma jeszcze kilka parametrów:
description – opis szablonu – jeśli go nie wypełnisz, zostanie wzięty z pliku template.json
name – nazwa szablonu – analogicznie jak wyżej
order – kolejność w jakiej pojawi się szablon na liście tworzenia nowego projektu
supportsDocker – jeśli ustawione na true, to podczas tworzenia projektu zobaczysz opcję (checkbox) pozwalającą zdokeryzować taki projekt. I tutaj uwaga! Jeśli chcesz żeby ta opcja była widoczna w VisualStudio, musisz do pliku template.json dodać parametr Framework (ten magiczny). Inaczej nie zadziała.
unsupportedHosts – możesz tutaj podać listę wersji, dla których ten szablon ma być niewidoczny na dialogu tworzenia nowego projektu, np. taka konfiguracja ukryje szablon w VisualStudio:
"unsupportedHosts": [
{
"id": "vs"
}
]
Zaawansowane
Specjalne operacje
Jeśli silnik szablonów nie potrafi czegoś zrobić standardowo, to być może da Ci taką możliwość za pomocą specjalnych operacji. Te operacje pozwalają na zdefiniowanie dodatkowych akcji podczas tworzenia projektu na podstawie szablonu. Akcje mogą być globalne (dla wszystkich plików) lub ograniczone tylko do niektórych plików.
{
"customOperations": { //odnosi się do wszystich plików - globalnie
},
"specialCustomOperations": { //tylko do niektórych plików
}
}
Ja w jednym swoim szablonie potrzebowałem mieć różne grupy usingów. Szablon został utworzony pod konkretną solucję, w której te specjalne projekty (namespacey) już są. Jednak z nimi projekt szablonu się nie kompilował. Owszem, mogłem utworzyć jakiś plik z konkretnymi namespaceami i potem go usuwać, ale wpadłem na inny pomysł. Wyobraź sobie taki plik *.cs:
/*add-usings
using Nerdolando.BS.Common.Abstractions;
using Nerdolando.BS.Integrations;
add-usings*/
namespace WebAppWithApiTemplate.ApiClient
{
public class SpecialOperations
{
}
}
Zauważ, że usingi mam tutaj wykomentowane. Ale chcę, żeby pojawiły się w wynikowym projekcie. Dlatego posłużyłem się customową operacją z pliku template.json:
Najpierw podaję do jakich plików odnoszą się akcje. Tutaj – wszystkie pliki z rozszerzeniem *.cs. Następnie definuję operacje. Jest kilka predefiniowanych operacji, m.in. „replacement„. Każda z takich operacji ma swoją konfigurację. Niestety na listopad 2022 w schemacie template.json nie ma tego zdefiniowanego, więc nie będziesz miał podpowiedzi w Intellisense.
Dzięki za przeczytanie tego artykułu. Jeśli znalazłeś jakiś błąd albo czegoś nie rozumiesz, koniecznie daj znać w komentarzu. Daj też znać w komentarzu, jeśli uważasz, że taki artykuł jest za długi i powinien zostać podzielony na dwa 🙂
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.
Dodaj kolejny projekt Class Library do solucji, jeśli jeszcze go nie masz.
Doinstaluj do niego paczkę NuGet: Microsoft.AspNetCore.App
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 🙂
Często mówimy o tym, czym jest WebApi, jak je tworzyć, a jak nie. Ale jakoś nie mówimy o tym jak stworzyć dobrze fajnego klienta do tego WebAPI.
Mogłoby się zdawać, że wystarczy utworzyć instancję HttpClient i wywołać odpowiednią końcówkę. I czasem nawet można tak zrobić. Ale jeśli chcesz mieć naprawdę dobrego klienta do większego API niż tylko dwie końcówki, to ten artykuł pokaże Ci jak do tego podejść na konkretnym przykładzie.
Jest NuGetowa paczka – RestSharp. Jest to bardzo popularna darmowa biblioteka, która zdecydowanie ułatwia tworzenie klientów API. Jednak w tym artykule nie posłużymy się nią. Zrobimy coś sami. Potem sam zdecydujesz, czy wolisz tworzyć takie rozwiązania samodzielnie, czy z użyciem RestSharpa.
Przede wszystkim – WebAPI
Żeby klient API miał sens, musi przede wszystkim łączyć się z jakimś API. Dlatego też przygotowałem dość proste rozwiązanie, na którym będziemy pracować. Możesz je pobrać z GitHuba.
Uwaga! Nie zwracaj za bardzo uwagi na kod API – jest bardzo prosty, banalny i nie we wszystkich aspektach super poprawny. Nie zajmujemy się tutaj WebAPI, tylko klientem do API.
To Api trzyma dane w słowniku, to znaczy że po ponownym uruchomieniu, wszystkie dane znikną.
Api ma kilka końcówek, możesz sobie je zobaczyć, uruchamiając swaggera. Z grubsza to:
POST – /api/clients/all – pobiera listę klientów (dlaczego POST – o tym niżej)
POST – /api/clients – dodaje klienta
GET – /api/clients/{id} – pobiera klienta o konkretnym id
DELETE – /api/clients/{id} – usuwa klienta o konkretnym id
POST – /api/orders/all – pobiera zamówienia (dlaczego POST – o tym niżej)
POST – /api/orders – dodaje zamówienie
GET – /api/orders/client/{clientId} – pobiera zamówienia dla konkretnego klienta
GET – /api/orders/{id} – pobiera zamówienie o konkretnym id
Także mamy kilka końcówek podzielonych na dwa kontrolery.
Zaczynamy pisać klienta
OK, skoro już wiemy jak mniej więcej wygląda API, możemy utworzyć projekt, w którym napiszemy klienta. Niech to będzie zwykły projekt Class Library.
Model DTO
Najpierw musimy utworzyć modele DTO. DTO czyli Data Transfer Object – są to klasy, które przekazują dane między API, a klientem. Modele DTO mogą być jak najgłupsze się da. To po prostu worek na dane. Nic więcej.
Teraz możesz zapytać – po co tworzyć dodatkowy model, skoro mamy już dokładny model bazodanowy? Nie lepiej ten model bazodanowy z projektu WebApi przenieść do jakiegoś współdzielonego?
W tym konkretnym przypadku banalnej aplikacji – pewnie tak. Natomiast przy aplikacjach bardziej rozbudowanych przekazywanie danych za pomocą modeli bazodanowych może okazać się baaaardzo problematyczne. Sam wiele lat temu zrobiłem taki błąd. W pewnym momencie okazało się, że muszę stosować jakieś dziwne haki i czary, żeby to wszystko jakoś działało. Dlatego – stwórz osobny model DTO.
W przykładowej aplikacji są w projekcie Models. Modele DTO wyglądają prawie tak samo jak modele bazodanowe. Specjalnie dodałem do modeli bazodanowych jedną właściwość (IsDeleted), żeby je czymś rozróżnić.
Zwróć uwagę na dwie klasy:
GetClientsRequestDto:
public class GetClientsRequestDto
{
public int Skip { get; set; }
public int Take { get; set; }
}
GetClientsResultDto:
public class GetClientsResultDto
{
public IEnumerable<ClientDto> Data { get; init; }
public int Offset { get; init; }
public GetClientsResultDto(IEnumerable<ClientDto> data, int offset)
{
Data = data;
Offset = offset;
}
}
W standardowym tutorialu tworzenia WebApi zobaczyłbyś, że gdy żądasz listy klientów, API zwraca po prostu listę klientów, np: IEnumerable<ClientDto>.
Jednak w prawdziwym świecie to może być za mało. Dlatego też stworzyłem dwie dodatkowe klasy:
GetClientsRequestDto – obiekt tej klasy będzie wysyłany wraz z żądaniem pobrania listy klientów
GetClientsResultDto – obiekt tej klasy będzie zwracany przez API zamiast zwykłej listy klientów.
Jak widzisz, te klasy zawierają w sobie informacje ograniczające ilość pobieranych danych. Jeśli miałbyś bazę z 10000 klientów i z jakiegoś powodu chciałbyś pobrać ich listę, to zupełnie bez sensu byłoby pobieranie wszystkich 10000 rekordów. To naprawdę sporo danych. Zamiast tego możesz pobierać te dane partiami i napisać jakiś prosty mechanizm paginacji. Do tego mogą właśnie służyć te dodatkowe klasy.
Analogicznie zrobiłem dla modelu OrderDto.
Abstrakcja
Skoro już mamy modele DTO, możemy pomyśleć o abstrakcji, która umożliwi nam testowanie klienta API.
Zgodnie z regułą pojedynczej odpowiedzialności (signle responsibility) klient API nie powinien być odpowiedzialny za wszystkie operacje związane z API. Ale powinien dać taką możliwość. Jak to osiągnąć? Poprzez dodatkowe klasy operacji. I tak będziemy mieć klasę odpowiedzialną za operacje na zamówieniach i drugą odpowiedzialną za klientów. Stwórzmy teraz takie abstrakcje:
public interface IClientOperations
{
public Task<ClientDto> AddClient(ClientDto data);
public Task<GetClientsResultDto> GetClients(GetClientsRequestDto data);
public Task<ClientDto> GetClientById(int id);
public Task<bool> DeleteClient(int id);
}
To jest interfejs, którego implementacja będzie odpowiedzialna za operacje na klientach. Analogicznie stworzymy drugi interfejs – do zamówień:
public interface IOrderOperations
{
public Task<OrderDto> AddOrder(OrderDto order);
public Task<GetOrdersResultDto> GetOrdersForClient(int clientId, GetOrdersRequestDto data);
public Task<GetOrdersResultDto> GetOrders(GetOrdersResultDto data);
public Task<bool> DeleteOrder(int id);
}
To są bardzo proste interfejsy i na pierwszy rzut oka wszystko jest ok. Ale co jeśli z WebApi otrzymasz jakiś konkretny błąd? Np. podczas dodawania nowego klienta mógłbyś otrzymać błąd w stylu: „Nazwa klienta jest za długa”. W taki sposób tego nie ogarniesz. Dlatego proponuję stworzyć dwie dodatkowe klasy, które będą przechowywały rezultat wywołania końcówki API:
public class BaseResponse
{
public int StatusCode { get; init; }
public bool IsSuccess { get { return StatusCode >= 200 && StatusCode <= 299 && string.IsNullOrWhitespace(ErrorMsg); } }
public string ErrorMsg { get; init; }
public BaseResponse(int statusCode = 200, string errMsg = "")
{
StatusCode = statusCode;
ErrorMsg = errMsg;
}
}
public class DataResponse<T> : BaseResponse
{
public T Data { get; init; }
public DataResponse(T data, int statusCode = 200, string errMsg = "")
: base(statusCode, errMsg)
{
Data = data;
}
}
Klasa BaseResponse i operacja zakończona poprawnie
Klasa BaseResponse będzie przechowywała kod odpowiedzi wraz z ewentualnym komunikatem o błędzie. Wg specyfikacji HTTP wszystkie kody od 200 do 299 włącznie oznaczają operację zakończoną poprawnie, dlatego też IsSuccess jest tak skonstruowane.
Teraz pojawia się pytanie – co oznacza „operacja zakończona poprawnie”? W kontekście WebApi zazwyczaj chodzi tutaj o to, że dane przesłane w żądaniu były prawidłowe, na serwerze nic się nie wywaliło, nie było problemu z autoryzacją i serwer odpowiedział prawidłowo. Jednak nie znaczy to, że operacja zakończyła się tak, jak byśmy sobie tego życzyli.
To trochę dziwnie brzmi, zatem pokażę Ci pewien przykład. Załóżmy, że chcesz pobrać klienta o ID = 5. Wg specyfikacji REST Api, jeśli taki klient nie istnieje, powinieneś otrzymać zwrotkę z kodem 404. Jednak błąd 404 oznacza również, że nie znaleziono określonej strony (końcówki API). Jest to pewien znany problem. Czasami się to tak zostawia, czasem można rozróżnić w taki sposób, że z WebAPI zwracamy kod 200 – operacja się powiodła, ale dołączamy informację o błędzie w odpowiedzi np: „Nie ma klienta o takim ID”.
To nam wszystko załatwia klasa BaseResponse.
Klasa DataResponse
Jak widzisz, DataResponse dziedziczy po BaseResponse. Jedyną różnicą jest to, że DataResponse przechowuje dodatkowo dane, które mogły przyjść w odpowiedzi. Teraz, mając takie klasy, możemy zmienić zwracany typ z interfejsów IClientOperations i IOrderOperations. Do tej pory wyglądało to tak:
public interface IClientOperations
{
public Task<ClientDto> AddClient(ClientDto data);
public Task<GetClientsResultDto> GetClients(GetClientsRequestDto data);
public Task<ClientDto> GetClientById(int id);
public Task<bool> DeleteClient(int id);
}
public interface IOrderOperations
{
public Task<OrderDto> AddOrder(OrderDto order);
public Task<GetOrdersResultDto> GetOrdersForClient(int clientId, GetOrdersRequestDto data);
public Task<GetOrdersResultDto> GetOrders(GetOrdersResultDto data);
public Task<bool> DeleteOrder(int id);
}
A teraz będziemy mieli coś takiego:
public interface IClientOperations
{
public Task<DataResponse<ClientDto>> AddClient(ClientDto data);
public Task<DataResponse<GetClientsResultDto>> GetClients(GetClientsRequestDto data);
public Task<DataResponse<ClientDto>> GetClientById(int id);
public Task<BaseResponse> DeleteClient(int id);
}
public interface IOrderOperations
{
public Task<DataResponse<OrderDto>> AddOrder(OrderDto order);
public Task<DataResponse<GetOrdersResultDto>> GetOrdersForClient(int clientId, GetOrdersRequestDto data);
public Task<DataResponse<GetOrdersResultDto>> GetOrders(GetOrdersResultDto data);
public Task<BaseResponse> DeleteOrder(int id);
}
Interfejs IApiClient
Skoro mamy już interfejsy dla poszczególnych operacji, możemy teraz napisać sobie interfejs do ApiClienta. I tutaj znów – ta abstrakcja nie jest konieczna. Jednak bez niej nie będziesz w stanie testować jednostkowo kodu, który używa klienta API.
Jak widzisz, klient API będzie dawał dostęp do poszczególnych operacji. To teraz zajmijmy się implementacją poszczególnych operacji, która zasadniczo będzie prosta.
Implementacja IClientOperations
Do komunikacji z WebApi wykorzystujemy HttpClient – dlatego też on musi znaleźć się w konstruktorze.
internal class ClientOperations : IClientOperations
{
private readonly HttpClient _httpClient;
public ClientOperations(HttpClient httpClient)
{
_httpClient = httpClient;
}
public async Task<DataResponse<ClientDto>> AddClient(ClientDto data)
{
var response = await _httpClient.PostAsJsonAsync("clients", data);
return await ResponseFactory.CreateDataResponse<ClientDto>(response, DefaultJsonSerializerOptions.Options);
}
public async Task<BaseResponse> DeleteClient(int id)
{
var response = await _httpClient.DeleteAsync($"clients/{id}");
return await ResponseFactory.CreateBaseResponse(response);
}
public async Task<DataResponse<ClientDto>> GetClientById(int id)
{
var response = await _httpClient.GetAsync($"clients/{id}");
return await ResponseFactory.CreateDataResponse<ClientDto>(response, DefaultJsonSerializerOptions.Options);
}
public async Task<DataResponse<GetClientsResultDto>> GetClients(GetClientsRequestDto data)
{
var response = await _httpClient.PostAsJsonAsync("clients/all", data);
return await ResponseFactory.CreateDataResponse<GetClientsResultDto>(response, DefaultJsonSerializerOptions.Options);
}
}
Dalej mamy implementację poszczególnych metod. Każda z nich jest oparta dokładnie na tej samej zasadzie:
wyślij żądanie na odpowiednią końcówkę
stwórz DataResponse/BaseResponse na podstawie otrzymanej odpowiedzi – HttpResponseMessage.
Zwróć uwagę tutaj na trzy rzeczy.
Klasa DefaultJsonSerializerOptions – jest to klasa, która trzyma domyślne dla aplikacji ustawienia serializacji JSON. W naszej aplikacji nie chcemy, żeby serializacja brała pod uwagę wielkość znaków. Jeśliby brała wtedy taki obiekt:
public class MyClass
{
public int Id { get; set; }
public string Name { get; set; }
}
nie zostałby powiązany z takim jsonem:
{
"id": 5,
"name": "Adam"
}
Z tego powodu, że występuje różnica w wielkości znaków. Niestety domyślne ustwienia serializatora z Microsoft biorą pod uwagę wielkość znaków. My chcemy tego uniknąć, dlatego powstała klasa, która przechowuje odpowiednie opcje. Znajduje się w projekcie Common.
ResponseFactory to pomocnicza klasa, która z odpowiedzi HttpRequestMessage tworzy interesujące nas obiekty DataResponse lub BaseResponse – omówimy ją za chwilę.
Pobieranie danych za pomocą POST…
No właśnie, spójrz na metodę GetClients. Ona pobiera dane za pomocą POST, a nie GET. Dlaczego tak jest? Czyżby to jaka herezja?
Przyczyną jest obecność klasy GetClientsRequestDto:
public class GetClientsRequestDto
{
public int Skip { get; set; }
public int Take { get; set; }
}
Metoda GET nie może mieć żadnych danych w ciele żądania. Oczywiście w tym przypadku można by te dwie właściwości włączyć do query stringa, wywołując końcówkę np: api/clients/all?skip=0&take=10. Jeśli jednak masz sporo więcej do filtrowania, do tego jakieś sortowanie i inne rzeczy… lub z jakiegoś powodu takie dane nie powinny być w query stringu, to spokojnie możesz je wrzucić do POSTa. Nikt Cię za to nie wychłosta 😉 Co więcej – to jest normalną praktyką w niektórych WebAPI.
ResponseFactory
Jak już wspomniałem, klasa ResponseFactory jest odpowiedzialna za utworzenie BaseResponse/DataResponse na podstawie przekazanego HttpResponseMessage. Jej implementacja w naszym przykładzie wygląda tak:
internal static class ResponseFactory
{
public static async Task<BaseResponse> CreateBaseResponse(HttpResponseMessage response)
{
if (response.IsSuccessStatusCode)
return new BaseResponse((int)response.StatusCode);
else
return new BaseResponse((int)response.StatusCode, await GetErrorMsgFromResponse(response));
}
public static async Task<DataResponse<T>> CreateDataResponse<T>(HttpResponseMessage response, JsonSerializerOptions jsonOptions)
{
if (response.IsSuccessStatusCode)
{
T data = await GetDataFromResponse<T>(response, jsonOptions);
return new DataResponse<T>(data, (int)response.StatusCode);
}
else
{
return new DataResponse<T>(default(T), (int)response.StatusCode, await GetErrorMsgFromResponse(response));
}
}
private static async Task<T> GetDataFromResponse<T>(HttpResponseMessage response, JsonSerializerOptions jsonOptions)
{
string content = await response.Content.ReadAsStringAsync();
return JsonSerializer.Deserialize<T>(content, jsonOptions);
}
private static async Task<string> GetErrorMsgFromResponse(HttpResponseMessage response)
{
string result = await response.Content.ReadAsStringAsync();
if (string.IsNullOrEmpty(result))
return response.ReasonPhrase;
else
return result;
}
}
Nie ma tu niczego skomplikowanego. Wszystko sprowadza się do tego, że odczytuję dane z contentu odpowiedzi i deserializuję je do odpowiedniego obiektu. To wszystko. Jedyne, co może być ciekawe to metoda GetErrorMsgFromResponse, która ma zwrócić komunikat błędu. Zakładam, że jeśli błąd wystąpi, zostanie umieszczony po prostu jako content odpowiedzi – tak jest skonstruowane przykładowe WebAPI.
Implementacja IOrderOperations
Jest analogiczna jak IClientOperations, dlatego też nie będę jej omawiał. Kod wygląda tak:
internal class OrderOperations : IOrderOperations
{
private readonly HttpClient _httpClient;
public OrderOperations(HttpClient httpClient)
{
_httpClient = httpClient;
}
public async Task<DataResponse<OrderDto>> AddOrder(OrderDto order)
{
var response = await _httpClient.PostAsJsonAsync("orders", order);
return await ResponseFactory.CreateDataResponse<OrderDto>(response, DefaultJsonSerializerOptions.Options);
}
public async Task<BaseResponse> DeleteOrder(int id)
{
var response = await _httpClient.DeleteAsync($"orders/{id}");
return await ResponseFactory.CreateBaseResponse(response);
}
public async Task<DataResponse<GetOrdersResultDto>> GetOrders(GetOrdersResultDto data)
{
var response = await _httpClient.PostAsJsonAsync("orders/all", data);
return await ResponseFactory.CreateDataResponse<GetOrdersResultDto>(response, DefaultJsonSerializerOptions.Options);
}
public async Task<DataResponse<GetOrdersResultDto>> GetOrdersForClient(int clientId, GetOrdersRequestDto data)
{
var response = await _httpClient.PostAsJsonAsync($"orders/client/{clientId}", data);
return await ResponseFactory.CreateDataResponse<GetOrdersResultDto> (response, DefaultJsonSerializerOptions.Options);
}
}
Implementacja ApiClient
OK, nadszedł wreszcie czas na napisanie implementacji głównego klienta API:
public class ApiClient : IApiClient
{
public IClientOperations ClientOperations { get; private set; }
public IOrderOperations OrderOperations { get; private set; }
private readonly HttpClient _httpClient;
public ApiClient(HttpClient httpClient)
{
_httpClient = httpClient;
ClientOperations = new ClientOperations(_httpClient);
OrderOperations = new OrderOperations(_httpClient);
}
}
Tutaj HttpClient przychodzi z dependency injection. Następnie są tworzone odpowiednie obiekty – ClientOperations i OrderOperations, do których przekazujemy tego HttpClienta. Prawda, że proste?
HttpPipeline, czyli zupełnie nowy świat
Żeby klient API był wymuskany, można do niego dodać HttpPipeline. Pisałem o tym w tym artykule, więc nie będę się powtarzał. Zostawię Ci tylko zajawkę, że dzięki Http Pipeline, możesz zrobić zupełnie wszystko z żądaniem (zanim dotrze do celu) i odpowiedzią (zanim wróci do HttpClient). To zupełnie nowy świat możliwości. Przede wszystkim możesz automatycznie ustawiać wersję API, możesz odświeżać bearer token, możesz logować całe żądanie. Nic Cię tu nie ogranicza. Dlatego koniecznie przeczytaj ten artykuł, żeby mieć pełen obraz.
Przykładowe użycie
W repozytorium do tego artykułu jest umieszczony projekt WebApp – jest to bardzo prosta aplikacja RazorPages, które po krótce pokazuje użycie klienta.
UWAGA! Kod w aplikacji przykładowej jak i w WebApi jest podatny na różne rodzaje ataków. Dlatego nie stosuj takich „uproszczeń” w prawdziwym życiu. Różne ataki i jak się przed nimi chronić zostały opisane w tej książce.
W ramach ćwiczeń możesz spróbować zaimplementować w tym rozwiązaniu paginację, a także resztę operacji związanych z zamówieniami.
Dzięki za przeczytanie artykułu. Mam nadzieję, że teraz będziesz przykładał większą wagę do klientów API, które tworzysz i artykuł podpowiedział Ci jak to zrobić dobrze. Jeśli czegoś nie zrozumiałeś lub znalazłeś jakiś błąd, koniecznie daj znać w komentarzu 🙂
Jak zapewne wiesz, sercem .Net jest middleware pipeline. To sprawia, że możemy sobie napisać dowolny komponent i wpiąć go w łańcuch przetwarzania żądania.
Jednak HttpClient też posiada swój „rurociąg”. Możesz napisać małe komponenty, które w odpowiedni sposób będą procesować żądanie. Dzięki temu możemy osiągnąć naprawdę bardzo fajne efekty, np. zautomatyzować wersjonowanie żądań albo odnawianie bearer tokena. W tym artykule pokażę Ci oba takie przykłady.
Czym jest HttpMessageHandler?
HttpMessageHandler zajmuje się najbardziej podstawową obsługą komunikatów. Każdy HttpClient zawiera HttpMessageHandler (domyślnie HttpClientHandler).
Czyli wyobraź sobie, jakby HttpClient był panem, który każe wysłać wiadomość, a MessageHandler był takim gołębiem pocztowym, który dalej się tym już zajmuje. To jest jednak klasa abstrakcyjna, po której dziedziczy kilka innych, m.in. DelegatingHandler, jak też wspomniany HttpClientHandler – gołąb pocztowy.
Czym jest DelegatingHandler?
I tu dochodzimy do sedna. DelegatingHandler to klasa, którą możesz wpiąć w łańcuch handlerów. Co więcej, każdy DelegatingHandler ma pod spodem HttpClientHandlera, który służy do faktycznego, fizycznego przekazania wiadomości.
To brzmi trochę jak czeskie kino, więc wejdźmy w przykład. Stwórzmy handler, który zapisze w logach wiadomość, że odbywa się żądanie.
Jak widać na załączonym obrazku, trzeba zrobić 3 rzeczy:
napisać klasę dziedziczącą po DelegatingHandler
przeciążyć metodę Send/SendAsync
wywołać Send/SendAsync z klasy bazowej.
Dopiero wywołanie SendAsync z klasy bazowej pchnie cały request do Internetów. Czyli, jeśli byś chciał, mógłbyś napisać takiego handlera, który niczego nie przepuści i zwróci jakiś ResponseMessage z dowolnym kodem.
Mając takiego handlera, musimy go wpiąć do pipeline’a http. Można to zrobić na dwa sposoby.
Rejestracja Handlera
Generalnie rejestrujemy go podczas rejestrowania serwisów. Konkretnie – podczas rejestrowania HttpClienta. O prawidłowym użyciu HttpClienta i tworzeniu go przez fabrykę, pisałem w tym artykule.
Najpierw rejestrujemy naszego handlera w DependencyInjection. Potem rejestrujemy HttpClient i dodajemy do niego naszego handlera przez metodę AddHttpMessageHandler. Pamiętaj tylko, żeby doinstalować z NuGeta paczkę Microsoft.Extensions.Http.
Tutaj możesz zarejestrować cały łańcuch takich handlerów. Oczywiście kolejność jest istotna. Handlery będą się wykonywały w kolejności ich rejestracji.
Jest jeszcze druga metoda. Jeśli z jakiegoś powodu tworzysz HttpClient ręcznie, możesz też utworzyć instancje swoich handlerów i umieścić jednego w drugim – jak w ruskiej babie, np:
services.AddScoped<LoggerHandler>();
services.AddScoped(sp =>
{
var loggerHandler = sp.GetRequiredService<LoggerHandler>();
var otherHandler = new OtherHandler();
loggerHandler.InnerHandler = otherHandler;
otherHandler.InnerHandler = new HttpClientHandler();
var client = new HttpClient(loggerHandler);
return client;
});
Spójrz, co ja tutaj robię. Na początku rejestruję LoggerHandler w dependency injection. Nie muszę tego oczywiście robić, ale mogę 🙂
Potem rejestruję fabrykę dla HttpClienta – tzn. metodę fabryczną (nie myl z HttpClientFactory) – ta metoda utworzy HttpClient, gdy będzie potrzebny.
I teraz w tej metodzie najpierw tworzę (za pomocą Dependency Injection) swój handler – LoggerHandler, potem tworzę jakiś inny handler o nazwie OtherHandler i teraz robię całą magię.
W środku LoggerHandlera umieszczam OtherHandlera. A w środku OtherHandlera umieszczam HttpClientHandler – bo jak pisałem wyżej – na samym dole zawsze jest HttpClientHandler (gołąb pocztowy), który zajmuje się już fizycznie przekazaniem message’a.
Czyli mamy LoggerHandlera, który ma w sobie OtherHandlera, który ma w sobie ostatnie ogniwo łańcucha – HttpClientHandlera.
Na koniec tworzę HttpClient, przekazując mu LoggerHandlera.
Oczywiście zgodnie z tym artykułem przestrzegam Cię przed takim tworzeniem HttpClienta. Zawsze na początku idź w stronę HttpClientFactory.
Do roboty – wersjonowanie API
W tym akapicie pokażę Ci bardzo prosty handler, który dodaje informację o wersji żądanego API.
O wersjonowaniu API pisałem już kiedyś tutaj. Napisałem w tym artykule: „Jeśli tworzę API, a do tego klienta, który jest oparty o HttpClient, bardzo lubię dawać informację o wersji w nagłówku. Wtedy w kliencie mam wszystko w jednym miejscu i nie muszę się martwić o poprawne budowanie ścieżki„
W momencie, gdy zaczynamy zabawę z handlerami, ten argument o wyższości przekazywania wersji w nagłówku jest już trochę inwalidą. No bo przecież handler nam wszystko załatwi.
Załóżmy, że chcemy wywołać taką końcówkę: https://example.com/api/v1/clients
Normalnie w każdym wywołaniu requesta z HttpClienta musielibyśmy dbać o tę wersję:
httpClient.GetAsync("api/v1/clients");
ale, używając odpowiedniego DelegatingHandlera ten problem nam odpada i końcówkę możemy wywołać tak:
Cała magia dzieje się w metodzie CreateUriWithVersion.
Na początku posługuję się magiczną klasą UriBuilder. Biorę część, która nazywa się Path (czyli np: /api/clients zamiast całego https://example.com/api/clients) i rozwalam ją na poszczególne elementy.
Teraz na tej liście szukam fragmentu ścieżki „api”. Jeśli nie znajdę, to znaczy że to nie jest ścieżka do wersjonowania i zwracam oryginalne Uri. Jeśli jednak znajdę, to dodaję info o wersji do tej listy. Na koniec wszystko łączę z powrotem do jednego stringa, uzyskując: /api/v1/clients.
Jak widzisz w metodzie SendAsync – swobodnie mogę sobie działać na wychodzącej wiadomości i nawet zmienić jej endpoint, na który strzela – co też czynię w tym momencie.
Na koniec wywołuję bazowe SendAsync, które wychodzi już na dobrą drogę z wersją: https://example.com/api/v1/clients.
Odświeżanie bearer tokena
To jest zdecydowanie bardziej użyteczny przypadek. Jeśli nie wiesz co to Bearer Token i jak działa uwierzytelnianie w API, koniecznie przeczytaj ten artykuł zanim pójdziesz dalej.
Generalnie, jeśli wyślesz jakieś żądanie z ustawionym Bearer Tokenem i dostaniesz odpowiedź 401 to znaczy, że token jest niepoprawny – jeśli wcześniej działał, to wygasł. W tym momencie trzeba go odświeżyć. Możemy w tym celu posłużyć się Delegating Handlerem. I wierz mi – zanim poznałem ten mechanizm, robiłem to na inne sposoby, ale DelegatingHandler jest najlepszym, najprostszym i najczystszym rozwiązaniem. A robię to w taki sposób:
public class AuthDelegatingHandler: DelegatingHandler
{
private readonly ILogger<AuthDelegatingHandler> _logger;
private readonly IAuthTokenProvider _tokenProvider;
public AuthDelegatingHandler(ILogger<AuthDelegatingHandler> logger, IAuthTokenProvider tokenProvider)
{
_logger = logger;
_tokenProvider = tokenProvider;
}
protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
{
await AssignAuthHeader(request);
var response = await base.SendAsync(request, cancellationToken);
if (response.StatusCode == HttpStatusCode.Unauthorized)
{
if (!await TryRefreshingTokens(request))
return response;
else
{
await AssignAuthHeader(request);
return await base.SendAsync(request, cancellationToken);
}
}
else
return response;
}
private async Task AssignAuthHeader(HttpRequestMessage request)
{
TokenInfo tokens = await _tokenProvider.ReadToken();
if (tokens == null)
{
request.Headers.Authorization = null;
return;
}
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", tokens.AccessToken);
}
private async Task<bool> TryRefreshingTokens(HttpRequestMessage request)
{
_logger.LogInformation("Unauthorized, trying reauthorization");
var rtResponse = await CallRefreshEndpoint(request);
if (!rtResponse.IsSuccessStatusCode)
return false;
else
{
await ExchangeTokens(rtResponse);
return true;
}
}
private async Task<HttpResponseMessage> CallRefreshEndpoint(HttpRequestMessage request)
{
using var refreshRequest = new HttpRequestMessage();
try
{
var currentTokens = await _tokenProvider.ReadToken();
refreshRequest.Method = HttpMethod.Post;
refreshRequest.Content = JsonContent.Create(currentTokens);
refreshRequest.RequestUri = GetTokenRefreshEndpoint(request);
return await base.SendAsync(refreshRequest, CancellationToken.None);
}catch(Exception ex)
{
_logger.LogError(ex, "");
throw;
}
}
private Uri GetTokenRefreshEndpoint(HttpRequestMessage request)
{
var baseAddress = request.RequestUri.GetLeftPart(UriPartial.Authority);
var baseUri = new Uri(baseAddress);
var endpointPart = "api/token/refresh";
return new Uri(baseUri, endpointPart);
}
private async Task ExchangeTokens(HttpResponseMessage msg)
{
JsonSerializerOptions o = new();
o.FromTradesmanDefaults();
TokenResultDto data = await msg.Content.ReadFromJsonAsync<TokenResultDto>(o);
TokenInfo ti = new TokenInfo
{
AccessToken = data.AccessToken,
RefreshToken = data.RefreshToken
};
await _tokenProvider.WriteToken(ti);
}
}
A teraz wyjaśnię Ci ten kod krok po kroku.
Przede wszystkim wstrzykuję do tej klasy interfejs IAuthTokenProvider. To jest mój własny interfejs. Zadaniem klasy, która go implementuje jest zapisanie i odczytanie informacji o tokenach – bearer token i refresh token. Miejsce i sposób zapisu zależy już ściśle od konkretnego projektu. W aplikacji desktopowej lub mobilnej może to być po prostu pamięć. W aplikacji internetowej (np. Blazor) może to być local storage. Unikałbym zapisywania takich informacji w ciastkach, ponieważ ciastka są wysyłane przez sieć z każdym żądaniem. LocalStorage to miejsce do przetrzymywania danych na lokalnym komputerze. Dane tam trzymane nigdzie nie wychodzą. Dlatego to jest dobre miejsce jeśli chodzi o aplikacje internetowe.
Czyli po prostu odczytuję informacje o tokenach. Jeśli ich nie ma, to znaczy, że albo nastąpiło wylogowanie, albo tokeny jeszcze nie zostały uzyskane. W takim przypadku upewniam się, że nagłówek autoryzacyjny nie istnieje.
Jeśli jednak tokeny istnieją, to wystarczy utworzyć nagłówek autoryzacyjny.
W kolejnym kroku po prostu przesyłam żądanie z nagłówkiem autoryzacyjnym:
I teraz tak, w drugiej linijce przesyłam żądanie dalej. I sprawdzam odpowiedź. I jeśli odpowiedź jest inna niż 401, zwracam tą odpowiedź i fajrant. Jeśli jednak otrzymałem zwrotkę 401 – Unauthorized, to tak jak pisałem wcześniej – prawdopodobnie bearer token wygasł i trzeba go odświeżyć. A robię to w taki sposób:
Spójrz na metodę CallRefreshEndpoint, bo ona jest tutaj sercem.
Na początku tworzę zupełnie nowy RequestMessage. Ustawiam go tak, żeby strzelił na końcówkę do odświeżania tokenów i wysyłam. Tak więc, jak widzisz mogę przesłać zupełnie inny message niż ten, który dostałem.
W każdym razie dostaję zwrotkę, która mogła się zakończyć wydaniem nowych tokenów. Jeśli tak, to podmieniam je na stare. I spójrz teraz ponownie na metodę SendAsync:
Jeśli nie udało się odświeżyć tokenów (Refresh Token też mógł wygasnąć), wtedy nie robę już niczego więcej, po prostu zwracam odpowiedź do aplikacji. Teraz aplikacja może zarządzić, co zrobić z takim klopsem. Może np. pokazać stronę do logowania.
Jeśli jednak udało się odświeżyć tokeny, to ponownie przypisuję nagłówek autoryzacyjny (z nowym bearer tokenem) i jeszcze raz przesyłam oryginalną wiadomość. W tym momencie autoryzacja powinna się już powieść.
Handlery są łańcuchem
Pamiętaj, że DelegatingHandlers działają jak łańcuch. Czyli pierwszy uruchamia drugi, drugi trzeci itd. Jeśli wywołujesz metodę base.SendAsync, to do roboty rusza kolejny handler w łańcuchu. Aż w końcu dochodzi do HttpClientHandler, który fizycznie przesyła komunikat do serwera.
Czyli nie obawiaj się rekurencji. Jeśli wywołujesz base.SendAsync, to nie dostaniesz tego żądania w tym handlerze, tylko w kolejnym.
Dzięki za przeczytanie artykułu. Mam nadzieję, że w głowie pojawiły Ci się pomysły, jak można wykorzystać delegating handlery na różne sposoby. Jeśli czegoś nie zrozumiałeś lub znalazłeś błąd w artykule, koniecznie 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
