Usar varios entornos en ASP.NET CoreUse multiple environments in ASP.NET Core

Por Rick AndersonBy Rick Anderson

ASP.NET Core configura el comportamiento de las aplicaciones en función del entorno en tiempo de ejecución mediante una variable de entorno.ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

EntornosEnvironments

ASP.NET Core lee la variable de entorno ASPNETCORE_ENVIRONMENT al inicio de la aplicación y almacena el valor en IWebHostEnvironment.EnvironmentName.ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in IWebHostEnvironment.EnvironmentName. ASPNETCORE_ENVIRONMENT se puede establecer en cualquier valor, pero el marco proporciona tres valores:ASPNETCORE_ENVIRONMENT can be set to any value, but three values are provided by the framework:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

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

    app.UseStaticFiles();
    app.UseMvc();
}

El código anterior:The preceding code:

El asistente de etiquetas de entorno usa el valor de IHostingEnvironment.EnvironmentName para incluir o excluir el marcado en el elemento:The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude markup in the element:

<environment include="Development">
    <div>The effective tag is: &lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: &lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

En Windows y macOS, los valores y las variables de entorno no distinguen mayúsculas de minúsculas.On Windows and macOS, environment variables and values aren't case sensitive. Los valores y las variables de entorno de Linux distinguen mayúsculas de minúsculas de forma predeterminada.Linux environment variables and values are case sensitive by default.

DesarrolloDevelopment

El entorno de desarrollo puede habilitar características que no deben exponerse en producción.The development environment can enable features that shouldn't be exposed in production. Por ejemplo, las plantillas de ASP.NET Core habilitan la página de excepciones para el desarrollador en el entorno de desarrollo.For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

El entorno para el desarrollo del equipo local se puede establecer en el archivo Properties\launchSettings.json del proyecto.The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Los valores de entorno establecidos en launchSettings.json invalidan los valores establecidos en el entorno del sistema.Environment values set in launchSettings.json override values set in the system environment.

En el siguiente fragmento de JSON se muestran tres perfiles de un archivo launchSettings.json:The following JSON shows three profiles from a launchSettings.json file:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:54339/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:54340/"
    },
    "Kestrel Staging": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:51997/"
    }
  }
}

Nota

La propiedad applicationUrl en launchSettings.json puede especificar una lista de direcciones URL del servidor.The applicationUrl property in launchSettings.json can specify a list of server URLs. Use un punto y coma entre las direcciones URL de la lista:Use a semicolon between the URLs in the list:

"EnvironmentsSample": {
   "commandName": "Project",
   "launchBrowser": true,
   "applicationUrl": "https://localhost:5001;http://localhost:5000",
   "environmentVariables": {
     "ASPNETCORE_ENVIRONMENT": "Development"
   }
}

Cuando la aplicación se inicia con dotnet run, se usa el primer perfil con "commandName": "Project".When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. El valor de commandName especifica el servidor web que se va a iniciar.The value of commandName specifies the web server to launch. commandName puede ser uno de los siguientes:commandName can be any one of the following:

  • IISExpress
  • IIS
  • Project (que inicia Kestrel)Project (which launches Kestrel)

Cuando una aplicación se inicia con dotnet run:When an app is launched with dotnet run:

  • Se lee launchSettings.json, si está disponible.launchSettings.json is read if available. La configuración de environmentVariables de launchSettings.json reemplaza las variables de entorno.environmentVariables settings in launchSettings.json override environment variables.
  • Se muestra el entorno de hospedaje.The hosting environment is displayed.

En la siguiente salida se muestra una aplicación que se ha iniciado con dotnet run:The following output shows an app started with dotnet run:

PS C:\Websites\EnvironmentsSample> dotnet run
Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.

La pestaña Depurar de las propiedades de proyecto de Visual Studio proporciona una GUI para editar el archivo launchSettings.json:The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:

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

Los cambios realizados en los perfiles de proyecto podrían no surtir efecto hasta que se reinicie el servidor web.Changes made to project profiles may not take effect until the web server is restarted. Es necesario reiniciar Kestrel para que pueda detectar los cambios realizados en su entorno.Kestrel must be restarted before it can detect changes made to its environment.

Advertencia

En launchSettings.json no se deben almacenar secretos.launchSettings.json shouldn't store secrets. Se puede usar la herramienta Administrador de secretos a fin de almacenar secretos para el desarrollo local.The Secret Manager tool can be used to store secrets for local development.

