Konfiguracja i opcje programu w .NET

Konfiguracja i opcje programu w .NET

Wstęp

Z tego artykułu dowiesz się na czym polega konfiguracja w .NET i jak odczytywać ustawienia na różne sposoby w swoich klasach (IOptions, IOptionsSnapshot, IOptionsMonitor), a także czym są opcje nazwane (named options).

Konfiguracja w .NET to nie tylko IConfigure, czy też IOptions. To naprawdę bardzo fajnie przemyślany mechanizm, który zdecydowanie warto poznać.

Na szybko (kliknij, by rozwinąć)

Jak odczytać ustawienia zagnieżdżone?

Posłuż się dwukropkiem, np. jeśli w plik appsettings.json masz konfigurację:

{
  "ConnectionStrings": {
      "MainConnectionString": "cs"
   }
}

To główny connection string możesz pobrać tak:

string mainCs = Configuration["ConnectionStrings:MainConnectionString"];

Jak odczytać ustawienia do obiektu POCO?

Załóżmy, że masz taki plik appsettings.json:

{
"EmailSettings": {
  "SmtpAddress": "https://smtp.example.com",
  "From": "Admin",
  "FromEmail": "admin@example.com"
}
}

I analogiczną klasę – klasa musi mieć publicznie dostępne właściwości do zapisu i odczytu:

public class EmailOptions
{
    public string SmtpAddress { get; set; }
    public string From { get; set; }
    public string FromEmail { get; set; }
}

Teraz musisz skonfigurować te opcje:

services.Configure<EmailOptions>(Configuration.GetSection("EmailSettings"));

Na koniec możesz odczytać ich wartości w poszczególnych obiektach za pomocą IOptions<T>, IOptionsSnapshot<T> lub IOptionsMonitor<T> – szczegółowo to jest opisane niżej

Dlaczego .NET nie odczytuje zmiennych środowiskowych do konfiguracji?

Spokojnie, odczytuje. Jeśli uruchamiasz aplikację z wiersza poleceń przez dotnet run, to po zmianie zmiennych środowiskowych zrestartuj wiersz poleceń. Jeśli uruchamiasz z Visual Studio – to po zmianie zrestartuj Visual Studio. Szczegóły w treści artykułu.

appsettings, czy nie appsettings… – czyli dostawcy konfiguracji

Być może nie wiesz, ale w .NET nie musisz trzymać konfiguracji w pliku appsettings. Co więcej, NIE jest to zalecane miejsce dla danych wrażliwych – tak jak skrupulatnie przekonują Cię o tym tutoriale na YouTube.

Jest wiele miejsc, w których możesz trzymać swoją konfigurację (zwłaszcza wrażliwe dane) i sam nawet możesz dopisać własne mechanizmy (np. odczyt konfiguracji z rejestru przy aplikacji desktopowej).

Taki mechanizm odczytywania danych nazywa się configuration provider – czyli dostawca konfiguracji. W .NET masz do dyspozycji kilku takich dostawców, którzy są w stanie pobrać Twoją konfigurację z miejsc takich jak:

  • plik appsettings.json
  • zmienne środowiskowe
  • Azure Key Vault (polecam do trzymania danych wrażliwych)
  • argumenty linii poleceń

Odczytywanie konfiguracji

