Configuración en .NET

La configuración de .NET se realiza mediante uno o varios proveedores de configuración. Los proveedores de configuración leen los datos de configuración de los pares clave-valor usando distintos orígenes de configuración:

• Archivos de configuración, como appsettings.json
• Variables de entorno
• Azure Key Vault
• Azure App Configuration
• Argumentos de la línea de comandos
• Proveedores personalizados, instalados o creados
• Archivos de directorio
• Objetos .NET en memoria
• Proveedores de terceros

Conceptos y abstracciones

Dados uno o varios orígenes de configuración, el IConfiguration tipo proporciona una vista unificada de los datos de configuración. La configuración es de solo lectura y el patrón de configuración no está diseñado para que se pueda escribir mediante programación. La IConfiguration interfaz es una sola representación de todos los orígenes de configuración, como se muestra en el diagrama siguiente:

Configuración de aplicaciones de consola

Las aplicaciones de consola de .NET creadas con la plantilla de comandos dotnet new o Visual Studio de forma predeterminada no exponen las funcionalidades de configuración. Para agregar la configuración en una nueva aplicación de consola de .NET, agregue una referencia de paquete a Microsoft.Extensions.Configuration. Este paquete es la base para la configuración en aplicaciones .NET. Proporciona ConfigurationBuilder y tipos relacionados.

using Microsoft.Extensions.Configuration;

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

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

// Outputs:
//   SomeValue

El código anterior:

• Crea una nueva instancia de ConfigurationBuilder.
• Agrega una colección en memoria de pares clave-valor al generador de configuración.
• Llama al Build() método para crear una IConfiguration instancia.
• Escribe el valor de la SomeKey clave en la consola.

Aunque en este ejemplo se usa una configuración en memoria, hay muchos proveedores de configuración disponibles, lo que expone la funcionalidad para las variables de entorno basadas en archivos, los argumentos de la línea de comandos y otros orígenes de configuración. Para obtener más información, consulte Proveedores de configuración en .NET.

Enfoque de hospedaje alternativo

Normalmente, las aplicaciones harán más que solo leer la configuración. Es probable que usen la inserción de dependencias, el registro y otros servicios. Se recomienda el enfoque de host genérico de .NET para las aplicaciones que usan estos servicios. En su lugar, considere la posibilidad de agregar una referencia de paquete a Microsoft.Extensions.Hosting. Modifique el archivo Program.cs para que coincida con el código siguiente:

using Microsoft.Extensions.Hosting;

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

// Application code should start here.

await host.RunAsync();

El Host.CreateApplicationBuilder(String[]) método proporciona la configuración predeterminada para la aplicación en el orden siguiente, de la prioridad más alta a la más baja:

1. Argumentos de línea de comandos mediante el proveedor de configuración de línea de comandos.
2. Variables de entorno utilizando el proveedor de configuración de variables de entorno.
3. Secretos de la aplicación cuando la aplicación se ejecuta en el Development entorno.
4. appsettings.json mediante el proveedor de configuración JSON.
5. appsettings.Environment.json con el proveedor de configuración JSON. Por ejemplo, appsettings. Producción. json y appsettings. Desarrollo. json.
6. ChainedConfigurationProvider : agrega un existente IConfiguration como origen.

Agregar un proveedor de configuración invalida los valores de configuración anteriores. Por ejemplo, el proveedor de configuración de línea de comandos invalida todos los valores de otros proveedores porque se agrega por última vez. Si SomeKey se establece tanto en appsettings.json como en el entorno, se usa el valor de entorno porque se agregó después de appsettings.json.

Enlace

Una de las principales ventajas de usar las abstracciones de configuración de .NET es la capacidad de enlazar valores de configuración a instancias de objetos .NET. Por ejemplo, el proveedor de configuración JSON se puede usar para asignar archivosappsettings.json a objetos .NET y se usa con la inserción de dependencias. Esto habilita el patrón de opciones, que utiliza clases para proporcionar un acceso fuertemente tipado a grupos de configuraciones relacionadas. El enlazador predeterminado está basado en la reflexión, pero hay un generador de origen alternativo que es fácil de activar.

La configuración de .NET proporciona varias abstracciones. Tenga en cuenta las interfaces siguientes:

• IConfiguration: representa un conjunto de propiedades de configuración de la aplicación clave-valor.
• IConfigurationRoot: representa la raíz de una IConfiguration jerarquía.
• IConfigurationSection: representa una sección de valores de configuración de la aplicación.

