探索Asp net core3中的 项目文件、Program.cs和通用host（译）

Asp.net Core

引言

原文地址

在这篇博客中我将探索一些关于Asp.net core 3.0应用的基础功能——.csproj 项目文件和Program源文件。我将会描述他们从asp.net core 2.X在默认模版中是怎样改变的，以及探讨Aspnetcore3.0使用的Api的变化。

介绍

.Net core 3.0 会在九月23号的 NET Conf上发布，但现在已经有一个支持的预览版本（Preview 8）。最新的预览版本与最终发布版本不可能有太多的变化，所以现在是开始尝试和查看3.0增加的功能的好时机。

Net core 3.0主要的更新是把windows桌面应用运行了Net core 上，但是Asp Net core 也增加了很多东西。也许最大的新特性就是服务端Blazor(我个人最感兴趣的是客户端的版本，但是现在还不可用)，但是也有一些迭代的改变和新特性加入了Asp Net Core。

在这篇博客中，我将探索一些关于非常 “基础” 的更新。

如果你打算把Asp net Core 2.X 软件迁移到3.0 ，一定要查阅迁移指南

在这篇博客中，当你创建一个新的Asp Net core应用时，比如 你用dotnet new webapi，我将探索.csproj 文件和Program.cs文件。在文章的最后，我将比较StartUp文件相对于2.X版本是怎样变化的，以及Asp Net core 中使用中的模版有什么不同（比如 web，webapi，mvc）

新项目文件与共享框架的变化

当你创建完一个新的Asp Net core项目，然后打开.csproj文件，它基本上是如下的样子：

1
2
3
4
5
6
7
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

</Project>

如果你与Asp net core 2.X的项目文件做比较，主要有如下的相同点和不同点

  • <TargetFramework> 不再是netcoreapp2.1或者2.2 ，而是netcoreapp3.0了，这是因为我们把目标框架2.1/2.2 替换成了3.0
  • <Project> 元素仍然是 Microsoft.Net.Sdk.Web，虽然已经更新成了ASP.NET Core 3.0,但是你的项目文件中的语法仍然是没有变化
  • Microsoft.AspNetCore.App meta 包已经不存在。

这里的最后一个有意思的变更。在我之前的博客中提到，在Asp Net core2.X你引用一个名叫Microsoft.AspNetCore.App的共享框架元数据包。这个共享框架提供了大量的好处，比如避免你在你的应用中手动安装所有的独立的程序包以及允许你使用 运行时的向前滚动更新的特性。

在Asp Net core3.0中，微软已经不再以Nuget元数据包的形式发布这个共享框架，也不存在3.0.0版本的Microsoft.AspNetCore.App。这个共享框架仍然和以前一样通过Net core 安装，但是在3.0中你的使用略有不同。

在Asp Net core2.X 中，为了引用这个共享框架，你会添加如下代码到你的项目文件中：

1
2
3
<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

相反，在3.0中你要使用 <FrameworkReference> 元素

1
2
3
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

“但是停一下”，你说：“为什么我的Asp Net Core 项目文件没有这个？”
这是个好问题，答案是 Microsoft.Net.Sdk.Web 默认包含了。

不再有用于共享框架组件的包

在3.0中另外一个最大的变更是你不再需要独立安装共享框架的其他部分的Nuget程序包了。例如，在Asp Net Core 2.X中，你可以用 像 Microsoft.AspNetCore.Authentication或Microsoft.AspNetCore.Authentication这样的独立的程序包来替换依赖于整个框架的程序包：

1
2
3
4
<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.Authentication" Version="2.1.0"/>
  <PackageReference Include="Microsoft.AspNetCore.Identity" Version="2.1.0"/>
</ItemGroup>

这通常对库最有用，因为应用程序总是需要依赖于共享框架。然而，在 Net Core3.0中，这一切都不可能了。这些Nuget包不会在发布了。相反，如果你需要在你的项目中引用其中的类库，你必须添加这个 <FrameworkReference> 元素到你的项目中

