entornos de tiempo de ejecución de ASP.NET Core

ASP.NET Core configura el comportamiento de la aplicación en función del entorno de tiempo de ejecución, que normalmente refleja dónde se ejecuta la aplicación.

Normalmente, las aplicaciones se ejecutan en el entorno de desarrollo durante el desarrollo local y las pruebas en la máquina de un desarrollador con un conjunto de comportamientos configurados. Por el contrario, se ejecutan en el entorno de producción cuando se implementan en un servidor con un conjunto diferente de comportamientos configurados. Se puede usar cualquier número de entornos adicionales, como el entorno de ensayo proporcionado por el marco para almacenar provisionalmente una aplicación antes de la implementación activa u otros entornos que crean los desarrolladores.

En este artículo se describen los entornos en tiempo de ejecución de la aplicación, cómo usar el entorno para controlar el comportamiento de la aplicación y cómo establecer el entorno.

Para obtener instrucciones sobre entornos Blazor, que agrega o reemplaza las instrucciones de este artículo, consulta Entornos de ASP.NET Core Blazor.

Environments

Aunque el entorno puede ser cualquier valor de cadena, el marco proporciona los siguientes valores de entorno:

• Development
• Staging
• Production

El entorno de producción está configurado para maximizar la seguridad, el rendimiento y la confiabilidad de las aplicaciones. Entre los ajustes y configuraciones comunes para desarrolladores que difieren del Entorno de Desarrollo se incluyen:

• Habilitación del almacenamiento en caché.
• Agrupación y minificación de recursos del lado cliente, junto con la posibilidad de servirlos desde una red CDN.
• Deshabilitación de páginas de errores de diagnóstico y habilitación de páginas de errores amigables.
• Habilitación del registro y la supervisión de producción. Por ejemplo, el registro está habilitado para Azure Application Insights.

La última configuración de entorno que lee 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.

Registro

La salida del shell de comandos de una aplicación en ejecución al inicio indica el entorno de la aplicación. En el ejemplo siguiente, la aplicación se ejecuta en el entorno de ensayo:

info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Staging

Variables de entorno que determinan el entorno en tiempo de ejecución

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

• DOTNET_ENVIRONMENT
• ASPNETCORE_ENVIRONMENT

Cuando se usa WebApplication, el DOTNET_ENVIRONMENT valor tiene prioridad sobre ASPNETCORE_ENVIRONMENT. Cuando se usa WebHost, ASPNETCORE_ENVIRONMENT tiene prioridad.

Si no se establecen las DOTNET_ENVIRONMENT variables de entorno y ASPNETCORE_ENVIRONMENT , el entorno de producción es el entorno predeterminado.

En Windows y macOS, los nombres de variables de entorno no distinguen mayúsculas de minúsculas. Las variables de entorno de Linux distinguen mayúsculas de minúsculas.

Control de la ejecución de código por entorno

Use WebApplicationBuilder.Environment o WebApplication.Environment para agregar servicios o middleware condicionalmente en función del entorno actual.

El siguiente código en el archivo de la aplicación Program:

• Usa WebApplication.Environment para distinguir el entorno.
• Llama UseExceptionHandler, que agrega Middleware de Control de Excepciones al pipeline de procesamiento de solicitudes para gestionar las excepciones.
• Llama a UseHsts, que agrega HSTS Middleware para aplicar el encabezado Strict-Transport-Security.

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

En el ejemplo anterior se comprueba el entorno actual de la canalización de procesamiento de solicitudes. Para comprobar el entorno actual al configurar los servicios, use builder.Environment en lugar de app.Environment.

Dentro de la aplicación, IHostEnvironment proporciona información general sobre el entorno de hospedaje de la aplicación y la IHostEnvironment.EnvironmentName propiedad indica el entorno actual de la aplicación.

Control del contenido representado

Inserte IHostEnvironment en un componente representado en el servidor Razor y use los métodos de extensión del servicio y la propiedad EnvironmentName para determinar el entorno para representar contenido.

@inject IHostEnvironment Env

@if (Env.IsDevelopment())
{
    <div>The environment is Development.</div>
}

@if (!Env.IsDevelopment())
{
    <div>The environment isn't Development.</div>
}

@if (Env.IsStaging() || Env.EnvironmentName == "Testing")
{
    <div>The environment is either Staging or Testing.</div>
}

Para los Blazor Web Appque requieren que el entorno controle la representación del lado cliente, consulte Prerender ASP.NET componentes principalesRazor.

Establecer el entorno en un shell de comandos cuando se ejecuta la aplicación (dotnet run)

Use la -e|--environment opción para establecer el entorno:

dotnet run -e Staging

Establecer el entorno con el archivo de configuración de inicio (launchSettings.json)

El entorno para el desarrollo local se puede establecer en el Properties\launchSettings.json archivo del proyecto. Valores de entorno configurados en launchSettings.json anulan los valores establecidos por el entorno del sistema.

El archivo launchSettings.json:

• Solo se usa en el equipo de desarrollo local.
• No se implementa cuando se publica la aplicación.
• Puede contener varios perfiles, cada uno configurando un entorno diferente.

En el ejemplo siguiente se establece el entorno de ensayo para el perfil de https inicio mediante la ASPNETCORE_ENVIRONMENT variable de entorno:

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "applicationUrl": "https://localhost:7205",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Staging"
  }
}

En Visual Studio, hay dos enfoques para establecer el entorno a través de perfiles de inicio:

• Presione Alt+Entrar o seleccione Propiedades después de hacer clic con el botón derecho en el proyecto en el Explorador de soluciones. Seleccione Depurar>General y, después, seleccione el vínculo Open debug launch profiles UI (Abrir perfiles de inicio de depuración).

• Con el proyecto seleccionado en Solution Explorer, seleccione {NOMBRE DEL PROYECTO} Propiedades de depuración en el menú Depurar, donde el {PROJECT NAME} marcador de posición es un nombre de proyecto.

Los enfoques anteriores abren el cuadro de diálogo Perfiles de inicio , donde puede editar la configuración de la variable de entorno en el launchSettings.json archivo. 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.

Los perfiles se pueden seleccionar en la interfaz de usuario de Visual Studio junto al botón Iniciar (✔).

Cuando una solución contiene varios proyectos, establezca solo el entorno para el proyecto de inicio.

Como alternativa, use el dotnet run comando con la -lp|--launch-profile opción establecida en el nombre del perfil. Este enfoque solo admite perfiles de inicio basados en el Project comando .

dotnet run -lp "https"

Cuando se usa Visual Studio Code con el Kit de desarrollo de C# para Visual Studio Code (Introducción a C# en VS Code), los perfiles de inicio se seleccionan desde el archivo de launchSettings.json la aplicación.

Si no se usa el Kit de desarrollo de C#, establezca la ASPNETCORE_ENVIRONMENT variable de entorno en la .vscode/launch.jsonenv sección , junto con cualquier otra variable de entorno establecida en la sección:

"env": {
    "ASPNETCORE_ENVIRONMENT": "Staging",
    ...
},

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

Establecimiento del entorno con 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 no se establece el entorno, el valor predeterminado es el entorno de producción, que deshabilita la mayoría de las funciones de depuración. El método para establecer el entorno depende del sistema operativo.

Azure App Service

Las aplicaciones implementadas en Azure App Service adoptan el entorno de producción de forma predeterminada.

Para establecer la ASPNETCORE_ENVIRONMENT variable de entorno, consulte los siguientes recursos en la documentación de Azure:

• Configuración de una aplicación de App Service
• Configuración de entornos de ensayo en Azure App Service

Azure App Service reinicia automáticamente la aplicación después de agregar, cambiar o eliminar una configuración de aplicación.

Establecimiento de una variable de entorno para un proceso

Para establecer la ASPNETCORE_ENVIRONMENT variable de entorno para la sesión actual (shell de comandos) cuando se inicia la aplicación mediante dotnet run, use los siguientes comandos. Una vez establecida la variable de entorno, la aplicación se inicia sin un perfil de inicio mediante la --no-launch-profile opción .

1. En el shell de comandos, establezca la variable de entorno utilizando el método adecuado para su sistema operativo.

2. Ejecute el dotnet run comando sin usar un perfil de inicio:

   dotnet run --no-launch-profile
   

Al usar PowerShell, los pasos anteriores se pueden combinar en los dos comandos siguientes. En el ejemplo siguiente se establece el entorno de ensayo:

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

Establecimiento global de la variable de entorno

Use las instrucciones adecuadas para que el sistema operativo establezca la variable de ASPNETCORE_ENVIRONMENT entorno.

Cuando la ASPNETCORE_ENVIRONMENT variable de entorno se establece globalmente, surte efecto para el dotnet run comando en cualquier shell de comandos abierto después de establecer el valor. Valores de entorno establecidos por perfiles de inicio en el archivo launchSettings.json anulan los valores establecidos para el entorno del sistema.

Establecer el entorno para las aplicaciones implementadas en IIS

Para establecer la ASPNETCORE_ENVIRONMENT variable de entorno con el web.config archivo, consulte web.config archivo.

Para establecer la variable de entorno en la implementación en IIS, incluya la <EnvironmentName> propiedad en el archivo de proyecto o el perfil de publicación (.pubxml ). En el ejemplo siguiente se configura el entorno en web.config en el entorno de preparación cuando se publica el proyecto.

<PropertyGroup>
  <EnvironmentName>Staging</EnvironmentName>
</PropertyGroup>

Para establecer la ASPNETCORE_ENVIRONMENT variable de entorno para una aplicación que se ejecuta en un grupo de aplicaciones aislado (compatible con IIS 10.0 o posterior), consulte Variables de entorno <environmentVariables>. Cuando se establece la ASPNETCORE_ENVIRONMENT variable de entorno para un grupo de aplicaciones, su valor invalida una configuración en el nivel del sistema.

Al hospedar una aplicación en IIS y agregar o cambiar la ASPNETCORE_ENVIRONMENT variable de entorno, use cualquiera de los enfoques siguientes para que el nuevo valor surta efecto para ejecutar aplicaciones:

• Ejecute net stop was /y seguido de net start w3svc en un shell de comandos.
• Reinicia el servidor.

Docker

Establezca el entorno de la aplicación mediante cualquiera de los enfoques de esta sección.

Uso de un Dockerfile

Establezca la ASPNETCORE_ENVIRONMENT variable de entorno dentro del Dockerfile mediante la ENV instrucción :

ENV ASPNETCORE_ENVIRONMENT=Staging

Uso de Docker Compose

En el caso de las aplicaciones multiservicio administradas con Docker Compose, defina las ASPNETCORE_ENVIRONMENT variables de entorno dentro del docker-compose.yml archivo:

version: "3.9"
services:
  web:
    build: .
    ports:
      - "8000:5000"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
      - API_KEY=...

Un entorno establecido en tiempo de ejecución con Docker Compose invalida un entorno establecido por dockerfile.

Uso del docker run comando

Al ejecutar el contenedor de Docker con el docker run comando , establezca la ASPNETCORE_ENVIRONMENT variable de entorno con la -e|--env opción :

docker run -e ASPNETCORE_ENVIRONMENT=Staging aspnet_core_image

Un entorno establecido en tiempo de ejecución con docker run invalida un entorno establecido por el Dockerfile.

Archivo de entorno de Docker

Establezca la variable de ASPNETCORE_ENVIRONMENT entorno mediante un archivo de entorno de Docker (.env).

env_variables.env:

ASPNETCORE_ENVIRONMENT=Staging

Cargue el archivo con la --env-file opción al ejecutar el docker run comando:

docker run --env-file ./env_variables.env aspnet_core_image

Un entorno establecido en tiempo de ejecución con docker run invalida un entorno establecido por el Dockerfile.

Establecer el entorno en el código de inicio de la aplicación

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

Configuración de carga por entorno

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

Acceso al entorno desde una Startup clase

Se requería el uso de una Startup clase (Startup.cs) con Configure métodos y ConfigureServices antes de la versión de .NET 6 y aún se admite.

Inserte IWebHostEnvironment en el constructor para controlar la ejecución del Startup código. Este enfoque es útil cuando la aplicación requiere configurar el código de inicio solo para unos pocos entornos con diferencias mínimas de código por entorno.

En el ejemplo siguiente, el entorno se mantiene en el _env campo y controla la ejecución del código en función del entorno de la aplicación:

public class Startup
{
    private readonly IWebHostEnvironment _env;

    public Startup(IWebHostEnvironment env)
    {
        _env = env;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else if (_env.IsStaging())
        {
            ...
        }
        else
        {
            ...
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            ...
        }
        else
        {
            ...
        }

        ...
    }
}

Startup Clase específica del entorno

Una aplicación puede definir varias Startup clases para distintos entornos según la convención de nomenclatura de clase Startup{EnvironmentName}, donde el {ENVIRONMENT NAME} marcador de posición es el nombre del entorno.

La clase cuyo sufijo de nombre coincide con el entorno actual se establece como prioritaria. Si no se encuentra una clase Startup{EnvironmentName} coincidente, se usa la clase Startup.

Para implementar clases en entornos basados en Startup, cree tantas clases Startup{EnvironmentName} como sea necesario y una clase de reserva Startup.

public class StartupDevelopment
{
    ...
}

public class StartupProduction
{
    ...
}

public class Startup
{
    ...
}

Donde se crea el generador de hosts, llame a HostingAbstractionsWebHostBuilderExtensions.UseStartup, que acepta un nombre de ensamblado para cargar la clase correcta Startup :

public static IHostBuilder CreateHostBuilder(string[] args)
{
    var assemblyName = typeof(Startup).GetTypeInfo().Assembly.FullName;

    return Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup(assemblyName);
        });
}

Métodos de clase específicos Startup del entorno

Los Configure métodos y ConfigureServices admiten versiones específicas del entorno del formulario Configure{ENVIRONMENT NAME} y Configure{ENVIRONMENT NAME}Services, donde el {ENVIRONMENT NAME} marcador de posición es el nombre del entorno. Si no se encuentra un nombre de entorno coincidente para los métodos con nombre, se usa el ConfigureServices método o Configure , respectivamente.

public void ConfigureDevelopmentServices(IServiceCollection services)
{
    ...
}

public void ConfigureStagingServices(IServiceCollection services)
{
    ...
}

public void ConfigureProductionServices(IServiceCollection services)
{
    ...
}

public void ConfigureServices(IServiceCollection services)
{
    ...
}

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