Konstruktory konfiguracji dla platformy ASP.NET

Autor: Stephen Molloy i Rick Anderson

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

Konstruktory konfiguracji:

  • Są dostępne w wersji .NET Framework 4.7.1 lub nowszej.
  • Zapewnienie elastycznego mechanizmu odczytywania wartości konfiguracji.
  • Sprostanie niektórym podstawowym potrzebom 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ł wcześniej niedostępnych (na przykład zmiennych środowiskowych i Key Vault platformy Azure) w systemie konfiguracji platformy .NET.

Konstruktory konfiguracji klucza/wartości

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 .NET Framework configurationBuilders nie jest ograniczona do określonych sekcji lub wzorców konfiguracji. Jednak wiele konstruktorów konfiguracji w Microsoft.Configuration.ConfigurationBuilders programie (github, NuGet) działa w ramach wzorca klucza/wartości.

Ustawienia konstruktorów konfiguracji klucza/wartości

Następujące ustawienia mają zastosowanie do wszystkich konstruktorów konfiguracji klucza/wartości w programie Microsoft.Configuration.ConfigurationBuilders.

Tryb

Konstruktory konfiguracji używają zewnętrznego źródła informacji o klucz/wartość, aby wypełnić wybrane elementy klucza/wartości systemu konfiguracji. W szczególności <appSettings/> sekcje i <connectionStrings/> otrzymują specjalne traktowanie od 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 tryb wylicza każdy klucz w sekcji. Jeśli w źródle zewnętrznym znajduje się pasujący klucz:

    • Konstruktory konfiguracji zastępują wartość w wynikowej sekcji konfiguracji wartością ze źródła zewnętrznego.
  • Greedy - Ten tryb jest ściśle związany z trybem Strict . Zamiast ograniczać się do kluczy, które już istnieją w oryginalnej konfiguracji:

    • Konstruktory konfiguracji dodają wszystkie pary klucz/wartość ze źródła zewnętrznego do wynikowej sekcji konfiguracji.
  • Expand — Działa na nieprzetworzonym pliku XML, zanim zostanie przeanalizowany w obiekcie sekcji konfiguracji. Można go traktować jako rozszerzenie tokenów w ciągu. Każda część nieprzetworzonego ciągu XML zgodnego ze wzorcem ${token} jest kandydatem do rozszerzenia tokenu. Jeśli nie znaleziono odpowiedniej wartości w źródle zewnętrznym, token nie zostanie zmieniony. Konstruktory w tym trybie nie są ograniczone do <appSettings/> sekcji i <connectionStrings/> .

Następujące znaczniki z web.config włącza 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 element <appSettings/> i <connectionStrings/> pokazany 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 web.config", jeśli zmienna środowiskowa ServiceID nie jest ustawiona.
  • Wartość zmiennej środowiskowej ServiceID , jeśli zostanie ustawiona.

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

Zrzut ekranu przedstawia edytor zmiennych środowiskowych z wyróżnionymi zmiennymi ServiceID i ServiceKey.

Uwaga: może być konieczne zamknięcie i ponowne uruchomienie programu Visual Studio w celu wyświetlenia zmian w zmiennych środowiskowych.

Obsługa prefiksów

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

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

Użyj dowolnego z poniższych metod, aby wstrzyknąć zarówno do konfiguracji, jak <appSettings/> i <connectionStrings/> za pomocą zmiennych środowiskowych:

  • EnvironmentConfigBuilder W trybie domyślnym Strict i odpowiednie nazwy kluczy w pliku konfiguracji. Powyższy kod i znaczniki są takie podejście. Korzystając z tego podejścia , nie można mieć identycznych nazwanych kluczy w obu i <appSettings/><connectionStrings/>.
  • Użyj dwóch EnvironmentConfigBuilders w Greedy trybie z odrębnymi prefiksami i stripPrefix. Dzięki temu 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 EnvironmentConfigBuilders w Greedy trybie 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. 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 powyższego znaczników można użyć tego samego prostego źródła klucza/wartości, aby wypełnić konfigurację dla dwóch różnych sekcji.

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