例如EF Core和social authentication providers 这些程序包中另外一个需要注意的事情是它们也不再是共享框架的一部分了，如果你需要使用这些程序包，你必须手动从nuget上安装到你的项目中。

对于这些程序包的完整清单，查阅这个Github issue

Program.cs 文件从 2.X到 3.0的变化

Asp Net Core 3.0中的Proram.cs文件第一眼看上去与2.X版本的非常相似。但是已经有许多类型发生了改变，这是因为在Net Core 3.0中，Asp Net Core为了运行在通用host上已经进行了重新构建,使用独立的Web Host已经被替代。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

通用Host是从2.1版本被发布的，这是个非常好的想法，但是我发现关于它的各种问题,主要问题是它为类库产生了太多的工作,值得庆幸的是，3.0中的这一变化应该可以解决这些问题。

很大程度上，这个变化产生的最终结果是和你过去使用的Net Core2.X版本基本相似，但是用于配置你的app的全部配置的方法WebHost.CreateDefaultBuilder() 被替换成了两个逻辑步骤，这个两个独立的方法叫做：

  • Host.CreateDefaultBuilder() ，负责配置你的app配置、日志以及依赖注入容器

  • IHostBuilder.ConfigureWebHostDefaults() ,负责为经典的Asp Net Core 应用添加所需要的所有东西，比如：配置Kestrel和使用一个 Startup.cs用于配置你的DI容器和中间件管道

通用Host builder

正如我之前说的那样，通用Host为Asp Net core 3.0的构建提供了基础。它同样也提供了你先前在Asp Net core应用中使用的基础性的Microsoft.Extensions.* 元素，比如：日志、配置和依赖注入。

下面的代码是一个简化版本的 Host.CreateDefaultBuilder() 方法。它和2.X版本的 WebHost.CreateDefaultBuilder() 作用一样。但是我会简短说一下值得关注的变化。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
public static IHostBuilder CreateDefaultBuilder(string[] args)
{
    var builder = new HostBuilder();

    builder.UseContentRoot(Directory.GetCurrentDirectory());
    builder.ConfigureHostConfiguration(config =>
    {
        // Uses DOTNET_ environment variables and command line args
    });

    builder.ConfigureAppConfiguration((hostingContext, config) =>
    {
        // JSON files, User secrets, environment variables and command line arguments
    })
    .ConfigureLogging((hostingContext, logging) =>
    {
        // Adds loggers for console, debug, event source, and EventLog (Windows only)
    })
    .UseDefaultServiceProvider((context, options) =>
    {
        // Configures DI provider validation
    });

    return builder;
}

简而言之，这个方法与2.X版本的不同点如下：

  • Hosting配置使用以 DOTNET_ 为前缀的环境变量
  • Hosting配置使用命令行变量
  • 增加了 EventSourceLogger 和 EventLogLogger 日志提供者
  • 可以选择使用ServiceProvider验证功能
  • 没有关于Web Hosting 的特定配置

第一个有意思的地方就是Host配置是如何设置的。对于Web Host而言，默认使用以 ASPNETCORE_ 为前缀的环境变量作为配置。所以设置ASPNETCORE_ENVIRONMENT 环境变量将会设置 Environment 配置的值。对于 通用Host来说，这个前缀现在是DOTNET_ ,和传给应用运行时的任意命令行参数。

这个host配置起的作用好比是决定你的应用运行在什么的主机环境，host配置与你应用配置（与IOptions接口一起使用的配置）是隔离开来的。

配置你的app设置的方法 ConfigureAppConfiguration() 与2.X相比是没有变化的，所以它仍然使用appsettings.json文件、appsetting.ENV.json风格文件、用户机密数据、环境变量以及命令行参数。

通用Host的日志部分已经在3.0进行了扩展。它仍旧通过你的app配置来配置日志等级过滤器,以及添加控制台和Debug日志提供者。然而它同样也添加来事件源日志提供者，事件源日志用于和像windows上的ETW、Linux上的LTTng这样的系统日志进行交互。另外，添加一个Event Log provider，只能在windows才会把日志信息写入Windows Event Log。

