[翻译] ASP.NET Core 3.0 的新增功能

目录

• asp.net core 3.0 的新增功能
  • blazor
  • grpc
  • signalr
  • 新的 razor 指令
  • 证书与 kerberos 身份验证
  • • startup 构造函数注入的更改
  • kestrel
  • 默认启用 http/2
  • httpcontext 上的管道
  • iis 中改进了的错误报告
  • 服务角色服务和辅助角色 sdk
  • forwarded 标头中间件的改进
  • asp.net core 3.0 仅可在 .net core 3.0 上运行
  • 使用 asp.net core 共享框架
  • 从 asp.net core 共享框架中移除的程序集

asp.net core 3.0 的新增功能

全文翻译自微软官方文档英文版 what's new in asp.net core 3.0

本文重点介绍了 asp.net core 3.0 中最重要的更改，并提供相关文档的连接。

blazor

blazor 是 asp.net core 中的一个新的框架，用于使用 .net 构建交互式的客户端 web ui：

• 使用 c# 而不是 javascript 创建丰富的交互式 ui。
• 共享用 .net 编写的服务器端和客户端应用程序逻辑。
• 将 ui 渲染为 html 和 css，以提供广泛的浏览器支持，包括移动浏览器。

blazor 框架支持的场景：

• 可重用的 ui 组件（razor 组件）
• 客户端路由
• 组件布局
• 对依赖注入的支持
• 表单与验证
• 使用 razor 类库构建组件库
• javascript 互操作

有关更多信息，请参阅：asp.net core 中的 blazor 简介。

blazor server

blazor 将组件渲染逻辑与 ui 更新的逻辑进行了解耦。blazor server 支持在服务器上的 asp.net core 应用程序中承载 razor 组件。ui 的更新通过一个 signalr 连接进行处理。blazor server 在 asp.net core 3.0 中受支持。

blazor webassembly （预览）

blazor 应用程序也可以使用基于 webassembly 的 .net 运行时直接在浏览器中运行。blazor webassembly 在 asp.net core 3.0 中处于预览状态，且不受支持。未来的 asp.net core 版本将支持 blazor webassembly。

razor 组件

blazor 应用程序是由组件 (components) 构建而成的。组件是自包含的用户界面元素，例如页面、对话框或者表单等。组件是普通的 .net 类，用于定义 ui 呈现逻辑和客户端事件处理程序。您可以创建没有 javascript 的富交互式 web 应用程序。

blazor 中的组件通常使用 razor 语法编写，它是 html 和 c# 的自然融合。razor 组件与 razor pages（页面）和 mvc 视图 (view) 相似，因为它们都使用 razor。与基于“请求-响应”模型的页面与视图不同，组件专门用于处理 ui 合成。

grpc

grpc：

• 是一种流行的高性能 rpc（远程过程调用）框架。
• 为 api 开发提供了一种“契约优先“的方式。
• 使用各种现代的技术，例如：
  • 通过 http/2 传输
  • 使用 protocol buffers 作为接口描述语言
  • 二进制序列化格式
• 提供以下功能：
  • 身份验证
  • 双向的数据流与流程控制
  • 取消与超时

asp.net core 3.0 中的 grpc 功能包括：

• grpc.aspnetcore — 一个用于承载 grpc 服务的 asp.net core 框架。asp.net core 上的 grpc 能够与日志记录、依赖注入 (di) 身份验证和授权等标准的 asp.net core 功能集成在一起。
• grpc.net.client — 一个面向 .net core，构建在 httpclient 上的 grpc 客户端。
• grpc.net.clientfactory — 用于将 grpc 客户端与 httpclientfactory 集成。

有关更多信息，参见：asp.net core 上 grpc 的简介

signalr

请参见更新 signal 代码以获取迁移说明。signalr 现在使用 system.text.json 来序列化/反序列化 json 消息。有关还原为基于 newtonsoft.json 的序列化程序的说明，请参阅切换到 newtonsoft.json。

在 signalr 的 javascript 和 .net 客户端中，添加了对自动重新连接的支持。默认情况下，客户端尝试自动重新连接，并在 2, 10 和 30 秒后（如有必要）重试。如果客户端成功重新连接，它将受到一个新的连接 id。自动重新连接是选择性加入的：

const connection = new signalr.hubconnectionbuilder()
    .withurl("/chathub")
    .withautomaticreconnect()
    .build();

