Compartir a través de

Generadores de configuración de ASP.NET

De Stephen Molloy y Rick Anderson

Los generadores de configuración proporcionan un mecanismo moderno y ágil para las aplicaciones ASP.NET que hacen posible obtener valores de configuración de orígenes externos.

Generadores de configuración:

  • Están disponibles en .NET Framework 4.7.1 y versiones posteriores.
  • Proporcionan un mecanismo flexible para leer los valores de configuración.
  • Solucionan algunas necesidades básicas de las aplicaciones, ya que se mueven a un entorno centrado en contenedores y en la nube.
  • Se pueden usar para mejorar la protección de datos de configuración mediante el dibujo de orígenes previamente no disponibles (por ejemplo, Azure Key Vault y variables de entorno) en el sistema de configuración de .NET.

Generadores de configuración de clave-valor

Un escenario común que los generadores de configuración pueden controlar es proporcionar un mecanismo básico de reemplazo de clave-valor para las secciones de configuración que siguen un patrón de clave-valor. El concepto de .NET Framework de ConfigurationBuilders no se limita a secciones o patrones de configuración específicos. Sin embargo, muchos de los generadores de configuración de Microsoft.Configuration.ConfigurationBuilders (github, NuGet) funcionan dentro del patrón de clave-valor.

Ajustes de generadores de configuración de clave-valor

La siguiente configuración se aplica a todos los generadores de configuración de clave-valor en Microsoft.Configuration.ConfigurationBuilders.

Modo

Los generadores de configuración usan un origen externo de información de clave-valor para rellenar los elementos clave-valor seleccionados del sistema de configuración. En concreto, las secciones <appSettings/> y <connectionStrings/> reciben un tratamiento especial por parte de los generadores de configuración. Los generadores funcionan en tres modos:

  • Strict: modo predeterminado. En este modo, el generador de configuración solo funciona en secciones de configuración conocidas centradas en clave-valor. El modo Strict enumera cada clave de la sección. Si se encuentra una clave coincidente en el origen externo:

    • Los generadores de configuración reemplazan el valor de la sección de configuración resultante por el valor del origen externo.

  • Greedy: este modo está estrechamente relacionado con el modo Strict. En lugar de limitarse a las claves que ya existen en la configuración original:

    • Los generadores de configuración agregan todos los pares clave-valor del origen externo a la sección de configuración resultante.

  • Expand: funciona en el XML sin formato antes de su análisis en un objeto de sección de configuración. Se puede considerar como una expansión de tokens en una cadena. Cualquier parte de la cadena XML sin formato que coincida con el patrón ${token} es candidata para la expansión de tokens. Si no se encuentra ningún valor correspondiente en el origen externo, no se cambia el token. Los generadores de este modo no se limitan a las secciones <appSettings/> y <connectionStrings/>.

El marcado siguiente de web.config habilita EnvironmentConfigBuilder en el modo Strict:

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

El código siguiente lee <appSettings/>, y <connectionStrings/> se muestra en el archivo web.config anterior:

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

El código anterior establecerá los valores de propiedad en:

  • Los valores del archivo web.config si las claves no están establecidas en variables de entorno.
  • Valores de la variable de entorno, si se establecen.

Por ejemplo, ServiceID contendrá:

  • "ServiceID value from web.config", si no se establece la variable de entorno ServiceID.
  • El valor de la variable de entorno ServiceID, si se establece.

En la imagen siguiente, se muestran los pares clave-valor <appSettings/> del archivo web.config anterior establecido en el editor de entornos:

Captura de pantalla que muestra el editor de variables de entorno con las variables ServiceID y ServiceKey resaltadas.

Nota: Es posible que tenga que salir de Visual Studio y reiniciarlo para ver los cambios en las variables de entorno.

Control de prefijos

Los prefijos de clave pueden simplificar la configuración de claves porque:

  • La configuración de .NET Framework es compleja y anidada.
  • Los orígenes de clave-valor externos suelen ser básicos y planos por naturaleza. Por ejemplo, las variables de entorno no están anidadas.

Use cualquiera de los métodos siguientes para insertar <appSettings/> y <connectionStrings/> en la configuración a través de variables de entorno:

  • Con EnvironmentConfigBuilder en el modo predeterminado Strict y los nombres de clave adecuados en el archivo de configuración. El código y el marcado anteriores adoptan este enfoque. Con este enfoque, no se puede tener claves con nombres idénticos en <appSettings/> y <connectionStrings/>.
  • Use dos EnvironmentConfigBuilders en modo Greedy con prefijos distintos y stripPrefix. Con este enfoque, la aplicación puede leer <appSettings/> y <connectionStrings/> sin necesidad de actualizar el archivo de configuración. En la sección siguiente, stripPrefix, se muestra cómo hacerlo.
  • Use dos EnvironmentConfigBuilders en modo Greedy con prefijos distintos. Con este enfoque, no puede tener nombres de clave duplicados, ya que los nombres de clave deben diferir por prefijo. Por ejemplo:
<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>

Con el marcado anterior, se puede usar el mismo origen plano de clave/valor para rellenar la configuración de dos secciones diferentes.

En la imagen siguiente, se muestran los pares clave-valor <appSettings/> y <connectionStrings/> del archivo web.config anterior establecido en el editor de entorno:

Captura de pantalla que muestra el editor de variables de entorno con las variables AppSetting_default, AppSetting_ServiceID y ConnStr_default resaltadas.

El código siguiente lee los valores <appSettings/> y <connectionStrings/> incluidos en el archivo web.config anterior:

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

El código anterior establecerá los valores de propiedad en:

  • Los valores del archivo web.config si las claves no están establecidas en variables de entorno.
  • Valores de la variable de entorno, si se establecen.

Por ejemplo, con el archivo web.config anterior, los pares clave-valor de la imagen del editor de entorno anterior y el código anterior, se establecen los siguientes valores:

Key Value
AppSetting_ServiceID AppSetting_ServiceID de variables env
AppSetting_default AppSetting_default de env
ConnStr_default ConnStr_default de env

stripPrefix

stripPrefix: booleano, el valor predeterminado es false.

El marcado XML anterior separa la configuración de la aplicación de las cadenas de conexión, pero requiere todas las claves del archivo web.config para usar el prefijo especificado. Por ejemplo, el prefijo AppSetting debe agregarse a la clave ServiceID ("AppSetting_ServiceID"). Con stripPrefix, el prefijo no se usa en el archivo web.config. El prefijo es necesario en el origen del generador de configuración (por ejemplo, en el entorno). Anticipamos que la mayoría de los desarrolladores usarán stripPrefix.

Las aplicaciones suelen quitar el prefijo. El siguiente archivo web.config quita el prefijo:

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

En el archivo web.config anterior, la clave default está en <appSettings/> y <connectionStrings/>.

En la imagen siguiente, se muestran los pares clave-valor <appSettings/> y <connectionStrings/> del archivo web.config anterior establecido en el editor de entorno:

Captura de pantalla que muestra el editor de variables de entorno con las variables AppSetting_default, AppSetting_ServiceID y ConnStr_default resaltadas.

El código siguiente lee los valores <appSettings/> y <connectionStrings/> incluidos en el archivo web.config anterior:

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

El código anterior establecerá los valores de propiedad en:

  • Los valores del archivo web.config si las claves no están establecidas en variables de entorno.
  • Valores de la variable de entorno, si se establecen.

Por ejemplo, con el archivo web.config anterior, los pares clave-valor de la imagen del editor de entorno anterior y el código anterior, se establecen los siguientes valores:

Key Value
ServiceID AppSetting_ServiceID de variables env
default AppSetting_default de env
default ConnStr_default de env

tokenPattern

tokenPattern: cadena, el valor predeterminado es @"\$\{(\w+)\}"

El comportamiento Expand de los generadores busca en el XML sin procesar los tokens que tienen un aspecto similar a ${token}. La búsqueda se realiza con la expresión regular predeterminada @"\$\{(\w+)\}". El conjunto de caracteres que coincide con \w es más estricto que lo que XML y muchos orígenes de configuración permiten. Use tokenPattern cuando se necesiten más caracteres de los @"\$\{(\w+)\}" necesarios en el nombre del token.

tokenPattern: cadena:

  • Permite a los desarrolladores cambiar la expresión regular que se usa para la coincidencia de tokens.
  • No se realiza ninguna validación para asegurarse de que es una expresión regular bien formada y que no es peligrosa.
  • Debe contener un grupo de captura. La expresión regular completa debe coincidir con todo el token. La primera captura debe ser el nombre del token que buscar en el origen de configuración.

Generadores de configuración en Microsoft.Configuration.ConfigurationBuilders

EnvironmentConfigBuilder

<add name="Environment"
    [mode|prefix|stripPrefix|tokenPattern] 
    type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Environment" />

El EnvironmentConfigBuilder:

  • Es el más sencillo de los generadores de configuración.
  • Lee los valores del entorno.
  • No tiene ninguna opción de configuración adicional.
  • El valor del atributo name es arbitrario.

Nota: En un entorno de contenedor de Windows, las variables establecidas en tiempo de ejecución solo se insertan en el entorno de proceso de EntryPoint. Las aplicaciones que se ejecutan como servicio o un proceso que no sea EntryPoint no seleccionan estas variables a menos que se inserten de otro modo a través de un mecanismo en el contenedor. En el caso de los contenedores basados en IIS/ASP.NET, la versión actual de ServiceMonitor.exe lo controla solo en DefaultAppPool. Es posible que otras variantes de contenedor basadas en Windows necesiten desarrollar su propio mecanismo de inyección para procesos que no son de EntryPoint.

UserSecretsConfigBuilder

Advertencia

Nunca almacene contraseñas, cadenas de conexión confidenciales u otros datos confidenciales en el código fuente. Los secretos de producción no se deben usar para desarrollo o prueba.

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

En el XML anterior, la ruta de acceso userSecretsFile puede usar ~/ o ~\. Por ejemplo, la ruta de acceso podría escribirse como userSecretsFile="~/secrets.file. Consulte la clase ConfigurationBuilders Utils para obtener más información.

Este generador de configuración proporciona una característica similar a ASP.NET Core Secret Manager.

El UserSecretsConfigBuilder se puede usar en proyectos de .NET Framework, pero se debe especificar un archivo de secretos. Como alternativa, puede definir la propiedad UserSecretsId en el archivo de proyecto y crear el archivo de secretos sin procesar en la ubicación correcta para leer. Para mantener las dependencias externas fuera del proyecto, el archivo secreto tiene formato XML. El formato XML es un detalle de implementación y no se debe confiar en el formato. Si necesita compartir un archivo secrets.json con proyectos de .NET Core, considere la posibilidad de usar SimpleJsonConfigBuilder. El formato SimpleJsonConfigBuilder de .NET Core también debe considerarse un detalle de implementación sujeto a cambios.

Atributos de configuración para UserSecretsConfigBuilder:

  • userSecretsId: este es el método preferido para identificar un archivo de secretos XML. Funciona de forma similar a .NET Core, que usa una propiedad de proyecto UserSecretsId para almacenar este identificador. La cadena debe ser única, no es necesario que sea un GUID. Con este atributo, el UserSecretsConfigBuilder busca en una ubicación local conocida (%APPDATA%\Microsoft\UserSecrets\<UserSecrets Id>\secrets.xml) un archivo de secretos que pertenece a este identificador.
  • userSecretsFile: atributo opcional que especifica el archivo que contiene los secretos. El carácter ~ se puede usar al principio para hacer referencia a la raíz de la aplicación. Se requiere este atributo o el atributo userSecretsId. Si se especifican ambos, userSecretsFile tiene prioridad.
  • optional: valor booleano predeterminado true: impide una excepción si no se encuentra el archivo de secretos.
  • El valor del atributo name es arbitrario.

El archivo de secretos tiene el formato siguiente:

<?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" />

El AzureKeyVaultConfigBuilder lee los valores almacenados en Azure Key Vault.

vaultName es necesario (el nombre del almacén o un identificador URI al almacén). Los demás atributos permiten controlar a qué almacén conectarse, pero solo son necesarios si la aplicación no se está ejecutando en un entorno que funciona con Microsoft.Azure.Services.AppAuthentication. La biblioteca de autenticación de servicios de Azure se usa para recoger automáticamente la información de conexión del entorno de ejecución, si es posible. Puede invalidar automáticamente la selección de información de conexión al proporcionar una cadena de conexión.

  • vaultName: obligatorio si uri no se proporciona. Especifica el nombre del almacén en la suscripción de Azure desde la que se van a leer pares clave-valor.
  • uri: se conecta a otros proveedores de Key Vault con el valor especificado uri. Si no se especifica, Azure (vaultName) es el proveedor del almacén.
  • version: Azure Key Vault proporciona una característica de control de versiones para secretos. Si version se especifica, el generador solo recupera secretos que coinciden con esta versión.
  • preloadSecretNames: de forma predeterminada, este generador consulta todos los nombres de claves del almacén de claves cuando se inicializa. Para evitar la lectura de todos los valores de clave, establezca este atributo como false. Al establecer esto como false, se leen los secretos de uno en uno. La lectura de secretos de uno en uno puede resultar útil si el almacén permite el acceso "Get", pero no el acceso "List". Nota: Al usar el modo Greedy, preloadSecretNames debe ser true (el valor predeterminado).

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 es un generador de configuración básico que usa los archivos de un directorio como origen de valores. El nombre de un archivo es la clave y el contenido es el valor. Este generador de configuración puede ser útil cuando se ejecuta en un entorno de contenedor orquestado. Los sistemas como Docker Swarm y Kubernetes proporcionan secrets a sus contenedores de Windows orquestados de esta manera clave por archivo.

Detalles del atributo:

  • directoryPath - Obligatorio. Especifica una ruta de acceso para buscar valores. Los secretos de Docker para Windows se almacenan en el directorio C:\ProgramData\Docker\secrets de forma predeterminada.
  • ignorePrefix: se excluyen los archivos que empiecen por este prefijo. Se establece en "ignore." de forma predeterminada.
  • keyDelimiter: el valor predeterminado es null. Si se especifica, el generador de configuración recorre varios niveles del directorio y crea nombres de clave con este delimitador. Si este valor es null, el generador de configuración solo examina el nivel superior del directorio.
  • optional: el valor predeterminado es false. Especifica si el generador de configuración debe producir errores si el directorio de origen no existe.

SimpleJsonConfigBuilder

Advertencia

Nunca almacene contraseñas, cadenas de conexión confidenciales u otros datos confidenciales en el código fuente. Los secretos de producción no se deben usar para desarrollo o prueba.

<add name="SimpleJson"
    [mode|prefix|stripPrefix|tokenPattern]
    jsonFile="~\config.json"
    [optional="true"]
    [jsonMode="(Flat|Sectional)"]
    type="Microsoft.Configuration.ConfigurationBuilders.SimpleJsonConfigBuilder,
    Microsoft.Configuration.ConfigurationBuilders.Json" />

Los proyectos de .NET Core usan con frecuencia archivos JSON para la configuración. El generador SimpleJsonConfigBuilder permite usar archivos JSON de .NET Core en .NET Framework. Este generador de configuración proporciona una asignación básica de un origen plano de clave-valor en áreas de clave-valor específicas de la configuración de .NET Framework. Este generador de configuración no proporciona configuraciones jerárquicas. El archivo de respaldo JSON es similar a un diccionario, no a un objeto jerárquico complejo. Se puede usar un archivo jerárquico de varios niveles. Este proveedor flatten la profundidad al anexar el nombre de propiedad en cada nivel mediante : como delimitador.

Detalles del atributo:

  • jsonFile - Obligatorio. Especifica el archivo JSON del que se va a leer. El carácter ~ se puede usar al principio para hacer referencia a la raíz de la aplicación.

  • optional: booleano, el valor predeterminado es true. Impide que se produzcan excepciones si no se encuentra el archivo JSON.

  • jsonMode - [Flat|Sectional]. Flat es el valor predeterminado. Cuando jsonMode es Flat, el archivo JSON es un único origen plano de clave-valor. EnvironmentConfigBuilder y AzureKeyVaultConfigBuilder también son orígenes planos de clave-valor. Cuando SimpleJsonConfigBuilder está configurado en modo Sectional:

    • El archivo JSON se divide conceptualmente en el nivel superior en varios diccionarios.
    • Cada uno de los diccionarios solo se aplica a la sección de configuración que coincide con el nombre de propiedad de nivel superior adjunto a ellos. Por ejemplo:
    {
        "appSettings" : {
            "setting1" : "value1",
            "setting2" : "value2",
            "complex" : {
                "setting1" : "complex:value1",
                "setting2" : "complex:value2",
            }
        }
    }

Orden de los generadores de configuración

Consulte Orden de ejecución de ConfigurationBuilders en el repositorio de GitHub aspnet/MicrosoftConfigurationBuilders.

Implementación de un generador de configuración de clave-valor personalizado

Si los generadores de configuración no satisfacen sus necesidades, puede escribir uno personalizado. La clase base KeyValueConfigBuilder controla los modos de sustitución y la mayoría de los problemas de prefijo. Un proyecto de implementación solo necesita lo siguiente:

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

La clase base KeyValueConfigBuilder proporciona gran parte del trabajo y el comportamiento coherente entre los generadores de configuración clave-valor.

Recursos adicionales