最后，当你的app运行在开发环境时，通用Host配置依赖注入容器的目的是它会验证范围（Scopes），这个操作和2.X一样。这旨在抓取捕获的依赖关系的实例，在这些实例中，你将一个范围（Scopes）的服务注入到单例服务中。在3.0中，通用Host通用能启动 ValidateOnBuild 的功能，我将会在下一篇博客中讲到。

通用Host一个关键的点是他是通用的，它和Asp Net core 或者Http 工作负载没有任何关联。你可以像经典的Asp Net core 应用一样把通用Host作为你的控制台app或者其他长运行服务的基石。在3.0中你只需要在你的Asp net core 层的顶部增加一个 ConfigureWebHostDefaults() 就可以搞定。

用ConfigureWebHostDefaults恢复Asp Net core功能

这篇博客已经很长了，所以在这里我不想深入挖掘太多的细节，但是，对于添加Asp Net core “层”到 通用Host上面而言，ConfigureWebHostDefaults扩展方法是非常有用的。就简单层面而言，调用这个方法会使Kestrel web 服务添加到这个host上面，但是这里面也存在了大量的其他的改变。下面是关于这个方法提供内容概览,(包含了GenericWebHostBuilder提供的特性)

  • 为Host 配置添加了 ASPNETCORE_ 前缀的环境变量（除了 DOTNET_ 前缀的变量和命令行参数）
  • 增加了 GenericWebHostService ，这是一个IHostedService的实现，它通常运行在Asp Net core服务上，这是一个主要的特性，这个特性为Asp Net core 复用通用Host提供了可能。
  • 增加了一个额外的app配置源，在RazorUI类库中，这个 StaticWebAssetsLoader 与静态文件（css/js）共同发挥作用。
  • 使用默认Kestrel配置（与2.X一样）
  • 增加 HostFilteringStartupFilter (和2.0一样)
  • 增加 ForwardedHeadersStartupFilter ,如果 ForwardedHeaders_Enabled 配置值是true，例如，如果ASPNETCORE_FORWARDEDHEADERS_ENABLED 环境变量的值是true。
  • 启动windows上的IIS集成
  • 增加一个端点路由到DI容器中

大部分东西是和Asp net core2.x相同的，不同的地方是：app作为一个IHostService运行的基础设施、端点路由和ForwardedHeadersStartupFilter ,其中端点路由在3.0是全局启用的（不再像2.X局限于MVC/Razor页面了）

ForwardedHeadersStartupFilter 在1.0已经出现了，当你的app运行在代理后面会用到它，是为了确保你的应用能处理SSL-负载和生成正确的URL。这么设计的目的是你能仅仅通过设置一个环境变量去配置一个使用 X-Forwarded-For 和 X-Forwarded-Proto 请求头的中间件。

总结

在这篇博客中我深挖了从Asp Net Core2.X到3.0中的仅仅两个文件——.csproj文件和Program.cs文件的变化。从表面上看，者仅仅是一些细微的变化，所有从2.X移植到3.0应该不会太难。这是天真地掩盖了其中的巨大的变化——共享框架的明显的变化，以及Asp Net core 已经在通用Host上重建了。

我认为大家遇到的最大的问题是Nuget 程序包的差异——一些app将要必须移除Asp Net Core 程序包的引用，同时要明确地引用其他的程序包。尽管解决这个问题是不太难，但是它会对不熟悉这个变化的用户带来困惑，所以应该第一时间审查这些变化

文章目录
  1. 1. 引言
  2. 2. 介绍
  3. 3. 新项目文件与共享框架的变化
  4. 4. 不再有用于共享框架组件的包
  5. 5. Program.cs 文件从 2.X到 3.0的变化
  6. 6. 通用Host builder
  7. 7. 用ConfigureWebHostDefaults恢复Asp Net core功能
  8. 8. 总结
|