使用 ASP.NET Core 的 gRPC 服务

注意

此版本不是本文的最新版本。 对于当前版本,请参阅此文的 .NET 8 版本

警告

此版本的 ASP.NET Core 不再受支持。 有关详细信息,请参阅 .NET 和 .NET Core 支持策略。 对于当前版本,请参阅此文的 .NET 8 版本

重要

此信息与预发布产品相关,相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

对于当前版本,请参阅此文的 .NET 8 版本

本文档演示如何通过 ASP.NET Core 开始使用 gRPC 服务。

先决条件

开始使用 ASP.NET Core 中的 gRPC 服务

查看或下载示例代码如何下载)。

请参阅 gRPC 服务入门,获取关于如何创建 gRPC 项目的详细说明。

将 gRPC 服务添加到 ASP.NET Core 应用

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPC

Program.cs中:

  • gRPC 通过 AddGrpc 方法启用。
  • 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

若要查看翻译为非英语语言的代码注释,请在 此 GitHub 讨论问题中告诉我们。

ASP.NET Core 中间件和功能共享路由管道,因此可以将应用配置为提供其他请求处理程序。 其他请求处理程序(如 MVC 控制器)与已配置的 gRPC 服务并行工作。

服务器选项

gRPC 服务可由所有内置 ASP.NET Core 服务器托管。

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本。

有关为 ASP.NET Core 应用选择正确服务器的详细信息,请参阅 ASP.NET Core 中的 Web 服务器实现

Kestrel

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。 Kestrel 侧重于最佳性能和内存利用率,但它没有 HTTP.sys 中的某些高级功能,如端口共享。

Kestrel gRPC 终结点:

HTTP/2

gRPC 需要 HTTP/2。 适用于 ASP.NET Core 的 gRPC 验证 HttpRequest.ProtocolHTTP/2

Kestrel在大多数新式操作系统上支持 HTTP/2。 默认情况下,Kestrel 终结点配置为支持 HTTP/1.1 和 HTTP/2 连接。

TLS

用于 gRPC 的 Kestrel 终结点应使用 TLS 进行保护。 在开发环境中,当存在 ASP.NET Core 开发证书时,会在 https://localhost:5001 自动创建使用 TLS 进行保护的终结点。 不需要任何配置。 https 前缀验证 Kestrel 终结点是否正在使用 TLS。

在生产环境中,必须显式配置 TLS。 以下 appsettings.json 示例中提供了使用 TLS 进行保护的 HTTP/2 终结点:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

或者,可以在 Program.cs 中配置 Kestrel 终结点:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

有关使用 Kestrel 启用 TLS 的详细信息,请参阅 Kestrel HTTPS 终结点配置

协议协商

TLS 的用途不仅限于保护通信。 当终结点支持多个协议时,TLS 应用程序层协议协商 (ALPN) 握手可用于协商客户端与服务器之间的连接协议。 此协商确定连接是使用 HTTP/1.1 还是 HTTP/2。

如果在不使用 TLS 的情况下配置了 HTTP/2 终结点,则必须将终结点的 ListenOptions.Protocols 设置为 HttpProtocols.Http2。 如果没有 TLS,则无法使用具有多个协议(例如 HttpProtocols.Http1AndHttp2)的终结点,因为没有协商。 到不安全终结点的所有连接均默认为 HTTP/1.1,且 gRPC 调用会失败。

有关使用 Kestrel 启用 HTTP/2 和 TLS 的详细信息,请参阅 Kestrel 终结点配置

注意

macOS 不支持使用 .NET 8 之前版本的 ASP.NET Core gRPC 及 TLS。 使用 .NET 7 或更早版本时,在 macOS 上成功运行 gRPC 服务需要其他配置。 有关详细信息,请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用

IIS

Internet Information Services (IIS) 是一种灵活、安全且可管理的 Web 服务器,用于托管 Web 应用(包括 ASP.NET Core)。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 IIS 托管 gRPC 服务。

必须将 IIS 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅将 ASP.NET Core 与 IIS 上的 HTTP/2 配合使用

HTTP.sys

HTTP.sys 是仅在 Windows 上运行的适用于 ASP.NET Core 的 Web 服务器。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 HTTP.sys 托管 gRPC 服务。

必须将 HTTP.sys 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅 HTTP.sys Web 服务器 HTTP/2 支持

非 ASP.NET Core 项目中的主机 gRPC