Tworząc aplikację poprzez WebApplication.CreateBuilder lub Host.CreateDefaultBuilder, dodajemy m.in. kilku domyślnych providerów, którzy odczytują konfigurację z różnych miejsc i wszystko umieszczają w jednym obiekcie IConfiguration (a konkretniej, to providerzy ze swoimi danymi siedzą w IConfiguration). Konfiguracja jest dostarczana w dwóch etapach (w kolejności):

  1. Konfiguracja hosta, w której są odczytywane:
    • zmienne środowiskowe z prefixem DOTNET_
    • zmienne środowiskowe z prefixem DOTNET_ z pliku launchSettings.json
    • zmienne środowiskowe z prefixem ASPNETCORE_
    • zmienne środowiskowe z prefixem ASPNETCORE_ z pliku launchSettings.json (przy czym specjalna zmienna: ASPNETCORE_ENVIRONMENT wskazuje na aktualne środowisko (produkcja, development, staging -> to jest ładowane do HostingEnvironment. Jeśli tej zmiennej nie ma, to .NET traktuje to jako środowisko produkcyjne)
    • parametry z linii poleceń
  2. Konfiguracja aplikacji – w tym momencie znamy już HostingEnvironment (czyli wiadomo, czy to produkcja, develop, staging…)
    • konfiguracja z pliku appsettings.json
    • konfiguracja z pliku appsettings.environment.json – gdzie „environment” to określenie aktualnego środowiska („Production”, „Development”, „Staging”…)
    • konfiguracja z secrets.json
    • wszystkie zmienne środowiskowe

Pamiętaj, żeby nigdy nie odczytywać aktualnego środowiska z konfiguracji: Configuration["ASPNETCORE_ENVIRONMENT"], bo może to być błędne. Środowisko jest trzymane w IHostingEnvironment i to tego powinieneś używać do odczytu.

Dlaczego możesz się na tym przejechać? Załóżmy, że ktoś z jakiegoś powodu wpisze ustawienie ASPNETCORE_ENVIRONMENT do pliku appsettings.json. I już będzie klops. Bo owszem, ustawienie w obiekcie IConfiguration zostanie „nadpisane”, jednak IHostingEnvironment będzie trzymał zupełnie inne dane.

Co z tymi zmiennymi środowiskowymi i co to launchSettings.json?

Dlaczego .NET nie odczytuje zmiennych środowiskowych?

Czasami możesz odnieść takie wrażenie, że to po prostu nie działa. Też tak miałem, dopóki nie zdałem sobie sprawy z tego, jak naprawdę działają zmienne środowiskowe.

Program odczytuje te zmienne w momencie swojego uruchamiania. I to jest najważniejsze zdanie w tym akapicie. Zmienne środowiskowe nie są „aktualizowane” w aplikacji. Jeśli uruchomisz swoją aplikację z wiersza poleceń (dotnet run), to Twój program otrzyma takie zmienne jakie otrzymał wiersz poleceń podczas swojego uruchamiania.

Jeśli uruchamiasz program z VisualStudio, to Twój program otrzyma takie zmienne, jakie dostał VisualStudio podczas swojego uruchamiania.

Dlatego, jeśli zmieniasz wartości zmiennych środowiskowych, pamiętaj żeby zrestartować wiersz poleceń / Visual Studio. Wtedy Twoja aplikacja dostanie aktualne zmienne.

Jeśli zmieniasz zmienne na poziomie IIS, zrestartuj IIS.

Jest to pewna upierdliwość. Dlatego mamy plik launchSettings.json, w którym możesz sobie poustawiać różne zmienne środowiskowe. Te zmienne będą odczytywane podczas każdego uruchamiania Twojego programu – nie musisz niczego restartować.

Oczywiście pamiętaj, że plik launchSettings.json służy tylko do developmentu. Więc jeśli poustawiasz tam jakieś zmienne, których używasz, pamiętaj żeby ustawić je też na środowisku produkcyjnym.

Nie zdradzaj tajemnicy, czyli secrets.json

Domyślne pliki z ustawieniami – appsettings.json i appsettings.Development.json są przesyłane do repozytorium kodu. Jeśli pracujesz w zamkniętym zespole, to nie ma to większego znaczenia – dopóki w programie nie używasz jakiś swoich prywatnych subskrypcji.

Jeśli w plikach appsettings trzymasz dane wrażliwe (connection stringi, hasła, klucze), to miej świadomość, że one będą widoczne w repozytorium kodu i KAŻDY z dostępem będzie mógł z nich skorzystać (w szczególności GitHub).

Dlatego też powstał plik secrets.json. Aby go utworzyć/otworzyć, kliknij w Visual Studio prawym klawiszem myszy na swój projekt i z menu wybierz Manage User Secrets:

Możesz też użyć .NetCli i wykonać polecenie dotnet user-secrets

Wywołanie w VisualStudio otworzy Ci edytor tekstu taki sam jak dla pliku appsettings. Zresztą secrets.json ma dokładnie taką samą budowę.

Różnica między secrets.json a appsettings.json jest taka, że secrets.json nie znajduje się ani w katalogu z kodem (leży gdzieś tam w AppData), ani w repozytorium. Więc możesz sobie w nim bezkarnie umieszczać wszystkie klucze, hasła itd, których używasz w programie.

Oczywiście możesz mieć różne pliki sekretów w różnych projektach.

Gdzie dokładnie leży plik secrets.json?

W takiej lokalizacji: AppData\Roaming\Microsoft\UserSecrets\{Id sekretów}\secrets.json

Id sekretów to GUID, który jest przechowywany w pliku (csproj) konkretnego projektu.

Kolejność konfiguracji

Jak już zapewne wiesz – .NET odczytuje konfigurację w konkretnej kolejności – opisanej wyżej. A co jeśli w różnych miejscach (np. appsettings.json i secrets.json) będą ustawienia, które tak samo się nazywają? Nico. Ustawienia, które odczytują się później będą tymi aktualnymi. Czyli jeśli w pliku appsetting.json umieścisz:

"tajne-haslo" : ""

I to samo umieścisz w pliku secrets.json, który jest odczytywany później:

"tajne-haslo" : "admin123"

To z konfiguracji odczytasz „admin123”.

Dla wścibskich

Tak naprawdę te wartości nie są nadpisywane i przy odrobinie kombinowania możesz odczytać konkretne wartości z konkretnych miejsc (jako że IConfiguration nie trzyma bezpośrednio tych wartości, tylko ma listę ConfigurationProviderów). Domyślnie .NET szuka klucza „od tyłu” – w odwrotnej kolejności niż były dodawane do IConfiguration, ale moim zdaniem może to być szczegół implementacyjny, który w przyszłości może ulec zmianie. Jednak nie czytałem dokumentacji projektowej.

Pobieranie danych z konfiguracji

Prawdopodobnie to wiesz. Do klasy Startup wstrzykiwany jest obiekt implementujący IConfiguration i wtedy z niego możemy pobrać sobie dane, które nas interesują:

public IConfiguration Configuration { get; }

public Startup(IConfiguration configuration)
{
	Configuration = configuration;
}

//..
void Foo()
{
  string password = Configuration["tajne-haslo"];
}

Jeśli w konfiguracji masz bardziej zagnieżdżone dane, np:

{
  "EmailSettings": {
    "ServiceMailing": {
      "SmtpAddress": "https://smtp.example.com",
      "From": "Admin",
      "FromEmail": "admin@example.com"
    }
  }
}

posługujesz się dwukropkiem, żeby oddzielić kolejne poziomy, np:

string smtp = Configuration["EmailSettings:ServiceMailing:SmtpAddress"];

Jeśli chcesz tworzyć wielopoziomowe obiekty za pomocą zmiennych środowiskowych, to każdy poziom oddzielasz dwoma podkreślnikami: „__”, np:

setx EmailSettings__ServiceMailing__SmtpAddress "https://smtp.example.com" /M

To oczywiście podstawowe pobieranie danych z konfiguracji, przejdźmy teraz do fajniejszych rzeczy.

Tworzenie opcji dla programu

Dużo lepszym i fajniejszym rozwiązaniem jest tworzenie opcji dla komponentów Twojego programu. Załóżmy, że masz serwis do wysyłania e-maili. On może wyglądać tak:

public class EmailService
{
    const string OPTION_SMTP_ADDRESS = "https://smtp.example.com";
    const string OPTION_FROM = "Admin";
    const string OPTION_FROM_EMAIL = "admin@example.com";

    public void SendMail(string msg, string subject)
    {

    }
}

Albo jeszcze gorzej – tak:

public class EmailService
{
#if DEBUG
    const string OPTION_SMTP_ADDRESS = "https://smtp.local.example.com";
#else
    const string OPTION_SMTP_ADDRESS = "https://smtp.example.com";
#endif

    const string OPTION_FROM = "Admin";
    const string OPTION_FROM_EMAIL = "admin@example.com";

    public void SendMail(string msg, string subject)
    {

    }
}

I wtedy metoda SendMail będzie posługiwała się tymi nieszczęsnymi stałymi. Dużo lepszym rozwiązaniem byłoby trzymanie opcji w zupełnie innej klasie:

public class EmailOptions
{
    public string SmtpAddress { get; set; }
    public string From { get; set; }
    public string FromEmail { get; set; }
}

i wstrzyknięcie w jakiś sposób tych opcji do obiektu EmailService. Jest to możliwe. I zaraz pokażę Ci jak.

Konfiguracja opcji

Załóżmy, że Twój plik appsettings.json zawiera taki fragment:

"EmailSettings": {
  "SmtpAddress": "https://smtp.example.com",
  "From": "Admin",
  "FromEmail": "admin@example.com"
}

Tutaj najważniejsze jest to, jak masz nazwane poszczególne właściwości. Muszą być tak samo nazwane jak właściwości w Twojej klasie EmailOptions.

A w klasie EmailOptions to MUSZĄ być właściwości do publicznego odczytu i zapisu (nie mogą to być pola).

Jeśli już masz skonstruowaną klasę opcji (EmailOptions) i fragment konfiguracji (np. ten powyżej), możesz podczas konfiguracji serwisów dodatkowo skonfigurować te opcje:

services.Configure<EmailOptions>(Configuration.GetSection("EmailSettings"));

Czyli mówisz: „Klasa EmailOptions ma trzymać dane odczytane z sekcji w konfiguracji o nazwie „EmailSettings”.

Od teraz możesz klasę EmailOptions z wypełnionymi wartościami wstrzykiwać do swoich obiektów na trzy sposoby… Każdy z nich ma swoje wady i zalety.

Interfejs IOptions<T>

To pierwszy sposób pobrania opcji i chyba najprostszy. Wystarczy, że wstrzykniesz IOptions<T> do obiektu, w którym chcesz mieć swoją konfigurację:

public class EmailService
{
    EmailOptions options;

    public EmailService(IOptions<EmailOptions> options)
    {
        this.options = options.Value;  //pamiętaj, że opcje będziesz miał we właściwości Value
    }

    public void SendMail(string msg, string subject)
    {

    }
}

Zobacz jak sprytnie pozbyliśmy się tych brzydkich stałych z kodu na rzecz opcji trzymanych w odpowiednim obiekcie.

Plusy:

  • IOptions jest zarejestrowane jako singleton
  • Może być wstrzyknięte do każdego obiektu niezależnie od jego cyklu życia (Scoped, Singleton, czy Transient)

Minusy:

  • Odczytuje konfigurację TYLKO podczas uruchamiania systemu – to moim zdaniem jest najważniejsza kwestia. Przy niektórych opcjach to będzie wystarczające, przy innych nie.
  • Nie pozwala na „named options” (o tym za chwilę)

Interfejs IOptionsSnapshot<T>

Przykład wstrzyknięcia:

public EmailService(IOptionsSnapshot<EmailOptions> options)
{
    this.options = options.Value;
}

Czyli dokładnie tak samo. Różnice natomiast są trzy.

Plusy:

  • daje Ci aktualne opcje – nawet jeśli zmienią się w pliku – bez konieczności restartu aplikacji
  • obsługuje „named options”, o czym później

Minusy:

  • zarejestrowane jako scoped – odczytuje opcje z każdym requestem, jednak nie wstrzykniesz tego do serwisów rejestrowanych jako singleton.

Interfejs IOptionsMonitor<T>

To wygląda trochę jak hybryda dwóch poprzednich interfejsów.

  • jest rejestrowany jako singleton, więc może być wstrzyknięty do serwisu niezależnie od jego cyklu życia
  • potrafi zaktualizować opcje, gdy się zmienią – bez restartu aplikacji
  • obsługuje „named options”

Użycie tego jest nieco bardziej skomplikowane. Oto przykład:

IOptionsMonitor<EmailOptions> optionsMonitor;

public EmailService(IOptionsMonitor<EmailOptions> optionsMonitor)
{
    this.optionsMonitor = optionsMonitor;
}

public void SendMail(string msg, string subject)
{
    EmailOptions options = optionsMonitor.CurrentValue;
}

Pierwsza różnica jest taka, że nie trzymasz w swoim serwisie obiektu klasy EmailOptions tak jak to było do tej pory. Zamiast tego trzymasz cały monitor. A gdy potrzebujesz odczytać AKTUALNE opcje, posługujesz się właściwością CurrentValue tego monitora.

Teraz jeśli opcje fizycznie zostaną zmienione (np. w pliku appsettings.json), tutaj będziesz miał aktualne wartości – bez potrzeby restartowania aplikacji.

UWAGA! Zmiany zmiennych środowiskowych nie będą uwzględnione.

Czym są NamedOptions?

Spójrz na taki plik appsettings.json:

{
  "EmailSettings": {
    "ServiceMailing": {
      "SmtpAddress": "https://smtp.example.com",
      "From": "Admin",
      "FromEmail": "admin@example.com"
    },
    "NewsletterMailing": {
      "SmtpAddress": "https://smtp.news.example.com",
      "From": "John Rambo",
      "FromEmail": "john@news.example.com"
    }
  }
}

Masz tutaj różne ustawienia dla maili serwisowych i newslettera. Nie musisz tworzyć całej takiej struktury klas. Zwróć uwagę na to, że zarówno ServiceMailing jak i NewsletterMailing mają dokładnie takie same pola. Dokładnie też takie, jak klasa EmailOptions.

Możesz się tutaj posłużyć IOptionsSnapshot lub IOptionsMonitor, żeby wydobyć konkretne ustawienia (przypominam – IOptions nie obsługuje named options).

Najpierw trzeba jednak skonfigurować opcje, przekazując ich nazwy:

services.Configure<EmailOptions>("ServiceMailing", Configuration.GetSection("EmailSettings:ServiceMailing"));
services.Configure<EmailOptions>("NewsletterMailing", Configuration.GetSection("EmailSettings:NewsletterMailing"));

Zwróć uwagę tutaj na dwie rzeczy:

  • w pierwszym parametrze podajesz „nazwę zestawu opcji” – po tej nazwie będziesz później pobierał opcje do obiektu
  • w drugim pobierasz konkretną sekcję, w której są umieszczone te dane (tak jak do tej pory)

Teraz możesz odpowiednie opcje odczytać w taki sposób:

public class EmailService
{
    EmailOptions serviceMailOptions;
    EmailOptions newsletterMailOptions;

    public EmailService(IOptionsSnapshot<EmailOptions> options)
    {
        serviceMailOptions = options.Get("ServiceMailing");
        newsletterMailOptions = options.Get("NewsletterMailing");
    }
}

Odłóż wczytywanie opcji na później

Odraczanie czytywanie opcji może być przydatne dla twórców bibliotek. Więc jeśli tego nie robisz, możesz śmiało opuścić ten akapit. Jeśli Cię to interesuje, to rozwiń go:

Kliknij tu, żeby rozwinąć ten akapit

Przedstawię trochę bezsensowny przykład, ale dzięki temu załapiesz jak wczytywać konfigurację później.

Pomyśl sobie, że tworzysz jakąś bibliotekę do wysyłania maili. Użytkownik może ją skonfigurować jak w powyższych przykładach:

"EmailSettings": {
  "SmtpAddress": "https://smtp.example.com",
  "From": "Admin",
  "FromEmail": "admin@example.com"
}

Użytkownik może podać oczywiście dowolne dane. Ale Ty chcesz w swojej bibliotece mieć pewność, że jeśli FromEmail zawiera słowo „admin”, to pole From będzie zawierało „Admin”. Czyli konfiguracja taka jak poniżej będzie niepoprawna:

"EmailSettings": {
  "SmtpAddress": "https://smtp.example.com",
  "From": "John Rambo",
  "FromEmail": "admin@example.com"
}

Jako twórca biblioteki, stworzyłeś rozszerzenie dla IServiceCollection, które pozwala na konfigurację Twojej biblioteki:

public static IServiceCollection AddEmail(this IServiceCollection services, Action<EmailOptions> configureAction)
{
    EmailOptions emailOptions = new EmailOptions();
    configureAction(emailOptions);

    if (emailOptions.FromEmail.Contains("admin", StringComparison.InvariantCultureIgnoreCase))
        emailOptions.From = "Admin";

    services.Configure<EmailOptions>(options =>
    {
        options.SmtpAddress = emailOptions.SmtpAddress;
        options.FromEmail = emailOptions.FromEmail;
        options.From = emailOptions.From
    });

    services.AddSingleton<EmailService>();

    return services;
}

I niby wszystko jest ok. Na początku umożliwiasz użytkownikowi konfigurację, potem ją sprawdzasz i rejestrujesz odpowiednie opcje.

Użytkownik teraz może w ConfigureServices tak zarejestrować Twój serwis do maili:

services.AddEmail(o =>
{
	o.SmtpAddress = "smtp.example.com";
	o.FromEmail = "admin@example.com";
	o.From = "John Rambo";
});

I wszystko będzie OK. Twoje zabezpieczenie zadziała. Ale co jeśli użytkownik będzie chciał być sprytny i nadpisze ustawienia jeszcze raz?

services.AddEmail(o =>
{
	o.SmtpAddress = "smtp.example.com";
	o.FromEmail = "admin@example.com";
	o.From = "John Rambo";
});

services.Configure<EmailOptions>(o =>
{
	o.From = "John Rambo";
});

Wtedy EmailService otrzyma niepoprawne ustawienia (właściwość From znów będzie zawierała „John Rambo”).

Post konfiguracja

.NET przeprowadza konfigurację w dwóch etapach. Możesz posłużyć się metodą services.Configure lub services.PostConfigure.

.NET najpierw zbuduje CAŁĄ konfigurację, która została zarejestrowana metodą Configure (skrótowo powiedzmy, że „zbuduje wszystkie wywołania Configure”). A w drugim kroku zbuduje CAŁĄ konfigurację zarejestrowaną metodą PostConfigure. I teraz jeśli zmienisz kod swojej biblioteki:

public static IServiceCollection AddEmail(this IServiceCollection services, Action<EmailOptions> configureAction)
{
    EmailOptions emailOptions = new EmailOptions();
    configureAction(emailOptions);

    if (emailOptions.FromEmail.Contains("admin", StringComparison.InvariantCultureIgnoreCase))
        emailOptions.From = "Admin";

    services.PostConfigure<EmailOptions>(options =>
    {
        options.SmtpAddress = emailOptions.SmtpAddress;
        options.FromEmail = emailOptions.FromEmail;
        options.From = emailOptions.From;
    });

    services.AddSingleton<EmailService>();

    return services;
}

w taki sposób, że zamiast Configure użyjesz PostConfigure, to wszystko zadziała. EmailService otrzyma poprawne dane.

Pewnie zapytasz teraz – „No dobrze, a czy użytkownik nie może użyć PostConfigure i znowu nadpisać mi opcje?” – pewnie, że może i nadpisze. Tak jak mówiłem na początku – to niezbyt udany przykład, ale chyba załapałeś o co chodzi z odroczoną konfiguracją 🙂 Walidację opcji tak naprawdę powinno się robić inaczej…

Jeśli spotkałeś się z przykładem z życia, gdzie PostConfigure jest lepsze albo pełni ważną rolę – daj znać w komentarzu.

Dobre praktyki

Jest kilka dobrych praktyk, które powinieneś stosować przy opcjach i naprawdę warto je stosować. Zdecydowanie mogą ułatwić Ci życie.

Twórz różne środowiska

Przede wszystkim, twórz w swoim projekcie różne środowiska. Development i Production to obowiązkowe minimum. Po prostu upewnij się, że masz takie pliki:

  • appsettings.json – ustawienia dla wersji produkcyjnej
  • appsettings.Development.json – ustawienia dla wersji developerskiej.

Tych plików możesz tworzyć znacznie więcej, np:

  • appsettings.Staging.json – ustawienia dla wersji przedprodukcyjnej (ostateczne testy przed wydaniem)
  • appsettings.Testing.json – jakieś ustawienia np. dla testów integracyjnych
  • appsettings.Local.json – jakieś typowe ustawienia dla środowiska lokalnego – Twojego komputera, na którym piszesz kod.

Pamiętaj, że o środowisku świadczy zmienna środowiskowa ASPNETCORE_ENVIRONMENT. Ona musi przyjąć jedną z nazw Twoich środowisk (Development, Production, Staging…). Jeśli tej zmiennej nie ma w systemie – uznaje się, że jest to wersja produkcyjna.

Nie posługuj się w kodzie dyrektywami w stylu:

#if DEBUG
  connectionString = Configuration["ConnectionStrings:DevConnectionString"];
#else
  connectionString = Configuration["ConnectionStrings:MainConnectionString"];
#endif

Zamiast tego używaj różnych środowisk… SERIO.

Nie trzymaj danych wrażliwych w appsetings

Pamiętaj, że pliki appsettings*.json lądują w repozytorium kodu. Chyba, że zignorujesz je w swoim systemie kontroli wersji. Jeśli tworzysz plik appsettings.Local.json – powinieneś automatycznie wyrzucać go z kontroli wersji.

Do trzymania wrażliwych danych używaj pliku secrets.json lub (w przypadku produkcji) – Azure KeyVault – jak to zrobić opiszę w osobnym artykule (zapisz się na newsletter lub polub stronę na fejsie, żeby go nie przegapić :)).

