Environments & AppSettings

Working with different environments for configuring DynamicWeb 10

ASP.NET Core 8 (and earlier) features the concept of environments, where you can load different configurations for an application at runtime depending on the environment it is being run in. By convention these are almost always Development, Staging, and Production:

Development is the environment used when developing a solution
Staging is a pre-production environment used for final testing before deployment to production. Ideally, this environment is a mirror of the production environment, so that any issues will be caught here before they affect end-users.
Production is the environment in which the solution runs when it is live and being used by end users. It should be configured to maximize security, performance, and robustness.

There are a handful of ways to affect the way DynamicWeb 10 starts and which environments it loads:

You can use one or more appsettings.json files to create different configuration collections and e.g. connect to local Files-folders in a development environment
You can define and switch between environments using VS, VS Code, .NET CLI or web.config file

In this guide, we'll go over these options and variables

AppSettings

Like most other .NET applications, DynamicWeb 10 can use an appsettings.json file to configure the startup parameters of the application. It should be placed in the application folder in parallel to bin and wwwroot: There are many ways you can use this file, but typical use cases include:

Setting the LogLevel for the environment
Specifying an alternative location for the Files-folder which DynamicWeb 10 expects to find in the wwwroot-folder
Changing the database server based on the environment

A minimal appsettings.json file would look like this:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

It only contains configuration for ASP.NET Core. A freshly installed DynamicWeb 10 solution using this configuration will run the DW10 Setup Guide at startup, as it doesn't detect a Files-folder.

If an existing DynamicWeb solution already exists locally, or if you simply want to keep your applications separate from your Files-project, you can reference it by using the FilesPath key:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "FilesPath": "/dw-solutions/Customer1/Files",
}

In the example above, the Files path is assumed to be a Linux path - on Windows the Files path uses backslashes which need to be escaped:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "FilesPath": "C:\\DwSolutions\\Customer1\\Files",
}

In addition to referencing an existing Files-folder, you can also change the database server that is defined for the solution. This is useful if the solution you're working on uses an external database, but you want to test some changes locally without affecting the external database:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "FilesPath": "/dw-solutions/Customer1/Files",
  "Database": {
    "Server": "localhost",
    "UserName": "sa",
    "Password": "SuperStrOng(!)Passw0rd"
  }
}

You can create multiple appsettings.json files for different environments. The naming pattern as specified by Microsoft is appsettings.[ENVIRONMENT].json.

Setting the Environment

The environment can be set in different ways depending on whether the application is being launched from Visual Studio, Visual Studio Code, .NET CLI, or IIS, but they all revolve around the same concept: setting the environment variable ASPNETCORE_ENVIRONMENT.

The value of this variable must match the [ENVIRONMENT] part of the environment-specific appsettings.json file mentioned in the previous section. This will cause the runtime to use that specific configuration file.

More information about environments can be found here.

Visual Studio

Visual Studio uses a configuration file called launchSettings.json to define different parameters for launching the application. The different launch profiles defined here can set environment variables, including ASPNETCORE_ENVIRONMENT.

Creating multiple launch profiles with different environment allows for easy switching between environment in Visual Studio:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:55979/",
      "sslPort": 44360
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "Dynamicweb (Development)": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "https://localhost:6001/admin",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },      
      "applicationUrl": "https://localhost:6001;http://localhost:6000",
      "nativeDebugging": true
    },
    "Dynamicweb (Production)": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "https://localhost:6001/admin",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      },      
      "applicationUrl": "https://localhost:6001;http://localhost:6000",
      "nativeDebugging": true
    }
  }
}

Visual Studio Code

When opening the application folder in VS Code for the first time, a prompt for adding missing items will appear. Clicking Yes to this prompt creates new files used to launch the application from within VS Code, including a launch.json file.

The launch.json file fills the same purpose as the launchSettings.json in Visual Studio and provides the same benefits including allowing you to set the environment variable and define launch profiles:

{
    "version": "0.2.0",
    "configurations": [
        {
            // Use IntelliSense to find out which attributes exist for C# debugging
            // Use hover for the description of the existing attributes
            // For further information visit https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md
            "name": "Dynamicweb (Development)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            // If you have changed target frameworks, make sure to update the program path.
            "program": "${workspaceFolder}/Dynamicweb.Cms/bin/Debug/net7.0/Cms.dll",
            "args": [],
            "cwd": "${workspaceFolder}/Dynamicweb.Cms",
            "stopAtEntry": false,
            // Enable launching a web browser when ASP.NET Core starts. For more information: https://aka.ms/VSCode-CS-LaunchJson-WebBrowser
            "serverReadyAction": {
                "action": "openExternally",
                "pattern": "\\bNow listening on:\\s+(https?://\\S+)"
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            // Use IntelliSense to find out which attributes exist for C# debugging
            // Use hover for the description of the existing attributes
            // For further information visit https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md
            "name": "Dynamicweb (Production)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            // If you have changed target frameworks, make sure to update the program path.
            "program": "${workspaceFolder}/Dynamicweb.Cms/bin/Debug/net7.0/Cms.dll",
            "args": [],
            "cwd": "${workspaceFolder}/Dynamicweb.Cms",
            "stopAtEntry": false,
            // Enable launching a web browser when ASP.NET Core starts. For more information: https://aka.ms/VSCode-CS-LaunchJson-WebBrowser
            "serverReadyAction": {
                "action": "openExternally",
                "pattern": "\\bNow listening on:\\s+(https?://\\S+)"
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Production"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach"
        }
    ]
}

.NET CLI

Starting the application using .NET CLI is a great option when running tests or other automated processes that start and stop the application, or for the segment of developers who prefer to spend their time in a terminal.

The .NET CLI has a few different ways to affect the runtime environment:, for instance by specifying the --environment flag:

dotnet run --environment Production

.NET CLI can also use a launchSettings.json file, in which case you can use the --launch-profile flag to specify a launch profile:

dotnet run --launch-profile "Development"

You can also set an environment for the terminal, as all supported operating systems allow the user to set environment variables. Please consult the documentation for your OS to learn how this is done.

IIS

Websites running in IIS use a web.config file to define their configuration. When hosting DynamicWeb on IIS, the web.config can be updated to set the environment variable ASPNETCORE_ENVIRONMENT, just like any other environment variable.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments="D:\DW\10.0.0\Dynamicweb.Host.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
        </environmentVariables>
      </aspNetCore>
      <security>
        <requestFiltering>
          <requestLimits maxAllowedContentLength="2048000000" />
            <denyUrlSequences>
              <add sequence=".php" />
            </denyUrlSequences>
          </requestFiltering>
      </security>
    </system.webServer>
  </location>
  <system.web>
    <customErrors mode="On" />
  </system.web>
</configuration>

Environment Variables

DynamicWeb 10 features a number of variables which may be used as environment variables. When used in this role they must be prefaced with DW_, so FilesPath becomes DW_FilesPath when used as an environment variable. This makes them easily identifiable among other environment variables.

Here FilesPath is used as an environment variable in a web.config file:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments="D:\DW\10.0.0\Dynamicweb.Host.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
          <environmentVariable name="DW_FilesPath" value="C:\DwSolutions\Customer1\Files">
        </environmentVariables>
      </aspNetCore>
      <security>
        <requestFiltering>
          <requestLimits maxAllowedContentLength="2048000000" />
            <denyUrlSequences>
              <add sequence=".php" />
            </denyUrlSequences>
          </requestFiltering>
      </security>
    </system.webServer>
  </location>
  <system.web>
    <customErrors mode="On" />
  </system.web>
</configuration>

The following variables are available:

Variable	Description
FilesPath	The path where the Files folder should be located. Both relative and absolute paths are supported
Database__Server	The location of the database server
Database__UserName	UserName for database access
Database__Password	Password for the database user
Database__Database	The name of the database

Variables defined here are in a format usable for environment variables, except they are missing the required prefix DW_. Some variables are part of an object instead of stand-alone variables. For example the Database__ variables would in the json format that appsettings.json uses be structured as an object. The object hierarchy is flattened by separating the keys with the double underscore (__). See the App section for an example.

In addition to the DynamicWeb specific variables, there are a number of .NET and ASP.NET Core variables that allow for configuration of the runtime.

Table of Contents