From e45acca4ad97690fa5aed050619e15b6649d3030 Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Tue, 22 Jan 2019 19:55:07 -0600 Subject: [PATCH] Clarify env var behaviors (#10555) Fixes #10165 --- aspnetcore/fundamentals/environments.md | 16 +++++++++- .../host-and-deploy/aspnet-core-module.md | 30 +++++++++++++++++-- .../visual-studio-publish-profiles.md | 12 +++++++- 3 files changed, 54 insertions(+), 4 deletions(-) diff --git a/aspnetcore/fundamentals/environments.md b/aspnetcore/fundamentals/environments.md index eebc8456df..5562a85b97 100644 --- a/aspnetcore/fundamentals/environments.md +++ b/aspnetcore/fundamentals/environments.md @@ -3,7 +3,7 @@ title: Use multiple environments in ASP.NET Core author: rick-anderson description: Learn how to control app behavior across multiple environments in ASP.NET Core apps. ms.author: riande -ms.date: 07/03/2018 +ms.date: 01/22/2019 uid: fundamentals/environments --- # Use multiple environments in ASP.NET Core @@ -232,6 +232,20 @@ When the `ASPNETCORE_ENVIRONMENT` environment variable is set globally, it takes To set the `ASPNETCORE_ENVIRONMENT` environment variable with *web.config*, see the *Setting environment variables* section of . When the `ASPNETCORE_ENVIRONMENT` environment variable is set with *web.config*, its value overrides a setting at the system level. +::: moniker range=">= aspnetcore-2.2" + +**Project file or publish profile** + +**For Windows IIS deployments:** Include the `` property in the publish profile (*.pubxml*) or project file. This approach sets the environment in *web.config* when the project is published: + +```xml + + Development + +``` + +::: moniker-end + **Per IIS Application Pool** 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>](/iis/configuration/system.applicationHost/applicationPools/add/environmentVariables/#appcmdexe) topic. When the `ASPNETCORE_ENVIRONMENT` environment variable is set for an app pool, its value overrides a setting at the system level. diff --git a/aspnetcore/host-and-deploy/aspnet-core-module.md b/aspnetcore/host-and-deploy/aspnet-core-module.md index 3aec3e1797..fc3721c8de 100644 --- a/aspnetcore/host-and-deploy/aspnet-core-module.md +++ b/aspnetcore/host-and-deploy/aspnet-core-module.md @@ -4,7 +4,7 @@ author: guardrex description: Learn how to configure the ASP.NET Core Module for hosting ASP.NET Core apps. ms.author: riande ms.custom: mvc -ms.date: 01/11/2019 +ms.date: 01/22/2019 uid: host-and-deploy/aspnet-core-module --- # ASP.NET Core Module @@ -280,7 +280,20 @@ For information on IIS sub-application configuration, see ` child element of an `` collection element. Environment variables set in this section take precedence over system environment variables. + +::: moniker-end + +::: moniker range="< aspnetcore-3.0" + +Environment variables can be specified for the process in the `processPath` attribute. Specify an environment variable with the `` child element of an `` collection element. + +> [!WARNING] +> Environment variables set in this section conflict with system environment variables set with the same name. If an environment variable is set in both the *web.config* file and at the system level in Windows, the value from the *web.config* file becomes appended to the system environment variable value (for example, `ASPNETCORE_ENVIRONMENT: Development;Development`), which prevents the app from starting. + +::: moniker-end The following example sets two environment variables. `ASPNETCORE_ENVIRONMENT` configures the app's environment to `Development`. A developer may temporarily set this value in the *web.config* file in order to force the [Developer Exception Page](xref:fundamentals/error-handling) to load when debugging an app exception. `CONFIG_DIR` is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file. @@ -317,6 +330,19 @@ The following example sets two environment variables. `ASPNETCORE_ENVIRONMENT` c ::: moniker-end +::: moniker range=">= aspnetcore-2.2" + +> [!NOTE] +> An alternative to setting the environment directly in *web.config* is to include the `` property in the publish profile (*.pubxml*) or project file. This approach sets the environment in *web.config* when the project is published: +> +> ```xml +> +> Development +> +> ``` + +::: moniker-end + > [!WARNING] > Only set the `ASPNETCORE_ENVIRONMENT` environment variable to `Development` on staging and testing servers that aren't accessible to untrusted networks, such as the Internet. diff --git a/aspnetcore/host-and-deploy/visual-studio-publish-profiles.md b/aspnetcore/host-and-deploy/visual-studio-publish-profiles.md index 9199ecd6b3..ac843f9f6f 100644 --- a/aspnetcore/host-and-deploy/visual-studio-publish-profiles.md +++ b/aspnetcore/host-and-deploy/visual-studio-publish-profiles.md @@ -4,7 +4,7 @@ author: rick-anderson description: Learn how to create publish profiles in Visual Studio and use them for managing ASP.NET Core app deployments to various targets. ms.author: riande ms.custom: mvc -ms.date: 12/06/2018 +ms.date: 01/22/2019 uid: host-and-deploy/visual-studio-publish-profiles --- # Visual Studio publish profiles for ASP.NET Core app deployment @@ -331,6 +331,16 @@ dotnet msbuild "AzureWebApp.csproj" > [!NOTE] > The [dotnet msbuild](/dotnet/core/tools/dotnet-msbuild) command is available cross-platform and can compile ASP.NET Core apps on macOS and Linux. However, MSBuild on macOS and Linux isn't capable of deploying an app to Azure or other MSDeploy endpoint. MSDeploy is only available on Windows. +## Set the environment + +Include the `` property in the publish profile (*.pubxml*) or project file to set the app's [environment](xref:fundamentals/environments): + +```xml + + Development + +``` + ## Exclude files When publishing ASP.NET Core web apps, the build artifacts and contents of the *wwwroot* folder are included. `msbuild` supports [globbing patterns](https://gruntjs.com/configuring-tasks#globbing-patterns). For example, the following `` element excludes all text (*.txt*) files from the *wwwroot/content* folder and all its subfolders.