Delen via

Configuratie in .NET

  • Artikel

Configuratie in .NET wordt uitgevoerd met behulp van een of meer configuratieproviders. Configuratieproviders lezen configuratiegegevens van sleutel-waardeparen met behulp van verschillende configuratiebronnen:

  • Instellingenbestanden, zoals appsettings.json
  • Omgevingsvariabelen
  • Azure Key Vault
  • Azure App Configuration
  • Opdrachtregelargumenten
  • Aangepaste providers, geïnstalleerd of gemaakt
  • Mapbestanden
  • .NET-objecten in het geheugen
  • Derde partijen

Notitie

Zie .NET Runtime-configuratie-instellingenvoor meer informatie over het configureren van de .NET-runtime zelf.

Concepten en abstracties

Gezien een of meer configuratiebronnen biedt het IConfiguration type een uniforme weergave van de configuratiegegevens. De configuratie is alleen-lezen en het configuratiepatroon is niet ontworpen om programmatisch schrijfbaar te zijn. De IConfiguration-interface is één weergave van alle configuratiebronnen, zoals wordt weergegeven in het volgende diagram:

De interface 'IConfiguration' is één weergave van alle configuratiebronnen.

Console-apps configureren

.NET-consoletoepassingen die zijn gemaakt met behulp van de dotnet nieuwe opdrachtsjabloon of Visual Studio standaard geen configuratiemogelijkheden beschikbaar maken. Als u configuratie wilt toevoegen aan een nieuwe .NET-consoletoepassing, u een pakketverwijzing toevoegen aan Microsoft.Extensions.Configuration-. Dit pakket vormt de basis voor configuratie in .NET-apps. Het biedt de ConfigurationBuilder en gerelateerde typen.

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

De voorgaande code:

  • Hiermee maakt u een nieuw ConfigurationBuilder-exemplaar.
  • Hiermee voegt u een verzameling sleutel-waardeparen toe aan de configuratiebouwer.
  • Roept de Build() methode aan om een IConfiguration-exemplaar te maken.
  • Hiermee schrijft u de waarde van de SomeKey-sleutel naar de console.

Hoewel in dit voorbeeld een in-memory configuratie wordt gebruikt, zijn er veel configuratieproviders beschikbaar, waarbij functionaliteit beschikbaar is voor bestandsgebaseerde, omgevingsvariabelen, opdrachtregelargumenten en andere configuratiebronnen. Zie Configuratieproviders in .NETvoor meer informatie.

Alternatieve hostingbenadering

Uw apps doen doorgaans meer dan enkel het lezen van configuratie. Ze gebruiken waarschijnlijk afhankelijkheidsinjectie, logboekregistratie en andere services. De benadering .NET Generic Host wordt aanbevolen voor apps die gebruikmaken van deze services. Overweeg in plaats daarvan een pakketverwijzing toe te voegen aan Microsoft.Extensions.Hosting. Wijzig het Program.cs-bestand zodat het overeenkomt met de volgende code:

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

De methode Host.CreateApplicationBuilder(String[]) biedt standaardconfiguratie voor de app in de volgende volgorde, van hoogste naar laagste prioriteit:

  1. Opdrachtregelargumenten met behulp van de opdrachtregelconfiguratieprovider.
  2. Omgevingsvariabelen met behulp van de configuratieprovider Omgevingsvariabelen .
  3. app-geheimen wanneer de app wordt uitgevoerd in de Development-omgeving.
  4. appsettings.json met de JSON-configuratieprovider.
  5. appsettings.Environment.json met behulp van de JSON-configuratieprovider. Bijvoorbeeld appsettings.Production.json en appsettings.Development.json.
  6. ChainedConfigurationProvider: voegt een bestaande IConfiguration toe als bron.

Als u een configuratieprovider toevoegt, worden eerdere configuratiewaarden overschreven. De opdrachtregelconfiguratieprovider bijvoorbeeld alle waarden van andere providers overschrijft omdat deze het laatst is toegevoegd. Als SomeKey is ingesteld in zowel appsettings.json als de omgeving, wordt de omgevingswaarde gebruikt omdat deze na appsettings.jsonis toegevoegd.

Bindend

Een van de belangrijkste voordelen van het gebruik van de .NET-configuratieabstracties is de mogelijkheid om configuratiewaarden te binden aan exemplaren van .NET-objecten. De JSON-configuratieprovider kan bijvoorbeeld worden gebruikt om appsettings.json bestanden toe te wijzen aan .NET-objecten en wordt gebruikt met afhankelijkheidsinjectie. Hierdoor kan het -optiepatroon, dat klassen gebruikt om sterk getypte toegang te bieden tot groepen van verwante instellingen. De standaardbinding is gebaseerd op weerspiegeling, maar er is een alternatieve brongenerator die u eenvoudig kunt inschakelen.

.NET-configuratie biedt verschillende abstracties. Houd rekening met de volgende interfaces:

  • IConfiguration: Vertegenwoordigt een set eigenschappen van de toepassingsconfiguratie voor sleutel/waarde.
  • IConfigurationRoot: vertegenwoordigt de wortel van een IConfiguration-hiërarchie.
  • IConfigurationSection: Vertegenwoordigt een sectie met toepassingsconfiguratiewaarden.

Deze abstracties zijn agnostisch voor hun onderliggende configuratieprovider (IConfigurationProvider). Met andere woorden, u kunt een IConfiguration exemplaar gebruiken voor toegang tot elke configuratiewaarde van meerdere providers.

