Konstruktory konfiguracji dla platformy ASP.NET

Przez Stephen Molloy i Rick Anderson

Konstruktorzy konfiguracji zapewniają nowoczesny i zwinny mechanizm dla aplikacji ASP.NET w celu uzyskania wartości konfiguracji ze źródeł zewnętrznych.

Konstruktorzy konfiguracji:

• Są dostępne w programie .NET Framework 4.7.1 lub nowszym.
• Zapewnij elastyczny mechanizm odczytywania wartości konfiguracji.
• Rozwiąż niektóre podstawowe potrzeby aplikacji podczas przechodzenia do środowiska skoncentrowanego na kontenerze i chmurze.
• Może służyć do poprawy ochrony danych konfiguracji przez pobieranie ze źródeł, które były wcześniej niedostępne (na przykład usługa Azure Key Vault i zmienne środowiskowe) w systemie konfiguracji platformy .NET.

Budowniki konfiguracji klucz/wartość

Typowym scenariuszem, który można obsłużyć przez konstruktorów konfiguracji, jest zapewnienie podstawowego mechanizmu wymiany klucza/wartości dla sekcji konfiguracji, które są zgodne ze wzorcem klucza/wartości. Koncepcja programu ConfigurationBuilders programu .NET Framework nie jest ograniczona do określonych sekcji lub wzorców konfiguracji. Jednak wiele konstruktorów konfiguracji w Microsoft.Configuration.ConfigurationBuilders (github, NuGet) działa w ramach schematu klucz/wartość.

Ustawienia narzędzi konfiguracyjnych klucz-wartość

Następujące ustawienia mają zastosowanie do wszystkich kompilatorów konfiguracji klucz-wartość w Microsoft.Configuration.ConfigurationBuilders.

Tryb

Konstruktorzy konfiguracji wykorzystują zewnętrzne źródło informacji z parami klucz-wartość, aby wypełnić wybrane elementy systemu konfiguracji. W szczególności sekcje <appSettings/> i <connectionStrings/> otrzymują specjalne traktowanie ze strony konstruktorów konfiguracji. Konstruktorzy działają w trzech trybach:

• Strict - Tryb domyślny. W tym trybie konstruktor konfiguracji działa tylko w dobrze znanych sekcjach konfiguracji opartych na kluczu/wartościach. Strict mode wylicza każdy klucz w sekcji . Jeśli w źródle zewnętrznym zostanie znaleziony pasujący klucz:

  • Konstruktorzy konfiguracji zastępują wartość w wynikowej sekcji konfiguracji wartością ze źródła zewnętrznego.

• Greedy - Ten tryb jest ściśle powiązany z Strict trybem. Zamiast ograniczać się do kluczy, które już istnieją w oryginalnej konfiguracji:

  • Konstruktorzy konfiguracji dodają wszystkie pary klucz/wartość z zewnętrznego źródła do wynikowej sekcji konfiguracji.

• Expand — Działa na nieprzetworzonym kodzie XML, zanim zostanie przeanalizowany w obiekcie sekcji konfiguracji. Można to traktować jako rozszerzenie tokenów w ciągu znaków. Każda część nieprzetworzonego ciągu XML zgodnego ze wzorcem ${token} jest kandydatem do rozszerzenia tokenu. Jeśli w źródle zewnętrznym nie zostanie znaleziona żadna odpowiadająca wartość, token nie zostanie zmieniony. Konstruktory w tym trybie nie są ograniczone do sekcji <appSettings/> i <connectionStrings/>.

Następujące znaczniki z pliku web.config umożliwiają program EnvironmentConfigBuilder w Strict trybie:

<configuration>

  <configSections>
    <section name="configBuilders" 
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="MyEnvironment"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="MyEnvironment">
    <add key="ServiceID" value="ServiceID value from web.config" />
    <add key="ServiceKey" value="ServiceKey value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="MyEnvironment">
    <add name="default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>

Poniższy kod odczytuje elementy <appSettings/> i <connectionStrings/> pokazane w poprzednim pliku web.config.

using System;
using System.Configuration;
using System.Web.UI;

namespace MyConfigBuilders
{
    public partial class About : Page
    {
        public string ServiceID { get; set; }
        public string ServiceKey { get; set; }
        public string ConString { get; set; }