Cuando se usa Visual Studio Code, las variables de entorno se pueden establecer en el archivo .vscode/launch.json.When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. En el siguiente ejemplo se establece el entorno en Development:The following example sets the environment to Development:

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",

            ... additional VS Code configuration settings ...

            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

Un archivo .vscode/launch.json del proyecto no se lee al iniciar la aplicación con dotnet run en la misma manera que Properties/launchSettings.json.A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as Properties/launchSettings.json. Cuando se inicia una aplicación en desarrollo que no tiene un archivo launchSettings.json, establezca el valor del entorno con una variable de entorno o con un argumento de línea de comandos para el comando dotnet run.When launching an app in development that doesn't have a launchSettings.json file, either set the environment with an environment variable or a command-line argument to the dotnet run command.

ProducciónProduction

El entorno de producción debe configurarse para maximizar la seguridad, el rendimiento y la solidez de la aplicación.The production environment should be configured to maximize security, performance, and app robustness. Las opciones de configuración comunes que difieren de las del entorno de desarrollo son:Some common settings that differ from development include:

  • Almacenamiento en caché.Caching.
  • Los recursos del cliente se agrupan, se reducen y se atienden potencialmente desde una CDN.Client-side resources are bundled, minified, and potentially served from a CDN.
  • Las páginas de error de diagnóstico están deshabilitadas.Diagnostic error pages disabled.
  • Las páginas de error descriptivas están habilitadas.Friendly error pages enabled.
  • El registro y la supervisión de la producción están habilitados.Production logging and monitoring enabled. Por ejemplo, Application Insights.For example, Application Insights.

Establecimiento del entornoSet the environment

A menudo resulta útil establecer un entorno específico para realizar las pruebas con una variable de entorno o una configuración de plataforma.It's often useful to set a specific environment for testing with an environment variable or platform setting. Si el entorno no está establecido, el valor predeterminado es Production, lo que deshabilita la mayoría de las características de depuración.If the environment isn't set, it defaults to Production, which disables most debugging features. El método para establecer el entorno depende del sistema operativo.The method for setting the environment depends on the operating system.

Cuando se compila el host, la última configuración de entorno leída por la aplicación determina el entorno de la aplicación.When the host is built, the last environment setting read by the app determines the app's environment. El entorno de la aplicación no se puede cambiar mientras se ejecuta la aplicación.The app's environment can't be changed while the app is running.

Configuración de plataforma o variable de entornoEnvironment variable or platform setting

Azure App ServiceAzure App Service

