共用方式為


搭配 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 中:

  • 使用 AddGrpc 方法啟用 gRPC。
  • 每個 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 的詳細資訊,請參閱 KestrelHTTPS 端點組態

通訊協定交涉

TLS 不僅僅用於保護通訊安全。 端點支援多個通訊協定時,TLS 應用程式層通訊協定交涉 (ALPN) 交握可用來交涉用戶端與伺服器之間的連線通訊協定。 此交涉會決定連線是使用 HTTP/1.1 或 HTTP/2。

如果未使用 TLS 設定 HTTP/2 端點,則必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 具有多個通訊協定的端點 (例如 HttpProtocols.Http1AndHttp2) 無法在沒有 TLS 的情況下使用,因為並未進行交涉。 與不安全端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

如需使用 Kestrel 啟用 HTTP/2 和 TLS 的詳細資訊,請參閱Kestrel端點組態

注意

在 .NET 8 之前,macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 若使用 .NET 7 或更早版本,就須在 macOS 上成功執行 gRPC 服務的額外設定。 如需詳細資訊,請參閱無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

IIS

Internet Information Services (IIS) 是裝載 Web 應用程式 (包括 ASP.NET Core) 的彈性、安全且可管理的 Web 伺服器。 需使用 .NET 5 和 Windows 11 組建 22000 或 Windows Server 2022 組建 20348 或更新版本,才能使用 IIS 裝載 gRPC 服務。

IIS 必須設定為使用 TLS 和 HTTP/2。 如需詳細資訊,請參閱在 IIS 上搭配使用 ASP.NET Core 與 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 訊息資料,例如,方法、主機、標頭和結尾。 Access 是透過傳遞至每個 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 擴充方法提供 HttpContext (表示 ASP.NET API 中的基礎 HTTP/2 訊息) 的完整存取權:

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 中:

  • 使用 AddGrpc 方法啟用 gRPC。
  • 每個 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 的詳細資訊,請參閱 KestrelHTTPS 端點組態

通訊協定交涉

TLS 不僅僅用於保護通訊安全。 端點支援多個通訊協定時,TLS 應用程式層通訊協定交涉 (ALPN) 交握可用來交涉用戶端與伺服器之間的連線通訊協定。 此交涉會決定連線是使用 HTTP/1.1 或 HTTP/2。

如果未使用 TLS 設定 HTTP/2 端點,則必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 具有多個通訊協定的端點 (例如 HttpProtocols.Http1AndHttp2) 無法在沒有 TLS 的情況下使用,因為並未進行交涉。 與不安全端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

如需使用 Kestrel 啟用 HTTP/2 和 TLS 的詳細資訊,請參閱Kestrel端點組態

注意

在 .NET 8 之前,macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 若使用 .NET 7 或更早版本,就須在 macOS 上成功執行 gRPC 服務的額外設定。 如需詳細資訊,請參閱無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

IIS

Internet Information Services (IIS) 是裝載 Web 應用程式 (包括 ASP.NET Core) 的彈性、安全且可管理的 Web 伺服器。 需使用 .NET 5 和 Windows 11 組建 22000 或 Windows Server 2022 組建 20348 或更新版本,才能使用 IIS 裝載 gRPC 服務。

IIS 必須設定為使用 TLS 和 HTTP/2。 如需詳細資訊,請參閱在 IIS 上搭配使用 ASP.NET Core 與 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 訊息資料,例如,方法、主機、標頭和結尾。 Access 是透過傳遞至每個 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 擴充方法提供 HttpContext (表示 ASP.NET API 中的基礎 HTTP/2 訊息) 的完整存取權:

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 中:

  • 使用 AddGrpc 方法啟用 gRPC。
  • 每個 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 的詳細資訊,請參閱 KestrelHTTPS 端點組態

通訊協定交涉

TLS 不僅僅用於保護通訊安全。 端點支援多個通訊協定時,TLS 應用程式層通訊協定交涉 (ALPN) 交握可用來交涉用戶端與伺服器之間的連線通訊協定。 此交涉會決定連線是使用 HTTP/1.1 或 HTTP/2。

如果未使用 TLS 設定 HTTP/2 端點,則必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 具有多個通訊協定的端點 (例如 HttpProtocols.Http1AndHttp2) 無法在沒有 TLS 的情況下使用,因為並未進行交涉。 與不安全端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

如需使用 Kestrel 啟用 HTTP/2 和 TLS 的詳細資訊,請參閱Kestrel端點組態

注意

在 .NET 8 之前,macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 若使用 .NET 7 或更早版本,就須在 macOS 上成功執行 gRPC 服務的額外設定。 如需詳細資訊,請參閱無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

IIS

Internet Information Services (IIS) 是裝載 Web 應用程式 (包括 ASP.NET Core) 的彈性、安全且可管理的 Web 伺服器。 需使用 .NET 5 和 Windows 11 組建 22000 或 Windows Server 2022 組建 20348 或更新版本,才能使用 IIS 裝載 gRPC 服務。

