Konfiguration i .NET

  • Artikel

Konfigurationen i .NET utförs med hjälp av en eller flera konfigurationsprovidrar. Konfigurationsprovidrar läser konfigurationsdata från nyckel/värde-par med hjälp av olika konfigurationskällor:

  • Inställningar filer, till exempel appsettings.json
  • Miljövariabler
  • Azure Key Vault
  • Azure App Configuration
  • Kommandoradsargument
  • Anpassade leverantörer, installerade eller skapade
  • Katalogfiler
  • Minnesinterna .NET-objekt
  • Tredjepartsleverantörer

Kommentar

Information om hur du konfigurerar själva .NET-körningen finns i Konfigurationsinställningar för .NET Runtime.

Begrepp och abstraktioner

Med en eller flera konfigurationskällor IConfiguration ger typen en enhetlig vy över konfigurationsdata. Konfigurationen är skrivskyddad och konfigurationsmönstret är inte utformat för att vara programmatiskt skrivbart. Gränssnittet IConfiguration är en enda representation av alla konfigurationskällor, enligt följande diagram:

The `IConfiguration` interface is a single representation of all the configuration sources.

Konfigurera konsolappar

.NET-konsolprogram som skapats med hjälp av den nya kommandomallen dotnet eller Visual Studio exponerar som standard inte konfigurationsfunktioner. Om du vill lägga till konfiguration i ett nytt .NET-konsolprogram lägger du till en paketreferens till Microsoft.Extensions.Configuration. Det här paketet är grunden för konfigurationen i .NET-appar. Den innehåller de ConfigurationBuilder och relaterade typerna.

using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>()
    {
        ["SomeKey"] = "SomeValue"
    })
    .Build();

Console.WriteLine(configuration["SomeKey"]);

// Outputs:
//   SomeValue

Koden ovan:

  • Skapar en ny ConfigurationBuilder instans.
  • Lägger till en minnesintern samling nyckel/värde-par i konfigurationsverktyget.
  • Build() Anropar metoden för att skapa en IConfiguration instans.
  • Skriver värdet för SomeKey nyckeln till konsolen.

Även om det här exemplet använder en minnesintern konfiguration finns det många tillgängliga konfigurationsproviders som exponerar funktioner för filbaserade, miljövariabler, kommandoradsargument och andra konfigurationskällor. Mer information finns i Konfigurationsprovidrar i .NET.

Alternativ värdmetod

Vanligtvis gör dina appar mer än att bara läsa konfigurationen. De kommer sannolikt att använda beroendeinmatning, loggning och andra tjänster. Metoden .NET Generic Host rekommenderas för appar som använder dessa tjänster. Överväg i stället att lägga till en paketreferens till Microsoft.Extensions.Hosting. Ändra Program.cs-filen så att den matchar följande kod:

using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Application code should start here.

await host.RunAsync();

Metoden Host.CreateApplicationBuilder(String[]) tillhandahåller standardkonfiguration för appen i följande ordning, från högsta till lägsta prioritet:

  1. Kommandoradsargument med hjälp av kommandoradskonfigurationsprovidern.
  2. Miljövariabler med konfigurationsprovidern Miljövariabler.
  3. Apphemligheter när appen körs i Development miljön.
  4. appsettings.json med JSON-konfigurationsprovidern.
  5. appsettings.Environment. json med JSON-konfigurationsprovidern. Till exempel apparinställningar.Produktion.json och appsettings.Utveckling.json.
  6. ChainedConfigurationProvider : Lägger till en befintlig IConfiguration som källa.

Om du lägger till en konfigurationsprovider åsidosätts tidigare konfigurationsvärden. Till exempel åsidosätter kommandoradskonfigurationsprovidern alla värden från andra leverantörer eftersom den lades till sist. Om SomeKey anges i både appsettings.json och miljön används miljövärdet eftersom det lades till efter appsettings.json.

Bindning

En av de viktigaste fördelarna med att använda .NET-konfigurationsabstraktioner är möjligheten att binda konfigurationsvärden till instanser av .NET-objekt. JSON-konfigurationsprovidern kan till exempel användas för att mappa appsettings.json filer till .NET-objekt och används med beroendeinmatning. Detta aktiverar alternativmönstret, som använder klasser för att ge starkt skrivskyddad åtkomst till grupper med relaterade inställningar. .NET-konfigurationen innehåller olika abstraktioner. Överväg följande gränssnitt:

Dessa abstraktioner är agnostiska för deras underliggande konfigurationsprovider (IConfigurationProvider). Med andra ord kan du använda en IConfiguration instans för att komma åt valfritt konfigurationsvärde från flera leverantörer.

Pärmen kan använda olika metoder för att bearbeta konfigurationsvärden:

  • Direkt deserialisering (med inbyggda konverterare) för primitiva typer.
  • TypeConverter För en komplex typ när typen har en.
  • Reflektion för en komplex typ som har egenskaper.

Kommentar

Pärmen har några begränsningar:

  • Egenskaper ignoreras om de har privata setters eller om deras typ inte kan konverteras.
  • Egenskaper utan motsvarande konfigurationsnycklar ignoreras.

Bindningshierarkier

Konfigurationsvärden kan innehålla hierarkiska data. Hierarkiska objekt representeras med hjälp av avgränsare : i konfigurationsnycklarna. Om du vill komma åt ett konfigurationsvärde använder du : tecknet för att avgränsa en hierarki. Tänk till exempel på följande konfigurationsvärden:

{
  "Parent": {
    "FavoriteNumber": 7,
    "Child": {
      "Name": "Example",
      "GrandChild": {
        "Age": 3
      }
    }
  }
}

Följande tabell representerar exempelnycklar och deras motsvarande värden för föregående exempel JSON:

Tangent Värde
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Grundläggande exempel

Om du vill komma åt konfigurationsvärden i deras grundläggande form, utan hjälp av den allmänna värdmetoden , använder du ConfigurationBuilder typen direkt.

Dricks

Typen System.Configuration.ConfigurationBuilder skiljer sig från Microsoft.Extensions.Configuration.ConfigurationBuilder typen. Allt det här innehållet är specifikt för Microsoft.Extensions.* NuGet-paketen och namnrymderna.

Överväg följande C#-projekt:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="8.0.1" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="8.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="8.0.0" />
  </ItemGroup>

</Project>

Den föregående projektfilen refererar till flera NuGet-konfigurationspaket:

Överväg ett exempel appsettings.json fil:

{
    "Settings": {
        "KeyOne": 1,
        "KeyTwo": true,
        "KeyThree": {
            "Message": "Oh, that's nice...",
            "SupportedVersions": {
                "v1": "1.0.0",
                "v3": "3.0.7"
            }
        },
        "IPAddressRange": [
            "46.36.198.121",
            "46.36.198.122",
            "46.36.198.123",
            "46.36.198.124",
            "46.36.198.125"
        ]
    }
}

Nu, med tanke på den här JSON-filen, här är ett exempel på förbrukningsmönster med hjälp av konfigurationsverktyget direkt:

using Microsoft.Extensions.Configuration;

// Build a config object, using env vars and JSON providers.
IConfigurationRoot config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .AddEnvironmentVariables()
    .Build();

// Get values from the config given their key and their target type.
Settings? settings = config.GetRequiredSection("Settings").Get<Settings>();

// Write the values to the console.
Console.WriteLine($"KeyOne = {settings?.KeyOne}");
Console.WriteLine($"KeyTwo = {settings?.KeyTwo}");
Console.WriteLine($"KeyThree:Message = {settings?.KeyThree?.Message}");

// Application code which might rely on the config could start here.

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Oh, that's nice...

Föregående C#-kod:

  • Instansierar en ConfigurationBuilder.
  • Lägger till filen som "appsettings.json" ska identifieras av JSON-konfigurationsprovidern.
  • Lägger till miljövariabler som identifieras av miljövariabelkonfigurationsprovidern.
  • Hämtar det obligatoriska "Settings" avsnittet och motsvarande Settings instans med hjälp av instansen config .

Objektet Settings formas på följande sätt:

public sealed class Settings
{
    public required int KeyOne { get; set; }
    public required bool KeyTwo { get; set; }
    public required NestedSettings KeyThree { get; set; } = null!;
}

public sealed class NestedSettings
{
    public required string Message { get; set; } = null!;
}

Grundläggande exempel med värdtjänster

För att få åtkomst till IConfiguration värdet kan du förlita dig igen på Microsoft.Extensions.Hosting NuGet-paketet. Skapa ett nytt konsolprogram och klistra in följande projektfilinnehåll i det:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>true</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <Content Include="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="8.0.0" />
  </ItemGroup>

</Project>