Nie używaj stringów (jako identyfikatorów) bezpośrednio

To chyba dotyczy wszystkiego – nie tylko opcji. Posługuj się w tym celu stałymi lub operatorem nameof. Np. zamiast wklepywać:

services.Configure<EmailOptions>(Configuration.GetSection("EmailSettings")); //nazwa sekcji na sztywno

wykorzystaj stałe:

public class EmailOptions
{
    public const string EmailOptionsSectionName = "EmailSettings";
    public string SmtpAddress { get; set; }
    public string From { get; set; }
    public string FromEmail { get; set; }
}

//
services.Configure<EmailOptions>(Configuration.GetSection(EmailOptions.EmailOptionsSectionName));

Sprawdzaj poprawność swoich opcji

Swoje opcje możesz walidować przez DataAnnotation (standard) lub FluentValidation (osobna biblioteka) i faktycznie powinieneś to robić, jeśli opcje mają jakieś ograniczenia lub z jakiegoś powodu mogą być niepoprawne.

To jednak temat na osobny artykuł, który już zacząłem pisać 🙂 Zapisz się na newsletter lub polub Masterbranch na Facebooku, żeby go nie przegapić 🙂


To tyle, jeśli chodzi o zarządzanie opcjami w .NET. Jak pisałem wyżej – są jeszcze dwa aspekty, które na pewno będę chciał poruszyć w osobnych artykułach – walidajca opcji i odczytywanie opcji z Azure KeyVault. Być może napiszę też artykuł o tworzeniu własnego ConfigurationProvidera.