IIS 必須設定為使用 TLS 和 HTTP/2。 如需詳細資訊,請參閱在 IIS 上搭配使用 ASP.NET Core 與 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 訊息資料,例如,方法、主機、標頭和結尾。 Access 是透過傳遞至每個 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 擴充方法提供 HttpContext (表示 ASP.NET API 中的基礎 HTTP/2 訊息) 的完整存取權:

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 中:

  • 使用 AddGrpc 方法啟用 gRPC。
  • 每個 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 的詳細資訊,請參閱 KestrelHTTPS 端點組態

通訊協定交涉

TLS 不僅僅用於保護通訊安全。 端點支援多個通訊協定時,TLS 應用程式層通訊協定交涉 (ALPN) 交握可用來交涉用戶端與伺服器之間的連線通訊協定。 此交涉會決定連線是使用 HTTP/1.1 或 HTTP/2。

如果未使用 TLS 設定 HTTP/2 端點,則必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 具有多個通訊協定的端點 (例如 HttpProtocols.Http1AndHttp2) 無法在沒有 TLS 的情況下使用,因為並未進行交涉。 與不安全端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

如需使用 Kestrel 啟用 HTTP/2 和 TLS 的詳細資訊,請參閱Kestrel端點組態

注意

在 .NET 8 之前,macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 若使用 .NET 7 或更早版本,就須在 macOS 上成功執行 gRPC 服務的額外設定。 如需詳細資訊,請參閱無法在 macOS 上啟動 ASP.NET Core gRPC 應用程式

IIS

Internet Information Services (IIS) 是裝載 Web 應用程式 (包括 ASP.NET Core) 的彈性、安全且可管理的 Web 伺服器。 需使用 .NET 5 和 Windows 11 組建 22000 或 Windows Server 2022 組建 20348 或更新版本,才能使用 IIS 裝載 gRPC 服務。

IIS 必須設定為使用 TLS 和 HTTP/2。 如需詳細資訊,請參閱在 IIS 上搭配使用 ASP.NET Core 與 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 訊息資料,例如,方法、主機、標頭和結尾。 Access 是透過傳遞至每個 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 擴充方法提供 HttpContext (表示 ASP.NET API 中的基礎 HTTP/2 訊息) 的完整存取權:

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 中:

  • 使用 AddGrpc 方法啟用 gRPC。
  • 每個 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 的詳細資訊,請參閱 KestrelHTTPS 端點組態

通訊協定交涉

TLS 不僅僅用於保護通訊安全。 端點支援多個通訊協定時,TLS 應用程式層通訊協定交涉 (ALPN) 交握可用來交涉用戶端與伺服器之間的連線通訊協定。 此交涉會決定連線是使用 HTTP/1.1 或 HTTP/2。

如果未使用 TLS 設定 HTTP/2 端點,則必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 具有多個通訊協定的端點 (例如 HttpProtocols.Http1AndHttp2) 無法在沒有 TLS 的情況下使用,因為並未進行交涉。 與不安全端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

如需使用 Kestrel 啟用 HTTP/2 和 TLS 的詳細資訊,請參閱Kestrel端點組態

注意

在 .NET 8 之前,macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 若使用 .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 訊息資料,例如,方法、主機、標頭和結尾。 Access 是透過傳遞至每個 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 擴充方法提供 HttpContext (表示 ASP.NET API 中的基礎 HTTP/2 訊息) 的完整存取權:

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 中:

  • 使用 AddGrpc 方法啟用 gRPC。
  • 每個 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 的詳細資訊,請參閱 KestrelHTTPS 端點組態

通訊協定交涉

TLS 不僅僅用於保護通訊安全。 端點支援多個通訊協定時,TLS 應用程式層通訊協定交涉 (ALPN) 交握可用來交涉用戶端與伺服器之間的連線通訊協定。 此交涉會決定連線是使用 HTTP/1.1 或 HTTP/2。

如果未使用 TLS 設定 HTTP/2 端點,則必須將端點的 ListenOptions.Protocols 設定為 HttpProtocols.Http2。 具有多個通訊協定的端點 (例如 HttpProtocols.Http1AndHttp2) 無法在沒有 TLS 的情況下使用,因為並未進行交涉。 與不安全端點的所有連線都會預設使用 HTTP/1.1,而 gRPC 呼叫會失敗。

如需使用 Kestrel 啟用 HTTP/2 和 TLS 的詳細資訊,請參閱Kestrel端點組態

注意

在 .NET 8 之前,macOS 不支援具有 TLS 的 ASP.NET Core gRPC。 若使用 .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 訊息資料,例如,方法、主機、標頭和結尾。 Access 是透過傳遞至每個 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 擴充方法提供 HttpContext (表示 ASP.NET API 中的基礎 HTTP/2 訊息) 的完整存取權:

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
        });
    }
}

其他資源