Page 34 - MSDN Magazine, September 2017

Let’s briefly take a look at the most important calls made in CreateDefaultBuilder and their purpose. Although these are all made for you (by CreateDefaultBuilder), it’s still good to under- stand what’s happening behind the scenes.
UseKestrel specifies that your application should use Kestrel, a libuv-based cross-platform Web server. The other option here would be to use HttpSys as the Web server (UseHttpSys). HttpSys is supported only on Windows (Windows 7/2008 R2 and later), but has the advantages of allowing Windows authentication and being safe to run directly exposed to the Internet (Kestrel, on the other hand, should sit behind a reverse proxy like IIS, Nginx or Apache if it will receive requests from the Internet).
UseContentRoot specifies the root directory for the applica- tion where ASP.NET Core will find site-wide content like config files. Note that this is not the same as the Web root (where static files will be served from), though by default the Web root is based on the content root ([ContentRoot]/wwwroot).
ConfigureAppConfiguration creates the configuration object the app will use to read settings at run time. When called from Cre- ateDefaultBuilder, this will read application configuration settings from an appsettings.json file, an environment-specific .json file (if one exists), environment variables and command-line arguments. If in a development environment, it will also use user secrets. This method is new in ASP.NET Core 2.0 and I’ll discuss it in more detail later.
ConfigureLogging sets up logging for the application. When called from CreateDefaultBuilder, console and debug logging pro- viders are added. Like ConfigureAppConfiguration, this method is new and is discussed more later.
UseIISIntegration configures the application to run in IIS. Note that UseKestrel is still needed. IIS is acting as the reverse proxy and Kestrel is still used as the host. Also, UseIISIntegration won’t have any effect if the app isn’t running behind IIS, so it’s safe to call even if the app will be run in non-IIS scenarios.
In many cases, the default configuration provided by Create- DefaultBuilder will be sufficient. All that’s needed beyond that call is to specify the Startup class for your application with a call to UseStartup<T>, where T is the Startup type.
If CreateDefaultBuilder doesn’t meet your scenario’s needs, you should feel free to customize how the IWebHost is being created. If you need to make only small tweaks, you can call CreateDefault- Builder and then modify the WebHostBuilder that’s returned (perhaps by calling ConfigureAppConfiguration again, for exam- ple, to add more configuration sources). If you need to make larger changes to the IWebHost, you can skip calling CreateDefaultBuilder completely and just construct a WebHostBuilder yourself, as you would have with ASP.NET Core 1.0 or 1.1. Even if you go this route, you can still take advantage of the new ConfigureAppConfiguration and ConfigureLogging methods. More details on Web host con- figuration are available at bit.ly/2uuSwwM.
ASP.NET Core Environments
A couple of actions CreateDefaultBuilder takes depend on in which environment your ASP.NET Core application is running. The concept of environments isn’t new in 2.0, but is worth briefly reviewing because it comes up frequently.
In ASP.NET Core, the environment an application is running in is indicated by the ASPNETCORE_ENVIRONMENT environment variable. You can set this to any value you like, but the values Devel- opment, Staging and Production are typically used. So, if you set the ASPNETCORE_ENVIRONMENT variable to Development prior to calling dotnet run (or if you set that environment variable in a launchSettings.json file), your app will run in Development mode (instead of Production, which is the default without any variables set). This value is used by several ASP.NET Core features (I’ll refer- ence it when discussing Configuration and Logging, later) to modify runtime behavior and can be accessed in your own code using the IHostingEnvironment service. More information on ASP.NET Core environments is available in the ASP.NET Core docs (bit.ly/2eICDMF).
ASP.NET Core Configuration
ASP.NET Core uses the Microsoft.Extensions.Configuration package’s IConfiguration interface to provide runtime configu- ration settings. As mentioned previously, CreateDefaultBuilder will read settings from .json files and environment variables. The configuration system is extensible, though, and can read configura- tion information from a wide variety of providers (.json files, .xml files, .ini files, environment variables, Azure Key Vault and so forth.).
When working with IConfiguration and IConfigurationBuilder objects, remember that the order the providers are added is important. Later providers can override settings from previous providers, so you’ll want to add common base providers first and then, later, add environment-specific providers that might override some of the settings.
ConfigurationsettingsinASP.NETCorearehierarchical.Inthe new project you created, for example, appsettings.json (see Figure 3) contains a top-level Logging element with sub-settings under- neath it. These settings indicate the minimum priority of messages to log (via the “LogLevel” settings) and whether the app’s logical scope at the time the message is logged should be recorded (via IncludeScopes). To retrieve nested settings like these, you can either use the IConfiguration.GetSection method to retrieve a single section of the configuration or specify the full path of a particular setting, delimited with colons. So, the value of IncludeScopes in the project could be retrieved as:
Configuration["Logging:IncludeScopes"]
When defining configuration settings with environment vari- ables, the environment variable name should include all levels of the hierarchy and can be delimited with either a colon (:) or double underscore (__). For example, an environment variable called Logging__IncludeScopes would override the IncludeScopes setting of the example file in Figure 3, assuming that the environ- ment variable provider is added after the settings file, like it is in the CreateDefaultBuilder case.
Because WebHost.CreateDefaultBuilder is reading configura- tion from both appsettings.json and environment-specific .json files, you’ll notice that logging behavior changes when you change environments (appsettings.Development.json overrides the default appsettings.json’s LogLevel settings with more verbose “debug” and “information” levels). If you set the environment to Development prior to calling dotnet run, you should notice a fair bit of logging
30 msdn magazine
ASP.NET Core