搭配 ASP.NET Core 的 gRPC 服務

發行項
11/06/2024

注意

這不是這篇文章的最新版本。如需目前版本，請參閱本文的 .NET 8 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支援原則。如需目前版本，請參閱本文的 .NET 8 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前版本，請參閱本文的 .NET 8 版本。

本文件說明如何使用 ASP.NET Core 開始使用 gRPC 服務。

必要條件

Visual Studio 2022 和 ASP.NET 與 Web 開發工作負載。

開始在 ASP.NET Core 中使用 gRPC 服務

檢視或下載範例程式碼 (如何下載)。

Visual Studio
Visual Studio Code / Visual Studio for Mac

如需如何建立 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。
應使用傳輸層安全性 (TLS) 來保護。

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 需求：
- Grpc.AspNetCore 的 NuGet 套件參考。
- .proto 檔案。

如需使用 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 服務。

必要條件

Visual Studio 2022 和 ASP.NET 與 Web 開發工作負載。

開始在 ASP.NET Core 中使用 gRPC 服務

檢視或下載範例程式碼 (如何下載)。

Visual Studio
Visual Studio Code / Visual Studio for Mac

如需如何建立 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 討論問題中告訴我們。

伺服器選項

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。
應使用傳輸層安全性 (TLS) 來保護。

HTTP/2

gRPC 需要 HTTP/2。 ASP.NET Core 的 gRPC 會驗證 HttpRequest.Protocol 為 HTTP/2。

在大多數新式作業系統上Kestrel支援 HTTP/2。 Kestrel 端點預設會設定為支援 HTTP/1.1 和 HTTP/2 連線。

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 端點組態。

通訊協定交涉

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

注意

IIS

IIS 必須設定為使用 TLS 和 HTTP/2。如需詳細資訊，請參閱在 IIS 上搭配使用 ASP.NET Core 與 HTTP/2。

HTTP.sys

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 需求：
- Grpc.AspNetCore 的 NuGet 套件參考。
- .proto 檔案。

如需使用 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
        });
    }
}

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 服務。

必要條件

Visual Studio 2022 和 ASP.NET 與 Web 開發工作負載。
.NET 6.0 SDK

開始在 ASP.NET Core 中使用 gRPC 服務

檢視或下載範例程式碼 (如何下載)。

Visual Studio
Visual Studio Code / Visual Studio for Mac

如需如何建立 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 討論問題中告訴我們。

伺服器選項

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。
應使用傳輸層安全性 (TLS) 來保護。

HTTP/2

gRPC 需要 HTTP/2。 ASP.NET Core 的 gRPC 會驗證 HttpRequest.Protocol 為 HTTP/2。

在大多數新式作業系統上Kestrel支援 HTTP/2。 Kestrel 端點預設會設定為支援 HTTP/1.1 和 HTTP/2 連線。

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 端點組態。

通訊協定交涉

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

注意

IIS

IIS 必須設定為使用 TLS 和 HTTP/2。如需詳細資訊，請參閱在 IIS 上搭配使用 ASP.NET Core 與 HTTP/2。

HTTP.sys

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 需求：
- Grpc.AspNetCore 的 NuGet 套件參考。
- .proto 檔案。

如需使用 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
        });
    }
}

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 服務。

必要條件

Visual Studio 2019 16.8 或更新版本，其中包含 ASP.NET 和網頁程式開發工作負載
.NET 5.0 SDK

開始在 ASP.NET Core 中使用 gRPC 服務

檢視或下載範例程式碼 (如何下載)。

Visual Studio
Visual Studio Code / Visual Studio for Mac

如需如何建立 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 討論問題中告訴我們。

伺服器選項

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。
應使用傳輸層安全性 (TLS) 來保護。

HTTP/2

gRPC 需要 HTTP/2。 ASP.NET Core 的 gRPC 會驗證 HttpRequest.Protocol 為 HTTP/2。

在大多數新式作業系統上Kestrel支援 HTTP/2。 Kestrel 端點預設會設定為支援 HTTP/1.1 和 HTTP/2 連線。

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 端點組態。

通訊協定交涉

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

注意

IIS

IIS 必須設定為使用 TLS 和 HTTP/2。如需詳細資訊，請參閱在 IIS 上搭配使用 ASP.NET Core 與 HTTP/2。

HTTP.sys

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 需求：
- Grpc.AspNetCore 的 NuGet 套件參考。
- .proto 檔案。