Den föregående projektfilen definierar att:

  • Programmet är en körbar fil.
  • En appsettings.json fil ska kopieras till utdatakatalogen när projektet kompileras.
  • NuGet-paketreferensen Microsoft.Extensions.Hosting läggs till.

Lägg till filen appsettings.json i roten av projektet med följande innehåll:

{
    "KeyOne": 1,
    "KeyTwo": true,
    "KeyThree": {
        "Message": "Thanks for checking this out!"
    }
}

Ersätt innehållet i Program.cs-filen med följande C#-kod:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
int keyOneValue = config.GetValue<int>("KeyOne");
bool keyTwoValue = config.GetValue<bool>("KeyTwo");
string? keyThreeNestedValue = config.GetValue<string>("KeyThree:Message");

// Write the values to the console.
Console.WriteLine($"KeyOne = {keyOneValue}");
Console.WriteLine($"KeyTwo = {keyTwoValue}");
Console.WriteLine($"KeyThree:Message = {keyThreeNestedValue}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//   KeyOne = 1
//   KeyTwo = True
//   KeyThree:Message = Thanks for checking this out!

När du kör det här programmet Host.CreateApplicationBuilder definierar beteendet för att identifiera JSON-konfigurationen och exponera den via instansen IConfiguration . Från instansen host kan du be tjänstleverantören om instansen IConfiguration och sedan be den om värden.

Dricks

Att använda den råa IConfiguration instansen på det här sättet, även om det är praktiskt, skalas inte särskilt bra. När programmen blir mer komplexa och deras motsvarande konfigurationer blir mer komplexa rekommenderar vi att du använder alternativmönstret som ett alternativ.

Grundläggande exempel med värd och användning av indexerar-API:et

Överväg samma appsettings.json filinnehåll från föregående exempel:

{
    "SupportedVersions": {
        "v1": "1.0.0",
        "v3": "3.0.7"
    },
    "IPAddressRange": [
        "46.36.198.123",
        "46.36.198.124",
        "46.36.198.125"
    ]
}

Ersätt innehållet i Program.cs-filen med följande C#-kod:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateApplicationBuilder(args).Build();

// Ask the service provider for the configuration abstraction.
IConfiguration config = host.Services.GetRequiredService<IConfiguration>();

// Get values from the config given their key and their target type.
string? ipOne = config["IPAddressRange:0"];
string? ipTwo = config["IPAddressRange:1"];
string? ipThree = config["IPAddressRange:2"];
string? versionOne = config["SupportedVersions:v1"];
string? versionThree = config["SupportedVersions:v3"];

// Write the values to the console.
Console.WriteLine($"IPAddressRange:0 = {ipOne}");
Console.WriteLine($"IPAddressRange:1 = {ipTwo}");
Console.WriteLine($"IPAddressRange:2 = {ipThree}");
Console.WriteLine($"SupportedVersions:v1 = {versionOne}");
Console.WriteLine($"SupportedVersions:v3 = {versionThree}");

// Application code which might rely on the config could start here.

await host.RunAsync();

// This will output the following:
//     IPAddressRange:0 = 46.36.198.123
//     IPAddressRange:1 = 46.36.198.124
//     IPAddressRange:2 = 46.36.198.125
//     SupportedVersions:v1 = 1.0.0
//     SupportedVersions:v3 = 3.0.7

Värdena används med indexerarens API där varje nyckel är en sträng och värdet är en sträng. Konfigurationen stöder egenskaper, objekt, matriser och ordlistor.

Konfigurationsleverantörer

I följande tabell visas de konfigurationsprovidrar som är tillgängliga för .NET Core-appar.

Provider Tillhandahåller konfiguration från
Konfigurationsprovider för Azure App Azure App Configuration
Konfigurationsprovider för Azure Key Vault Azure Key Vault
Konfigurationsprovider för kommandorad Kommandoradsparametrar
Anpassad konfigurationsprovider Anpassad källa
Konfigurationsprovider för miljövariabler Miljövariabler
Filkonfigurationsprovider JSON-, XML- och INI-filer
Konfigurationsprovider för nyckel per fil Katalogfiler
Minneskonfigurationsprovider Minnesinterna samlingar
Apphemligheter (Secret Manager) Fil i användarprofilkatalogen

Dricks

I vilken ordning konfigurationsprovidrar läggs till är det viktigt. När flera konfigurationsprovidrar används och mer än en provider anger samma nyckel används den sista som läggs till.

Mer information om olika konfigurationsprovidrar finns i Konfigurationsprovidrar i .NET.

Se även