ASP.NET Core gRPC 服务器通常从 gRPC 模板创建。 模板创建的项目文件使用 Microsoft.NET.SDK.Web 作为 SDK:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Microsoft.NET.SDK.Web SDK 值会自动添加对 ASP.NET Core 框架的引用。 该引用允许应用使用托管服务器所需的 ASP.NET Core 类型。

可以使用以下项目文件设置将 gRPC 服务器添加到 非 ASP.NET Core 项目:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

上面的项目文件可完成以下操作:

  • 不要使用 Microsoft.NET.SDK.Web 作为 SDK。
  • Microsoft.AspNetCore.App 添加框架引用。
    • 该框架引用允许非 ASP.NET Core 应用(例如 Windows 服务、WPF 应用或 WinForms 应用)使用 ASP.NET Core API。
    • 该应用现在可以使用 ASP.NET Core API 来启动 ASP.NET Core 服务器。
  • 添加 gRPC 要求:

有关使用 Microsoft.AspNetCore.App 框架引用的详细信息,请参阅使用 ASP.NET Core 共享框架

与 ASP.NET Core API 集成

gRPC 服务对 ASP.NET Core 功能(如依赖关系注入 (DI)日志记录)具有完全访问权限。 例如,服务实现可以通过构造函数从 DI 容器解析记录器服务:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

默认情况下,gRPC 服务实现可以解析具有任意生存期(单一实例、范围内或暂时)的其他 DI 服务。

解析 gRPC 方法中的 HttpContext

gRPC API 提供对某些 HTTP/2 消息数据(如方法、主机、标头和尾部)的访问权限。 访问是通过传递到每个 gRPC 方法的 ServerCallContext 参数进行的:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext 不提供对所有 ASP.NET API 中 HttpContext 的完全访问权限。 GetHttpContext 扩展方法提供对在 ASP.NET API 中表示基础 HTTP/2 消息的 HttpContext 的完全访问权限:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

其他资源

本文档演示如何通过 ASP.NET Core 开始使用 gRPC 服务。

先决条件

开始使用 ASP.NET Core 中的 gRPC 服务

查看或下载示例代码如何下载)。

请参阅 gRPC 服务入门,获取关于如何创建 gRPC 项目的详细说明。

将 gRPC 服务添加到 ASP.NET Core 应用

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPC

Program.cs中:

  • gRPC 通过 AddGrpc 方法启用。
  • 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

若要查看翻译为非英语语言的代码注释,请在 此 GitHub 讨论问题中告诉我们。

ASP.NET Core 中间件和功能共享路由管道,因此可以将应用配置为提供其他请求处理程序。 其他请求处理程序(如 MVC 控制器)与已配置的 gRPC 服务并行工作。

服务器选项

gRPC 服务可由所有内置 ASP.NET Core 服务器托管。

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本。

有关为 ASP.NET Core 应用选择正确服务器的详细信息,请参阅 ASP.NET Core 中的 Web 服务器实现

Kestrel

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。 Kestrel 侧重于最佳性能和内存利用率,但它没有 HTTP.sys 中的某些高级功能,如端口共享。

Kestrel gRPC 终结点:

HTTP/2

gRPC 需要 HTTP/2。 适用于 ASP.NET Core 的 gRPC 验证 HttpRequest.ProtocolHTTP/2

Kestrel在大多数新式操作系统上支持 HTTP/2。 默认情况下,Kestrel 终结点配置为支持 HTTP/1.1 和 HTTP/2 连接。

TLS

用于 gRPC 的 Kestrel 终结点应使用 TLS 进行保护。 在开发环境中,当存在 ASP.NET Core 开发证书时,会在 https://localhost:5001 自动创建使用 TLS 进行保护的终结点。 不需要任何配置。 https 前缀验证 Kestrel 终结点是否正在使用 TLS。

在生产环境中,必须显式配置 TLS。 以下 appsettings.json 示例中提供了使用 TLS 进行保护的 HTTP/2 终结点:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

或者,可以在 Program.cs 中配置 Kestrel 终结点:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

有关使用 Kestrel 启用 TLS 的详细信息,请参阅 Kestrel HTTPS 终结点配置

协议协商

TLS 的用途不仅限于保护通信。 当终结点支持多个协议时,TLS 应用程序层协议协商 (ALPN) 握手可用于协商客户端与服务器之间的连接协议。 此协商确定连接是使用 HTTP/1.1 还是 HTTP/2。

如果在不使用 TLS 的情况下配置了 HTTP/2 终结点,则必须将终结点的 ListenOptions.Protocols 设置为 HttpProtocols.Http2。 如果没有 TLS,则无法使用具有多个协议(例如 HttpProtocols.Http1AndHttp2)的终结点,因为没有协商。 到不安全终结点的所有连接均默认为 HTTP/1.1,且 gRPC 调用会失败。

