搭配 ASP.NET Core 的 gRPC 服務

  • 發行項

本文件說明如何使用 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.Protocol 為 HTTP/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.Protocol 為 HTTP/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.Protocol 為 HTTP/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.Protocol 為 HTTP/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.Protocol 為 HTTP/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.Protocol 為 HTTP/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
        });
    }
}

其他資源