《ASP.NET Core 6框架揭秘》实例演示[02]：基于路由MVC和gRPC的应用开发

Posted 2022-07-28 dotNET跨平台

ASP.NET Core可以视为一种底层框架，它为我们构建出了基于管道的请求处理模型，这个管道由一个服务器和多个中间件构成，而与路由相关的EndpointRoutingMiddleware和EndpointMiddleware是两个最为重要的中间件。MVC和gRPC开发框架就建立在路由基础上。本篇提供了四个实例用来演示如何利用路由、MVC和gRPC来开发API/APP。[本文节选《ASP.NET Core 6框架揭秘》第1章]

[113]路由的应用（源代码）
[114]开发MVC API（源代码）
[115]开发MVC APP（源代码）
[116]开发gRPC API（源代码）

[113]路由的应用

ASP.NET Core的路由是由EndpointRoutingMiddleware和EndpointMiddleware这两个中间件实现的，在所有预定义的中间件类中，这应该算是最重要的两个中间件了，因为不仅仅是MVC和gRPC框架建立在路由系统之上，后面介绍的Dapr.NET针对发布订阅和Actor编程模式也是如此。如下面的代码片段所示，我们在利用WebApplicationBuilder将代表承载应用的WebApplication对象构建出来之后，并没有注册任何的中间件，而是调用它的MapGet扩展方法注册了一个指向路径“/greet”的路由终结点（Endpoint）。该终结点的处理器是一个指向Greet方法的委托，意味着请求路径为“/greet”的GET请求会路由到这个终结点，并最终调用这个方法进行处理。

using App;
var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddSingleton<IGreeter, Greeter>()
    .Configure<GreetingOptions>(builder
        .Configuration.GetSection("greeting"));
var app = builder.Build();
app.MapGet("/greet", Greet);
app.Run();static string Greet(IGreeter greeter) 
    => greeter.Greet(DateTimeOffset.Now);

ASP.NET Core的路由系统的强大之处在于，我们可以使用任何类型的委托作为注册终结点的处理器，路由系统在调用处理器方法之前会“智能地”提取相应的数据初始化每一个参数。当方法执行之后，它还会针对我们具体返回的对象来对请求实施响应。对于我们提供的Greet方法来说，路由系统在调用它之前会利用依赖注入容器提供作为参数的IGreeter对象。由于返回的是一个字符串，文本经过编码后会直接作为响应的主体内容, 响应的内容类型（Content-Type）最终会被设置为“text/plain”。程序启动之后，如果我们利用浏览器请求“/greet”这个路径，针对当前时间解析出来的问候语会以图1的形式呈现出来。

图1 采用路由返回的问候

[114]开发MVC API

我们直接将上面演示的程序改写成MVC应用。MVC应用以Controller为核心，所有的请求总是指向定义在某个Controller类型中的某个Action方法。当应用接收到请求之后，会激活对应的Controller对象，并通过执行对应的Action方法来处理该请求。按照约定，合法的Controller类型必须是以“Controller”作为后缀命名的公共实例类型。我们一般会让定义的Controller类型派生自Controller基类以“借用”一些有用的API，但这不是必须的，比如下面定义的GreetingController就没有指定基类。

public class GreetingController

    [HttpGet("/greet")]    
    public string Greet(
    [FromServices] IGreeter greeter) 
    => greeter.Greet(DateTimeOffset.Now);

由于MVC框架是建立在路由系统之上的，定义在Controller类型中的Action方法最终会转换成一个或者多个注册到指定路径模板的终结点。对于定义在GreetingController类型中的Action方法Greet来说，我们通过标注的HttpGetAttrbute特性不仅为对应的路由终结点定义了针对HTTP方法的约束（该终结点仅限于处理GET请求），还同时指定了绑定的请求路径（“/greet”）。

依赖的服务可以直接注入到Controller类型中。具体来说，它支持两种注入形式，一种是注入到构造函数中，另一种则是直接注入到Action方法中。对于方法注入，对应参数上必须标注一个FromServiceAttribute特性。我们IGreeter对象就是采用这种方式注入注入到Greet方法中的。和路由系统针对返回对象的处理方式一样，MVC框架针对Action方法的返回值也会根据其类型进行针对性的处理。Greet方法直接返回的字符串会直接作为响应的主体内容，响应的内容类型（Content-Type）会被设置为“text/plain”。