有关使用 Kestrel 启用 HTTP/2 和 TLS 的详细信息,请参阅 Kestrel 终结点配置

注意

macOS 不支持使用 .NET 8 之前版本的 ASP.NET Core gRPC 及 TLS。 使用 .NET 7 或更早版本时,在 macOS 上成功运行 gRPC 服务需要其他配置。 有关详细信息,请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用

IIS

Internet Information Services (IIS) 是一种灵活、安全且可管理的 Web 服务器,用于托管 Web 应用(包括 ASP.NET Core)。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 IIS 托管 gRPC 服务。

必须将 IIS 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅将 ASP.NET Core 与 IIS 上的 HTTP/2 配合使用

HTTP.sys

HTTP.sys 是仅在 Windows 上运行的适用于 ASP.NET Core 的 Web 服务器。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 HTTP.sys 托管 gRPC 服务。

必须将 HTTP.sys 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅 HTTP.sys Web 服务器 HTTP/2 支持

非 ASP.NET Core 项目中的主机 gRPC

ASP.NET Core gRPC 服务器通常从 gRPC 模板创建。 模板创建的项目文件使用 Microsoft.NET.SDK.Web 作为 SDK:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Microsoft.NET.SDK.Web SDK 值会自动添加对 ASP.NET Core 框架的引用。 该引用允许应用使用托管服务器所需的 ASP.NET Core 类型。

可以使用以下项目文件设置将 gRPC 服务器添加到 非 ASP.NET Core 项目:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

上面的项目文件可完成以下操作:

  • 不要使用 Microsoft.NET.SDK.Web 作为 SDK。
  • Microsoft.AspNetCore.App 添加框架引用。
    • 该框架引用允许非 ASP.NET Core 应用(例如 Windows 服务、WPF 应用或 WinForms 应用)使用 ASP.NET Core API。
    • 该应用现在可以使用 ASP.NET Core API 来启动 ASP.NET Core 服务器。
  • 添加 gRPC 要求:

有关使用 Microsoft.AspNetCore.App 框架引用的详细信息,请参阅使用 ASP.NET Core 共享框架

与 ASP.NET Core API 集成

gRPC 服务对 ASP.NET Core 功能(如依赖关系注入 (DI)日志记录)具有完全访问权限。 例如,服务实现可以通过构造函数从 DI 容器解析记录器服务:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

默认情况下,gRPC 服务实现可以解析具有任意生存期(单一实例、范围内或暂时)的其他 DI 服务。

解析 gRPC 方法中的 HttpContext

gRPC API 提供对某些 HTTP/2 消息数据(如方法、主机、标头和尾部)的访问权限。 访问是通过传递到每个 gRPC 方法的 ServerCallContext 参数进行的:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext 不提供对所有 ASP.NET API 中 HttpContext 的完全访问权限。 GetHttpContext 扩展方法提供对在 ASP.NET API 中表示基础 HTTP/2 消息的 HttpContext 的完全访问权限:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

其他资源

本文档演示如何通过 ASP.NET Core 开始使用 gRPC 服务。

先决条件

开始使用 ASP.NET Core 中的 gRPC 服务

查看或下载示例代码如何下载)。

请参阅 gRPC 服务入门,获取关于如何创建 gRPC 项目的详细说明。

将 gRPC 服务添加到 ASP.NET Core 应用

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPC

Program.cs中:

  • gRPC 通过 AddGrpc 方法启用。
  • 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

// Additional configuration is required to successfully run gRPC on macOS.
// For instructions on how to configure Kestrel and gRPC clients on macOS, visit https://go.microsoft.com/fwlink/?linkid=2099682

// Add services to the container.
builder.Services.AddGrpc();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

若要查看翻译为非英语语言的代码注释,请在 此 GitHub 讨论问题中告诉我们。

ASP.NET Core 中间件和功能共享路由管道,因此可以将应用配置为提供其他请求处理程序。 其他请求处理程序(如 MVC 控制器)与已配置的 gRPC 服务并行工作。

服务器选项

gRPC 服务可由所有内置 ASP.NET Core 服务器托管。

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本。

有关为 ASP.NET Core 应用选择正确服务器的详细信息,请参阅 ASP.NET Core 中的 Web 服务器实现

Kestrel

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。 Kestrel 侧重于最佳性能和内存利用率,但它没有 HTTP.sys 中的某些高级功能,如端口共享。

Kestrel gRPC 终结点:

HTTP/2

gRPC 需要 HTTP/2。 适用于 ASP.NET Core 的 gRPC 验证 HttpRequest.ProtocolHTTP/2

Kestrel在大多数新式操作系统上支持 HTTP/2。 默认情况下,Kestrel 终结点配置为支持 HTTP/1.1 和 HTTP/2 连接。

TLS

用于 gRPC 的 Kestrel 终结点应使用 TLS 进行保护。 在开发环境中,当存在 ASP.NET Core 开发证书时,会在 https://localhost:5001 自动创建使用 TLS 进行保护的终结点。 不需要任何配置。 https 前缀验证 Kestrel 终结点是否正在使用 TLS。

在生产环境中,必须显式配置 TLS。 以下 appsettings.json 示例中提供了使用 TLS 进行保护的 HTTP/2 终结点:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

或者,可以在 Program.cs 中配置 Kestrel 终结点:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.Protocols = HttpProtocols.Http2;
        listenOptions.UseHttps("<path to .pfx file>",
            "<certificate password>");
    });
});

有关使用 Kestrel 启用 TLS 的详细信息,请参阅 Kestrel HTTPS 终结点配置

协议协商

TLS 的用途不仅限于保护通信。 当终结点支持多个协议时,TLS 应用程序层协议协商 (ALPN) 握手可用于协商客户端与服务器之间的连接协议。 此协商确定连接是使用 HTTP/1.1 还是 HTTP/2。

如果在不使用 TLS 的情况下配置了 HTTP/2 终结点,则必须将终结点的 ListenOptions.Protocols 设置为 HttpProtocols.Http2。 如果没有 TLS,则无法使用具有多个协议(例如 HttpProtocols.Http1AndHttp2)的终结点,因为没有协商。 到不安全终结点的所有连接均默认为 HTTP/1.1,且 gRPC 调用会失败。

有关使用 Kestrel 启用 HTTP/2 和 TLS 的详细信息,请参阅 Kestrel 终结点配置

注意

macOS 不支持使用 .NET 8 之前版本的 ASP.NET Core gRPC 及 TLS。 使用 .NET 7 或更早版本时,在 macOS 上成功运行 gRPC 服务需要其他配置。 有关详细信息,请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用

IIS

Internet Information Services (IIS) 是一种灵活、安全且可管理的 Web 服务器,用于托管 Web 应用(包括 ASP.NET Core)。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 IIS 托管 gRPC 服务。

必须将 IIS 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅将 ASP.NET Core 与 IIS 上的 HTTP/2 配合使用

HTTP.sys

HTTP.sys 是仅在 Windows 上运行的适用于 ASP.NET Core 的 Web 服务器。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 HTTP.sys 托管 gRPC 服务。

必须将 HTTP.sys 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅 HTTP.sys Web 服务器 HTTP/2 支持

非 ASP.NET Core 项目中的主机 gRPC

ASP.NET Core gRPC 服务器通常从 gRPC 模板创建。 模板创建的项目文件使用 Microsoft.NET.SDK.Web 作为 SDK:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Microsoft.NET.SDK.Web SDK 值会自动添加对 ASP.NET Core 框架的引用。 该引用允许应用使用托管服务器所需的 ASP.NET Core 类型。

可以使用以下项目文件设置将 gRPC 服务器添加到 非 ASP.NET Core 项目:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

上面的项目文件可完成以下操作:

  • 不要使用 Microsoft.NET.SDK.Web 作为 SDK。
  • Microsoft.AspNetCore.App 添加框架引用。
    • 该框架引用允许非 ASP.NET Core 应用(例如 Windows 服务、WPF 应用或 WinForms 应用)使用 ASP.NET Core API。
    • 该应用现在可以使用 ASP.NET Core API 来启动 ASP.NET Core 服务器。
  • 添加 gRPC 要求:

有关使用 Microsoft.AspNetCore.App 框架引用的详细信息,请参阅使用 ASP.NET Core 共享框架

与 ASP.NET Core API 集成

gRPC 服务对 ASP.NET Core 功能(如依赖关系注入 (DI)日志记录)具有完全访问权限。 例如,服务实现可以通过构造函数从 DI 容器解析记录器服务:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

默认情况下,gRPC 服务实现可以解析具有任意生存期(单一实例、范围内或暂时)的其他 DI 服务。

解析 gRPC 方法中的 HttpContext