De binder kan verschillende benaderingen gebruiken om configuratiewaarden te verwerken:

  • Directe deserialisatie (met behulp van ingebouwde conversieprogramma's) voor primitieve typen.
  • De TypeConverter voor een complex type als het type er een heeft.
  • Weerspiegeling voor een complex type met eigenschappen.

Notitie

De binder heeft enkele beperkingen:

  • Eigenschappen worden genegeerd als ze privé-setters hebben of als hun type niet kan worden geconverteerd.
  • Eigenschappen zonder bijbehorende configuratiesleutels worden genegeerd.

Bindinghiërarchieën

Configuratiewaarden kunnen hiërarchische gegevens bevatten. Hiërarchische objecten worden weergegeven met het gebruik van het : scheidingsteken in de configuratiesleutels. Als u toegang wilt krijgen tot een configuratiewaarde, gebruikt u het : teken om een hiërarchie te scheiden. Denk bijvoorbeeld aan de volgende configuratiewaarden:

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

De volgende tabel vertegenwoordigt voorbeeldsleutels en de bijbehorende waarden voor de voorgaande voorbeeld-JSON:

Sleutel Waarde
"Parent:FavoriteNumber" 7
"Parent:Child:Name" "Example"
"Parent:Child:GrandChild:Age" 3

Basisvoorbeeld

Als u configuratiewaarden in de basisvorm wilt openen, gebruikt u het ConfigurationBuilder type rechtstreeks zonder hulp van de algemene host benadering.

Tip

Het type System.Configuration.ConfigurationBuilder verschilt van het type Microsoft.Extensions.Configuration.ConfigurationBuilder. Al deze inhoud is specifiek voor de Microsoft.Extensions.* NuGet-pakketten en -naamruimten.

Overweeg het volgende C#-project:

<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>

Het voorgaande projectbestand verwijst naar verschillende NuGet-configuratiepakketten:

Bekijk een voorbeeld van appsettings.json bestand:

{
    "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"
        ]
    }
}

Op basis van dit JSON-bestand ziet u nu een voorbeeld van een verbruikspatroon met behulp van de opbouwfunctie voor configuraties:

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...

De voorgaande C#-code:

  • Instantieert een ConfigurationBuilder.
  • Voegt het "appsettings.json"-bestand toe dat moet worden herkend door de JSON-configuratieprovider.
  • Hiermee worden omgevingsvariabelen toegevoegd die worden herkend door de configuratieprovider voor omgevingsvariabelen.
  • Hiermee haalt u de benodigde sectie "Settings" en de bijbehorende Settings instantie op met behulp van de config-instantie.

Het Settings object heeft de volgende vorm:

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!;
}

Basisvoorbeeld met hosting

Voor toegang tot de IConfiguration-waarde kunt u opnieuw vertrouwen op het Microsoft.Extensions.Hosting NuGet-pakket. Maak een nieuwe consoletoepassing en plak de volgende inhoud van het projectbestand erin:

<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>

In het voorgaande projectbestand wordt gedefinieerd dat:

  • De toepassing is een uitvoerbaar bestand.
  • Een appsettings.json-bestand moet worden gekopieerd naar de uitvoermap wanneer het project wordt gecompileerd.
  • De Microsoft.Extensions.Hosting NuGet-pakketreferentie wordt toegevoegd.

Voeg het appsettings.json bestand toe aan de hoofdmap van het project met de volgende inhoud:

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

Vervang de inhoud van het Program.cs-bestand door de volgende C#-code:

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!

Wanneer u deze toepassing uitvoert, definieert de Host.CreateApplicationBuilder het gedrag om de JSON-configuratie te detecteren en beschikbaar te maken via het IConfiguration exemplaar. Vanuit het host exemplaar kunt u de serviceprovider om het IConfiguration exemplaar vragen, en vervolgens om de waarden vragen.

Tip

Het gebruik van de onbewerkte IConfiguration instantie op deze manier, hoewel handig, schaalt niet erg goed. Wanneer toepassingen complexer worden en de bijbehorende configuraties complexer worden, raden we u aan om het patroon opties te gebruiken als alternatief.

Basisvoorbeeld met hosting en het gebruik van de indexeerfunctie-API

Houd rekening met dezelfde appsettings.json bestandsinhoud uit het vorige voorbeeld:

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

Vervang de inhoud van het Program.cs-bestand door de volgende C#-code:

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

De waarden worden geopend met behulp van de indexeerfunctie-API waarbij elke sleutel een tekenreeks is en de waarde een tekenreeks is. Configuratie ondersteunt eigenschappen, objecten, matrices en woordenlijsten.

Configuratieproviders

In de volgende tabel ziet u de configuratieproviders die beschikbaar zijn voor .NET Core-apps.

Aanbieder Biedt configuratie van
Azure-app-configuratieprovider Azure App Configuration
Azure Key Vault-configuratieprovider Azure Key Vault
opdrachtregelconfiguratieprovider Opdrachtregelparameters
aangepaste configuratieprovider Aangepaste bron
configuratieprovider voor omgevingsvariabelen Omgevingsvariabelen
bestandsconfiguratieprovider JSON-, XML- en INI-bestanden
nl-NL: Sleutel-per-bestand-configuratieprovider Mapbestanden
geheugenconfiguratieprovider Verzamelingen in het geheugen
App-geheimen (Secret Manager) Het bestand in de gebruikersprofielmap

Tip

De volgorde waarin configuratieproviders worden toegevoegd, is belangrijk. Wanneer meerdere configuratieproviders worden gebruikt en meer dan één provider dezelfde sleutel opgeeft, wordt de laatste toegevoegde sleutel gebruikt.

Zie Configuratieproviders in .NETvoor meer informatie over verschillende configuratieproviders.

Zie ook