Para establecer el entorno en Azure App Service, realice los pasos siguientes:To set the environment in Azure App Service, perform the following steps:

  1. Seleccione la aplicación desde la hoja App Services.Select the app from the App Services blade.
  2. En el grupo Configuración, seleccione la hoja Configuración.In the Settings group, select the Configuration blade.
  3. En la pestaña Configuración de aplicaciones, seleccione Nueva configuración de aplicación.In the Application settings tab, select New application setting.
  4. En la ventana Agregar o editar la configuración de la aplicación, escriba ASPNETCORE_ENVIRONMENT para el Nombre.In the Add/Edit application setting window, provide ASPNETCORE_ENVIRONMENT for the Name. En Valor, proporcione el entorno (por ejemplo, Staging).For Value, provide the environment (for example, 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.Select the Deployment slot setting check box if you wish the environment setting to remain with the current slot when deployment slots are swapped. Para más información, consulte Configuración de entornos de ensayo en Azure App Service en la documentación de Azure.For more information, see Set up staging environments in Azure App Service in the Azure documentation.
  6. Seleccione Aceptar para cerrar la ventana Agregar o editar la configuración de la aplicación.Select OK to close the Add/Edit application setting window.
  7. Seleccione Guardar en la parte superior de la hoja Configuración.Select Save at the top of the Configuration blade.

Azure App Service reinicia automáticamente la aplicación después de que se agregue, cambie o elimine una configuración de aplicación (variable de entorno) en Azure Portal.Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed, or deleted in the Azure portal.

WindowsWindows

Para establecer ASPNETCORE_ENVIRONMENT en la sesión actual, cuando la aplicación se ha iniciado con dotnet run, use los comandos siguientes:To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

Símbolo del sistemaCommand prompt

set ASPNETCORE_ENVIRONMENT=Development

PowerShellPowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Estos comandos solo tienen efecto en la ventana actual.These commands only take effect for the current window. Cuando se cierre la ventana, la configuración de ASPNETCORE_ENVIRONMENT volverá a la configuración predeterminada o al valor del equipo.When the window is closed, the ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.

Para establecer el valor globalmente en Windows, use cualquiera de los métodos siguientes:To set the value globally in Windows, use either of the following approaches:

  • Abra el Panel de control > Sistema > Configuración avanzada del sistema y agregue o edite el valor ASPNETCORE_ENVIRONMENT:Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    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:Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    Símbolo del sistemaCommand prompt

    setx ASPNETCORE_ENVIRONMENT Development /M
    

    El modificador /M indica que hay que establecer la variable de entorno en el nivel de sistema.The /M switch indicates to set the environment variable at the system level. Si no se usa el modificador /M, la variable de entorno se establece para la cuenta de usuario.If the /M switch isn't used, the environment variable is set for the user account.

    PowerShellPowerShell

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

    El valor de opción Machine indica que hay que establecer la variable de entorno en el nivel de sistema.The Machine option value indicates to set the environment variable at the system level. Si el valor de opción se cambia a User, la variable de entorno se establece para la cuenta de usuario.If the option value is changed to User, the environment variable is set for the user account.

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.When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set.

web.configweb.config

Para establecer la variable de entorno ASPNETCORE_ENVIRONMENT con web.config, vea la sección Establecimiento de variables de entorno de Módulo ASP.NET Core.To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables section of Módulo ASP.NET Core.

Archivo del proyecto o perfil de publicaciónProject file or publish profile

Para las implementaciones de IIS de Windows: Incluya la propiedad <EnvironmentName> del perfil de publicación (.pubxml) o un archivo de proyecto.For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Este método establece el entorno en web.config cuando se publica el proyecto:This approach sets the environment in web.config when the project is published:

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

Por grupo de aplicaciones de IISPer IIS Application Pool

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).To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic. 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.When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

Importante

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:When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of the following approaches to have the new value picked up by apps:

  • Ejecute net stop was /y seguido de net start w3svc en un símbolo del sistema.Execute net stop was /y followed by net start w3svc from a command prompt.
  • Reinicie el servidor.Restart the server.

macOSmacOS

Para establecer el entorno actual para macOS, puede hacerlo en línea al ejecutar la aplicación:Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Development dotnet run

De forma alternativa, defina el entorno con export antes de ejecutar la aplicación:Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Development

Las variables de entorno de nivel de equipo se establecen en el archivo .bashrc o .bash_profile.Machine-level environment variables are set in the .bashrc or .bash_profile file. Edite el archivo con cualquier editor de texto.Edit the file using any text editor. Agregue la siguiente instrucción:Add the following statement:

export ASPNETCORE_ENVIRONMENT=Development

LinuxLinux

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.For Linux distros, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Establecimiento del entorno en el códigoSet the environment in code

Llame a UseEnvironment al compilar el host.Call UseEnvironment when building the host. Vea Host genérico de .NET.See Host genérico de .NET.

Configuración de entornoConfiguration by environment

Para cargar la configuración por entorno, se recomienda lo siguiente:To load configuration by environment, we recommend:

Métodos y clase Startup basados en entornoEnvironment-based Startup class and methods

Inserción de IWebHostEnvironment en Startup.ConfigureInject IWebHostEnvironment into Startup.Configure

Inserte IWebHostEnvironment en Startup.Configure.Inject IWebHostEnvironment into 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.This approach is useful when the app only requires adjusting Startup.Configure for a few environments with minimal code differences per environment.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Development environment code
    }
    else
    {
        // Code for all other environments
    }
}

Inserción de IWebHostEnvironment en la clase StartupInject IWebHostEnvironment into the Startup class

Inserte IWebHostEnvironment en el constructor de Startup.Inject IWebHostEnvironment into the Startup constructor. 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.This approach is useful when the app requires configuring Startup for only a few environments with minimal code differences per environment.

En el ejemplo siguiente:In the following example:

  • El entorno se mantiene en el campo _env.The environment is held in the _env field.
  • _env se usa en ConfigureServices y Configure para aplicar la configuración de inicio en función del entorno de la aplicación._env is used in ConfigureServices and Configure to apply startup configuration based on the app's environment.
public class Startup
{
    private readonly IWebHostEnvironment _env;

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

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else if (_env.IsStaging())
        {
            // Staging environment code
        }
        else
        {
            // Code for all other environments
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else
        {
            // Code for all other environments
        }
    }
}

Convenciones de la clase StartupStartup class conventions

Cuando se inicia una aplicación ASP.NET Core, la clase Startup arranca la aplicación.When an ASP.NET Core app starts, the Startup class bootstraps the app. La aplicación puede definir clases Startup independientes para distintos entornos (por ejemplo, StartupDevelopment).The app can define separate Startup classes for different environments (for example, StartupDevelopment). La clase Startup correspondiente se selecciona en tiempo de ejecución.The appropriate Startup class is selected at runtime. La clase cuyo sufijo de nombre coincide con el entorno actual se establece como prioritaria.The class whose name suffix matches the current environment is prioritized. Si no se encuentra una clase Startup{EnvironmentName} coincidente, se usa la clase Startup.If a matching Startup{EnvironmentName} class isn't found, the Startup class is used. Este enfoque es útil cuando la aplicación requiere configurar el inicio para algunos entornos con muchas diferencias de código en cada uno.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

Para implementar clases Startup basadas en entornos, cree una clase Startup{EnvironmentName} para cada entorno en uso y una clase Startup de reserva:To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each environment in use and a fallback Startup class:

// Startup class to use in the Development environment
public class StartupDevelopment
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Startup class to use in the Production environment
public class StartupProduction
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Fallback Startup class
// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

Si quiere que los comentarios de código se traduzcan en más idiomas además del inglés, háganoslo saber en este problema de debate de GitHub.If you would like to see code comments translated to languages other than English, let us know in this GitHub discussion issue.

Use la sobrecarga UseStartup(IWebHostBuilder, String) que acepta un nombre de ensamblado:Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

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

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

    return WebHost.CreateDefaultBuilder(args)
        .UseStartup(assemblyName);
}

Convenciones del método StartupStartup method conventions

Configure y ConfigureServices son compatibles con versiones específicas del entorno con el formato Configure<EnvironmentName> y Configure<EnvironmentName>Services.Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services. Este enfoque es útil cuando la aplicación requiere configurar el inicio para algunos entornos con muchas diferencias de código en cada uno.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

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

        app.UseStaticFiles();
        app.UseMvc();
    }

    public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (!env.IsStaging())
        {
            throw new Exception("Not staging.");
        }

        app.UseExceptionHandler("/Error");
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Recursos adicionalesAdditional resources

Por Rick AndersonBy Rick Anderson

ASP.NET Core configura el comportamiento de las aplicaciones en función del entorno en tiempo de ejecución mediante una variable de entorno.ASP.NET Core configures app behavior based on the runtime environment using an environment variable.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

EntornosEnvironments

ASP.NET Core lee la variable de entorno ASPNETCORE_ENVIRONMENT al inicio de la aplicación y almacena el valor en IHostingEnvironment.EnvironmentName.ASP.NET Core reads the environment variable ASPNETCORE_ENVIRONMENT at app startup and stores the value in IHostingEnvironment.EnvironmentName. ASPNETCORE_ENVIRONMENT se puede establecer en cualquier valor, pero el marco proporciona tres valores:ASPNETCORE_ENVIRONMENT can be set to any value, but three values are provided by the framework:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

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

    app.UseStaticFiles();
    app.UseMvc();
}

El código anterior:The preceding code:

El asistente de etiquetas de entorno usa el valor de IHostingEnvironment.EnvironmentName para incluir o excluir el marcado en el elemento:The Environment Tag Helper uses the value of IHostingEnvironment.EnvironmentName to include or exclude markup in the element:

<environment include="Development">
    <div>The effective tag is: &lt;environment include="Development"&gt;</div>
</environment>
<environment exclude="Development">
    <div>The effective tag is: &lt;environment exclude="Development"&gt;</div>
</environment>
<environment include="Staging,Development,Staging_2">
    <div>
        The effective tag is:
        &lt;environment include="Staging,Development,Staging_2"&gt;
    </div>
</environment>

En Windows y macOS, los valores y las variables de entorno no distinguen mayúsculas de minúsculas.On Windows and macOS, environment variables and values aren't case sensitive. Los valores y las variables de entorno de Linux distinguen mayúsculas de minúsculas de forma predeterminada.Linux environment variables and values are case sensitive by default.

DesarrolloDevelopment

El entorno de desarrollo puede habilitar características que no deben exponerse en producción.The development environment can enable features that shouldn't be exposed in production. Por ejemplo, las plantillas de ASP.NET Core habilitan la página de excepciones para el desarrollador en el entorno de desarrollo.For example, the ASP.NET Core templates enable the Developer Exception Page in the development environment.

El entorno para el desarrollo del equipo local se puede establecer en el archivo Properties\launchSettings.json del proyecto.The environment for local machine development can be set in the Properties\launchSettings.json file of the project. Los valores de entorno establecidos en launchSettings.json invalidan los valores establecidos en el entorno del sistema.Environment values set in launchSettings.json override values set in the system environment.

En el siguiente fragmento de JSON se muestran tres perfiles de un archivo launchSettings.json:The following JSON shows three profiles from a launchSettings.json file:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:54339/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      }
    },
    "EnvironmentsSample": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:54340/"
    },
    "Kestrel Staging": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_My_Environment": "1",
        "ASPNETCORE_DETAILEDERRORS": "1",
        "ASPNETCORE_ENVIRONMENT": "Staging"
      },
      "applicationUrl": "http://localhost:51997/"
    }
  }
}

Nota

La propiedad applicationUrl en launchSettings.json puede especificar una lista de direcciones URL del servidor.The applicationUrl property in launchSettings.json can specify a list of server URLs. Use un punto y coma entre las direcciones URL de la lista:Use a semicolon between the URLs in the list:

"EnvironmentsSample": {
   "commandName": "Project",
   "launchBrowser": true,
   "applicationUrl": "https://localhost:5001;http://localhost:5000",
   "environmentVariables": {
     "ASPNETCORE_ENVIRONMENT": "Development"
   }
}

Cuando la aplicación se inicia con dotnet run, se usa el primer perfil con "commandName": "Project".When the app is launched with dotnet run, the first profile with "commandName": "Project" is used. El valor de commandName especifica el servidor web que se va a iniciar.The value of commandName specifies the web server to launch. commandName puede ser uno de los siguientes:commandName can be any one of the following:

  • IISExpress
  • IIS
  • Project (que inicia Kestrel)Project (which launches Kestrel)

Cuando una aplicación se inicia con dotnet run:When an app is launched with dotnet run:

  • Se lee launchSettings.json, si está disponible.launchSettings.json is read if available. La configuración de environmentVariables de launchSettings.json reemplaza las variables de entorno.environmentVariables settings in launchSettings.json override environment variables.
  • Se muestra el entorno de hospedaje.The hosting environment is displayed.

En la siguiente salida se muestra una aplicación que se ha iniciado con dotnet run:The following output shows an app started with dotnet run:

PS C:\Websites\EnvironmentsSample> dotnet run
Using launch settings from C:\Websites\EnvironmentsSample\Properties\launchSettings.json...
Hosting environment: Staging
Content root path: C:\Websites\EnvironmentsSample
Now listening on: http://localhost:54340
Application started. Press Ctrl+C to shut down.

La pestaña Depurar de las propiedades de proyecto de Visual Studio proporciona una GUI para editar el archivo launchSettings.json:The Visual Studio project properties Debug tab provides a GUI to edit the launchSettings.json file:

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

Los cambios realizados en los perfiles de proyecto podrían no surtir efecto hasta que se reinicie el servidor web.Changes made to project profiles may not take effect until the web server is restarted. Es necesario reiniciar Kestrel para que pueda detectar los cambios realizados en su entorno.Kestrel must be restarted before it can detect changes made to its environment.

Advertencia

En launchSettings.json no se deben almacenar secretos.launchSettings.json shouldn't store secrets. Se puede usar la herramienta Administrador de secretos a fin de almacenar secretos para el desarrollo local.The Secret Manager tool can be used to store secrets for local development.

Cuando se usa Visual Studio Code, las variables de entorno se pueden establecer en el archivo .vscode/launch.json.When using Visual Studio Code, environment variables can be set in the .vscode/launch.json file. En el siguiente ejemplo se establece el entorno en Development:The following example sets the environment to Development:

{
   "version": "0.2.0",
   "configurations": [
        {
            "name": ".NET Core Launch (web)",

            ... additional VS Code configuration settings ...

            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            }
        }
    ]
}

Un archivo .vscode/launch.json del proyecto no se lee al iniciar la aplicación con dotnet run en la misma manera que Properties/launchSettings.json.A .vscode/launch.json file in the project isn't read when starting the app with dotnet run in the same way as Properties/launchSettings.json. Cuando se inicia una aplicación en desarrollo que no tiene un archivo launchSettings.json, establezca el valor del entorno con una variable de entorno o con un argumento de línea de comandos para el comando dotnet run.When launching an app in development that doesn't have a launchSettings.json file, either set the environment with an environment variable or a command-line argument to the dotnet run command.

ProducciónProduction

El entorno de producción debe configurarse para maximizar la seguridad, el rendimiento y la solidez de la aplicación.The production environment should be configured to maximize security, performance, and app robustness. Las opciones de configuración comunes que difieren de las del entorno de desarrollo son:Some common settings that differ from development include:

  • Almacenamiento en caché.Caching.
  • Los recursos del cliente se agrupan, se reducen y se atienden potencialmente desde una CDN.Client-side resources are bundled, minified, and potentially served from a CDN.
  • Las páginas de error de diagnóstico están deshabilitadas.Diagnostic error pages disabled.
  • Las páginas de error descriptivas están habilitadas.Friendly error pages enabled.
  • El registro y la supervisión de la producción están habilitados.Production logging and monitoring enabled. Por ejemplo, Application Insights.For example, Application Insights.

Establecimiento del entornoSet the environment

A menudo resulta útil establecer un entorno específico para realizar las pruebas con una variable de entorno o una configuración de plataforma.It's often useful to set a specific environment for testing with an environment variable or platform setting. Si el entorno no está establecido, el valor predeterminado es Production, lo que deshabilita la mayoría de las características de depuración.If the environment isn't set, it defaults to Production, which disables most debugging features. El método para establecer el entorno depende del sistema operativo.The method for setting the environment depends on the operating system.

Cuando se compila el host, la última configuración de entorno leída por la aplicación determina el entorno de la aplicación.When the host is built, the last environment setting read by the app determines the app's environment. El entorno de la aplicación no se puede cambiar mientras se ejecuta la aplicación.The app's environment can't be changed while the app is running.

Configuración de plataforma o variable de entornoEnvironment variable or platform setting

Azure App ServiceAzure App Service