gRPC API 提供对某些 HTTP/2 消息数据(如方法、主机、标头和尾部)的访问权限。 访问是通过传递到每个 gRPC 方法的 ServerCallContext 参数进行的:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext 不提供对所有 ASP.NET API 中 HttpContext 的完全访问权限。 GetHttpContext 扩展方法提供对在 ASP.NET API 中表示基础 HTTP/2 消息的 HttpContext 的完全访问权限:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

其他资源

本文档演示如何通过 ASP.NET Core 开始使用 gRPC 服务。

先决条件

开始使用 ASP.NET Core 中的 gRPC 服务

查看或下载示例代码如何下载)。

请参阅 gRPC 服务入门,获取关于如何创建 gRPC 项目的详细说明。

将 gRPC 服务添加到 ASP.NET Core 应用

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPC

Startup.cs中:

  • gRPC 通过 AddGrpc 方法启用。
  • 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

若要查看翻译为非英语语言的代码注释,请在 此 GitHub 讨论问题中告诉我们。

ASP.NET Core 中间件和功能共享路由管道,因此可以将应用配置为提供其他请求处理程序。 其他请求处理程序(如 MVC 控制器)与已配置的 gRPC 服务并行工作。

服务器选项

gRPC 服务可由所有内置 ASP.NET Core 服务器托管。

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本。

有关为 ASP.NET Core 应用选择正确服务器的详细信息,请参阅 ASP.NET Core 中的 Web 服务器实现

Kestrel

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。 Kestrel 侧重于最佳性能和内存利用率,但它没有 HTTP.sys 中的某些高级功能,如端口共享。

Kestrel gRPC 终结点:

HTTP/2

gRPC 需要 HTTP/2。 适用于 ASP.NET Core 的 gRPC 验证 HttpRequest.ProtocolHTTP/2

Kestrel在大多数新式操作系统上支持 HTTP/2。 默认情况下,Kestrel 终结点配置为支持 HTTP/1.1 和 HTTP/2 连接。

TLS

用于 gRPC 的 Kestrel 终结点应使用 TLS 进行保护。 在开发环境中,当存在 ASP.NET Core 开发证书时,会在 https://localhost:5001 自动创建使用 TLS 进行保护的终结点。 不需要任何配置。 https 前缀验证 Kestrel 终结点是否正在使用 TLS。

在生产环境中,必须显式配置 TLS。 以下 appsettings.json 示例中提供了使用 TLS 进行保护的 HTTP/2 终结点:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

或者,可以在 Program.cs 中配置 Kestrel 终结点:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

有关使用 Kestrel 启用 TLS 的详细信息,请参阅 Kestrel HTTPS 终结点配置

协议协商

TLS 的用途不仅限于保护通信。 当终结点支持多个协议时,TLS 应用程序层协议协商 (ALPN) 握手可用于协商客户端与服务器之间的连接协议。 此协商确定连接是使用 HTTP/1.1 还是 HTTP/2。

如果在不使用 TLS 的情况下配置了 HTTP/2 终结点,则必须将终结点的 ListenOptions.Protocols 设置为 HttpProtocols.Http2。 如果没有 TLS,则无法使用具有多个协议(例如 HttpProtocols.Http1AndHttp2)的终结点,因为没有协商。 到不安全终结点的所有连接均默认为 HTTP/1.1,且 gRPC 调用会失败。

有关使用 Kestrel 启用 HTTP/2 和 TLS 的详细信息,请参阅 Kestrel 终结点配置

注意

macOS 不支持使用 .NET 8 之前版本的 ASP.NET Core gRPC 及 TLS。 使用 .NET 7 或更早版本时,在 macOS 上成功运行 gRPC 服务需要其他配置。 有关详细信息,请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用

IIS

Internet Information Services (IIS) 是一种灵活、安全且可管理的 Web 服务器,用于托管 Web 应用(包括 ASP.NET Core)。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 IIS 托管 gRPC 服务。

必须将 IIS 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅将 ASP.NET Core 与 IIS 上的 HTTP/2 配合使用

HTTP.sys

HTTP.sys 是仅在 Windows 上运行的适用于 ASP.NET Core 的 Web 服务器。 需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本才能使用 HTTP.sys 托管 gRPC 服务。

必须将 HTTP.sys 配置为使用 TLS 和 HTTP/2。 有关详细信息,请参阅 HTTP.sys Web 服务器 HTTP/2 支持

非 ASP.NET Core 项目中的主机 gRPC

ASP.NET Core gRPC 服务器通常从 gRPC 模板创建。 模板创建的项目文件使用 Microsoft.NET.SDK.Web 作为 SDK:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Microsoft.NET.SDK.Web SDK 值会自动添加对 ASP.NET Core 框架的引用。 该引用允许应用使用托管服务器所需的 ASP.NET Core 类型。