        protected void Page_Load(object sender, EventArgs e)
        {
            ServiceID = ConfigurationManager.AppSettings["ServiceID"];
            ServiceKey = ConfigurationManager.AppSettings["ServiceKey"];
            ConString = ConfigurationManager.ConnectionStrings["default"]
                                            ?.ConnectionString;
        }
    }
}

Powyższy kod ustawi wartości właściwości na:

• Wartości w pliku web.config jeśli klucze nie są ustawione w zmiennych środowiskowych.
• Wartości zmiennej środowiskowej, jeśli są ustawione.

Na przykład ServiceID będzie zawierać:

• "Wartość ServiceID z pliku web.config", jeśli zmienna środowiskowa ServiceID nie jest ustawiona.
• Wartość zmiennej środowiskowej ServiceID , jeśli jest ustawiona.

Na poniższej ilustracji przedstawiono <appSettings/> klucze/wartości z poprzedniego pliku web.config ustawionego w edytorze środowiska:

Uwaga: może być konieczne zamknięcie i ponowne uruchomienie programu Visual Studio, aby zobaczyć zmiany w zmiennych środowiskowych.

Obsługa prefiksów

Prefiksy kluczy mogą uprościć ustawianie kluczy, ponieważ:

• Konfiguracja programu .NET Framework jest złożona i zagnieżdżona.
• Zewnętrzne źródła klucz/wartość są często podstawowe i płaskie z natury. Na przykład zmienne środowiskowe nie są zagnieżdżone.

Użyj dowolnego z następujących podejść, aby wstrzyknąć zarówno <appSettings/> jak i <connectionStrings/> do konfiguracji za pomocą zmiennych środowiskowych.

• W przypadku EnvironmentConfigBuilder w trybie domyślnym Strict i z odpowiednimi nazwami kluczy w pliku konfiguracji. Poprzedni kod i znaczniki przyjmują to podejście. Korzystając z tego podejścia, nie można mieć identycznych nazwanych kluczy zarówno w systemach , jak <appSettings/> i <connectionStrings/>.
• Użyj dwóch EnvironmentConfigBuilder w trybie Greedy z odrębnymi prefiksami i stripPrefix. Dzięki takiemu podejściu aplikacja może odczytywać <appSettings/> i <connectionStrings/> bez konieczności aktualizowania pliku konfiguracji. W następnej sekcji stripPrefix pokazano, jak to zrobić.
• Użyj dwóch komponentów EnvironmentConfigBuilder w trybie Greedy z odrębnymi prefiksami. Dzięki temu podejściu nie można mieć zduplikowanych nazw kluczy, ponieważ nazwy kluczy muszą się różnić od prefiksu. Na przykład:

<configuration>

  <configSections>
    <section name="configBuilders"
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="AS_Environment" mode="Greedy" prefix="AppSetting_"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment" />
      <add name="CS_Environment" mode="Greedy" prefix="ConnStr_"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="AS_Environment">
    <add key="AppSetting_ServiceID" value="ServiceID value from web.config" />
    <add key="AppSetting_default" value="AppSetting_default value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="CS_Environment">
    <add name="ConnStr_default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>

W przypadku przedstawionego znacznika można użyć tego samego prostego źródła klucz/wartość, aby skonfigurować dwie różne sekcje.

Na poniższej ilustracji przedstawiono <appSettings/><connectionStrings/> klucze/wartości z poprzedniego pliku web.config ustawionego w edytorze środowiska:

Poniższy kod odczytuje klucze/wartości <appSettings/> i <connectionStrings/>, które są zawarte w poprzednim pliku web.config.

public partial class Contact : Page
{
    public string ServiceID { get; set; }
    public string AppSetting_default { get; set; }
    public string ConString { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        ServiceID = ConfigurationManager.AppSettings["AppSetting_ServiceID"];
        AppSetting_default = ConfigurationManager.AppSettings["AppSetting_default"];
        ConString = ConfigurationManager.ConnectionStrings["ConnStr_default"]
                                     ?.ConnectionString;
    }
}

Powyższy kod ustawi wartości właściwości na:

• Wartości w pliku web.config, jeśli klucze nie są ustawione w zmiennych środowiskowych.
• Wartości zmiennej środowiskowej, jeśli są ustawione.

Na przykład, korzystając z poprzedniego pliku web.config, klucze/wartości z wcześniejszego obrazu edytora środowiska i poprzedniego kodu, zostają ustawione następujące wartości:

Klucz	Wartość
AppSetting_ServiceID	AppSetting_ServiceID ze zmiennych środowiskowych
AppSetting_default	AppSetting_default wartość domyślna z env
ConnStr_default	Domyślna wartość ConnStr z środowiska

stripPrefix

stripPrefix: wartość logiczna, wartość domyślna to false.

Powyższy kod XML oddziela ustawienia aplikacji od parametry połączenia, ale wymaga, aby wszystkie klucze w pliku web.config używały określonego prefiksu. Na przykład prefiks AppSetting musi zostać dodany do ServiceID klucza ("AppSetting_ServiceID"). W stripPrefix prefiks nie jest używany w pliku web.config. Prefiks jest wymagany w konstruktorze konfiguracji (na przykład w środowisku). Przewidujemy, że większość deweloperów będzie używać stripPrefix.

Aplikacje zazwyczaj usuwają prefiks. Następujący plik web.config usuwa prefiks:

<configuration>

  <configSections>
    <section name="configBuilders"
             type="System.Configuration.ConfigurationBuildersSection, 
             System.Configuration, Version=4.0.0.0, Culture=neutral, 
             PublicKeyToken=b03f5f7f11d50a3a"
             restartOnExternalChanges="false" requirePermission="false" />
  </configSections>

  <configBuilders>
    <builders>
      <add name="AS_Environment" mode="Greedy" prefix="AppSetting_" 
           stripPrefix="true"
           type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
      <add name="CS_Environment" mode="Greedy" prefix="ConnStr_" 
           stripPrefix="true"
            type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, 
           Microsoft.Configuration.ConfigurationBuilders.Environment, 
           Version=1.0.0.0, Culture=neutral" />
    </builders>
  </configBuilders>

  <appSettings configBuilders="AS_Environment">
    <add key="ServiceID" value="ServiceID value from web.config" />
    <add key="default" value="AppSetting_default value from web.config" />
  </appSettings>

  <connectionStrings configBuilders="CS_Environment">
    <add name="default" connectionString="Data Source=web.config/mydb.db" />
  </connectionStrings>

W poprzednim pliku web.config klucz default znajduje się zarówno w <appSettings/>, jak i <connectionStrings/>.

Na poniższej ilustracji przedstawiono <appSettings/><connectionStrings/> klucze/wartości z poprzedniego pliku web.config ustawionego w edytorze środowiska:

Poniższy kod odczytuje klucze/wartości <appSettings/> i <connectionStrings/>, zawarte w poprzednim pliku web.config:

public partial class About2 : Page
{
    public string ServiceID { get; set; }
    public string AppSetting_default { get; set; }
    public string ConString { get; set; }

    protected void Page_Load(object sender, EventArgs e)
    {
        ServiceID = ConfigurationManager.AppSettings["ServiceID"];
        AppSetting_default = ConfigurationManager.AppSettings["default"];
        ConString = ConfigurationManager.ConnectionStrings["default"]
                                        ?.ConnectionString;
    }
}

Powyższy kod ustawi wartości właściwości na:

• Wartości w pliku web.config jeśli klucze nie są ustawione w zmiennych środowiskowych.
• Wartości zmiennej środowiskowej, jeśli są ustawione.

Na przykład, korzystając z poprzedniego pliku web.config, klucze/wartości w poprzednim obrazie edytora środowiska oraz wcześniejszym kodzie, można ustawić następujące wartości:

Klucz	Wartość
Identyfikator usługi	AppSetting_ServiceID ze zmiennych środowiskowych
domyślny	Domyślna wartość AppSetting z środowiska
domyślny	ConnStr_domyslna_wartosc_ze_srodowiska

wzorzec tokenu

tokenPattern: Ciąg, domyślnie @"\$\{(\w+)\}"

Zachowanie Expand konstruktorów wyszukuje nieprzetworzone dane XML dla tokenów, które wyglądają następująco: ${token}. Wyszukiwanie odbywa się przy użyciu domyślnego wyrażenia @"\$\{(\w+)\}"regularnego . Zestaw znaków, który odpowiada \w, jest bardziej rygorystyczny niż pozwala XML oraz wiele źródeł konfiguracji. Użyj tokenPattern, gdy w nazwie tokenu wymagana jest większa liczba znaków niż @"\$\{(\w+)\}".