Para establecer el entorno en Azure App Service, realice los pasos siguientes:To set the environment in Azure App Service, perform the following steps:

  1. Seleccione la aplicación desde la hoja App Services.Select the app from the App Services blade.
  2. En el grupo Configuración, seleccione la hoja Configuración.In the Settings group, select the Configuration blade.
  3. En la pestaña Configuración de aplicaciones, seleccione Nueva configuración de aplicación.In the Application settings tab, select New application setting.
  4. En la ventana Agregar o editar la configuración de la aplicación, escriba ASPNETCORE_ENVIRONMENT para el Nombre.In the Add/Edit application setting window, provide ASPNETCORE_ENVIRONMENT for the Name. En Valor, proporcione el entorno (por ejemplo, Staging).For Value, provide the environment (for example, 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.Select the Deployment slot setting check box if you wish the environment setting to remain with the current slot when deployment slots are swapped. Para más información, consulte Configuración de entornos de ensayo en Azure App Service en la documentación de Azure.For more information, see Set up staging environments in Azure App Service in the Azure documentation.
  6. Seleccione Aceptar para cerrar la ventana Agregar o editar la configuración de la aplicación.Select OK to close the Add/Edit application setting window.
  7. Seleccione Guardar en la parte superior de la hoja Configuración.Select Save at the top of the Configuration blade.

Azure App Service reinicia automáticamente la aplicación después de que se agregue, cambie o elimine una configuración de aplicación (variable de entorno) en Azure Portal.Azure App Service automatically restarts the app after an app setting (environment variable) is added, changed, or deleted in the Azure portal.

WindowsWindows

Para establecer ASPNETCORE_ENVIRONMENT en la sesión actual, cuando la aplicación se ha iniciado con dotnet run, use los comandos siguientes:To set the ASPNETCORE_ENVIRONMENT for the current session when the app is started using dotnet run, the following commands are used:

Símbolo del sistemaCommand prompt

set ASPNETCORE_ENVIRONMENT=Development

PowerShellPowerShell

$Env:ASPNETCORE_ENVIRONMENT = "Development"

Estos comandos solo tienen efecto en la ventana actual.These commands only take effect for the current window. Cuando se cierre la ventana, la configuración de ASPNETCORE_ENVIRONMENT volverá a la configuración predeterminada o al valor del equipo.When the window is closed, the ASPNETCORE_ENVIRONMENT setting reverts to the default setting or machine value.

Para establecer el valor globalmente en Windows, use cualquiera de los métodos siguientes:To set the value globally in Windows, use either of the following approaches:

  • Abra el Panel de control > Sistema > Configuración avanzada del sistema y agregue o edite el valor ASPNETCORE_ENVIRONMENT:Open the Control Panel > System > Advanced system settings and add or edit the ASPNETCORE_ENVIRONMENT value:

    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:Open an administrative command prompt and use the setx command or open an administrative PowerShell command prompt and use [Environment]::SetEnvironmentVariable:

    Símbolo del sistemaCommand prompt

    setx ASPNETCORE_ENVIRONMENT Development /M
    

    El modificador /M indica que hay que establecer la variable de entorno en el nivel de sistema.The /M switch indicates to set the environment variable at the system level. Si no se usa el modificador /M, la variable de entorno se establece para la cuenta de usuario.If the /M switch isn't used, the environment variable is set for the user account.

    PowerShellPowerShell

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

    El valor de opción Machine indica que hay que establecer la variable de entorno en el nivel de sistema.The Machine option value indicates to set the environment variable at the system level. Si el valor de opción se cambia a User, la variable de entorno se establece para la cuenta de usuario.If the option value is changed to User, the environment variable is set for the user account.

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.When the ASPNETCORE_ENVIRONMENT environment variable is set globally, it takes effect for dotnet run in any command window opened after the value is set.

web.configweb.config

Para establecer la variable de entorno ASPNETCORE_ENVIRONMENT con web.config, vea la sección Establecimiento de variables de entorno de Módulo ASP.NET Core.To set the ASPNETCORE_ENVIRONMENT environment variable with web.config, see the Setting environment variables section of Módulo ASP.NET Core.

Archivo del proyecto o perfil de publicaciónProject file or publish profile

Para las implementaciones de IIS de Windows: Incluya la propiedad <EnvironmentName> del perfil de publicación (.pubxml) o un archivo de proyecto.For Windows IIS deployments: Include the <EnvironmentName> property in the publish profile (.pubxml) or project file. Este método establece el entorno en web.config cuando se publica el proyecto:This approach sets the environment in web.config when the project is published:

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

Por grupo de aplicaciones de IISPer IIS Application Pool

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).To set the ASPNETCORE_ENVIRONMENT environment variable for an app running in an isolated Application Pool (supported on IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic. 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.When the ASPNETCORE_ENVIRONMENT environment variable is set for an app pool, its value overrides a setting at the system level.

Importante

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:When hosting an app in IIS and adding or changing the ASPNETCORE_ENVIRONMENT environment variable, use any one of the following approaches to have the new value picked up by apps:

  • Ejecute net stop was /y seguido de net start w3svc en un símbolo del sistema.Execute net stop was /y followed by net start w3svc from a command prompt.
  • Reinicie el servidor.Restart the server.

macOSmacOS

Para establecer el entorno actual para macOS, puede hacerlo en línea al ejecutar la aplicación:Setting the current environment for macOS can be performed in-line when running the app:

ASPNETCORE_ENVIRONMENT=Development dotnet run

De forma alternativa, defina el entorno con export antes de ejecutar la aplicación:Alternatively, set the environment with export prior to running the app:

export ASPNETCORE_ENVIRONMENT=Development

Las variables de entorno de nivel de equipo se establecen en el archivo .bashrc o .bash_profile.Machine-level environment variables are set in the .bashrc or .bash_profile file. Edite el archivo con cualquier editor de texto.Edit the file using any text editor. Agregue la siguiente instrucción:Add the following statement:

export ASPNETCORE_ENVIRONMENT=Development

LinuxLinux

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.For Linux distros, use the export command at a command prompt for session-based variable settings and bash_profile file for machine-level environment settings.

Establecimiento del entorno en el códigoSet the environment in code

Llame a UseEnvironment al compilar el host.Call UseEnvironment when building the host. Vea Host web de ASP.NET Core.See Host web de ASP.NET Core.

Configuración de entornoConfiguration by environment

Para cargar la configuración por entorno, se recomienda lo siguiente:To load configuration by environment, we recommend:

Métodos y clase Startup basados en entornoEnvironment-based Startup class and methods

Inserción de IHostingEnvironment en Startup.ConfigureInject IHostingEnvironment into Startup.Configure

Inserte IHostingEnvironment en Startup.Configure.Inject IHostingEnvironment into Startup.Configure. Este enfoque es útil cuando la aplicación solo requiere la configuración de Startup.Configure para algunos entornos con diferencias de código mínimas en cada uno.This approach is useful when the app only requires configuring Startup.Configure for only a few environments with minimal code differences per environment.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Development environment code
    }
    else
    {
        // Code for all other environments
    }
}