可以使用以下项目文件设置将 gRPC 服务器添加到 非 ASP.NET Core 项目:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

上面的项目文件可完成以下操作:

  • 不要使用 Microsoft.NET.SDK.Web 作为 SDK。
  • Microsoft.AspNetCore.App 添加框架引用。
    • 该框架引用允许非 ASP.NET Core 应用(例如 Windows 服务、WPF 应用或 WinForms 应用)使用 ASP.NET Core API。
    • 该应用现在可以使用 ASP.NET Core API 来启动 ASP.NET Core 服务器。
  • 添加 gRPC 要求:

有关使用 Microsoft.AspNetCore.App 框架引用的详细信息,请参阅使用 ASP.NET Core 共享框架

与 ASP.NET Core API 集成

gRPC 服务对 ASP.NET Core 功能(如依赖关系注入 (DI)日志记录)具有完全访问权限。 例如,服务实现可以通过构造函数从 DI 容器解析记录器服务:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

默认情况下,gRPC 服务实现可以解析具有任意生存期(单一实例、范围内或暂时)的其他 DI 服务。

解析 gRPC 方法中的 HttpContext

gRPC API 提供对某些 HTTP/2 消息数据(如方法、主机、标头和尾部)的访问权限。 访问是通过传递到每个 gRPC 方法的 ServerCallContext 参数进行的:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext 不提供对所有 ASP.NET API 中 HttpContext 的完全访问权限。 GetHttpContext 扩展方法提供对在 ASP.NET API 中表示基础 HTTP/2 消息的 HttpContext 的完全访问权限:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

其他资源

本文档演示如何通过 ASP.NET Core 开始使用 gRPC 服务。

先决条件

开始使用 ASP.NET Core 中的 gRPC 服务

查看或下载示例代码如何下载)。

请参阅 gRPC 服务入门,获取关于如何创建 gRPC 项目的详细说明。

将 gRPC 服务添加到 ASP.NET Core 应用

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPC

Startup.cs中:

  • gRPC 通过 AddGrpc 方法启用。
  • 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

若要查看翻译为非英语语言的代码注释,请在 此 GitHub 讨论问题中告诉我们。

ASP.NET Core 中间件和功能共享路由管道,因此可以将应用配置为提供其他请求处理程序。 其他请求处理程序(如 MVC 控制器)与已配置的 gRPC 服务并行工作。

服务器选项

gRPC 服务可由所有内置 ASP.NET Core 服务器托管。

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本。

有关为 ASP.NET Core 应用选择正确服务器的详细信息,请参阅 ASP.NET Core 中的 Web 服务器实现

Kestrel

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。 Kestrel 侧重于最佳性能和内存利用率,但它没有 HTTP.sys 中的某些高级功能,如端口共享。

Kestrel gRPC 终结点:

HTTP/2

gRPC 需要 HTTP/2。 适用于 ASP.NET Core 的 gRPC 验证 HttpRequest.ProtocolHTTP/2

Kestrel在大多数新式操作系统上支持 HTTP/2。 默认情况下,Kestrel 终结点配置为支持 HTTP/1.1 和 HTTP/2 连接。

TLS

用于 gRPC 的 Kestrel 终结点应使用 TLS 进行保护。 在开发环境中,当存在 ASP.NET Core 开发证书时,会在 https://localhost:5001 自动创建使用 TLS 进行保护的终结点。 不需要任何配置。 https 前缀验证 Kestrel 终结点是否正在使用 TLS。

在生产环境中,必须显式配置 TLS。 以下 appsettings.json 示例中提供了使用 TLS 进行保护的 HTTP/2 终结点:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

或者,可以在 Program.cs 中配置 Kestrel 终结点:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

有关使用 Kestrel 启用 TLS 的详细信息,请参阅 Kestrel HTTPS 终结点配置

协议协商

TLS 的用途不仅限于保护通信。 当终结点支持多个协议时,TLS 应用程序层协议协商 (ALPN) 握手可用于协商客户端与服务器之间的连接协议。 此协商确定连接是使用 HTTP/1.1 还是 HTTP/2。

如果在不使用 TLS 的情况下配置了 HTTP/2 终结点,则必须将终结点的 ListenOptions.Protocols 设置为 HttpProtocols.Http2。 如果没有 TLS,则无法使用具有多个协议(例如 HttpProtocols.Http1AndHttp2)的终结点,因为没有协商。 到不安全终结点的所有连接均默认为 HTTP/1.1,且 gRPC 调用会失败。