可以通过传递基于毫秒的持续时间数组来指定重新连接间隔：

.withautomaticreconnect([0, 3000, 5000, 10000, 15000, 30000])
//.withautomaticreconnect([0, 2000, 10000, 30000]) 默认时间间隔

可以传入自定义实现以完全控制重新连接间隔。

如果在上次重新连接间隔之后重新连接失败，则：

• 客户端认为连接已离线。
• 客户端停止尝试重新连接。

为了在连接中断时提供 ui 反馈，signalr 客户端 api 已扩展为包括以下事件处理程序：

• onreconnecting: 为开发人员提供了禁用 ui 或告知用户该应用程序处于脱机状态的机会。
• onreconnected: 重新建立连接后，使开发人员有机会更新 ui。

以下代码在尝试连接时使用 onreconnecting 更新 ui：

connection.onreconnecting((error) => {
    const status = `connection lost due to error "${error}". reconnecting.`;
    document.getelementbyid("messageinput").disabled = true;
    document.getelementbyid("sendbutton").disabled = true;
    document.getelementbyid("connectionstatus").innertext = status;
});

以下代码在连接恢复时使用 onreconnected 更新 ui：

connection.onreconnected((connectionid) => {
    const status = `connection reestablished. connected.`;
    document.getelementbyid("messageinput").disabled = false;
    document.getelementbyid("sendbutton").disabled = false;
    document.getelementbyid("connectionstatus").innertext = status;
});

当 hub 方法需要授权时，signalr 3.0 及更高版本为授权处理程序提供自定义资源。该资源是 hubinvocationcontext 的实例。hubinvocationcontext 包括：

• hubcallercontext
• 正在调用的 hub 方法的名称。
• hub 方法的参数。

考虑以下聊天室应用程序示例，该应用程序允许通过 azure active directory 进行多个组织登录。 具有 microsoft 账户的任何人都可以登录聊天，但只有所属组织的成员可以禁止用户或查看用户的聊天记录。 该应用可以限制特定用户的某些功能。

public class domainrestrictedrequirement :
    authorizationhandler<domainrestrictedrequirement, hubinvocationcontext>,
    iauthorizationrequirement
{
    protected override task handlerequirementasync(
        authorizationhandlercontext context,
        domainrestrictedrequirement requirement,
        hubinvocationcontext resource)
    {
        if (context.user?.identity?.name == null)
        {
            return task.completedtask;
        }

        if (isuserallowedtodothis(
                resource.hubmethodname,
                context.user.identity.name))
        {
            context.succeed(requirement);
        }

        return task.completedtask;
    }

    private bool isuserallowedtodothis(string hubmethodname, string currentusername)
    {
        if (hubmethodname.equals("banuser",
            stringcomparison.ordinalignorecase))
        {
            return currentusername.equals(
                "[e-mail]",
                stringcomparison.ordinalignorecase);
        }

        return currentusername.endswith(
                "@jabbr.net",
                stringcomparison.ordinalignorecase));
    }
}

在前面的代码中，domainrestrictedrequirement 用作自定义 iauthorizationrequirement。由于传递了 hubinvocationcontext 资源，因此内部逻辑可以：

• 检查正在调用 hub 的上下文。
• 决定是否允许用户执行特定的 hub 方法。

可以使用策略名称来修饰各个 hub 方法，代码会在运行时进行检查。当客户端尝试调用各个 hub 方法时，domainrestrictedrequirement 处理程序将会运行并控制对方法的访问。基于 domainrestrictedrequirement 控制访问的方式：

• 所有已登录用户都可以调用 sendmessage 方法。
• 只有使用 @jabbr.net 电子邮件地址登录的用户才能查看用户的历史记录。
• 只有 [e-mail] 可以禁止用户进入聊天室。

[authorize]
public class chathub : hub
{
    public void sendmessage(string message)
    {
    }

    [authorize("domainrestricted")]
    public void banuser(string username)
    {
    }

    [authorize("domainrestricted")]
    public void viewuserhistory(string username)
    {
    }
}

创建 domainrestricted 策略可能涉及：

• 在 startup.cs 中添加新策略。
• 将自定义的 domainrestrictedrequirement 需求作为参数提供。
• 使用授权中间件注册 domainrestricted。

services
    .addauthorization(options =>
    {
        options.addpolicy("domainrestricted", policy =>
        {
            policy.requirements.add(new domainrestrictedrequirement());
        });
    });

signalr hub 使用。signalr hub 连接先前已显式地完成：

app.usesignalr(routes =>
{
    routes.maphub<chathub>("hubs/chat");
});

在以前的版本中，开发人员需要在各个不同的位置启用控制器、razor 页面和 signalr hub。显式的连接导致一系列几乎相同的路由片段：

app.usesignalr(routes =>
{
    routes.maphub<chathub>("hubs/chat");
});

app.userouting(routes =>
{
    routes.maprazorpages();
});

signalr 3.0 hub 可以通过终结点路由进行路由。使用终结点路由，通常可以在 userouting 中配置所有的路由：

app.userouting(routes =>
{
    routes.maprazorpages();
    routes.maphub<chathub>("hubs/chat");
});

asp.net core 3.0 signalr 添加了：

客户端到服务器的流。通过客户端到服务器的流传输，服务器端方法可以采用 iasyncenumerable<t> 或者 channelreader<t> 的实例。在以下 c# 实例中，hub 上的 uploadstream 方法将从客户端接收字符串流：

public async task uploadstream(iasyncenumerable<string> stream)
{
    await foreach (var item in stream)
    {
        // 处理流中的内容
    }
}

.net 客户端应用程序可以将一个 iasyncenumerable<t> 或者 channelreader<t> 的实例作为上述 uploadstream hub 方法的 stream 参数进行传递。

在 for 循环完成，且本地函数退出之后，将流完成发送(after the for loop has completed and the local function exits, the stream completion is sent)：

async iasyncenumerable<string> clientstreamdata()
{
    for (var i = 0; i < 5; i++)
    {
        var data = await fetchsomedata();
        yield return data;
    }
}

await connection.sendasync("uploadstream", clientstreamdata());

javascript 客户端应用将 signalr subject (或者一个 rxjs subject) 用于上述 uploadstream hub 方法的 stream 参数。

let subject = new signalr.subject();
await connection.send("startstream", "myasciiartstream", subject);

当 javascript 代码捕获到字符串并准备将其发送到服务器时，它可以使用 subject.next 方法来处理字符串。

subject.next("example");
subject.complete();

使用类似前面两个代码段的代码，可以创建实时流式传输体验。

新的 json 序列化

现在默认情况下，asp.net core 3.0 使用 system.text.json 进行 json 序列化：

• 异步读取和写入 json。
• 针对 utf-8 文本进行了优化。
• 通常会比 newtonsoft.json 具有更高的性能。

要将 json.net 添加到 asp.net core 3.0 请参阅添加基于 newtonsoft.json 的 json 格式支持。

新的 razor 指令

以下列表包含了新的 razor 指令：

• — @attribute 指令将给定属性应用于生成页面或者视图的类。例如：@attribute [authorize]。
• — @implements 指令为生成的类实现一个接口。例如：@implements idisposable。

证书与 kerberos 身份验证

证书身份验证要求：

• 配置服务器以接收证书。
• 在 startup.configure 中添加身份验证中间件。
• 在 startup.configureservices 中添加证书身份验证服务。

public void configureservices(iservicecollection services)
{
    services.addauthentication(
        certificateauthenticationdefaults.authenticationscheme)
            .addcertificate();
    // 其他服务配置已移除。
}

public void configure(iapplicationbuilder app, ihostingenvironment env)
{
    app.useauthentication();
    // 其他应用配置已移除。
}

证书身份验证的选项 (options) 提供以下功能：

• 接受自签名证书。
• 检查证书吊销。
• 检查提供的证书是否具有正确的使用标志。

默认的用户主体 (user principal) 是根据证书属性构建的。用户主体包含一个事件。通过相应该事件，可以补充或者替换该主体。有关更多信息，请参见在 asp.net core 中配置证书身份验证。

windows 身份验证 已扩展到了 linux 和 macos 上。在以前的版本中，windows 身份验证仅限于 iis 和 httpsys。在 asp.net core 3.0 中，kestrel 能够在 windows, linux 和 macos 上为加入了 windows 域的主机使用 negotiate（协商）, kerberos 和 ntlm。kestrel 对这些身份验证架构的支持由 microsoft.aspnetcore.authentication.negotiate nuget 包提供。与其他身份验证服务一样，在用用程序范围内配置身份验证，然后配置服务：

public void configureservices(iservicecollection services)
{
    services.addauthentication(negotiatedefaults.authenticationscheme)
        .addnegotiate();
    // 其他服务配置已移除。
}

public void configure(iapplicationbuilder app, ihostingenvironment env)
{
    app.useauthentication();
    // 其他应用配置已移除。
}

主机要求：

• windows 主机必须将 (spn) 添加到承载该应用程序的用户账户中。
• linux 和 macos 主机必须加入域。
  • 必须为 web 进程创建 spn。
  • 必须在主机上生成和配置。

有关更多信息，请参见在 asp.net core 中配置 windows 身份验证。

模板变更

web ui 模板（razor pages, 带有控制器和视图的 mvc）已删除以下内容：

• “cookie 同意” ui 不再包含在内。若要在 asp.net core 3.0 模板生成的应用程序中启用“cookie 同意”功能，请参阅 asp.net core 中的常规数据保护法规 (gdpr) 支持。
• 现在，脚本和相关的静态资产被作为本地文件引用，而不再使用 cdn。有关更多信息，请参见脚本和相关的静态资产现在被作为本地文件引用而不再使用 cdn (aspnet/aspnetcore.docs #14350)。

angular 模板已更新为使用 angular 8。

默认情况下，razor 类库 (rcl) 模板默认为用于 razor 组件开发。visual studio 中新的模板选项为页面和视图提供模板支持。在命令行中从模板创建 rcl 时，请传入 -support-pages-and-views 选项 (dotnet new razorclasslib -support-pages-and-views)。

通用主机

asp.net core 3.0 模板使用 .net 通用主机。以前的版本使用 webhostbuilder。使用 .net core 通用主机(hostbuilder)，可以更好地将 asp.net core 应用程序与其他非特定与 web 的服务器方案集成。有关更多信息，请参见 hostbuilder 替换 webhostbuilder。

主机配置

在发布 asp.net core 3.0 之前，带有 aspnetcore_ 前缀的环境变量会被加载，用于 web 主机的主机配置。在 3.0 中，addevironmentvariables 用于加载带有 dotnet_ 以前追的环境变量，以使用 createdefaultbuilder 进行主机配置。

startup 构造函数注入的更改

通用主机仅支持一下类型的 startup 构造函数注入：

• ihostenvironment
• iwebhostenvironment
• iconfiguration

仍然可以将所有服务以参数的形式直接注入 startup.configure 方法，参见 通用主机限制 startup 构造函数注入 (aspnet/announcements #353).

kestrel

• 为了迁移到通用主机，kestrel 配置已更新。在 3.0 中，kestrel 在 configurewebhostdefaults 提供的 web 主机构建器 (host builder) 上进行配置。
• 连接适配器 (connection adapter) 已从 kestrel 中删除，并由连接中间件代替 (connection middleware)。该中间件类似于 asp.net core 管道中的 http 中间件，但用于较低级别的连接。
• kestrel 传输层已在 connections.abstractions 中作为公共接口公开。
• 标头 (header) 和尾部 (trailer) 之间的歧义已通过将尾部标头 (trailing header) 移动到新的集合来解决。
• 同步 io api（例如 httprequest.body.read）是引起线程饥饿进而导致程序崩溃的常见原因。在 3.0 中，默认情况下 allowsynchronousio 被禁用。

有关更多信息，请参见kestrel - 从 asp.net core 2.2 迁移到 3.0。

默认启用 http/2

默认情况下，kestrel 中为 https 端点启用了 http/2。当操作系统支持时，对 iis 或者 http.sys 的 http/2 的支持将被启用。

请求计数器

hosting eventsource (microsoft.aspnetcore.hosting) 发出与传入请求有关的以下 eventcounter：

• requests-per-second
• total-requests
• current-requests
• failed-requests

终结点路由

终结点路由得到了增强，该路由使各种框架（例如 mvc）可以与中间件更好地协同工作：

• 中间件和终结点的顺序可以在 startup.configure 的请求处理管道中进行配置。
• 终结点和中间件与其他基于 asp.net core 的技术（例如运行状况检查）进行良好的编排。
• 终结点可以在中间件和 mvc 中实现各种策略，例如 cors 或者授权等。
• 过滤器和特性 (attribute) 可以被放置在控制器的方法上。

有关更多信息，请参见 asp.net core 中的路由。

运行状况检查

运行状况检查通过通用主机使用终结点路由。在 startup.configure 中，使用终结点 url 或者相对路径，在终结点构建器上调用 maphealthchecks：

app.useendpoints(endpoints =>
{
    endpoints.maphealthchecks("/health");
});

运行状况检查终结点可以：

• 指定一个或多个允许的主机/端口。
• 要求授权。
• 要求 cors。

有关更多信息，请参见以下文章：

• 运行状况检查 - 从 asp.net core 2.2 迁移到 3.0
• asp.net core 中的运行状况检查

httpcontext 上的管道

现在可以使用 system.io.pipelines api 读取请求正文并写入响应正文。httprequest.bodyreader 属性提供了一个 pipereader，可以用于读取请求正文；httpresponse.bodywriter 属性提供了一个 pipewriter，可以用于写入响应正文。httprequest.bodyreader 是 httprequest.body 流的相似物； httpresponse.bodywriter 是 httpresponse.body 流的相似物。

iis 中改进了的错误报告

现在，在 iis 中托管 asp.net core 应用程序时的启动错误会生成更丰富的诊断数据。这些错误会在适用的情况下使用堆栈跟踪，报告给 windows 事件日志。此外，所有的警告、错误和未处理的异常，都会记录到 windows 事件日志中。

服务角色服务和辅助角色 sdk

.net core 3.0 引入了新的辅助角色服务 (worker service) 应用模板。该模板是在 .net core 中编写长时间运行的服务的起点。

有关更多信息，请参见：

• 作为 windows 服务运行的 .net core 辅助角色 (.net core workers as windows services)
• 在 asp.net core 中使用托管服务实现后台任务
• 在 windows 服务中承载 asp.net core

forwarded 标头中间件的改进

在早期版本的 asp.net core 中，应用在部署到 azure linux 或者除 iis 之外的任何反向代理之后，调用 usehsts 和 usehttpsredirection 都是有问题的。转发 linux 和非 iis 反向代理的方案中介绍了以前版本的修复方式。

此场景已在 asp.net core 3.0 中修复。当 aspnetcore_forwardedheaders_enabled 环境变量设置为 true 时，主机将启用 forwarded 标头中间件。在 asp.net core 的容器镜像中，aspnetcore_forwardedheaders_enabled 已被设置为 true。

性能提升

asp.net core 3.0 包括许多改进，可以减少内存使用并提高吞吐量：

• 在将内置的依赖注入容器用于 scoped 服务时，减少内存的使用量。
• 减少整个框架的内存分配，包括中间件的各类场景和路由。
• 减少 websocket 连接的内存使用量。
• 减少 https 连接的内存使用量，并提高吞吐量。
• 新的、经过优化的、完全异步的 json 序列化器。
• 减少表单 (form) 解析的内存使用量，并提高吞吐量。

asp.net core 3.0 仅可在 .net core 3.0 上运行

从 asp.net core 3.0开始，.net framework 不再是受支持的目标框架。以 .net framework 为目标的项目可以继续通过使用 .net core 2.1 lts 版本在完全受支持的状态下运行。绝大多数与 asp.net core 2.1.x 相关的软件包，都将在 .net core 2.1 的三年长期支持期内获得支持。(most asp.net core 2.1.x related packages will be supported indefinitely, beyond the 3 year lts period for .net core 2.1.)

有关迁移的更多信息，请参见 将代码从 .net framework 移植到 .net core。

使用 asp.net core 共享框架

microsoft.aspnetcore.app 元包中包含的 asp.net core 3.0 共享框架 (shared framework) 不再需要项目文件中的显式 <packagereference /> 元素。在项目文件中使用 microsoft.net.sdk.web sdk 时，将自动引用共享框架：

<project sdk="microsoft.net.sdk.web">

从 asp.net core 共享框架中移除的程序集

从 asp.net core 3.0 共享程序集中移除的最值得注意的程序集是：

• newtonsoft.json (json.net)。要将 json.net 添加到 asp.net core 3.0，请参阅 添加基于 newtonsoft.json 的 json 格式支持。asp.net core 3.0 引入了 system.text.json 来读写 json。有关更多信息，请参阅本文档中新的 json 序列化。
• entity framework core

有关共享框架中所移除程序集的完整列表，请参阅 从 microsoft.aspnetcore.app 3.0 中移除的程序集。有关进行此修改的动机，更多信息请参阅microsoft.aspnetcore.app 在 3.0 中的破坏性变更 和 asp.net core 3.0 中的更改初探。