Jeśli znalazłeś w artykule jakiś błąd lub czegoś nie rozumiesz, koniecznie daj znać w komentarzu 🙂

Obrazek wyróżniający: Tło plik wektorowy utworzone przez mamewmy – pl.freepik.com

Podziel się artykułem na:
Entity Framework w osobnym projekcie

Entity Framework w osobnym projekcie

Jeśli szukasz szybkiego rozwiązania, kliknij tu. Jeśli chcesz się nieco więcej dowiedzieć, przeczytaj cały post.

Wstęp

Gdy tworzymy nową aplikację z identyfikacją użytkowników (Identity) w VisualStudio, domyślny kreator tworzy jeden projekt, do którego pcha wszystkie klasy. Do malutkich rzeczy, czy nauki to w zupełności wystarczy. Jednak w świecie rzeczywistym chcielibyśmy mieć osobny projekt do modeli i osobny projekt dla warstwy danych (Data Access Layer).

Niby nie jest to trudne, wystarczy przenieść nasz DbContext do innego projektu i już. A co z migracjami? Migracje nadal będą się tworzyć w projekcie głównym. Nie o to chodzi. Chcemy migracje też w projekcie z danymi.

Dlaczego to nie jest oczywiste?

Musisz zdać sobie sprawę z tego, jak działają migracje w Entity Framework (czy też EfCore), a także jak działa aktualizacja bazy danych.