如需使用 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
        });
    }
}

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 服務。

必要條件

Visual Studio 2019 16.4 或更新版本，其中包含 ASP.NET 和網頁程式開發工作負載
.NET Core 3.1 SDK

開始在 ASP.NET Core 中使用 gRPC 服務

檢視或下載範例程式碼 (如何下載)。

Visual Studio
Visual Studio Code / Visual Studio for Mac

如需如何建立 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 討論問題中告訴我們。

伺服器選項

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。
應使用傳輸層安全性 (TLS) 來保護。

HTTP/2

gRPC 需要 HTTP/2。 ASP.NET Core 的 gRPC 會驗證 HttpRequest.Protocol 為 HTTP/2。

在大多數新式作業系統上Kestrel支援 HTTP/2。 Kestrel 端點預設會設定為支援 HTTP/1.1 和 HTTP/2 連線。

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 端點組態。

通訊協定交涉

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

注意

在非 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 需求：
- Grpc.AspNetCore 的 NuGet 套件參考。
- .proto 檔案。

如需使用 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
        });
    }
}

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 服務。

必要條件

Visual Studio 2019 和 ASP.NET 與 Web 開發工作負載
.NET Core 3.0 SDK

開始在 ASP.NET Core 中使用 gRPC 服務

檢視或下載範例程式碼 (如何下載)。

Visual Studio
Visual Studio Code / Visual Studio for Mac

如需如何建立 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 討論問題中告訴我們。

伺服器選項

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。
應使用傳輸層安全性 (TLS) 來保護。

HTTP/2

gRPC 需要 HTTP/2。 ASP.NET Core 的 gRPC 會驗證 HttpRequest.Protocol 為 HTTP/2。

在大多數新式作業系統上Kestrel支援 HTTP/2。 Kestrel 端點預設會設定為支援 HTTP/1.1 和 HTTP/2 連線。

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 端點組態。

通訊協定交涉

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

注意

在非 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 需求：
- Grpc.AspNetCore 的 NuGet 套件參考。
- .proto 檔案。

如需使用 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
        });
    }
}

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 服務新增至 ASP.NET Core 應用程式

設定 gRPC

伺服器選項

Kestrel

HTTP/2

TLS

通訊協定交涉

IIS

HTTP.sys

在非 ASP.NET Core 專案中裝載 gRPC

與 ASP.NET Core API 整合

解決 gRPC 方法中的 HttpContext

其他資源

必要條件

開始在 ASP.NET Core 中使用 gRPC 服務

將 gRPC 服務新增至 ASP.NET Core 應用程式

設定 gRPC

伺服器選項

Kestrel

HTTP/2

TLS

通訊協定交涉

IIS

HTTP.sys

在非 ASP.NET Core 專案中裝載 gRPC

與 ASP.NET Core API 整合

解決 gRPC 方法中的 HttpContext

其他資源

必要條件

開始在 ASP.NET Core 中使用 gRPC 服務

將 gRPC 服務新增至 ASP.NET Core 應用程式

設定 gRPC

伺服器選項

Kestrel

HTTP/2

TLS

通訊協定交涉

IIS

HTTP.sys

在非 ASP.NET Core 專案中裝載 gRPC

與 ASP.NET Core API 整合

解決 gRPC 方法中的 HttpContext

其他資源

必要條件

開始在 ASP.NET Core 中使用 gRPC 服務

將 gRPC 服務新增至 ASP.NET Core 應用程式

設定 gRPC

伺服器選項

Kestrel

HTTP/2

TLS

通訊協定交涉

IIS

HTTP.sys

在非 ASP.NET Core 專案中裝載 gRPC

與 ASP.NET Core API 整合

解決 gRPC 方法中的 HttpContext

其他資源

必要條件

開始在 ASP.NET Core 中使用 gRPC 服務

將 gRPC 服務新增至 ASP.NET Core 應用程式

設定 gRPC

伺服器選項

Kestrel

HTTP/2

TLS

通訊協定交涉

在非 ASP.NET Core 專案中裝載 gRPC

與 ASP.NET Core API 整合

解決 gRPC 方法中的 HttpContext

其他資源

必要條件

開始在 ASP.NET Core 中使用 gRPC 服務

將 gRPC 服務新增至 ASP.NET Core 應用程式

設定 gRPC

伺服器選項