Zrzut ekranu przedstawia edytor zmiennych środowiskowych z wyróżnionymi zmiennymi AppSetting_default, AppSetting_ServiceID i ConnStr_default.

Poniższy kod odczytuje <appSettings/> klucze/wartości i <connectionStrings/> 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 przy użyciu poprzedniego pliku web.config klucze/wartości w poprzednim obrazie edytora środowiska i poprzedniego kodu są ustawione następujące wartości:

Klucz Wartość
AppSetting_ServiceID AppSetting_ServiceID ze zmiennych env
AppSetting_default AppSetting_default wartość z env
ConnStr_default ConnStr_default val from env

stripPrefix

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

Powyższy znacznik XML oddziela ustawienia aplikacji od parametrów połączenia, ale wymaga wszystkich kluczy w pliku web.config , aby użyć określonego prefiksu. Na przykład prefiks AppSetting musi zostać dodany do ServiceID klucza ("AppSetting_ServiceID"). W programie stripPrefixprefiks nie jest używany w pliku web.config . Prefiks jest wymagany w źródle konstruktora konfiguracji (na przykład w środowisku). Przewidujemy, że większość deweloperów będzie używać polecenia stripPrefix.

Aplikacje zazwyczaj usuwają prefiks. Następujące 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 defaultweb.config klucz znajduje się zarówno w pliku , jak <appSettings/> i <connectionStrings/>.

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

Zrzut ekranu przedstawia edytor zmiennych środowiskowych z wyróżnionymi zmiennymi AppSetting_default, AppSetting_ServiceID i ConnStr_default.

Poniższy kod odczytuje <appSettings/> klucze/wartości 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 przy użyciu poprzedniego pliku web.config klucze/wartości w poprzednim obrazie edytora środowiska i poprzedniego kodu są ustawione następujące wartości:

Klucz Wartość
Identyfikator usługi AppSetting_ServiceID ze zmiennych env
default AppSetting_default wartość z env
default ConnStr_default val from env

tokenPattern

tokenPattern: Ciąg, wartości domyślne @"\$\{(\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 pasujących \w jest bardziej rygorystyczny niż XML, a wiele źródeł konfiguracji zezwala. Użyj tokenPattern , gdy więcej znaków niż @"\$\{(\w+)\}" są wymagane w nazwie tokenu.

tokenPattern: Ciąg:

  • Umożliwia deweloperom zmianę wyrażenia regularnego używanego do dopasowywania tokenów.
  • Nie wykonano walidacji, aby upewnić się, że jest to dobrze sformułowany, nie-niebezpieczny 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 ustawione w czasie wykonywania są wstrzykiwane tylko do środowiska procesu EntryPoint. Aplikacje, które są uruchamiane jako usługa lub proces inny niż EntryPoint, nie pobierają tych zmiennych, chyba że są one w inny sposób wstrzykiwane za pośrednictwem mechanizmu w kontenerze. W przypadku kontenerówopartych na ASP.NETusług IIS/ bieżąca wersja ServiceMonitor.exe obsługuje to tylko w puli DefaultAppPool. Inne warianty kontenerów 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 parametrów 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" />

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

Element UserSecretsConfigBuilder może być używany w projektach .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 nieprzetworzonych wpisów tajnych w odpowiedniej lokalizacji do odczytu. Aby zachować zewnętrzne zależności poza projektem, plik tajny jest sformatowany w formacie XML. Formatowanie XML jest szczegółem implementacji, a format nie powinien być oparty na. 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 wpisów tajnych 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, nie musi być identyfikatorem GUID. Za pomocą tego atrybutu UserSecretsConfigBuilder wyszukaj dobrze znaną lokalizację lokalną (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml) dla pliku wpisów tajnych należących 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 pierwszeństwo ma pierwszeństwo.
  • optional: wartość logiczna, wartość true domyślna — uniemożliwia wyjątek, jeśli nie można odnaleźć pliku wpisów tajnych.
  • 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" />

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

