Usar varios entornos en ASP.NET Core

Por Rick Anderson y Kirk Larkin

ASP.NET Core configura el comportamiento de las aplicaciones en función del entorno en tiempo de ejecución mediante una variable de entorno.

Entornos

Para determinar el entorno de ejecución, ASP.NET Core lee de las siguientes variables de entorno:

1. DOTNET_ENVIRONMENT
2. ASPNETCORE_ENVIRONMENT cuando se llama al método WebApplication.CreateBuilder. Las plantillas de aplicación web de ASP.NET Core predeterminadas llaman a WebApplication.CreateBuilder. El valor DOTNET_ENVIRONMENT invalida ASPNETCORE_ENVIRONMENT cuando se usa WebApplicationBuilder. En el caso de otros hosts, como ConfigureWebHostDefaults y WebHost.CreateDefaultBuilder, ASPNETCORE_ENVIRONMENT tiene mayor prioridad.

IHostEnvironment.EnvironmentName se puede establecer en cualquier valor, pero el marco proporciona los siguientes valores:

• Development: el archivo launchSettings.json establece ASPNETCORE_ENVIRONMENT en Development en la máquina local.
• Staging
• Production: el valor predeterminado si DOTNET_ENVIRONMENT y ASPNETCORE_ENVIRONMENT no se han establecido.

El código siguiente:

• Es similar al código generado por las plantillas de ASP.NET Core.
• Habilita la página de excepciones del desarrollador cuando ASPNETCORE_ENVIRONMENT se establece en Development. El método WebApplication.CreateBuilder realiza automáticamente esta acción.
• Llama a UseExceptionHandler cuando el valor de ASPNETCORE_ENVIRONMENT es distinto de Development.
• Proporciona una instancia de IWebHostEnvironment en la propiedad Environment de WebApplication.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

El asistente de etiquetas de entorno utiliza el valor de IHostEnvironment.EnvironmentName para incluir o excluir el marcado en el elemento:

<environment include="Development">
    <div>Environment is Development</div>
</environment>
<environment exclude="Development">
    <div>Environment is NOT Development</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>Environment is: Staging, Development or Staging_2</div>
</environment>

La página Acerca de del código de ejemplo incluye el marcado anterior y muestra el valor de IWebHostEnvironment.EnvironmentName.

En Windows y macOS, los valores y las variables de entorno no distinguen mayúsculas de minúsculas. Los valores y las variables de entorno de Linux distinguen mayúsculas de minúsculas de forma predeterminada.

Creación de EnvironmentsSample

El código de ejemplo utilizado en este artículo se basa en un proyecto de Razor Pages denominado EnvironmentsSample.

Los siguientes comandos de la CLI de .NET crean y ejecutan una aplicación web denominada EnvironmentsSample:

dotnet new webapp -o EnvironmentsSample
cd EnvironmentsSample
dotnet run --verbosity normal

Cuando se ejecuta la aplicación, muestra una salida similar a lo siguiente:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7152
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5105
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Establecimiento del entorno en la línea de comandos

Use la marca --environment para establecer el entorno. Por ejemplo:

dotnet run --environment Production

El comando anterior establece el entorno en Production y muestra una salida similar a la siguiente en la ventana de comandos:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:7262
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5005
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Path\To\EnvironmentsSample

Desarrollo y launchSettings.json

El entorno de desarrollo puede habilitar características que no deben exponerse en producción. Por ejemplo, las plantillas de proyecto de ASP.NET Core habilitan la página de excepciones del desarrollador en el entorno de desarrollo. Debido al costo de rendimiento, la validación del ámbito y la validación de dependencias solo se producen en el desarrollo.

El entorno para el desarrollo del equipo local se puede establecer en el archivo Properties\launchSettings.json del proyecto. Los valores de entorno establecidos en launchSettings.json invalidan los valores establecidos en el entorno del sistema.

El archivo launchSettings.json:

• Solo se usa en el equipo de desarrollo local.
• No se implementa.
• Contiene la configuración del perfil.

El siguiente código JSON muestra el archivo launchSettings.json de un proyecto web de ASP.NET Core denominado EnvironmentsSample creado con Visual Studio o dotnet new:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

El código JSON anterior contiene dos perfiles:

• EnvironmentsSample: El nombre del perfil es el nombre del proyecto. Como se muestra en el primer perfil, este perfil se usa de forma predeterminada. La clave "commandName" tiene el valor "Project", por tanto, se inicia el servidor web Kestrel.

• IIS Express: la clave "commandName" tiene el valor "IISExpress", por lo tanto, IISExpress es el servidor web.

Puede establecer el perfil de inicio en el proyecto o en cualquier otro perfil incluido en launchSettings.json. Por ejemplo, en la imagen siguiente, al seleccionar el nombre del proyecto, se inicia el servidor web Kestrel.

El valor de commandName puede especificar el servidor web que se va a iniciar. commandName puede ser uno de los siguientes:

• IISExpress: Inicia IIS Express.
• IIS: No se ha iniciado ningún servidor web. Se espera que IIS esté disponible.
• Project : inicia Kestrel.

La pestaña Depurar/General de las propiedades del proyecto de Visual Studio 2022 proporciona un vínculo Open debug launch profiles UI (Abrir interfaz de usuario de perfiles de inicio de depuración). Este vínculo abre un cuadro de diálogo Launch Profiles (Perfiles de inicio) que le permite editar la configuración de las variables de entorno en el archivo launchSettings.json. También puede abrir el cuadro de diálogo Launch Profiles (Perfiles de inicio) desde el menú Depurar; para ello, seleccione <nombre del proyecto> Debug Properties (Propiedades de depuración). Los cambios realizados en los perfiles de proyecto podrían no surtir efecto hasta que se reinicie el servidor web. Es necesario reiniciar Kestrel para que pueda detectar los cambios realizados en su entorno.

El archivo launchSettings.json siguiente contiene varios perfiles:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:59481",
      "sslPort": 44308
    }
  },
  "profiles": {
    "EnvironmentsSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample-Staging": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample-Production": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7152;http://localhost:5105",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Los perfiles se pueden seleccionar de la forma siguiente:

• Desde la interfaz de usuario de Visual Studio.

• Mediante el comando dotnet run de la CLI con la opción --launch-profile establecida en el nombre del perfil. Este enfoque solo admite perfiles Kestrel.

  dotnet run --launch-profile "EnvironmentsSample"
  

Advertencia

En launchSettings.json no se deben almacenar secretos. Se puede usar la herramienta Administrador de secretos a fin de almacenar secretos para el desarrollo local.

Cuando se usa Visual Studio Code, las variables de entorno se pueden establecer en el archivo .vscode/launch.json. En el ejemplo siguiente se establecen varias variables de entorno de valores de configuración de host:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            // Configuration ommitted for brevity.
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development",
                "ASPNETCORE_URLS": "https://localhost:5001",
                "ASPNETCORE_DETAILEDERRORS": "1",
                "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
            },
            // Configuration ommitted for brevity.

El archivo .vscode/launch.json solo lo usa Visual Studio Code.

Producción

El entorno de producción debe configurarse para maximizar la seguridad, el rendimiento y la solidez de la aplicación. Las opciones de configuración comunes que difieren de las del entorno de desarrollo son:

• Almacenamiento en caché.
• Los recursos del cliente se agrupan, se reducen y se atienden potencialmente desde una CDN.
• Las páginas de error de diagnóstico están deshabilitadas.
• Las páginas de error descriptivas están habilitadas.
• El registro y la supervisión de la producción están habilitados. Por ejemplo, mediante Application Insights.

Configuración del entorno mediante el establecimiento de una variable de entorno

A menudo resulta útil establecer un entorno específico para realizar las pruebas con una variable de entorno o una configuración de plataforma. Si el entorno no está establecido, el valor predeterminado es Production, lo que deshabilita la mayoría de las características de depuración. El método para establecer el entorno depende del sistema operativo.

Cuando se compila el host, la última configuración de entorno leída por la aplicación determina el entorno de la aplicación. El entorno de la aplicación no se puede cambiar mientras se ejecuta la aplicación.

La página Acerca de del código de ejemplo muestra el valor de IWebHostEnvironment.EnvironmentName.

Azure App Service

Production es el valor predeterminado si DOTNET_ENVIRONMENT y ASPNETCORE_ENVIRONMENT no se han establecido. Las aplicaciones implementadas en Azure son Production de forma predeterminada.

Para establecer el entorno en una aplicación de Azure App Service, mediante el portal:

1. Seleccione la aplicación en la página App Services.
2. En el grupo Configuración, seleccione Configuración.
3. En la pestaña Configuración de aplicaciones, seleccione Nueva configuración de aplicación.
4. En la ventana Agregar o editar la configuración de la aplicación, escriba ASPNETCORE_ENVIRONMENT para el Nombre. En Valor, proporcione el entorno (por ejemplo, Staging).
5. Active la casilla Configuración de ranura de implementación si quiere que la configuración del entorno permanezca con la ranura actual cuando se intercambien las ranuras de implementación. Para más información, consulte Configuración de entornos de ensayo en Azure App Service en la documentación de Azure.
6. Seleccione Aceptar para cerrar el cuadro de diálogo Agregar o editar la configuración de la aplicación.
7. Seleccione Guardar en la parte superior de la página Configuración.

Azure App Service reinicia automáticamente la aplicación después de que se agregue, cambie o elimine una configuración de aplicación en Azure Portal.

Windows: establecimiento de la variable de entorno de un proceso

Los valores de entorno de launchSettings.json invalidan los valores establecidos en el entorno del sistema.

Para establecer ASPNETCORE_ENVIRONMENT en la sesión actual, cuando la aplicación se ha iniciado con dotnet run, use los comandos siguientes en un símbolo del sistema o en PowerShell:

set ASPNETCORE_ENVIRONMENT=Staging
dotnet run --no-launch-profile

$Env:ASPNETCORE_ENVIRONMENT = "Staging"
dotnet run --no-launch-profile

Windows: establecimiento de la variable de entorno globalmente

Los comandos anteriores establecen ASPNETCORE_ENVIRONMENT solo para los procesos iniciados desde esa ventana de comandos.

Para establecer el valor globalmente en Windows, use cualquiera de los métodos siguientes:

• Abra el Panel de control>Sistema>Configuración avanzada del sistema y agregue o edite el valor ASPNETCORE_ENVIRONMENT:

  

  

• Abra un símbolo del sistema con permisos de administrador y use el comando setx o abra un símbolo del sistema administrativo de PowerShell y use [Environment]::SetEnvironmentVariable:

  • setx ASPNETCORE_ENVIRONMENT Staging /M
    

    El modificador /M establece la variable de entorno a nivel del sistema. Si no se usa el modificador /M, la variable de entorno se establece para la cuenta de usuario.

  • [Environment]::SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Staging", "Machine")
    

    La opción Machine establece la variable de entorno a nivel del sistema. Si el valor de opción se cambia a User, la variable de entorno se establece para la cuenta de usuario.

Cuando la variable de entorno ASPNETCORE_ENVIRONMENT se establece de forma global, se aplica a dotnet run en cualquier ventana de comandos abierta después del establecimiento del valor. Los valores de entorno de launchSettings.json invalidan los valores establecidos en el entorno del sistema.

Windows: uso de web.config

Para establecer la variable de entorno ASPNETCORE_ENVIRONMENT con web.config, consulte la sección Establecimiento de las variables de entorno del archivo de configuración web.

Windows: implementaciones de IIS

Incluya la propiedad <EnvironmentName> del perfil de publicación (.pubxml) o un archivo de proyecto. Este método establece el entorno en web.config cuando se publica el proyecto:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Para establecer la variable de entorno ASPNETCORE_ENVIRONMENT para una aplicación que se ejecuta en un grupo de aplicaciones aislado (se admite en IIS 10.0 o posterior), consulte la sección Comando AppCmd.exe de Variables de entorno <environmentVariables>. Cuando la variable de entorno ASPNETCORE_ENVIRONMENT se establece para un grupo de aplicaciones, su valor reemplaza a un valor en el nivel de sistema.

Al hospedar una aplicación en IIS y agregar o cambiar la variable de entorno ASPNETCORE_ENVIRONMENT, use uno de los siguientes métodos para que las aplicaciones tomen el nuevo valor:

• Ejecute net stop was /y seguido de net start w3svc en un símbolo del sistema.
• Reinicie el servidor.

macOS

Para establecer el entorno actual para macOS, puede hacerlo en línea al ejecutar la aplicación:

ASPNETCORE_ENVIRONMENT=Staging dotnet run

De forma alternativa, defina el entorno con export antes de ejecutar la aplicación:

export ASPNETCORE_ENVIRONMENT=Staging

Las variables de entorno de nivel de equipo se establecen en el archivo .bashrc o .bash_profile. Edite el archivo con cualquier editor de texto. Agregue la siguiente instrucción:

export ASPNETCORE_ENVIRONMENT=Staging

Linux

Para distribuciones de Linux, use el comando export en un símbolo del sistema para la configuración de variables basada en sesión y el archivo bash_profile para la configuración del entorno a nivel de máquina.

Establecimiento del entorno en el código

Para establecer el entorno en el código, use WebApplicationOptions.EnvironmentName al crear WebApplicationBuilder, como se muestra en el ejemplo siguiente:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    EnvironmentName = Environments.Staging
}); 

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Configuración de entorno

Para cargar la configuración por entorno, consulte Configuración en ASP.NET Core.

Configuración de servicios y middleware por entorno

Use WebApplicationBuilder.Environment o WebApplication.Environment para agregar servicios o middleware condicionalmente en función del entorno actual. La plantilla de proyecto incluye un ejemplo de código que agrega middleware solo cuando el entorno actual no es el de desarrollo:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

El código resaltado comprueba el entorno actual al compilar la canalización de solicitudes. Para comprobar el entorno actual al configurar los servicios, use builder.Environment en lugar de app.Environment.

Recursos adicionales

• Vea o descargue el código de ejemplo (cómo descargarlo)
• Inicio de la aplicación en ASP.NET Core
• Configuración en ASP.NET Core
• Entornos de Blazor de ASP.NET Core