.net core精彩实例分享 -- 应用启动

介绍

随着.net core越来越流行，对.net core 基础知识的了解，实际应用等相关的知识也应该有所了解。所以就有了这篇文章，案例都是来自阅读的书籍，或者实际工作中感觉比较有用的应用。分享亦总结。

本文主要介绍 .net core 相关的应用启动案例。

具体案例 配置Web服务器的URL

【导语】

WebHost 是一个静态类，它公开了一系列简便的方法，可以使用各项默认配置参数创建 Web 主机，其中用得最的是 CreateDefaultBuilder 方法。CreateDefaultBuilder 方法一般使用默认的配置来创建 WebHostBuilder 实例，这些默认的配置包括：

（1）使用内置的 Kestrel 服务器组件，能够使 Web 应用在进程中独立运行。

（2）使用 IIS 交互。IIS 将作为反向代理端，将 HTTP 请求转发到Web应用程序。

（3）将应用程序的当前目录作为 Web 内容的根目录。

（4）加载 appsettings.json 或 appsettings..json 文件来对应用程序进行配置。

（5）加载环境变量和命令行参数。

（6）记录日志，并在控制台窗口和 Visual Studio 的“调试”窗口中输出日志信息。

调用 CreateDefaultBuilder 方法并返回 WebHostBuilder 实例，接着调用该实例的 Build 方法，就能创建 WebHost 实例了，最后调用 Run 扩展方法去启动 Web 服务器，Web 应用程序开始执行。

对 Web 服务器的配置都在 WebHostBuilder 对象上完成，一旦调用 Build 方法生成服务器主机后就不要再更改配置了，尤其是用于监听客户端请求的 URL。指定 URL 的方法有很多种，比较常用的有以下三种：

（1）调用 UseUrls 方法。这是一个扩展方法，它的内部调用了 IWebHostBuilder 的 UseSetting 方法。UseUrls 方法使用可变个数的字符串对象作为参数，可以方便地指定多个URL。

（2）调用 UseSetting 方法，配置的key参数为 WebHostDefault.ServerUrlsKey 字段（即字符串“urls”），配置的值是一个单独的字符串实例，如果有多个 URL，需要用英文的分号分隔。

（3）通过配置文件，如果默认的是 appsettings.json，可以自定义文件名称。

URL的格式一般为“协议方案”+“主机名”+“端口”，例如以下格式。

http://localhost:6000

如果需要监听本机某个端口上的所有地址，可以用星号（*）或者加号（+）代替主机名，格式如下。

http://*localhost*:8005

本实例将演示通过三种方式设置 Web 服务器的 URL。

【操作流程】

步骤1：新建一个空白的ASP.NET Core Web应用程序项目。

步骤2：找到 Program 类的 Main 方法，删除里面的代码，替换为以下代码。

var builder = new WebHostBuilder()
      .UseKestrel()
      .UseIISIntegration()
      .UseStartup()
      .UseUrls("http://localhost:6500");
builder.Build().Run();

也可以指定多个 URL。

var builder = new WebHostBuilder()
      ...
      .UseUrls("http://localhost:6500", "http://localhost:7000", "http://*:9730");

步骤3：使用 UseSetting 方法也可以配置 URL。

var builder = new WebHostBuilder()
      ...
      .UseSetting(WebHostDefaults.ServerUrlsKey, "http://localhost:8990");

如果要配置多个 URL，请用英文的分号隔开。

var builder = new WebHostBuilder()
      ...
      .UseSetting(WebHostDefaults.ServerUrlsKey, "http://localhost:8990;http://localhost:46133");

注意：UseSetting 方法的 value 参数是单个字符串实例，所以多个 URL 都是用一个字符串实例来表示的，这与 UseUrls 方法不同。

步骤4：还可以用 json 文件配置。再项目目录中新建一个 json 文件，假设命名为 host.json，并再新的JSON文件中 输入以下内容。

{
  "urls" :  "http://localhost:3600;http://*:80"
}

步骤5：然后回到 Main 方法，对代码做以下修改。

 var builder = new WebHostBuilder()
     ...
     .UseStartup();

ConfigurationBuilder config = new ConfigurationBuilder();
config.SetBasePath(builder.GetSetting(WebHostDefaults.ContentRootKey))
      .AddJsonFile("host.json");