有关使用 Kestrel 启用 HTTP/2 和 TLS 的详细信息,请参阅 Kestrel 终结点配置

注意

macOS 不支持使用 .NET 8 之前版本的 ASP.NET Core gRPC 及 TLS。 使用 .NET 7 或更早版本时,在 macOS 上成功运行 gRPC 服务需要其他配置。 有关详细信息,请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用

非 ASP.NET Core 项目中的主机 gRPC

ASP.NET Core gRPC 服务器通常从 gRPC 模板创建。 模板创建的项目文件使用 Microsoft.NET.SDK.Web 作为 SDK:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Microsoft.NET.SDK.Web SDK 值会自动添加对 ASP.NET Core 框架的引用。 该引用允许应用使用托管服务器所需的 ASP.NET Core 类型。

可以使用以下项目文件设置将 gRPC 服务器添加到 非 ASP.NET Core 项目:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

上面的项目文件可完成以下操作:

  • 不要使用 Microsoft.NET.SDK.Web 作为 SDK。
  • Microsoft.AspNetCore.App 添加框架引用。
    • 该框架引用允许非 ASP.NET Core 应用(例如 Windows 服务、WPF 应用或 WinForms 应用)使用 ASP.NET Core API。
    • 该应用现在可以使用 ASP.NET Core API 来启动 ASP.NET Core 服务器。
  • 添加 gRPC 要求:

有关使用 Microsoft.AspNetCore.App 框架引用的详细信息,请参阅使用 ASP.NET Core 共享框架

与 ASP.NET Core API 集成

gRPC 服务对 ASP.NET Core 功能(如依赖关系注入 (DI)日志记录)具有完全访问权限。 例如,服务实现可以通过构造函数从 DI 容器解析记录器服务:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

默认情况下,gRPC 服务实现可以解析具有任意生存期(单一实例、范围内或暂时)的其他 DI 服务。

解析 gRPC 方法中的 HttpContext

gRPC API 提供对某些 HTTP/2 消息数据(如方法、主机、标头和尾部)的访问权限。 访问是通过传递到每个 gRPC 方法的 ServerCallContext 参数进行的:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext 不提供对所有 ASP.NET API 中 HttpContext 的完全访问权限。 GetHttpContext 扩展方法提供对在 ASP.NET API 中表示基础 HTTP/2 消息的 HttpContext 的完全访问权限:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

其他资源

本文档演示如何通过 ASP.NET Core 开始使用 gRPC 服务。

先决条件

开始使用 ASP.NET Core 中的 gRPC 服务

查看或下载示例代码如何下载)。

请参阅 gRPC 服务入门,获取关于如何创建 gRPC 项目的详细说明。

将 gRPC 服务添加到 ASP.NET Core 应用

gRPC 需要 Grpc.AspNetCore 包。

配置 gRPC

Startup.cs中:

  • gRPC 通过 AddGrpc 方法启用。
  • 每个 gRPC 服务均通过 MapGrpcService 方法添加到路由管道。
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            // Communication with gRPC endpoints must be made through a gRPC client.
            // To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909
            endpoints.MapGrpcService<GreeterService>();
        });
    }
}

若要查看翻译为非英语语言的代码注释,请在 此 GitHub 讨论问题中告诉我们。

ASP.NET Core 中间件和功能共享路由管道,因此可以将应用配置为提供其他请求处理程序。 其他请求处理程序(如 MVC 控制器)与已配置的 gRPC 服务并行工作。

服务器选项

gRPC 服务可由所有内置 ASP.NET Core 服务器托管。

  • Kestrel
  • TestServer
  • IIS†
  • HTTP.sys†

†需要 .NET 5 和 Windows 11 内部版本 22000 或 Windows Server 2022 内部版本 20348 或更高版本。

有关为 ASP.NET Core 应用选择正确服务器的详细信息,请参阅 ASP.NET Core 中的 Web 服务器实现

Kestrel

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。 Kestrel 侧重于最佳性能和内存利用率,但它没有 HTTP.sys 中的某些高级功能,如端口共享。

Kestrel gRPC 终结点:

HTTP/2

gRPC 需要 HTTP/2。 适用于 ASP.NET Core 的 gRPC 验证 HttpRequest.ProtocolHTTP/2

Kestrel在大多数新式操作系统上支持 HTTP/2。 默认情况下,Kestrel 终结点配置为支持 HTTP/1.1 和 HTTP/2 连接。

TLS