Gdy uruchamiasz polecenie Add-Migration lub dotnet ef migrations add, narzędzie uruchamia Twoją główną aplikację. Uruchomienie aplikacji następuje w sposób normalny. Czyli przy aplikacji konsolowej, odpalona zostanie metoda Main. Przy aplikacji webowej, pójdzie cała konfiguracja.

Jednym z kroków jest inicjalizacja Entity Framework, np:

services.AddDbContext<ApplicationDbContext>(options =>
	options.UseSqlServer(
		Configuration.GetConnectionString("DefaultConnection")));

W tym momencie tworzymy połączenie z bazą danych i migracje mogą zostać utworzone. Pamiętaj, że do utworzenia migracji konieczne jest połączenie z bazą danych. Narzędzie musi sprawdzić, jak wygląda baza i jak wygląda model – musi mieć możliwość porównania tego.

Teraz jeśli uruchomisz migrację z parametrem -p, wskazując na konkretny projekt, np:

Add-Migration InitialDbCreate -p DataAccessLayer

Entity Framework będzie próbowało uruchomić projekt DataAccessLayer. Jeśli jest to zwykła biblioteka klas (class library), no to co się uruchomi? Nic. Dlatego też migracja nie będzie mogła się odbyć.

Ale można to nieco obejść. Narzędzie poszuka jeszcze klasy, która implementuje pewien interfejs. Jeśli znajdzie taką, utworzy jej obiekt i za jej pomocą skonfiguruje połączenie z bazą danych.