Inserción de IHostingEnvironment en la clase StartupInject IHostingEnvironment into the Startup class

Inserte IHostingEnvironment en el constructor Startup y asigne el servicio a un campo para su uso en la clase Startup.Inject IHostingEnvironment into the Startup constructor and assign the service to a field for use throughout the Startup class. Este enfoque es útil cuando la aplicación solo requiere configurar el inicio para algunos entornos con diferencias de código mínimas en cada uno.This approach is useful when the app requires configuring startup for only a few environments with minimal code differences per environment.

En el ejemplo siguiente:In the following example:

  • El entorno se mantiene en el campo _env.The environment is held in the _env field.
  • _env se usa en ConfigureServices y Configure para aplicar la configuración de inicio en función del entorno de la aplicación._env is used in ConfigureServices and Configure to apply startup configuration based on the app's environment.
public class Startup
{
    private readonly IHostingEnvironment _env;

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

    public void ConfigureServices(IServiceCollection services)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else if (_env.IsStaging())
        {
            // Staging environment code
        }
        else
        {
            // Code for all other environments
        }
    }

    public void Configure(IApplicationBuilder app)
    {
        if (_env.IsDevelopment())
        {
            // Development environment code
        }
        else
        {
            // Code for all other environments
        }
    }
}

Convenciones de la clase StartupStartup class conventions

Cuando se inicia una aplicación ASP.NET Core, la clase Startup arranca la aplicación.When an ASP.NET Core app starts, the Startup class bootstraps the app. La aplicación puede definir clases Startup independientes para distintos entornos (por ejemplo, StartupDevelopment).The app can define separate Startup classes for different environments (for example, StartupDevelopment). La clase Startup correspondiente se selecciona en tiempo de ejecución.The appropriate Startup class is selected at runtime. La clase cuyo sufijo de nombre coincide con el entorno actual se establece como prioritaria.The class whose name suffix matches the current environment is prioritized. Si no se encuentra una clase Startup{EnvironmentName} coincidente, se usa la clase Startup.If a matching Startup{EnvironmentName} class isn't found, the Startup class is used. Este enfoque es útil cuando la aplicación requiere configurar el inicio para algunos entornos con muchas diferencias de código en cada uno.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

Para implementar clases Startup basadas en entornos, cree una clase Startup{EnvironmentName} para cada entorno en uso y una clase Startup de reserva:To implement environment-based Startup classes, create a Startup{EnvironmentName} class for each environment in use and a fallback Startup class:

// Startup class to use in the Development environment
public class StartupDevelopment
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Startup class to use in the Production environment
public class StartupProduction
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

// Fallback Startup class
// Selected if the environment doesn't match a Startup{EnvironmentName} class
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
    }
}

Use la sobrecarga UseStartup(IWebHostBuilder, String) que acepta un nombre de ensamblado:Use the UseStartup(IWebHostBuilder, String) overload that accepts an assembly name:

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

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

    return WebHost.CreateDefaultBuilder(args)
        .UseStartup(assemblyName);
}

Convenciones del método StartupStartup method conventions

Configure y ConfigureServices son compatibles con versiones específicas del entorno con el formato Configure<EnvironmentName> y Configure<EnvironmentName>Services.Configure and ConfigureServices support environment-specific versions of the form Configure<EnvironmentName> and Configure<EnvironmentName>Services. Este enfoque es útil cuando la aplicación requiere configurar el inicio para algunos entornos con muchas diferencias de código en cada uno.This approach is useful when the app requires configuring startup for several environments with many code differences per environment.

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    public void ConfigureStagingServices(IServiceCollection services)
    {
        StartupConfigureServices(services);
    }

    private void StartupConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

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

        app.UseStaticFiles();
        app.UseMvc();
    }

    public void ConfigureStaging(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (!env.IsStaging())
        {
            throw new Exception("Not staging.");
        }

        app.UseExceptionHandler("/Error");
        app.UseStaticFiles();
        app.UseMvc();
    }
}

Recursos adicionalesAdditional resources