Compartir a través de


Usar varios entornos en ASP.NET Core

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulta la versión .NET 8 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para obtener más información, consulta la Directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulta la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulta la versión .NET 8 de este artículo.

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.

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

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 ASPNETCORE_ENVIRONMENT invalida DOTNET_ENVIRONMENT.

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:

El código siguiente:

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.

Inicio de IIS Express en el menú

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.

Variables de entorno de configuración de las propiedades del proyecto

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. Selecciona la aplicación en la página App Services.
  2. En el grupo Configuración, selecciona Variables de entorno.
  3. En la pestaña Configuración de la aplicación, selecciona + Agregar.
  4. En la ventana Agregar o editar la configuración de la aplicación, escribe ASPNETCORE_ENVIRONMENT para el Nombre. En Valor, proporciona el entorno (por ejemplo, Staging).
  5. Activa la casilla Configuración de ranura de implementación si quieres que la configuración del entorno permanezca con la ranura actual cuando se intercambien las ranuras de implementación. Para obtener más información, consulta Configuración de entornos de ensayo en Azure App Service en la documentación de Azure.
  6. Selecciona Aceptar para cerrar el cuadro de diálogo Agregar o editar la configuración de la aplicación.
  7. Selecciona 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, usa 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, usa cualquiera de los métodos siguientes:

  • Abre el Panel de control>Sistema>Configuración avanzada del sistema y agrega o edita el valor ASPNETCORE_ENVIRONMENT:

    Propiedades avanzadas del sistema

    Variable de entorno de ASP.NET Core

  • Abre un símbolo del sistema con permisos de administrador y use el comando setx o abre 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, consulta la sección Establecimiento de las variables de entorno del archivo de configuración web.

Windows: implementaciones de IIS

Incluye 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), consulta 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, usa uno de los siguientes métodos para que las aplicaciones tomen el nuevo valor:

  • Ejecuta net stop was /y seguido de net start w3svc en un símbolo del sistema.
  • Reinicia 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

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 a ConfigureWebHostDefaults. Las plantillas de aplicación web de ASP.NET Core predeterminadas llaman a ConfigureWebHostDefaults. El valor ASPNETCORE_ENVIRONMENT invalida DOTNET_ENVIRONMENT.

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

El código siguiente:

  • Llama a UseDeveloperExceptionPage cuando ASPNETCORE_ENVIRONMENT está establecido en Development.
  • Llama a UseExceptionHandler cuando el valor de ASPNETCORE_ENVIRONMENT está establecido en Staging, Productiono Staging_2.
  • Inserta IWebHostEnvironment en Startup.Configure. Este enfoque es útil cuando la aplicación solo requiere el ajuste de Startup.Configure para algunos entornos con diferencias de código mínimas en cada uno.
  • Es similar al código generado por las plantillas de ASP.NET Core.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    if (env.IsProduction() || env.IsStaging() || env.IsEnvironment("Staging_2"))
    {
        app.UseExceptionHandler("/Error");
    }

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

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

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>The effective tag is: <environment include="Development"></div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: <environment exclude="Development"></div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        <environment include="Staging,Development,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 documento se basa en un proyecto de páginas Razor denominado EnvironmentsSample.

El código siguiente crea y ejecuta una aplicación web denominada EnvironmentsSample:

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

Cuando se ejecuta la aplicación, muestra algunas de las salidas siguientes:

Using launch settings from c:\tmp\EnvironmentsSample\Properties\launchSettings.json
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
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:\tmp\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 ASP.NET Core habilitan la página de excepciones para el desarrollador en el entorno de 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:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

El marcado anterior contiene dos perfiles:

  • IIS Express: El perfil predeterminado que se usa cuando se inicia la aplicación en Visual Studio. 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. Por ejemplo, en la imagen siguiente, al seleccionar el nombre del proyecto, se inicia el servidor web Kestrel.

    Inicio de IIS Express en el menú

  • EnvironmentsSample: El nombre del perfil es el nombre del proyecto. Este perfil se utiliza de forma predeterminada al iniciar la aplicación con dotnet run. La clave "commandName" tiene el valor "Project", por tanto, 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 de las propiedades de proyecto de Visual Studio proporciona una GUI para editar el archivo launchSettings.json. 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.

Variables de entorno de configuración de las propiedades del proyecto

El archivo launchSettings.json siguiente contiene varios perfiles:

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:64645",
      "sslPort": 44366
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "IISX-Production": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    },
    "IISX-Staging": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "KestrelStaging": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    }
  }
}

Los perfiles se pueden seleccionar de la forma siguiente:

  • Desde la interfaz de usuario de Visual Studio.

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

    dotnet run --launch-profile "SampleApp"
    

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.

Establecimiento del 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 de Production de forma predeterminada.

Para establecer el entorno en Azure App Service, realice los pasos siguientes:

  1. Seleccione la aplicación desde la hoja App Services.
  2. En el grupo Configuración, seleccione la hoja 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 la ventana Agregar o editar la configuración de la aplicación.
  7. Seleccione Guardar en la parte superior de la hoja 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

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:

Símbolo del sistema

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

PowerShell

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

El comando anterior se establece 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:

    Propiedades avanzadas del sistema

    Variable de entorno de ASP.NET Core

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

    Símbolo del sistema

    setx ASPNETCORE_ENVIRONMENT Staging /M
    

    El modificador /M indica que hay que establecer la variable de entorno en el nivel de sistema. Si no se usa el modificador /M, la variable de entorno se establece para la cuenta de usuario.

    PowerShell

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

    El valor de opción Machine indica que hay que establecer la variable de entorno en el nivel de 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.

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.

Archivo del proyecto o perfil de publicación

Para las implementaciones de IIS de Windows: 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>

Por grupo de aplicaciones de IIS

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), vea la sección AppCmd.exe del tema Environment Variables <environmentVariables> (Variables de entorno). 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.

Cuando hospede una aplicación en IIS y agregue o cambie la variable de entorno ASPNETCORE_ENVIRONMENT, use cualquiera 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 en el nivel de equipo.

Establecimiento del entorno en el código

Llame a UseEnvironment al compilar el host. Consulte Host genérico de .NET en ASP.NET Core.

Configuración de entorno

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

Métodos y clase Startup basados en entorno

Inserción de IWebHostEnvironment en la clase Startup

Inserte IWebHostEnvironment en el constructor de Startup. Este enfoque es útil cuando la aplicación solo requiere la configuración de Startup para algunos entornos con diferencias de código mínimas en cada uno.

En el ejemplo siguiente:

  • El entorno se mantiene en el campo _env.
  • _env se usa en ConfigureServices y Configure para aplicar la configuración de inicio en función del entorno de la aplicación.
public class Startup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment env)
    {
        Configuration = configuration;
        _env = env;
    }

    public IConfiguration Configuration { get; }
    private readonly IWebHostEnvironment _env;

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else if (_env.IsStaging())
        {
            Console.WriteLine(_env.EnvironmentName);
        }
        else
        {
            Console.WriteLine("Not dev or staging");
        }

        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Convenciones de la clase Startup

Cuando se inicia una aplicación ASP.NET Core, la clase Startup arranca la aplicación. La aplicación puede definir varias clases de Startup para diferentes entornos. La clase Startup correspondiente se selecciona en tiempo de ejecución. 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. Este enfoque es útil cuando la aplicación requiere configurar el inicio para algunos entornos con muchas diferencias de código en cada uno. Las aplicaciones típicas no necesitarán este enfoque.

Para implementar clases Startup basadas en entornos, cree una clase Startup{EnvironmentName} y una clase Startup de reserva:

public class StartupDevelopment
{
    public StartupDevelopment(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {
        app.UseDeveloperExceptionPage();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class StartupProduction
{
    public StartupProduction(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app)
    {

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
        Console.WriteLine(MethodBase.GetCurrentMethod().DeclaringType.Name);
    }

    public IConfiguration Configuration { get; }

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

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

Use la sobrecarga UseStartup(IWebHostBuilder, String) que acepta un nombre de ensamblado:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

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

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

Convenciones del método Startup

Configure y ConfigureServices son compatibles con versiones específicas del entorno con el formato Configure<EnvironmentName> y Configure<EnvironmentName>Services. Si no se encuentra un método Configure<EnvironmentName>Services o Configure<EnvironmentName> coincidente, se usa el método ConfigureServices o Configure, respectivamente. Este enfoque es útil cuando la aplicación requiere configurar el inicio para algunos entornos con muchas diferencias de código en cada uno:

public class Startup
{
    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
    }

    public void ConfigureDevelopmentServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureProductionServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void ConfigureServices(IServiceCollection services)
    {
        MyTrace.TraceMessage();
        StartupConfigureServices(services);
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }

    public void ConfigureStaging(IApplicationBuilder app, IWebHostEnvironment env)
    {
        MyTrace.TraceMessage();

        app.UseExceptionHandler("/Error");
        app.UseHsts();

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

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRazorPages();
        });
    }
}

public static class MyTrace
{
    public static void TraceMessage([CallerMemberName] string memberName = "")
    {
        Console.WriteLine($"Method: {memberName}");
    }
}

Recursos adicionales