Rozwiązanie

  1. W swoim projekcie z danymi (tam, gdzie masz DbContext i chcesz mieć migracje) musisz utworzyć klasę implementującą specjalny interfejs IDesignTimeDbContextFactory. Ef właśnie tego poszuka (jeśli używasz Sql Servera, dodaj pakiet nuget: Microsoft.EntityFrameworkCore.SqlServer):
public class DbContextFactory : IDesignTimeDbContextFactory<ApplicationDbContext>
{
	public XMoneyDbContext CreateDbContext(string[] args)
	{
		DbContextOptionsBuilder<ApplicationDbContext> optionsBuilder = new DbContextOptionsBuilder<ApplicationDbContext>();

        optionsBuilder.UseSqlServer("tutaj Twój connection string")

        return new ApplicationDbContext(optionsBuilder.Options);
	}
}

Przeanalizujmy go:

  • deklarujesz fabrykę kontekstu bazy danych (Ef poszuka właśnie klasy implementującej ten interfejs), parametrem generycznym jest oczywiście Twój kontekst bazy danych.
  • najpierw tworzysz buildera do opcji kontekstu
  • ustawiasz opcje (np. UseSqlServer) i connection string
  • tworzysz swój kontekst i zwracasz go

I to właściwie tyle. Możesz już teraz uruchomić migrację z przełącznikiem -p:

Add-Migration NazwaMigracji -p NazwaTwojegoProjektu

lub

dotnet ef migrations add NazwaMigracji -p NazwaTwojegoProjektu

Podziel się artykułem na: