Configuración de la aplicación
Sugerencia
Este contenido es un extracto del libro electrónico "Blazor for ASP.NET Web Forms Developers for Azure" (Blazor para desarrolladores de ASP.NET Web Forms), disponible en Documentación de .NET o como un PDF descargable y gratuito que se puede leer sin conexión.
La forma principal de cargar la configuración de la aplicación en Web Forms consiste en usar entradas del archivo web.config, ya sea en el servidor o en un archivo de configuración relacionado al que web.config haga referencia. Puede usar el objeto estático para interactuar con la configuración de la aplicación ConfigurationManager, las cadenas de conexión de repositorio de datos y otros proveedores de configuración extendidos que se agregan a la aplicación. Es habitual ver las interacciones con la configuración de la aplicación como se muestra en el código siguiente:
var configurationValue = ConfigurationManager.AppSettings["ConfigurationSettingName"];
var connectionString = ConfigurationManager.ConnectionStrings["MyDatabaseConnectionName"].ConnectionString;
Con ASP.NET Core y Blazor del lado servidor, es posible que el archivo web.config esté presente si la aplicación se hospeda en un servidor IIS de Windows. Pero, no hay ninguna interacción de ConfigurationManager con esta configuración y puede recibir una configuración de aplicación más estructurada de otros orígenes. Ahora se verá cómo se recopila la configuración y cómo puede seguir accediendo a la información de configuración desde un archivo web.config.
Orígenes de configuración
ASP.NET Core reconoce que hay muchos orígenes de configuración que puede usar para la aplicación. El marco intenta ofrecerle lo mejor de estas características de forma predeterminada. La configuración se lee y se agrega desde estos diversos orígenes mediante ASP.NET Core. Los valores cargados posteriormente para la misma clave de configuración tienen prioridad sobre los valores anteriores.
ASP.NET Core se ha diseñado para ser compatible con la nube y para facilitar a operadores y desarrolladores la configuración de las aplicaciones. ASP.NET Core es consciente del entorno y sabe si se ejecuta en Production o Development. El indicador de entorno se establece en la variable de entorno del sistema ASPNETCORE_ENVIRONMENT. Si no se configura ningún valor, la aplicación se ejecuta en el entorno Production de forma predeterminada.
La aplicación puede desencadenar y agregar la configuración de varios orígenes según el nombre del entorno. De forma predeterminada, la configuración se carga desde los recursos siguientes en el orden mostrado:
- El archivo appsettings.json, si existe
- El archivo appsettings.{NOMBRE_DEL_ENTORNO}.json, si existe
- Archivo de secretos de usuario en disco, si existe
- Variables de entorno
- Argumentos de la línea de comandos
Formato del archivo appsettings.json y cómo acceder a él
El archivo appsettings.json puede ser jerárquico con valores estructurados como el siguiente código JSON:
{
"section0": {
"key0": "value",
"key1": "value"
},
"section1": {
"key0": "value",
"key1": "value"
}
}
Cuando se le presenta el código JSON anterior, el sistema de configuración acopla los valores secundarios y hace referencia a sus rutas de acceso jerárquicas completas. Las propiedades de la jerarquía se separan mediante un carácter de dos puntos (:). Por ejemplo, la clave de configuración section1:key0 accede al valor key0 del literal de objeto section1.
Secretos de usuario
Los secretos de usuario:
- Son valores de configuración que se almacenan en un archivo JSON en la estación de trabajo del desarrollador, fuera de la carpeta de desarrollo de la aplicación.
- Solo se cargan cuando se ejecutan en el entorno
Development. - Están asociados a una aplicación específica.
- Se administran con el comando
user-secretsde la CLI de .NET.
Configure la aplicación para el almacenamiento de secretos mediante la ejecución del comando user-secrets:
dotnet user-secrets init
El comando anterior agrega un elemento UserSecretsId al archivo del proyecto. El elemento contiene un GUID, que se usa para asociar secretos con la aplicación. Después, puede definir un secreto con el comando set. Por ejemplo:
dotnet user-secrets set "Parent:ApiKey" "12345"
El comando anterior hace que la clave de configuración Parent:ApiKey esté disponible en la estación de trabajo de un desarrollador con el valor 12345.
Para obtener más información sobre cómo crear, almacenar y administrar secretos de usuario, vea el documento Almacenamiento seguro de secretos de aplicación en el desarrollo en ASP.NET Core.
Variables de entorno
El siguiente conjunto de valores que se carga en la configuración de la aplicación son las variables de entorno del sistema. Ahora toda la configuración de variables de entorno del sistema es accesible por medio de la API de configuración. Los valores jerárquicos se acoplan y separan mediante caracteres de dos puntos cuando se leen dentro de la aplicación. Pero algunos sistemas operativos no admiten los nombres de variables de entorno con caracteres de dos puntos. ASP.NET Core soluciona esta limitación mediante la conversión de valores que tienen caracteres de subrayado doble (__) en un signo de dos puntos cuando se accede a ellos. El valor Parent:ApiKey de la sección de secretos de usuario anterior se puede reemplazar con la variable de entorno Parent__ApiKey.
Argumentos de la línea de comandos
La configuración también se puede proporcionar como argumentos de la línea de comandos cuando se inicia la aplicación. Use la notación de doble guión (--) o barra diagonal (/) para indicar el nombre del valor de configuración que se va a establecer y el valor que se va a configurar. La sintaxis es similar a la de los comandos siguientes:
dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890
El valor devuelto de web.config
Si ha implementado la aplicación en Windows en IIS, el archivo web.config todavía configura IIS para administrar la aplicación. De forma predeterminada, IIS agrega una referencia al módulo de ASP.NET Core (ANCM). ANCM es un módulo de IIS nativo en el que se hospeda la aplicación en lugar del servidor web Kestrel. Esta sección de web.config es similar al marcado XML siguiente:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<location path="." inheritInChildApplications="false">
<system.webServer>
<handlers>
<add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
</handlers>
<aspNetCore processPath=".\MyApp.exe"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess" />
</system.webServer>
</location>
</configuration>
La configuración específica de la aplicación se puede definir si se anida un elemento environmentVariables en el elemento aspNetCore. Los valores definidos en esta sección se presentan a la aplicación ASP.NET Core como variables de entorno. Las variables de entorno se cargan de forma correcta durante ese segmento de inicio de la aplicación.
<aspNetCore processPath="dotnet"
arguments=".\MyApp.dll"
stdoutLogEnabled="false"
stdoutLogFile=".\logs\stdout"
hostingModel="inprocess">
<environmentVariables>
<environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
<environmentVariable name="Parent:ApiKey" value="67890" />
</environmentVariables>
</aspNetCore>
Lectura de la configuración en la aplicación
En ASP.NET Core, la configuración se proporciona por medio de la interfaz IConfiguration. Esta interfaz de configuración la deben solicitar los componentes de Blazor, las páginas de Blazor y cualquier otra clase administrada por ASP.NET Core que necesite acceder a la configuración. El marco ASP.NET Core rellenará automáticamente esta interfaz con la configuración resuelta que se ha configurado antes. En el marcado de Razor de un componente o una página de Blazor, puede insertar el objeto IConfiguration con una directiva @inject en la parte superior del archivo .razor de la siguiente manera:
@inject IConfiguration Configuration
Esta instrucción hace que el objeto IConfiguration esté disponible como la variable Configuration en el resto de la plantilla de Razor.
Se pueden leer valores de configuración individuales si se especifica la jerarquía de valores de configuración que se busca como parámetro de indizador:
var mySetting = Configuration["section1:key0"];
Puede capturar secciones de configuración completas si usa el método GetSection para recuperar una colección de claves en una ubicación concreta con una sintaxis similar a GetSection("section1") para recuperar la configuración de section1 en el ejemplo anterior.
Configuración fuertemente tipada
Con Web Forms, es posible crear un tipo de configuración fuertemente tipado que se hereda del tipo ConfigurationSection y de tipos asociados. ConfigurationSection permite configurar algunas reglas de negocio y el procesamiento de esos valores de configuración.
En ASP.NET Core, puede especificar una jerarquía de clases que recibirá los valores de configuración. Estas clases:
- No necesitan heredarse de una clase primaria.
- Debe incluir propiedades
publicque coincidan con las propiedades y las referencias de tipo de la estructura de configuración que se quiere capturar.
Para el ejemplo de appsettings.json anterior, podría definir las clases siguientes para capturar los valores:
public class MyConfig
{
public MyConfigSection section0 { get; set;}
public MyConfigSection section1 { get; set;}
}
public class MyConfigSection
{
public string key0 { get; set; }
public string key1 { get; set; }
}
Esta jerarquía de clases se puede rellenar agregando la siguiente línea al método Startup.ConfigureServices, o bien la ubicación apropiada en Program.cs mediante la propiedad builder.Services en lugar de services:
services.Configure<MyConfig>(Configuration);
En el resto de la aplicación, puede agregar un parámetro de entrada a las clases o una directiva @inject en las plantillas de Razor de tipo IOptions<MyConfig> para recibir los valores de configuración fuertemente tipados. La propiedad IOptions<MyConfig>.Value dará como resultado el valor MyConfig rellenado a partir de los valores de configuración.
@inject IOptions<MyConfig> options
@code {
var MyConfiguration = options.Value;
var theSetting = MyConfiguration.section1.key0;
}
Puede encontrar más información sobre la característica de opciones en el documento Patrón de opciones de ASP.NET Core.