Estas abstracciones son independientes de su proveedor de configuración subyacente (IConfigurationProvider). En otras palabras, puede usar una IConfiguration instancia para acceder a cualquier valor de configuración de varios proveedores.

El vinculador puede usar diversos enfoques para procesar los valores de configuración.

• Deserialización directa (mediante convertidores integrados) para tipos primitivos.
• TypeConverter para un tipo complejo cuando el tipo tiene uno.
• Reflexión sobre un tipo complejo que tiene propiedades.

Jerarquías de enlace

Los valores de configuración pueden contener datos jerárquicos. Los objetos jerárquicos se representan con el uso del delimitador : en las claves de configuración. Para acceder a un valor de configuración, use el : carácter para delimitar una jerarquía. Por ejemplo, considere los siguientes valores de configuración:

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

En la tabla siguiente se representan claves de ejemplo y sus valores correspondientes para el json de ejemplo anterior:

Ejemplo básico

Para acceder a los valores de configuración en su forma básica, use el tipo ConfigurationBuilder directamente, sin la ayuda del enfoque de host genérico.

Tenga en cuenta el siguiente proyecto de C#:

<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.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.6" />
    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.6" />
  </ItemGroup>

</Project>

El archivo de proyecto anterior hace referencia a varios paquetes NuGet de configuración:

• Microsoft.Extensions.Configuration.Binder: funcionalidad para enlazar un objeto a datos de proveedores de configuración para Microsoft.Extensions.Configuration.
• Microsoft.Extensions.Configuration.Json: implementación del proveedor de configuración JSON para Microsoft.Extensions.Configuration.
• Microsoft.Extensions.Configuration.EnvironmentVariables: implementación del proveedor de configuración de variables de entorno para Microsoft.Extensions.Configuration.

Considere un ejemplo appsettings.json archivo:

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

Ahora, dado este archivo JSON, este es un patrón de consumo de ejemplo que usa directamente el generador de configuración:

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

El código de C# anterior:

• Crea instancias de ConfigurationBuilder.
• Agrega el archivo "appsettings.json" para que lo reconozca el proveedor de configuración JSON.
• Agrega variables de entorno como reconocidas por el proveedor de configuración de variables de entorno.
• Obtiene la sección necesaria "Settings" y la instancia correspondiente Settings mediante la instancia config.

El Settings objeto tiene la forma siguiente:

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

Ejemplo básico con hospedaje

Para acceder al valor IConfiguration, puede confiar nuevamente en el paquete NuGet Microsoft.Extensions.Hosting. Cree una nueva aplicación de consola y pegue el siguiente contenido del archivo de proyecto en ella:

<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.6" />
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.6" />
  </ItemGroup>

</Project>

El archivo de proyecto anterior define que:

• La aplicación es un ejecutable.
• Un archivo appsettings.json se va a copiar en el directorio de salida cuando se compila el proyecto.
• Se agrega la referencia del Microsoft.Extensions.Hosting paquete NuGet.

Agregue el archivo appsettings.json en la raíz del proyecto con el siguiente contenido:

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

Reemplace el contenido del archivo Program.cs por el siguiente código de C#:

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!

Al ejecutar esta aplicación, Host.CreateApplicationBuilder define el comportamiento para detectar la configuración json y exponerla a través de la IConfiguration instancia. Desde la instancia host, puede solicitar al proveedor de servicios la instancia IConfiguration y luego solicitarle valores.

Ejemplo básico con hospedaje y uso de la API del indexador

Tenga en cuenta el mismo contenido del archivoappsettings.json del ejemplo anterior:

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

Reemplace el contenido del archivo Program.cs por el siguiente código de C#:

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

Se obtiene acceso a los valores mediante la API del indexador donde cada clave es una cadena y el valor es una cadena. La configuración admite propiedades, objetos, matrices y diccionarios.

Proveedores de configuración

En la tabla siguiente se muestran los proveedores de configuración disponibles para las aplicaciones de .NET Core.

Para obtener más información sobre varios proveedores de configuración, consulte Proveedores de configuración en .NET.

Consulte también

• Proveedores de configuración en .NET
• Implementación de un proveedor de configuración personalizado
• Los errores de configuración se deben crear en el repositorio de github.com/dotnet/runtime
• Configuración en ASP.NET Core