Dela via

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ällningsfiler, 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

Not

Information om hur du konfigurerar själva .NET-runtime finns i .NET Runtime-konfigurationsinställningar.

Begrepp och abstraktioner

Med en eller flera konfigurationskällor ger den IConfiguration 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:

Gränssnittet

Konfigurera konsolappar

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

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

Föregående kod:

  • Skapar en ny ConfigurationBuilder instans.
  • Lägger till en minnesintern samling nyckel/värde-par i konfigurationsverktyget.
  • Anropar metoden Build() 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 Configuration Providers 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 kommandoradskonfigurationsprovider.
  2. Miljövariabler med konfigurationsprovidern för miljövariabler .
  3. Apphemligheter när appen körs i Development-miljön.
  4. appsettings.json med hjälp av JSON-konfigurationsprovidern.
  5. apparinställningar.Environment.json med hjälp av JSON-konfigurationsprovidern. Till exempel appinställningar.Produktion.json och appinställningar.Utveckling.json.
  6. ChainedConfigurationProvider : Adderar 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.

Bindande

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 möjliggör alternativmönstret, som använder klasser för att ge starkt typad åtkomst till grupper av relaterade inställningar. Standardbindningen är reflektionsbaserad, men det finns ett alternativ som är enkelt att aktivera.

.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 alla konfigurationsvärden från flera leverantörer.

Bindaren kan använda olika metoder för att hantera 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.

Not

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:

Nyckel 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 att använda det generiska värdtillvägagångssättet , använd då direkt ConfigurationBuilder typen.

Tips

Den System.Configuration.ConfigurationBuilder typen skiljer sig från den Microsoft.Extensions.Configuration.ConfigurationBuilder typen. Allt det här innehållet är specifikt för Microsoft.Extensions.* NuGet-paket och namnområden.

Ö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="9.0.3" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.3" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.3" />
  </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 "appsettings.json"-filen som ska identifieras av JSON-konfigurationsprovidern.
  • Lägger till miljövariabler som identifieras av miljövariabelkonfigurationsprovidern.
  • Hämtar det nödvändiga "Settings" avsnittet och motsvarande Settings instans med hjälp av den config instansen.

Det Settings objektet 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

Om du vill komma åt 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.Configuration.Binder" Version="9.0.3" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.3" />
  </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 definierar Host.CreateApplicationBuilder beteendet för att identifiera JSON-konfigurationen och exponera den via IConfiguration-instansen. Från den host instansen kan du be tjänsteleverantören om IConfiguration-instansen och sedan be den om värden.

Tips

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.

Leverantör Tillhandahåller konfiguration från
Azure App-konfigurationsprovider Azure App Configuration
Azure Key Vault-konfigurationsprovider Azure Key Vault
kommandoradskonfigurationsprovider Kommandoradsparametrar
Anpassad konfigurationsleverantör Anpassad källa
konfigurationsleverantör för miljövariabler Miljövariabler
Filkonfigurationsleverantör JSON-, XML- och INI-filer
Nyckel-per-fil-konfigurationsprovider Katalogfiler
Minneskonfigurationsprovider Minnesinterna samlingar
Applikationshemligheter (Hemlighetshanteraren) Fil i användarprofilkatalogen

Tips

Det är viktigt i vilken ordning konfigurationsleverantörer läggs till. 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 Configuration Providers i .NET.

Se även