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.

Descargar PDF

La forma principal de cargar la configuración de la aplicación en Formularios Web Forms es con entradas en el archivo web.config , ya sea en el servidor o en un archivo de configuración relacionado al que hace referenciaweb.config. Puede usar el objeto estático ConfigurationManager para interactuar con la configuración de la aplicación, las cadenas de conexión del 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 servidor Blazor, el archivo web.config puede estar presente si la aplicación está hospedada en un servidor de Windows IIS. 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. Echemos un vistazo a cómo se recopila la configuración y cómo usted puede seguir accediendo a la 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 ofrecer lo mejor de estas características de forma predeterminada. La configuración es leída y agregada por ASP.NET Core desde estos diversos orígenes. Los valores cargados posteriormente para la misma clave de configuración tienen prioridad sobre los valores anteriores.

ASP.NET Core se diseñó para ser consciente de la nube y facilitar la configuración de aplicaciones para los operadores y desarrolladores. ASP.NET Core es consciente del entorno y sabe si se está ejecutando en el entorno Production o Development. El indicador de entorno se establece en la variable de entorno del ASPNETCORE_ENVIRONMENT sistema. Si no hay ningún valor configurado, la aplicación se ejecuta de forma predeterminada en el Production entorno.

Tu aplicación puede activar y agregar configuración desde varios orígenes dependiendo del nombre del entorno. De forma predeterminada, la configuración se carga desde los siguientes recursos en el orden indicado:

1. appsettings.json archivo, si está presente
2. El archivo appsettings.{NOMBRE_DEL_ENTORNO}.json, si existe
3. Archivo de secretos de usuario en el disco, si está presente
4. Variables de entorno
5. 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 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 section1:key0 de configuración accede al valor section1 del objeto literal key0.

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 aplicaciones.
• Solo se carga cuando se ejecuta en el Development entorno.
• Asociado a una aplicación específica.
• Administrado con el comando user-secrets de la CLI de .NET.

Configure la aplicación para el almacenamiento de secretos ejecutando el user-secrets comando :

dotnet user-secrets init

El comando anterior agrega un UserSecretsId elemento al archivo del proyecto. El elemento contiene un GUID, que se usa para asociar secretos a la aplicación. A continuación, puede definir un secreto con el set comando . Por ejemplo:

dotnet user-secrets set "Parent:ApiKey" "12345"

El comando anterior hace que la Parent:ApiKey clave de configuración 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, consulte el documento Almacenamiento seguro de secretos de aplicaciones en desarrollo en ASP.NET Core .

Variables de entorno

El siguiente conjunto de valores cargados en la configuración de la aplicación es las variables de entorno del sistema. Ahora se puede acceder a todos los valores de la variable de entorno del sistema a través 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 de Parent:ApiKey de la sección de secretos de usuario anterior se puede sobrescribir 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 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 los siguientes comandos:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890

El regreso de web.config

Si ha implementado la aplicación en Windows en IIS, el archivo web.config sigue configurando IIS para administrar la aplicación. De forma predeterminada, IIS agrega una referencia al módulo principal de ASP.NET (ANCM). ANCM es un módulo IIS nativo que hospeda la aplicación en lugar del servidor web Kestrel. Esta sección web.config es similar al siguiente marcado XML:

<?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 anidando un elemento environmentVariables dentro del 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 correctamente 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>

Leer la configuración en la aplicación

ASP.NET Core proporciona la configuración de la aplicación a través de la IConfiguration interfaz . Los Blazor componentes, las Blazor páginas y cualquier otra clase administrada por ASP.NET Core que necesite acceso a la configuración deben solicitar esta interfaz de configuración. El marco ASP.NET Core rellenará automáticamente esta interfaz con la configuración resuelta configurada anteriormente. En una página Blazor o en el marcado Razor de un componente, puede insertar el objeto IConfiguration utilizando una directiva @inject en la parte superior del archivo .razor de la siguiente manera:

@inject IConfiguration Configuration

Esta instrucción anterior hace que el IConfiguration objeto esté disponible como la Configuration variable en todo el resto de la plantilla de Razor.

Las opciones de configuración individuales se pueden leer especificando la jerarquía de configuración buscada como parámetro de indexador:

var mySetting = Configuration["section1:key0"];

Puede capturar secciones de configuración completas mediante el GetSection método para recuperar una colección de claves en una ubicación específica con una sintaxis similar a GetSection("section1") para recuperar la configuración de section1 del ejemplo anterior.

Configuración fuertemente tipada

Con Web Forms, era posible crear un tipo de configuración fuertemente tipado que heredaba del tipo ConfigurationSection y de los tipos asociados. Un ConfigurationSection le permite configurar algunas reglas de negocio y el procesamiento para 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 las propiedades public que coincidan con las propiedades y las referencias de tipo de la configuración que desea capturar.

En el ejemplo anterior deappsettings.json , podría definir las siguientes clases 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 Startup.ConfigureServices método (o la ubicación adecuada en Program.cs mediante la builder.Services propiedad 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 IOptions<MyConfig>.Value propiedad producirá el valor MyConfig obtenido 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.

Siguiente anterior