tokenPattern: String:

• Umożliwia programistom zmianę wyrażenia regularnego używanego do pasowania tokenów.
• Nie wykonano walidacji, aby upewnić się, że jest to dobrze sformułowany, nienagroźny regex.
• Musi zawierać grupę przechwytywania. Cały rejestr musi być zgodny z całym tokenem. Pierwsze przechwytywanie musi być nazwą tokenu do wyszukania w źródle konfiguracji.

Konstruktory konfiguracji w programie Microsoft.Configuration.ConfigurationBuilders

EnvironmentConfigBuilder

<add name="Environment"
    [mode|prefix|stripPrefix|tokenPattern] 
    type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Environment" />

EnvironmentConfigBuilder:

• Jest najprostszym konstruktorem konfiguracji.
• Odczytuje wartości ze środowiska.
• Nie ma żadnych dodatkowych opcji konfiguracji.
• Wartość atrybutu name jest dowolna.

Uwaga: W środowisku kontenera systemu Windows zmienne ustawiane podczas uruchamiania są wstrzykiwane tylko do środowiska procesu EntryPoint. Aplikacje, które działają jako usługa lub proces inny niż EntryPoint, nie pobierają tych zmiennych, chyba że zostaną one w inny sposób wprowadzone za pośrednictwem mechanizmu w kontenerze. W przypadku kontenerów opartych na usługach IIS ASP.NET, bieżąca wersja ServiceMonitor.exe obsługuje to tylko w puli DefaultAppPool. Inne warianty kontenera oparte na systemie Windows mogą wymagać opracowania własnego mechanizmu iniekcji dla procesów innych niż EntryPoint.

UserSecretsConfigBuilder

Ostrzeżenie

Nigdy nie przechowuj haseł, poufnych parametry połączenia ani innych poufnych danych w kodzie źródłowym. Wpisy tajne produkcyjne nie powinny być używane do programowania ani testowania.

<add name="UserSecrets"
    [mode|prefix|stripPrefix|tokenPattern]
    (userSecretsId="{secret string, typically a GUID}" | userSecretsFile="~\secrets.file")
    [optional="true"]
    type="Microsoft.Configuration.ConfigurationBuilders.UserSecretsConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.UserSecrets" />

W poprzednim pliku XML ścieżka userSecretsFile może używać ~/ lub ~\. Na przykład ścieżka może być zapisana jako userSecretsFile="~/secrets.file. Aby uzyskać więcej informacji, zobacz klasę ConfigurationBuilders Utils .

Ten konstruktor konfiguracji udostępnia funkcję podobną do ASP.NET Core Secret Manager.

Element UserSecretsConfigBuilder może być używany w projektach programu .NET Framework, ale należy określić plik wpisów tajnych. Alternatywnie można zdefiniować UserSecretsId właściwość w pliku projektu i utworzyć plik surowych sekretów w odpowiedniej lokalizacji do odczytu. Aby zachować zależności zewnętrzne poza projektem, plik tajny jest sformatowany w formacie XML. Formatowanie XML jest szczegółem implementacji i nie należy na nim polegać. Jeśli musisz udostępnić plik secrets.json projektom platformy .NET Core, rozważ użycie narzędzia SimpleJsonConfigBuilder. Format SimpleJsonConfigBuilder platformy .NET Core należy również uznać za szczegóły implementacji, które mogą ulec zmianie.

Atrybuty konfiguracji dla elementu UserSecretsConfigBuilder:

• userSecretsId — Jest to preferowana metoda identyfikowania pliku sekretów XML. Działa podobnie do platformy .NET Core, która używa UserSecretsId właściwości projektu do przechowywania tego identyfikatora. Ciąg musi być unikatowy, ale nie musi to być identyfikator GUID. Za pomocą tego atrybutu wyszukaj w dobrze znanej lokalizacji lokalnej (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml) plik tajemnic należący do tego identyfikatora.
• userSecretsFile - Opcjonalny atrybut określający plik zawierający wpisy tajne. Znak ~ można użyć na początku, aby odwołać się do katalogu głównego aplikacji. Ten atrybut lub userSecretsId atrybut jest wymagany. Jeśli oba są określone, userSecretsFile ma pierwszeństwo.
• optional: wartość logiczna, domyślna wartość true — zapobiega rzuceniu wyjątku, jeśli nie można odnaleźć pliku z sekretami.
• Wartość atrybutu name jest dowolna.