builder.UseConfiguration(config.Build());
builder.Build().Run();

要使配置生效，不能调用 ConfigureAppConfiguration 方法，因为此方法仅用于配置应用程序级别的参数，而不是 Web 主机级别的参数。此时需要通过 ConfigurationBuilder 对象生成一个新的配置对象，然后调用 UseConfiguration 方法来对默认的配置进行覆盖。

SetBasePath 方法的作用是设定一个基础的目录路径，随后再调用 AddJsonFile 方法添加 JSON 文件时，只需要提供文件名即可，即相对路径（相对于 SetBasePath 方法所指定的路径）。

步骤6：运行应用程序项目，结果如下。

配置Web项目的调试方案

【导语】

在创建 ASP.NET Core Web 项目后，模板默认生成两个调式方案：

（1）以 ISS Express 为反向代理运行应用程序。

（2）用项目名称命名，独立运行项目（通过 dotnet 命令执行）。

开发人员可以根据实际需要对调式方案进行新增、删除和编辑。最简单的配置方法是通过项目属性窗口中的“调试”选项卡操作。“调试”页面的配置内容保存在项目目录下的 \Properties\launchSettings.json 文件中，文件的大致结构如下：

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:53196",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_Environment": "Development"
      }
    }，
    "": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_Environment": "Development"
      },
      "applicationUrl": "http://localhost:6000"
    }
  }
}

其中，profiles 字段下所包含的内容就是调试方案列表。方案名称可以自定义（模板生成默认名称有两个，一个是“IISExpress”，另一个与项目同名）。commandName 字段用于描述应用程序在调式时的启动方式，此值有四个选项：

（1）IIS Express：以 IIS Express 作为反向代理进程。

（2）IIS：以 IIS 服务（完整版 IIS）作为反向代理进程。

（3）Project：使用 dotnet 命令直接运行应用程序（附加 .dll 文件）。

（4）Executable：自定义一个可执行文件，这种调试方案一般不常用。

commandName 字段之后的各个字段在每种调试方案中并不固定，例如如果 commandName 指定为 Executable，那么随后就要设置 executablePath 字段以表示要启动的可执行文件的路径。但 IIS Express 调试方案中则不需要 executablePath 字段。

【操作流程】

步骤1：新建一个空白的 ASP.NET Core Web 应用程序项目。

步骤2：项目创建后，打开项目属性窗口，切换到“调试”选项卡页。

步骤3：单击“删除”按钮，将项目模板默认生成的调试方案全部删除。

步骤4：单击“新建”按钮，弹出“新建配置文件”对话框，在对话框中输入一个自定义的名称。

步骤5：在“启动”下拉列表框中选择“项目”，即 commandName 字段为 Project 值。

步骤6：在“环境变量”中添加一个新项目，名称为“ASPNETCORE_Environment”，值为“Development”。

“ASPNETCORE_”是默认的环境变量前缀，其后紧跟环境变量的名称。例如本例中，环境变量名称为“Environment”，它表示应用程序运行的环境，预定义的值有三个：Development、Staging、Production，也是可以自定义的。

步骤7：在“应用URL”中填写Web应用启动时监听的地址，本实例中使用的地址为 http://localhost:6000。

步骤8：(可选)如果需要应用程序在启动调试时自动打开浏览器，可以勾选”启动浏览器“复选框。

步骤9：保存并关闭项目属性窗口。此时在 Visual Studio 的调试工具按钮的级联菜单里面就包含自定义的调试方案了。

基于方法约定的Startup类

【导语】

在默认的项目模板中，会创建一个 Startup 类，并通过 WebHostBuilder 的扩展方法————UseStartup 来进行配置。Startup 并未要求类名必须为 Startup，可以自定义类名，但是要求必须包含约定的方法（可以是实例方法，也可以是静态方法）。方法有两个：

（1）ConfigureServices 方法：这个约定方法是可选的，当需要向容器添加服务时才定义。该方法只有一个参数，类型为 IServiceCollection。在 ConfigureServices 方法内部可以向 IServiceCollection 集合添加要用到的服务类型。

（2）Configure 方法：此方法是必须的，它支持参数的依赖注入，要求必须包含 IApplicationBuilder 类型的参数。如果有其他参数存在，IApplicationBuilder 类型的参数要放在参数列表的第一位，其余参数将由依赖注入来赋值。