在完成了针对GreetingController类型的定义之后，我们需要对入口程序进行如下的修改。如代码片段所示，在完成了针对IGreeter服务的注册和针对GreetingOptions配置选项的设置之后，我们调用同一个IServiceCollection对象的AddControllers扩展方法注册了与Controller相关服务的注册。在WebApplication对象被构建出来后，我们调用了它的MapControllers扩展方法将定义在所有Controller类型中的Action方法映射为对应的终结点。程序启动之后，如果我们利用浏览器请求“/greet”这个路径，我们依然会得到如图1的所示的输出结果。

using App;
var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddSingleton<IGreeter, Greeter>()
    .Configure<GreetingOptions>(builder
        .Configuration.GetSection("greeting"))
    .AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

[115]开发MVC APP

上面改造的MVC程序并没有涉及到视图，请求的响应内容是由Action方法直接提供的，现在我们利用视图来呈现最终响应的内容。由于上个例子调用IServiceCollection接口的AddControllers扩展方法只会注册Controller相关的服务，现在我们得将其换成AddControllersWithViews方法。顾名思义，新的扩展方法会将视图相关的服务添加进来。

using App;
var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddSingleton<IGreeter, Greeter>()
    .Configure<GreetingOptions>(builder
        .Configuration.GetSection("greeting"))
    .AddControllersWithViews();
var app = builder.Build();
app.MapControllers();
app.Run();

我们对GreetinigController进行了改造。如下面的代码片段所示，我们让它继承Controller这个基类。Action方法Greet的返回类型改为IActionResult接口，具体返回的是通过View方法创建的代表默认视图（针对当前Action方法）的ViewResult对象。在Action方法返回之前，它还利用对ViewBag的设置将当前时间传递到呈现的视图中。

public class GreetingController : Controller

    [HttpGet("/greet")]    
    public IActionResult Greet()
    
        ViewBag.Time = DateTimeOffset.Now;        
        return View();
    

ASP.NET Core MVC采用Razior视图引擎，视图被定义成一个后缀名为.cshtml的文件，这是一个按照Razor语法编写的静态HTML和动态C#代码动态交织的文本文件。由于上面为了呈现试图调用的View方法没有指定任何参数，所以视图引擎会根据当前Controller的名称（“Greeting”）和Action的名称（“Greet”）去定位定义目标视图的.cshtml文件。为了迎合默认的视图定位规则，我们需要采用Action的名称来命名创建的视图文件（Greet.cshtml），并将其添加到“Views/Greeting”目录下。

@using App
@inject IGreeter Greeter;
<html>
    <head>
        <title>Greeting</title>
    </head>
    <body>
        <p>@Greeter.Greet((DateTimeOffset)ViewBag.Time)</p>
    </body>
</html>

上面这个代码片段就是添加的视图文件（Views/Greeting/Greet.cshtml）的内容。总体来说，这是一个HTML文档，除了在主体部分呈现的问候语文本（前置的@字符定义动态执行的C#表达式）是根据指定时间动态解析出来的，其他内容则均为静态的HTML。我们借助@inject指令将依赖的IGreeter对象以属性的形式注入进来，并且将属性名称设置为Greeter，所以我们可以在视图中直接调用它的Greet方法得到呈现的问候语。调用Greet方法指定的时间是GreetingController利用ViewBag传递过来的，所以我们可以直接利用它将其提取出来。程序启动之后，如果我们利用浏览器请求“/greet”这个路径，虽然浏览器也会呈现出相同的文本（如图2所示），但是响应的内容是完全不同的。之前响应的仅仅是内容类型为“text/plain”的单纯文本，现在响应则是一份完整的HTML文档，内容类型为“text/html”。

图2　以试图形式返回的问候

[116]开发gRPC API

虽然Vistual Studio提供了创建gRPC的项目模板，该模板提供的脚手架会自动为我们创建一系列的初始文件，同时也会对项目做一些初始设置，但这反而是笔者不想要的，至少是不希望在这里使用这个模板。和前面一样，我们希望演示的实例只包含最本质和必要的元素，所以我们选择在一个空的解决方案上构建gRPC应用。