Plik wpisów tajnych ma następujący format:

<?xml version="1.0" encoding="utf-8" ?>
<root>
  <secrets ver="1.0">
    <secret name="secret key name" value="secret value" />
  </secrets>
</root>

AzureKeyVaultConfigBuilder

<add name="AzureKeyVault"
    [mode|prefix|stripPrefix|tokenPattern]
    (vaultName="MyVaultName" |
     uri="https:/MyVaultName.vault.azure.net")
    [version="secrets version"]
    [preloadSecretNames="true"]
    type="Microsoft.Configuration.ConfigurationBuilders.AzureKeyVaultConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Azure" />

AzureKeyVaultConfigBuilder odczytuje wartości przechowywane w usłudze Azure Key Vault.

vaultName jest wymagane (nazwa magazynu lub identyfikator URI do magazynu). Inne atrybuty umożliwiają kontrolę nad tym, do którego magazynu się podłączyć, ale są potrzebne tylko wtedy, gdy aplikacja nie działa w środowisku współpracującym z Microsoft.Azure.Services.AppAuthentication. Biblioteka uwierzytelniania usług platformy Azure służy do automatycznego odbierania informacji o połączeniu ze środowiska wykonawczego, jeśli jest to możliwe. Możesz zastąpić automatyczne pobieranie informacji o połączeniu, podając connection string.

• vaultName — Wymagane, jeśli uri nie podano. Określa nazwę sejfu w subskrypcji Azure, z którego mają być odczytywane pary klucz/wartość.
• uri — Łączy się z innymi dostawcami usługi Key Vault, używając określonej uri wartości. Jeśli nie zostanie określony, Azure (vaultName) jest dostawcą przechowalni.
• version — Usługa Azure Key Vault udostępnia funkcję przechowywania wersji wpisów tajnych. Jeśli version zostanie określony, konstruktor pobiera tylko sekrety pasujące do tej wersji.
• preloadSecretNames — Domyślnie ten builder wykonuje zapytanie o wszystkie nazwy kluczy w magazynie kluczy podczas jego inicjalizacji. Aby zapobiec odczytywaniu wszystkich wartości klucza, ustaw ten atrybut na false. Ustawienie tej wartości na false czyta tajemnice pojedynczo. Odczytywanie wpisów tajnych pojedynczo może być przydatne, jeśli magazyn zezwala na dostęp "Pobierz", ale nie na dostęp "List". Uwaga: w przypadku korzystania z Greedy trybu preloadSecretNames musi być true (wartość domyślna).

KeyPerFileConfigBuilder

<add name="KeyPerFile"
    [mode|prefix|stripPrefix|tokenPattern]
    (directoryPath="PathToSourceDirectory")
    [ignorePrefix="ignore."]
    [keyDelimiter=":"]
    [optional="false"]
    type="Microsoft.Configuration.ConfigurationBuilders.KeyPerFileConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.KeyPerFile" />

KeyPerFileConfigBuilder to podstawowy konstruktor konfiguracji, który używa plików katalogu jako źródła wartości. Nazwa pliku jest kluczem, a zawartość jest wartością. Ten konstruktor konfiguracji może być przydatny podczas uruchamiania w zorganizowanym środowisku kontenera. Systemy, takie jak Docker Swarm i Kubernetes, zapewniają secrets kontenerom Windows w sposób klucz-na-plik.

Szczegóły atrybutu:

• directoryPath - Wymagane. Określa ścieżkę do wyszukiwania wartości. Tajne dane w Docker dla Windows są domyślnie przechowywane w katalogu C:\ProgramData\Docker\secrets.
• ignorePrefix — Pliki rozpoczynające się od tego prefiksu są wykluczone. Domyślnie ustawione na „ignore”.
• keyDelimiter - Wartość domyślna to null. Jeśli jest określony, budowniczy konfiguracji wędruje przez wiele poziomów katalogu, tworząc nazwy kluczy za pomocą tego ogranicznika. Jeśli ta wartość to null, konstruktor konfiguracji patrzy tylko na najwyższy poziom katalogu.
• optional - Wartość domyślna to false. Określa, czy konstruktor konfiguracji powinien powodować błędy, jeśli katalog źródłowy nie istnieje.