这两个约定方法的格式如下：

void ConfigureServices(IServiceCollection services);
void Configure(IApplicationBuilder app)[,];

应用程序在运行时会查找约定方法的名称，所以在 Startup 类型中声明时，方法名称必须正确，否则运行时将因为找不到约定的方法而发生错误。

【操作流程】

步骤1：新建一个空白的 ASP.NET Core Web 应用程序项目。

步骤2：删除项目模板生成的 Startup 类，随后重新定义一个，并且类名为 MyStartup。

public class MyStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // ...
    }
    public void Configure(IApplicationBuilder app)
    {
        app.Run(async context =>
        {
            // 设置文本编码
            context.Response.ContentType = "text/html;charset=UTF-8";
            // 返回消息给客户端
            await context.Response.WriteAsync("这是一个 Web 应用");
        });
    }
}

app.Run 方法定义如何处理 HTTP 请求，本例中比较简单，直接向客户端回写一条文本消息。

步骤3：找到 Program 类的 Main 方法，删除项目模板生成的代码，替换为以下代码。

var builder = new WebHostBuilder()
                          .UseContentRoot(Directory.GetCurrentDirectory())
                          .UseKestrel()
                          .UseStartup();
            builder.Build().Run();

UseStartup 扩展方法指定定义好的类————MyStartup。

使用非预定义环境

【导语】

框架预定义的启动环境有三个：

（1）Development：在开发阶段使用。例如在此启动环境中，应用程序会显示详细的异常信息，以帮助调试。

（2）Staging：应用程序正式上线之前使用，类似于预览版本。

（3）Production：应用程序正式上线并投入生成时使用。例如此环境中应该禁止显示异常详细页面，禁用一些不必要的日志以提高性能等。

预定义的启动环境仅仅是个参考，开发人员可以根据实际的开发场景自定义启动环境的名称。在应用程序的任意代码中，随时可以通过访问 IHostingEnvironment.EnvironmentName 属性来检查应用程序当前所使用的环境，也可以调用 IsEnvironment 扩展方法进行判断。

【操作流程】

步骤1：新建一个空白的 ASP.NET Core Web 应用程序项目。

步骤2：定位到 Program 类下的 Main 方法，删除项目模板生成的代码，并输入以下代码。

var builder = new WebHostBuilder()
    .UseEnvironment("Preview")
    .UseKestrel()
    .UseUrls("http://localhost:6000")
    .UseContentRoot(Directory.GetCurrentDirectory())
    .UseStartup();
var host = builder.Build();
host.Run();

UseEnvironment 扩展方法用于设置应用程序的启动环境，此处使用了自定义名称“Preview”。

步骤3：Startup 类的 Configure 方法支持依赖注入，因此可以声明 IHostingEnvironment 类型的参数以接收注入，随后可以根据引用程序的运行环境的不同，向客户端返回不同的消息。

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html;charset=UTF-8";
        string responseMessage = null;
        if(env.IsEnvironment("Preview"))
        {
            responseMessage = "应用目前仍处于预览阶段";
        }
        else
        {
            responseMessage = "应用已正式上线";
        }
        await context.Response.WriteAsync(responseMessage);
    });
}

步骤4：运行应用程序，并从浏览器中访问对应的 URL。由于设置的启动环境为 Preview，因此浏览器中显示“应用目前仍处于预览阶段”。

PS：Startup类可以根据不同的环境来进行匹配，匹配方案有两种：

（1）类型匹配，即通过 Startup 类的命名来于环境匹配。例如，用于开发环境的 Startup 类可以使用命名为 StartupDevelopment，用于生产环境则可以命名为StartupProduction。命名格式为：{EnvironmentName}。

（2）Startup 类不予环境匹配，而是使用约定方法于环境匹配。Configure 方法的命名格式为：Configure{EnvironmentName},例如 ConfigureDevelopment；ConfigureServices 方法的命名格式为：ConfigureServices{EnvironmentName},例如 ConfigureServicesDevelopment。

开发者不仅需要编写特定于环境的 Startup 类，还可以编写默认的 Startup 类，这样如果程序找不到于环境变量匹配的 Startup 类，还可以使用默认的 Startup 类（即不带有{EnvironmentName}标识的命名）。

总结

本文到这里就结束了，下一篇将介绍依赖注入和中间件的知识案例。