用于 gRPC 的 Kestrel 终结点应使用 TLS 进行保护。 在开发环境中,当存在 ASP.NET Core 开发证书时,会在 https://localhost:5001 自动创建使用 TLS 进行保护的终结点。 不需要任何配置。 https 前缀验证 Kestrel 终结点是否正在使用 TLS。

在生产环境中,必须显式配置 TLS。 以下 appsettings.json 示例中提供了使用 TLS 进行保护的 HTTP/2 终结点:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

或者,可以在 Program.cs 中配置 Kestrel 终结点:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(options =>
            {
                options.Listen(IPAddress.Any, 5001, listenOptions =>
                {
                    listenOptions.Protocols = HttpProtocols.Http2;
                    listenOptions.UseHttps("<path to .pfx file>", 
                        "<certificate password>");
                });
            });
            webBuilder.UseStartup<Startup>();
        });

有关使用 Kestrel 启用 TLS 的详细信息,请参阅 Kestrel HTTPS 终结点配置

协议协商

TLS 的用途不仅限于保护通信。 当终结点支持多个协议时,TLS 应用程序层协议协商 (ALPN) 握手可用于协商客户端与服务器之间的连接协议。 此协商确定连接是使用 HTTP/1.1 还是 HTTP/2。

如果在不使用 TLS 的情况下配置了 HTTP/2 终结点,则必须将终结点的 ListenOptions.Protocols 设置为 HttpProtocols.Http2。 如果没有 TLS,则无法使用具有多个协议(例如 HttpProtocols.Http1AndHttp2)的终结点,因为没有协商。 到不安全终结点的所有连接均默认为 HTTP/1.1,且 gRPC 调用会失败。

有关使用 Kestrel 启用 HTTP/2 和 TLS 的详细信息,请参阅 Kestrel 终结点配置

注意

macOS 不支持使用 .NET 8 之前版本的 ASP.NET Core gRPC 及 TLS。 使用 .NET 7 或更早版本时,在 macOS 上成功运行 gRPC 服务需要其他配置。 有关详细信息,请参阅无法在 macOS 上启用 ASP.NET Core gRPC 应用

非 ASP.NET Core 项目中的主机 gRPC

ASP.NET Core gRPC 服务器通常从 gRPC 模板创建。 模板创建的项目文件使用 Microsoft.NET.SDK.Web 作为 SDK:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
  </ItemGroup>

</Project>

Microsoft.NET.SDK.Web SDK 值会自动添加对 ASP.NET Core 框架的引用。 该引用允许应用使用托管服务器所需的 ASP.NET Core 类型。

可以使用以下项目文件设置将 gRPC 服务器添加到 非 ASP.NET Core 项目:

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.47.0" />
    <Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
    
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

上面的项目文件可完成以下操作:

  • 不要使用 Microsoft.NET.SDK.Web 作为 SDK。
  • Microsoft.AspNetCore.App 添加框架引用。
    • 该框架引用允许非 ASP.NET Core 应用(例如 Windows 服务、WPF 应用或 WinForms 应用)使用 ASP.NET Core API。
    • 该应用现在可以使用 ASP.NET Core API 来启动 ASP.NET Core 服务器。
  • 添加 gRPC 要求:

有关使用 Microsoft.AspNetCore.App 框架引用的详细信息,请参阅使用 ASP.NET Core 共享框架

与 ASP.NET Core API 集成

gRPC 服务对 ASP.NET Core 功能(如依赖关系注入 (DI)日志记录)具有完全访问权限。 例如,服务实现可以通过构造函数从 DI 容器解析记录器服务:

public class GreeterService : Greeter.GreeterBase
{
    public GreeterService(ILogger<GreeterService> logger)
    {
    }
}

默认情况下,gRPC 服务实现可以解析具有任意生存期(单一实例、范围内或暂时)的其他 DI 服务。

解析 gRPC 方法中的 HttpContext

gRPC API 提供对某些 HTTP/2 消息数据(如方法、主机、标头和尾部)的访问权限。 访问是通过传递到每个 gRPC 方法的 ServerCallContext 参数进行的:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

ServerCallContext 不提供对所有 ASP.NET API 中 HttpContext 的完全访问权限。 GetHttpContext 扩展方法提供对在 ASP.NET API 中表示基础 HTTP/2 消息的 HttpContext 的完全访问权限:

public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(
        HelloRequest request, ServerCallContext context)
    {
        var httpContext = context.GetHttpContext();
        var clientCertificate = httpContext.Connection.ClientCertificate;

        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name + " from " + clientCertificate.Issuer
        });
    }
}

其他资源