SimpleJsonConfigBuilder

Ostrzeżenie

Nigdy nie przechowuj haseł, poufnych parametry połączenia ani innych poufnych danych w kodzie źródłowym. Wpisy tajne produkcyjne nie powinny być używane do programowania ani testowania.

<add name="SimpleJson"
    [mode|prefix|stripPrefix|tokenPattern]
    jsonFile="~\config.json"
    [optional="true"]
    [jsonMode="(Flat|Sectional)"]
    type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Json" />

Projekty platformy .NET Core często używają plików JSON do konfiguracji. Konstruktor SimpleJsonConfigBuilder umożliwia używanie plików JSON platformy .NET Core w programie .NET Framework. Ten kreator konfiguracji udostępnia podstawowe mapowanie z prostego źródła Key/Value do określonych sekcji konfiguracji programu .NET Framework. Ten konstruktor konfiguracji nie zapewnia konfiguracji o strukturze hierarchicznej. Plik kopii zapasowej JSON jest podobny do słownika, a nie złożonego obiektu hierarchicznego. Można użyć pliku hierarchicznego na wielu poziomach. Ten dostawca flatten zwiększa głębokość poprzez dołączanie nazwy właściwości na każdym poziomie, używając : jako separatora.

Szczegóły atrybutu:

• jsonFile - Wymagane. Określa plik JSON do odczytu. Znak ~ można użyć na początku, aby odwołać się do katalogu głównego aplikacji.

• optional - Typ logiczny, wartość domyślna to true. Zapobiega zgłaszaniu wyjątków, jeśli nie można odnaleźć pliku JSON.

• jsonMode - [Flat|Sectional]. Wartość domyślna to Flat. Gdy jsonMode jest Flat, plik JSON jest płaskim źródłem klucz/wartość. Wartości EnvironmentConfigBuilder i AzureKeyVaultConfigBuilder są również pojedynczymi prostymi źródłami klucza/wartości. Po skonfigurowaniu elementu SimpleJsonConfigBuilder w trybie Sectional:

  • Plik JSON jest koncepcyjnie podzielony wyłącznie na najwyższym poziomie na wiele słowników.
  • Każdy z słowników jest stosowany tylko do sekcji konfiguracji zgodnej z nazwą właściwości najwyższego poziomu dołączoną do nich. Na przykład:

    {
        "appSettings" : {
            "setting1" : "value1",
            "setting2" : "value2",
            "complex" : {
                "setting1" : "complex:value1",
                "setting2" : "complex:value2",
            }
        }
    }

Kolejność konstruktorów konfiguracji

Zobacz ConfigurationBuilders Order of Execution w repozytorium aspnet/MicrosoftConfigurationBuilders GitHub.

Implementowanie niestandardowego konstruktora konfiguracji klucza/wartości

Jeśli konstruktorzy konfiguracji nie spełniają Twoich potrzeb, możesz napisać niestandardowy. Klasa KeyValueConfigBuilder bazowa obsługuje tryby podstawienia i większość kwestii związanych z prefiksami. Projekt implementowania wymaga tylko:

• Dziedzicz z klasy bazowej i zaimplementuj podstawowe źródło par klucz/wartość za pomocą GetValue i GetAllValues
• Dodaj element Microsoft.Configuration.ConfigurationBuilders.Base do projektu.

using Microsoft.Configuration.ConfigurationBuilders;
using System.Collections.Generic;

public class MyCustomConfigBuilder : KeyValueConfigBuilder
{
    public override string GetValue(string key)
    {
        // Key lookup should be case-insensitive, because most key/value collections in 
        // .NET Framework config sections are case-insensitive.
        return "Value for given key, or null.";
    }

    public override ICollection<KeyValuePair<string, string>> GetAllValues(string prefix)
    {
        // Populate the return collection.
        return new Dictionary<string, string>() { { "one", "1" }, { "two", "2" } };
    }
}

Klasa KeyValueConfigBuilder bazowa zapewnia wiele pracy i spójne zachowanie w konstruktorach konfiguracji klucz/wartość.

Dodatkowe zasoby

• Repozytorium GitHub Configuration Builders
• Uwierzytelnianie między usługami w usłudze Azure Key Vault przy użyciu platformy .NET