图3 gRPC解决方案

如图3所示，我们在一个空的解决方案上添加了三个项目。Proto是一个空的类库项目，我们将会使用它来存放标准的Proto Buffers消息和gRPC服务的定义；Server是一个空的ASP.NET Core应用，gRPC服务的实现类型就放在这里，它同时也是承载gRPC服务的应用。Client是一个控制台程序，我们用它来模拟调用gRPC服务的客户端。gRPC是语言中立的远程调用框架，gRPC服务契约使用到的数据类型都采用标准的定义方式。具体来说，gRPC传输的数据采用Proto Buffers协议进行序列化，Proto Buffers采用高效紧凑的二进制编码。我们将用于定义数据类型和服务的Proto Buffers文件定义在Proto项目中，在这之前我们需要为这个空的类库项目添加针对“Grpc.AspNetCore”这个NuGet包的引用。

不再使用简单的“Hello World”，现在我们为演示的gPRC服务指定另一种稍微“复杂”一点的应用场景——用它来完成简单的加、减、乘、除运算。我们在Proto项目中添加一个名为Calculator.proto的文本文件，并在其中以如下的形式将Calculator这个rGPC服务定义出来。如代码片段所示，这个服务包含四个操作，它们的输入和输出都被定义成Proto Buffers消息。作为输入的InputMessage消息包含两个整型的数据成员（表示运算的两个操作数）。返回的OutpuMessage消息除了通过result表示计算结果外，还具有status和error两个成员，前者表示计算状态（成功还是失败），后者提供计算失败时的错误消息。

syntax = "proto3";
option csharp_namespace = "App";

 service Calculator 
   rpc Add (InputMessage) returns (OutpuMessage);
   rpc Substract (InputMessage) returns (OutpuMessage);
   rpc Multiply (InputMessage) returns (OutpuMessage);
   rpc Divide (InputMessage) returns (OutpuMessage);
 

 message InputMessage 
   int32 x = 1;
   int32 y = 2;
 

 message OutpuMessage 
   int32 status = 1;
   int32 result = 2;
   string error = 3;
 

创建的Calculator.proto文件无法直接使用，我们需要利用内置的代码生成器将它转换成.cs代码。具体的作为很简单，我们只需要在Visual Studio的解决方案窗口中右键选择这个文件，打开如图4所示的属性对话框。我们在Build Action下拉列表中选择“Protobuf compiler”选项，同时在gRPC Stub Classes下拉列表中选择“Client and Server”。

图4 Calculator.proto文件属性对话框

做了这样的设置之后，在任何时对Calculator.proto文件所作的改变都将触发代码的自动生成，具体生成的.cs文件会自动保存在obj目录下。由于在gRPC Stub Classes下拉列表中选择了“Client and Server”选项，所以它不仅会生成服务端用来定义服务实现类型的Stub类，还会生成客户端用来调用服务的Stub类。上面以可视化形式所作的设置最终会体现在项目文件（Proto.csproj）上，所以我们直接修改此文件也可以达到相同的目的，如下所示的就是这个文件的完整内容。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <None Remove="Calculator.proto" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.40.0" />
  </ItemGroup>
  <ItemGroup>
    <Protobuf Include="Calculator.proto" />
  </ItemGroup>
</Project>

Proto项目中的Calculator.proto文件仅仅是按照标准的形式定义的“服务契约”，我们需要在Server项目中定义具体的实现类型。在添加了针对Proto项目的引用之后，我们定义了如下这个名为CalculatorService的gRPC服务实现类型。如代码片段所示，我们让CalculatorService类型继承自一个内嵌于Calculator中的CalculatorBase类型，这个Calculator类型就是根据Calculator.proto生成的一个类型。

public class CalculatorService : Calculator.CalculatorBase

    private readonly ILogger _logger;
    public CalculatorService(ILogger<CalculatorService> logger) 
        => _logger = logger;

    public override Task<OutpuMessage> Add(
        InputMessage request,  ServerCallContext context) 
        => InvokeAsync((op1, op2) => op1 + op2, request);
    public override Task<OutpuMessage> Substract(
        InputMessage request,    ServerCallContext context) 
        => InvokeAsync((op1, op2) => op1 - op2, request);
    public override Task<OutpuMessage> Multiply(
        InputMessage request,     ServerCallContext context) 
        => InvokeAsync((op1, op2) => op1 * op2, request);
    public override Task<OutpuMessage> Divide(
       InputMessage request,     ServerCallContext context) 
       => InvokeAsync((op1, op2) => op1 / op2, request);

    private Task<OutpuMessage> InvokeAsync(
       Func<int, int, int> calculate,     InputMessage input)
    
        OutpuMessage output;
        try
        
            output = new OutpuMessage 
                Status = 0, Result = calculate(input.X, input.Y) ;
        
        catch (Exception ex)
        
            _logger.LogError(ex, "Calculation error.");
            output = new OutpuMessage 
                Status = 1, Error = ex.ToString() ;
        
        return Task.FromResult(output);
    

Calculator.proto文件为Calcultor服务定义的四个操作会转换成CalculatorBase类型中对应的虚方法，我们按照上面的方式重写了它们。在完成了针对gRPC服务实现类型的定义之后，我们需要对承载它的入口程序定义编写如下的代码。由于gRPC采用HTTP2传输协议，所以在利用WebApplicationBuilder的WebHost属性得到对应的IWebHostBuilder对象，我们调用其ConfigureKestrel扩展方法让默认注册的Kestrel服务器监听的终结点默认采用HTTP2协议。gRPC相关的服务通过调用IServiceCollection接口的AddGrpc扩展方法进行注册。由于gRPC也是建立在路由系统之上的，定义在服务中的每个操作最终也会转换成相应的路由终结点，这些终结点的生成和注册是通过调用WebApplication对象的MapGrpcService<TService>扩展方法完成的。

using App;
using Microsoft.AspNetCore.Server.Kestrel.Core;
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(kestrel 
    => kestrel.ConfigureEndpointDefaults( endpoint 
    => endpoint.Protocols =  HttpProtocols.Http2));
builder.Services.AddGrpc();
var app = builder.Build();
app.MapGrpcService<CalculatorService>();
app.Run();

Calculator.proto文件生成的代码包含用来调用对应gRPC服务的Stub类，所以模拟客户端的Client项目也需要添加对Proto项目的引用。在此之后，我们可以编写如下的程序调用gRPC服务完成四种基本的数学运算。

using App;
 using Grpc.Core;
 using Grpc.Net.Client;

 using var channel = GrpcChannel
    .ForAddress("http://localhost:5000");
 var client = new Calculator.CalculatorClient(channel);
 var inputMessage = new InputMessage  X = 1, Y = 0 ;

 await InvokeAsync(input => client
    .AddAsync(input), inputMessage, "+");
 await InvokeAsync(input => client
    .SubstractAsync(input), inputMessage, "-");
 await InvokeAsync(input => client
    .MultiplyAsync(input), inputMessage, "*");
 await InvokeAsync(input => client
    .DivideAsync(input), inputMessage, "/");

 static async Task InvokeAsync(
    Func<InputMessage, AsyncUnaryCall<OutpuMessage>> invoker,  
    InputMessage input, string @operator)
 
     var output = await invoker(input);
     if (output.Status == 0)
     
         Console.WriteLine(
            $"input.X@operatorinput.Y=output.Result");
     
     else
     
         Console.WriteLine(output.Error);
     
 

如上面的代码片段所示，我们通过调用GrpcChannel类型的静态方法ForAddress针对gRPC服务的地址“http://localhost:5000”创建了一个GrpcChannel对象，该对象表示与服务进行通信的“信道（Channel）”。我们利用它创建了一个CalculatorClient对象作为调用gRPC服务的客户端或者代理，CalculatorClient类型同样是内嵌在生成的Calculator类型中。最终我们利用这个代理完成了针对四种基本运算的服务调用，具体的gRPC调用实现在InvokeAsync这个本地方法中。接下来我们以命令行的方式先后启动Server和Client应用，客户端和服务端控制台上会呈现出如图5所示的输出结果。由于我们传入的参数分别为1和0，所以除了除法运算，其它三此调用都会返回成功的结果，针对除法的调用则会将错误信息呈现出来。由于CalculatorService进行了异常处理，并且将异常信息以日志的形式记录了下来，所以错误信息也输出到了服务端的控制台上。

图5 gRPC应用的承载与调用