vaultName jest wymagane (nazwa magazynu lub identyfikator URI magazynu). Inne atrybuty umożliwiają sterowanie tym, z którym magazynem ma się łączyć, ale są niezbędne tylko wtedy, gdy aplikacja nie działa w środowisku, z którym działa Microsoft.Azure.Services.AppAuthenticationprogram . Biblioteka uwierzytelniania usług platformy Azure służy do automatycznego odbierania informacji o połączeniu ze środowiska wykonawczego, jeśli to możliwe. Możesz automatycznie przesłonić informacje o połączeniu, podając parametry połączenia.

  • vaultName - Wymagane, jeśli uri nie podano. Określa nazwę magazynu w subskrypcji platformy Azure, z której mają być odczytywane pary klucz/wartość.
  • uri- Łączy się z innymi dostawcami Key Vault z określoną uri wartością. Jeśli nie zostanie określony, platforma Azure (vaultName) jest dostawcą magazynu.
  • version— Usługa Azure Key Vault udostępnia funkcję przechowywania wersji wpisów tajnych. Jeśli version zostanie określony, konstruktor pobiera tylko wpisy tajne pasujące do tej wersji.
  • preloadSecretNames — Domyślnie ten konstruktor wysyła zapytania o wszystkie nazwy kluczy w magazynie kluczy podczas inicjowania. Aby zapobiec odczytywaniu wszystkich wartości klucza, ustaw ten atrybut na false. Ustawienie tego ustawienia na false odczyt wpisów tajnych pojedynczo. Odczytywanie wpisów tajnych pojedynczo może być przydatne, jeśli magazyn zezwala na dostęp "Pobierz", ale nie dostęp do listy. 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 zaaranżowanych środowiskach kontenera. Systemy, takie jak Docker Swarm i Kubernetes, zapewniają secrets zaaranżowane kontenery systemu Windows w taki sposób jak klucz na plik.

Szczegóły atrybutu:

  • directoryPath - Wymagane. Określa ścieżkę do wyszukiwania wartości. Docker dla wpisów tajnych systemu Windows są domyślnie przechowywane w katalogu C:\ProgramData\Docker\secrets .
  • ignorePrefix - Pliki rozpoczynające się od tego prefiksu są wykluczone. Wartość domyślna to "ignore.".
  • keyDelimiter - Wartość domyślna to null. Jeśli zostanie określony, konstruktor konfiguracji przechodzi 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 parametrów 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 .NET Framework. Ten konstruktor konfiguracji udostępnia podstawowe mapowanie z płaskiego źródła klucza/wartości na określone obszary klucza/wartości konfiguracji .NET Framework. Ten konstruktor konfiguracji nie zapewnia konfiguracji hierarchicznych. Plik kopii zapasowej JSON jest podobny do słownika, a nie złożonego obiektu hierarchicznego. Można użyć pliku hierarchicznego z wieloma poziomami. Ten dostawca flattenjest głębokością, dołączając nazwę właściwości na każdym poziomie przy użyciu : ogranicznika.

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 - Wartość logiczna, wartość domyślna to true. Uniemożliwia zgłaszanie wyjątków, jeśli nie można odnaleźć pliku JSON.

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

    • Plik JSON jest koncepcyjnie podzielony tylko 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. Przykład:
    {
        "appSettings" : {
            "setting1" : "value1",
            "setting2" : "value2",
            "complex" : {
                "setting1" : "complex:value1",
                "setting2" : "complex:value2",
            }
        }
    }

Kolejność konstruktorów konfiguracji

Zobacz ConfigurationBuilders Order of Execution (Kolejność wykonywania programu ConfigurationBuilders ) 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 bazowa KeyValueConfigBuilder obsługuje tryby podstawień i większość problemów prefiksu. Projekt implementowania wymaga tylko:

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 bazowa KeyValueConfigBuilder zapewnia wiele działań i spójnych zachowań w konstruktorach konfiguracji klucz/wartość.

Dodatkowe zasoby