次の方法で共有


ASP.NET Core を使用した gRPC サービス

Note

これは、この記事の最新バージョンではありません。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。

警告

このバージョンの ASP.NET Core はサポート対象から除外されました。 詳細については、「.NET および .NET Core サポート ポリシー」を参照してください。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。

重要

この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。

現在のリリースについては、この記事の .NET 8 バージョンを参照してください。

このドキュメントでは、ASP.NET Core を使用して gRPC サービスを開始する方法について説明します。

必須コンポーネント

ASP.NET Core の gRPC サービスの概要

サンプル コードを表示またはダウンロードします (ダウンロード方法)。

gRPC プロジェクトを作成する詳細な手順については、gRPC サービスの概要に関するページをご覧ください。

ASP.NET Core アプリに gRPC サービスを追加する

gRPC には Grpc. AspNetCore パッケージが必要です。

gRPC を構成する

Program.cs:

  • gRPC を有効にするには、AddGrpc メソッドを使用します。
  • 各 gRPC サービスをルーティング パイプラインに追加するには、MapGrpcService メソッドを使用します。
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

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

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

var app = builder.Build();

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

app.Run();

コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。

ルーティング パイプラインは ASP.NET Core のミドルウェアと機能で共有されるため、追加の要求ハンドラーを提供するようにアプリを構成することができます。 MVC コントローラーなどの追加の要求ハンドラーは、構成されている gRPC サービスと並行して動作します。

サーバー オプション

gRPC サービスは、すべての組み込み ASP.NET Core サーバーによってホストできます。

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

†.NET 5 および Windows 11 ビルド 22000 または Windows Server 2022 ビルド 20348 以降が必要です。

ASP.NET Core アプリに使用する適切なサーバーの選択について詳しくは、「ASP.NET Core での Web サーバーの実装」を参照してください。

Kestrel

Kestrel は、ASP.NET Core 向けのクロスプラットフォーム Web サーバーです。 Kestrel は、ハイ パフォーマンスとメモリ使用率に重点を置いていますが、ポート共有などの HTTP.sys の高度な機能の一部はありません。

Kestrel gRPC エンドポイント:

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequestHTTP/2 であるかを検証します。

Kestrelは、最新のオペレーティング システムで HTTP/2 をサポートしています。 Kestrel エンドポイントは、既定で HTTP/1.1 接続と HTTP/2 接続をサポートするように構成されています。

TLS

gRPC に使用される Kestrel エンドポイントは、TLS で保護されている必要があります。 開発環境では、ASP.NET Core 開発証明書が存在する場合に、TLS で保護されたエンドポイントが https://localhost:5001 に自動的に作成されます。 構成は必要ありません。 https プレフィックスによって、Kestrel エンドポイントが TLS を使用していることが確認されます。

運用環境では、TLS を明示的に構成する必要があります。 次の appsettings.json の例では、TLS で保護された HTTP/2 エンドポイントが指定されています。

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

または、Program.cs 内に Kestrel エンドポイントを構成することもできます。

var builder = WebApplication.CreateBuilder(args);

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

Kestrel で TLS を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

プロトコル ネゴシエーション

TLS は、通信のセキュリティ保護以外にも使用されます。 エンドポイントで複数のプロトコルがサポートされている場合、クライアントとサーバー間の接続プロトコルをネゴシエートするために TLS ALPN (Application-Layer Protocol Negotiation) ハンドシェイクが使用されます。 このネゴシエーションでは、HTTP/1.1 または HTTP/2 のどちらが接続に使用されるかを判断します。

HTTP/2 エンドポイントが TLS を使用せずに構成されている場合は、エンドポイントの ListenOptions.ProtocolsHttpProtocols.Http2 に設定する必要があります。 複数のプロトコル (HttpProtocols.Http1AndHttp2 など) を持つエンドポイントは、ネゴシエーションがないため、TLS なしで使用することはできません。 セキュリティで保護されていないエンドポイントへの接続はすべて、既定で HTTP/1.1 に設定されるため、gRPC の呼び出しは失敗します。

Kestrel で HTTP/2 および TLS を有効にする方法について詳しくは、Kestrel のエンドポイント構成に関するページをご覧ください。

Note

macOS では、.NET 8 より前の ASP.NET Core gRPC と TLS はサポートされていません。 .NET 7 以前を使っているときに、macOS で gRPC サービスを正常に実行するには、追加の構成が必要です。 詳細については、macOS で ASP.NET Core gRPC アプリを起動できない場合に関するページを参照してください。

IIS

インターネット インフォメーション サービス (IIS) は、Web アプリ (ASP.NET Core を含む) をホストするための、柔軟かつ安全で管理しやすい Web サーバーです。 IIS で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

IIS は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、「IIS 上で HTTP/2 と共に ASP.NET Core を使用する」を参照してください。

HTTP.sys

HTTP.sys は、Windows 上でのみ動作する ASP.NET Core 用 Web サーバーです。 HTTP.sys で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

HTTP.sys は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、HTTP.sys Web サーバーの HTTP/2 サポートに関する記事を参照してください。

non-ASP.NET Core プロジェクトで gRPC をホストする

通常、ASP.NET Core gRPC サーバーは、gRPC テンプレートから作成されます。 テンプレートによって作成されたプロジェクト ファイルでは、SDK として Microsoft.NET.SDK.Web が使用されます。

<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 サーバーを non-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 サービスには、依存関係の挿入 (DI) やログ記録などの ASP.NET Core 機能へのフル アクセスがあります。 たとえば、サービスの実装では、コンストラクターを使用して DI コンテナーから logger サービスを解決できます。

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

既定では、gRPC サービスの実装では、任意の有効期間 (シングルトン、スコープ、または一時的) を持つ他の DI サービスを解決できます。

gRPC メソッドで HttpContext を解決する

gRPC API は、メソッド、ホスト、ヘッダー、トレーラーなど、一部の HTTP/2 メッセージ データへのアクセスを提供します。 アクセスには、各 gRPC メソッドに渡される ServerCallContext 引数が使用されます。

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

ServerCallContext を使用しても、すべての ASP.NET API で HttpContext へのフル アクセスが提供されるわけではありません。 GetHttpContext 拡張メソッドを使用すると、ASP.NET API で基となる HTTP/2 メッセージを表す HttpContext にフル アクセスできます。

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

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

その他の技術情報

このドキュメントでは、ASP.NET Core を使用して gRPC サービスを開始する方法について説明します。

必須コンポーネント

ASP.NET Core の gRPC サービスの概要

サンプル コードを表示またはダウンロードします (ダウンロード方法)。

gRPC プロジェクトを作成する詳細な手順については、gRPC サービスの概要に関するページをご覧ください。

ASP.NET Core アプリに gRPC サービスを追加する

gRPC には Grpc. AspNetCore パッケージが必要です。

gRPC を構成する

Program.cs:

  • gRPC を有効にするには、AddGrpc メソッドを使用します。
  • 各 gRPC サービスをルーティング パイプラインに追加するには、MapGrpcService メソッドを使用します。
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

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

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

var app = builder.Build();

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

app.Run();

コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。

ルーティング パイプラインは ASP.NET Core のミドルウェアと機能で共有されるため、追加の要求ハンドラーを提供するようにアプリを構成することができます。 MVC コントローラーなどの追加の要求ハンドラーは、構成されている gRPC サービスと並行して動作します。

サーバー オプション

gRPC サービスは、すべての組み込み ASP.NET Core サーバーによってホストできます。

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

†.NET 5 および Windows 11 ビルド 22000 または Windows Server 2022 ビルド 20348 以降が必要です。

ASP.NET Core アプリに使用する適切なサーバーの選択について詳しくは、「ASP.NET Core での Web サーバーの実装」を参照してください。

Kestrel

Kestrel は、ASP.NET Core 向けのクロスプラットフォーム Web サーバーです。 Kestrel は、ハイ パフォーマンスとメモリ使用率に重点を置いていますが、ポート共有などの HTTP.sys の高度な機能の一部はありません。

Kestrel gRPC エンドポイント:

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequestHTTP/2 であるかを検証します。

Kestrelは、最新のオペレーティング システムで HTTP/2 をサポートしています。 Kestrel エンドポイントは、既定で HTTP/1.1 接続と HTTP/2 接続をサポートするように構成されています。

TLS

gRPC に使用される Kestrel エンドポイントは、TLS で保護されている必要があります。 開発環境では、ASP.NET Core 開発証明書が存在する場合に、TLS で保護されたエンドポイントが https://localhost:5001 に自動的に作成されます。 構成は必要ありません。 https プレフィックスによって、Kestrel エンドポイントが TLS を使用していることが確認されます。

運用環境では、TLS を明示的に構成する必要があります。 次の appsettings.json の例では、TLS で保護された HTTP/2 エンドポイントが指定されています。

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

または、Program.cs 内に Kestrel エンドポイントを構成することもできます。

var builder = WebApplication.CreateBuilder(args);

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

Kestrel で TLS を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

プロトコル ネゴシエーション

TLS は、通信のセキュリティ保護以外にも使用されます。 エンドポイントで複数のプロトコルがサポートされている場合、クライアントとサーバー間の接続プロトコルをネゴシエートするために TLS ALPN (Application-Layer Protocol Negotiation) ハンドシェイクが使用されます。 このネゴシエーションでは、HTTP/1.1 または HTTP/2 のどちらが接続に使用されるかを判断します。

HTTP/2 エンドポイントが TLS を使用せずに構成されている場合は、エンドポイントの ListenOptions.ProtocolsHttpProtocols.Http2 に設定する必要があります。 複数のプロトコル (HttpProtocols.Http1AndHttp2 など) を持つエンドポイントは、ネゴシエーションがないため、TLS なしで使用することはできません。 セキュリティで保護されていないエンドポイントへの接続はすべて、既定で HTTP/1.1 に設定されるため、gRPC の呼び出しは失敗します。

Kestrel で HTTP/2 および TLS を有効にする方法について詳しくは、Kestrel のエンドポイント構成に関するページをご覧ください。

Note

macOS では、.NET 8 より前の ASP.NET Core gRPC と TLS はサポートされていません。 .NET 7 以前を使っているときに、macOS で gRPC サービスを正常に実行するには、追加の構成が必要です。 詳細については、macOS で ASP.NET Core gRPC アプリを起動できない場合に関するページを参照してください。

IIS

インターネット インフォメーション サービス (IIS) は、Web アプリ (ASP.NET Core を含む) をホストするための、柔軟かつ安全で管理しやすい Web サーバーです。 IIS で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

IIS は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、「IIS 上で HTTP/2 と共に ASP.NET Core を使用する」を参照してください。

HTTP.sys

HTTP.sys は、Windows 上でのみ動作する ASP.NET Core 用 Web サーバーです。 HTTP.sys で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

HTTP.sys は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、HTTP.sys Web サーバーの HTTP/2 サポートに関する記事を参照してください。

non-ASP.NET Core プロジェクトで gRPC をホストする

通常、ASP.NET Core gRPC サーバーは、gRPC テンプレートから作成されます。 テンプレートによって作成されたプロジェクト ファイルでは、SDK として Microsoft.NET.SDK.Web が使用されます。

<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 サーバーを non-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 サービスには、依存関係の挿入 (DI) やログ記録などの ASP.NET Core 機能へのフル アクセスがあります。 たとえば、サービスの実装では、コンストラクターを使用して DI コンテナーから logger サービスを解決できます。

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

既定では、gRPC サービスの実装では、任意の有効期間 (シングルトン、スコープ、または一時的) を持つ他の DI サービスを解決できます。

gRPC メソッドで HttpContext を解決する

gRPC API は、メソッド、ホスト、ヘッダー、トレーラーなど、一部の HTTP/2 メッセージ データへのアクセスを提供します。 アクセスには、各 gRPC メソッドに渡される ServerCallContext 引数が使用されます。

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

ServerCallContext を使用しても、すべての ASP.NET API で HttpContext へのフル アクセスが提供されるわけではありません。 GetHttpContext 拡張メソッドを使用すると、ASP.NET API で基となる HTTP/2 メッセージを表す HttpContext にフル アクセスできます。

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

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

その他の技術情報

このドキュメントでは、ASP.NET Core を使用して gRPC サービスを開始する方法について説明します。

必須コンポーネント

ASP.NET Core の gRPC サービスの概要

サンプル コードを表示またはダウンロードします (ダウンロード方法)。

gRPC プロジェクトを作成する詳細な手順については、gRPC サービスの概要に関するページをご覧ください。

ASP.NET Core アプリに gRPC サービスを追加する

gRPC には Grpc. AspNetCore パッケージが必要です。

gRPC を構成する

Program.cs:

  • gRPC を有効にするには、AddGrpc メソッドを使用します。
  • 各 gRPC サービスをルーティング パイプラインに追加するには、MapGrpcService メソッドを使用します。
using GrpcGreeter.Services;

var builder = WebApplication.CreateBuilder(args);

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

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

var app = builder.Build();

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

app.Run();

コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。

ルーティング パイプラインは ASP.NET Core のミドルウェアと機能で共有されるため、追加の要求ハンドラーを提供するようにアプリを構成することができます。 MVC コントローラーなどの追加の要求ハンドラーは、構成されている gRPC サービスと並行して動作します。

サーバー オプション

gRPC サービスは、すべての組み込み ASP.NET Core サーバーによってホストできます。

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

†.NET 5 および Windows 11 ビルド 22000 または Windows Server 2022 ビルド 20348 以降が必要です。

ASP.NET Core アプリに使用する適切なサーバーの選択について詳しくは、「ASP.NET Core での Web サーバーの実装」を参照してください。

Kestrel

Kestrel は、ASP.NET Core 向けのクロスプラットフォーム Web サーバーです。 Kestrel は、ハイ パフォーマンスとメモリ使用率に重点を置いていますが、ポート共有などの HTTP.sys の高度な機能の一部はありません。

Kestrel gRPC エンドポイント:

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequestHTTP/2 であるかを検証します。

Kestrelは、最新のオペレーティング システムで HTTP/2 をサポートしています。 Kestrel エンドポイントは、既定で HTTP/1.1 接続と HTTP/2 接続をサポートするように構成されています。

TLS

gRPC に使用される Kestrel エンドポイントは、TLS で保護されている必要があります。 開発環境では、ASP.NET Core 開発証明書が存在する場合に、TLS で保護されたエンドポイントが https://localhost:5001 に自動的に作成されます。 構成は必要ありません。 https プレフィックスによって、Kestrel エンドポイントが TLS を使用していることが確認されます。

運用環境では、TLS を明示的に構成する必要があります。 次の appsettings.json の例では、TLS で保護された HTTP/2 エンドポイントが指定されています。

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

または、Program.cs 内に Kestrel エンドポイントを構成することもできます。

var builder = WebApplication.CreateBuilder(args);

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

Kestrel で TLS を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

プロトコル ネゴシエーション

TLS は、通信のセキュリティ保護以外にも使用されます。 エンドポイントで複数のプロトコルがサポートされている場合、クライアントとサーバー間の接続プロトコルをネゴシエートするために TLS ALPN (Application-Layer Protocol Negotiation) ハンドシェイクが使用されます。 このネゴシエーションでは、HTTP/1.1 または HTTP/2 のどちらが接続に使用されるかを判断します。

HTTP/2 エンドポイントが TLS を使用せずに構成されている場合は、エンドポイントの ListenOptions.ProtocolsHttpProtocols.Http2 に設定する必要があります。 複数のプロトコル (HttpProtocols.Http1AndHttp2 など) を持つエンドポイントは、ネゴシエーションがないため、TLS なしで使用することはできません。 セキュリティで保護されていないエンドポイントへの接続はすべて、既定で HTTP/1.1 に設定されるため、gRPC の呼び出しは失敗します。

Kestrel で HTTP/2 および TLS を有効にする方法について詳しくは、Kestrel のエンドポイント構成に関するページをご覧ください。

Note

macOS では、.NET 8 より前の ASP.NET Core gRPC と TLS はサポートされていません。 .NET 7 以前を使っているときに、macOS で gRPC サービスを正常に実行するには、追加の構成が必要です。 詳細については、macOS で ASP.NET Core gRPC アプリを起動できない場合に関するページを参照してください。

IIS

インターネット インフォメーション サービス (IIS) は、Web アプリ (ASP.NET Core を含む) をホストするための、柔軟かつ安全で管理しやすい Web サーバーです。 IIS で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

IIS は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、「IIS 上で HTTP/2 と共に ASP.NET Core を使用する」を参照してください。

HTTP.sys

HTTP.sys は、Windows 上でのみ動作する ASP.NET Core 用 Web サーバーです。 HTTP.sys で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

HTTP.sys は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、HTTP.sys Web サーバーの HTTP/2 サポートに関する記事を参照してください。

non-ASP.NET Core プロジェクトで gRPC をホストする

通常、ASP.NET Core gRPC サーバーは、gRPC テンプレートから作成されます。 テンプレートによって作成されたプロジェクト ファイルでは、SDK として Microsoft.NET.SDK.Web が使用されます。

<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 サーバーを non-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 サービスには、依存関係の挿入 (DI) やログ記録などの ASP.NET Core 機能へのフル アクセスがあります。 たとえば、サービスの実装では、コンストラクターを使用して DI コンテナーから logger サービスを解決できます。

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

既定では、gRPC サービスの実装では、任意の有効期間 (シングルトン、スコープ、または一時的) を持つ他の DI サービスを解決できます。

gRPC メソッドで HttpContext を解決する

gRPC API は、メソッド、ホスト、ヘッダー、トレーラーなど、一部の HTTP/2 メッセージ データへのアクセスを提供します。 アクセスには、各 gRPC メソッドに渡される ServerCallContext 引数が使用されます。

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

ServerCallContext を使用しても、すべての ASP.NET API で HttpContext へのフル アクセスが提供されるわけではありません。 GetHttpContext 拡張メソッドを使用すると、ASP.NET API で基となる HTTP/2 メッセージを表す HttpContext にフル アクセスできます。

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

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

その他の技術情報

このドキュメントでは、ASP.NET Core を使用して gRPC サービスを開始する方法について説明します。

必須コンポーネント

ASP.NET Core の gRPC サービスの概要

サンプル コードを表示またはダウンロードします (ダウンロード方法)。

gRPC プロジェクトを作成する詳細な手順については、gRPC サービスの概要に関するページをご覧ください。

ASP.NET Core アプリに gRPC サービスを追加する

gRPC には Grpc. AspNetCore パッケージが必要です。

gRPC を構成する

Startup.cs:

  • gRPC を有効にするには、AddGrpc メソッドを使用します。
  • 各 gRPC サービスをルーティング パイプラインに追加するには、MapGrpcService メソッドを使用します。
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

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

        app.UseRouting();

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

コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。

ルーティング パイプラインは ASP.NET Core のミドルウェアと機能で共有されるため、追加の要求ハンドラーを提供するようにアプリを構成することができます。 MVC コントローラーなどの追加の要求ハンドラーは、構成されている gRPC サービスと並行して動作します。

サーバー オプション

gRPC サービスは、すべての組み込み ASP.NET Core サーバーによってホストできます。

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

†.NET 5 および Windows 11 ビルド 22000 または Windows Server 2022 ビルド 20348 以降が必要です。

ASP.NET Core アプリに使用する適切なサーバーの選択について詳しくは、「ASP.NET Core での Web サーバーの実装」を参照してください。

Kestrel

Kestrel は、ASP.NET Core 向けのクロスプラットフォーム Web サーバーです。 Kestrel は、ハイ パフォーマンスとメモリ使用率に重点を置いていますが、ポート共有などの HTTP.sys の高度な機能の一部はありません。

Kestrel gRPC エンドポイント:

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequestHTTP/2 であるかを検証します。

Kestrelは、最新のオペレーティング システムで HTTP/2 をサポートしています。 Kestrel エンドポイントは、既定で HTTP/1.1 接続と HTTP/2 接続をサポートするように構成されています。

TLS

gRPC に使用される Kestrel エンドポイントは、TLS で保護されている必要があります。 開発環境では、ASP.NET Core 開発証明書が存在する場合に、TLS で保護されたエンドポイントが https://localhost:5001 に自動的に作成されます。 構成は必要ありません。 https プレフィックスによって、Kestrel エンドポイントが TLS を使用していることが確認されます。

運用環境では、TLS を明示的に構成する必要があります。 次の appsettings.json の例では、TLS で保護された HTTP/2 エンドポイントが指定されています。

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

または、Program.cs 内に Kestrel エンドポイントを構成することもできます。

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

Kestrel で TLS を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

プロトコル ネゴシエーション

TLS は、通信のセキュリティ保護以外にも使用されます。 エンドポイントで複数のプロトコルがサポートされている場合、クライアントとサーバー間の接続プロトコルをネゴシエートするために TLS ALPN (Application-Layer Protocol Negotiation) ハンドシェイクが使用されます。 このネゴシエーションでは、HTTP/1.1 または HTTP/2 のどちらが接続に使用されるかを判断します。

HTTP/2 エンドポイントが TLS を使用せずに構成されている場合は、エンドポイントの ListenOptions.ProtocolsHttpProtocols.Http2 に設定する必要があります。 複数のプロトコル (HttpProtocols.Http1AndHttp2 など) を持つエンドポイントは、ネゴシエーションがないため、TLS なしで使用することはできません。 セキュリティで保護されていないエンドポイントへの接続はすべて、既定で HTTP/1.1 に設定されるため、gRPC の呼び出しは失敗します。

Kestrel で HTTP/2 および TLS を有効にする方法について詳しくは、Kestrel のエンドポイント構成に関するページをご覧ください。

Note

macOS では、.NET 8 より前の ASP.NET Core gRPC と TLS はサポートされていません。 .NET 7 以前を使っているときに、macOS で gRPC サービスを正常に実行するには、追加の構成が必要です。 詳細については、macOS で ASP.NET Core gRPC アプリを起動できない場合に関するページを参照してください。

IIS

インターネット インフォメーション サービス (IIS) は、Web アプリ (ASP.NET Core を含む) をホストするための、柔軟かつ安全で管理しやすい Web サーバーです。 IIS で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

IIS は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、「IIS 上で HTTP/2 と共に ASP.NET Core を使用する」を参照してください。

HTTP.sys

HTTP.sys は、Windows 上でのみ動作する ASP.NET Core 用 Web サーバーです。 HTTP.sys で gRPC サービスをホストするには、.NET 5 および Windows 11 ビルド 22000 以降または Windows Server 2022 ビルド 20348 以降が必要です。

HTTP.sys は、TLS と HTTP/2 を使用するように構成する必要があります。 詳細については、HTTP.sys Web サーバーの HTTP/2 サポートに関する記事を参照してください。

non-ASP.NET Core プロジェクトで gRPC をホストする

通常、ASP.NET Core gRPC サーバーは、gRPC テンプレートから作成されます。 テンプレートによって作成されたプロジェクト ファイルでは、SDK として Microsoft.NET.SDK.Web が使用されます。

<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 サーバーを non-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 サービスには、依存関係の挿入 (DI) やログ記録などの ASP.NET Core 機能へのフル アクセスがあります。 たとえば、サービスの実装では、コンストラクターを使用して DI コンテナーから logger サービスを解決できます。

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

既定では、gRPC サービスの実装では、任意の有効期間 (シングルトン、スコープ、または一時的) を持つ他の DI サービスを解決できます。

gRPC メソッドで HttpContext を解決する

gRPC API は、メソッド、ホスト、ヘッダー、トレーラーなど、一部の HTTP/2 メッセージ データへのアクセスを提供します。 アクセスには、各 gRPC メソッドに渡される ServerCallContext 引数が使用されます。

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

ServerCallContext を使用しても、すべての ASP.NET API で HttpContext へのフル アクセスが提供されるわけではありません。 GetHttpContext 拡張メソッドを使用すると、ASP.NET API で基となる HTTP/2 メッセージを表す HttpContext にフル アクセスできます。

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

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

その他の技術情報

このドキュメントでは、ASP.NET Core を使用して gRPC サービスを開始する方法について説明します。

必須コンポーネント

ASP.NET Core の gRPC サービスの概要

サンプル コードを表示またはダウンロードします (ダウンロード方法)。

gRPC プロジェクトを作成する詳細な手順については、gRPC サービスの概要に関するページをご覧ください。

ASP.NET Core アプリに gRPC サービスを追加する

gRPC には Grpc. AspNetCore パッケージが必要です。

gRPC を構成する

Startup.cs:

  • gRPC を有効にするには、AddGrpc メソッドを使用します。
  • 各 gRPC サービスをルーティング パイプラインに追加するには、MapGrpcService メソッドを使用します。
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

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

        app.UseRouting();

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

コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。

ルーティング パイプラインは ASP.NET Core のミドルウェアと機能で共有されるため、追加の要求ハンドラーを提供するようにアプリを構成することができます。 MVC コントローラーなどの追加の要求ハンドラーは、構成されている gRPC サービスと並行して動作します。

サーバー オプション

gRPC サービスは、すべての組み込み ASP.NET Core サーバーによってホストできます。

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

†.NET 5 および Windows 11 ビルド 22000 または Windows Server 2022 ビルド 20348 以降が必要です。

ASP.NET Core アプリに使用する適切なサーバーの選択について詳しくは、「ASP.NET Core での Web サーバーの実装」を参照してください。

Kestrel

Kestrel は、ASP.NET Core 向けのクロスプラットフォーム Web サーバーです。 Kestrel は、ハイ パフォーマンスとメモリ使用率に重点を置いていますが、ポート共有などの HTTP.sys の高度な機能の一部はありません。

Kestrel gRPC エンドポイント:

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequestHTTP/2 であるかを検証します。

Kestrelは、最新のオペレーティング システムで HTTP/2 をサポートしています。 Kestrel エンドポイントは、既定で HTTP/1.1 接続と HTTP/2 接続をサポートするように構成されています。

TLS

gRPC に使用される Kestrel エンドポイントは、TLS で保護されている必要があります。 開発環境では、ASP.NET Core 開発証明書が存在する場合に、TLS で保護されたエンドポイントが https://localhost:5001 に自動的に作成されます。 構成は必要ありません。 https プレフィックスによって、Kestrel エンドポイントが TLS を使用していることが確認されます。

運用環境では、TLS を明示的に構成する必要があります。 次の appsettings.json の例では、TLS で保護された HTTP/2 エンドポイントが指定されています。

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

または、Program.cs 内に Kestrel エンドポイントを構成することもできます。

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

Kestrel で TLS を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

プロトコル ネゴシエーション

TLS は、通信のセキュリティ保護以外にも使用されます。 エンドポイントで複数のプロトコルがサポートされている場合、クライアントとサーバー間の接続プロトコルをネゴシエートするために TLS ALPN (Application-Layer Protocol Negotiation) ハンドシェイクが使用されます。 このネゴシエーションでは、HTTP/1.1 または HTTP/2 のどちらが接続に使用されるかを判断します。

HTTP/2 エンドポイントが TLS を使用せずに構成されている場合は、エンドポイントの ListenOptions.ProtocolsHttpProtocols.Http2 に設定する必要があります。 複数のプロトコル (HttpProtocols.Http1AndHttp2 など) を持つエンドポイントは、ネゴシエーションがないため、TLS なしで使用することはできません。 セキュリティで保護されていないエンドポイントへの接続はすべて、既定で HTTP/1.1 に設定されるため、gRPC の呼び出しは失敗します。

Kestrel で HTTP/2 および TLS を有効にする方法について詳しくは、Kestrel のエンドポイント構成に関するページをご覧ください。

Note

macOS では、.NET 8 より前の ASP.NET Core gRPC と TLS はサポートされていません。 .NET 7 以前を使っているときに、macOS で gRPC サービスを正常に実行するには、追加の構成が必要です。 詳細については、macOS で ASP.NET Core gRPC アプリを起動できない場合に関するページを参照してください。

non-ASP.NET Core プロジェクトで gRPC をホストする

通常、ASP.NET Core gRPC サーバーは、gRPC テンプレートから作成されます。 テンプレートによって作成されたプロジェクト ファイルでは、SDK として Microsoft.NET.SDK.Web が使用されます。

<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 サーバーを non-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 サービスには、依存関係の挿入 (DI) やログ記録などの ASP.NET Core 機能へのフル アクセスがあります。 たとえば、サービスの実装では、コンストラクターを使用して DI コンテナーから logger サービスを解決できます。

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

既定では、gRPC サービスの実装では、任意の有効期間 (シングルトン、スコープ、または一時的) を持つ他の DI サービスを解決できます。

gRPC メソッドで HttpContext を解決する

gRPC API は、メソッド、ホスト、ヘッダー、トレーラーなど、一部の HTTP/2 メッセージ データへのアクセスを提供します。 アクセスには、各 gRPC メソッドに渡される ServerCallContext 引数が使用されます。

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

ServerCallContext を使用しても、すべての ASP.NET API で HttpContext へのフル アクセスが提供されるわけではありません。 GetHttpContext 拡張メソッドを使用すると、ASP.NET API で基となる HTTP/2 メッセージを表す HttpContext にフル アクセスできます。

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

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

その他の技術情報

このドキュメントでは、ASP.NET Core を使用して gRPC サービスを開始する方法について説明します。

必須コンポーネント

ASP.NET Core の gRPC サービスの概要

サンプル コードを表示またはダウンロードします (ダウンロード方法)。

gRPC プロジェクトを作成する詳細な手順については、gRPC サービスの概要に関するページをご覧ください。

ASP.NET Core アプリに gRPC サービスを追加する

gRPC には Grpc. AspNetCore パッケージが必要です。

gRPC を構成する

Startup.cs:

  • gRPC を有効にするには、AddGrpc メソッドを使用します。
  • 各 gRPC サービスをルーティング パイプラインに追加するには、MapGrpcService メソッドを使用します。
public class Startup
{
    // This method gets called by the runtime. Use this method to add services to the container.
    // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddGrpc();
    }

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

        app.UseRouting();

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

コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。

ルーティング パイプラインは ASP.NET Core のミドルウェアと機能で共有されるため、追加の要求ハンドラーを提供するようにアプリを構成することができます。 MVC コントローラーなどの追加の要求ハンドラーは、構成されている gRPC サービスと並行して動作します。

サーバー オプション

gRPC サービスは、すべての組み込み ASP.NET Core サーバーによってホストできます。

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

†.NET 5 および Windows 11 ビルド 22000 または Windows Server 2022 ビルド 20348 以降が必要です。

ASP.NET Core アプリに使用する適切なサーバーの選択について詳しくは、「ASP.NET Core での Web サーバーの実装」を参照してください。

Kestrel

Kestrel は、ASP.NET Core 向けのクロスプラットフォーム Web サーバーです。 Kestrel は、ハイ パフォーマンスとメモリ使用率に重点を置いていますが、ポート共有などの HTTP.sys の高度な機能の一部はありません。

Kestrel gRPC エンドポイント:

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequestHTTP/2 であるかを検証します。

Kestrelは、最新のオペレーティング システムで HTTP/2 をサポートしています。 Kestrel エンドポイントは、既定で HTTP/1.1 接続と HTTP/2 接続をサポートするように構成されています。

TLS

gRPC に使用される Kestrel エンドポイントは、TLS で保護されている必要があります。 開発環境では、ASP.NET Core 開発証明書が存在する場合に、TLS で保護されたエンドポイントが https://localhost:5001 に自動的に作成されます。 構成は必要ありません。 https プレフィックスによって、Kestrel エンドポイントが TLS を使用していることが確認されます。

運用環境では、TLS を明示的に構成する必要があります。 次の appsettings.json の例では、TLS で保護された HTTP/2 エンドポイントが指定されています。

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

または、Program.cs 内に Kestrel エンドポイントを構成することもできます。

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

Kestrel で TLS を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

プロトコル ネゴシエーション

TLS は、通信のセキュリティ保護以外にも使用されます。 エンドポイントで複数のプロトコルがサポートされている場合、クライアントとサーバー間の接続プロトコルをネゴシエートするために TLS ALPN (Application-Layer Protocol Negotiation) ハンドシェイクが使用されます。 このネゴシエーションでは、HTTP/1.1 または HTTP/2 のどちらが接続に使用されるかを判断します。

HTTP/2 エンドポイントが TLS を使用せずに構成されている場合は、エンドポイントの ListenOptions.ProtocolsHttpProtocols.Http2 に設定する必要があります。 複数のプロトコル (HttpProtocols.Http1AndHttp2 など) を持つエンドポイントは、ネゴシエーションがないため、TLS なしで使用することはできません。 セキュリティで保護されていないエンドポイントへの接続はすべて、既定で HTTP/1.1 に設定されるため、gRPC の呼び出しは失敗します。

Kestrel で HTTP/2 および TLS を有効にする方法について詳しくは、Kestrel のエンドポイント構成に関するページをご覧ください。

Note

macOS では、.NET 8 より前の ASP.NET Core gRPC と TLS はサポートされていません。 .NET 7 以前を使っているときに、macOS で gRPC サービスを正常に実行するには、追加の構成が必要です。 詳細については、macOS で ASP.NET Core gRPC アプリを起動できない場合に関するページを参照してください。

non-ASP.NET Core プロジェクトで gRPC をホストする

通常、ASP.NET Core gRPC サーバーは、gRPC テンプレートから作成されます。 テンプレートによって作成されたプロジェクト ファイルでは、SDK として Microsoft.NET.SDK.Web が使用されます。

<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 サーバーを non-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 サービスには、依存関係の挿入 (DI) やログ記録などの ASP.NET Core 機能へのフル アクセスがあります。 たとえば、サービスの実装では、コンストラクターを使用して DI コンテナーから logger サービスを解決できます。

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

既定では、gRPC サービスの実装では、任意の有効期間 (シングルトン、スコープ、または一時的) を持つ他の DI サービスを解決できます。

gRPC メソッドで HttpContext を解決する

gRPC API は、メソッド、ホスト、ヘッダー、トレーラーなど、一部の HTTP/2 メッセージ データへのアクセスを提供します。 アクセスには、各 gRPC メソッドに渡される ServerCallContext 引数が使用されます。

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

ServerCallContext を使用しても、すべての ASP.NET API で HttpContext へのフル アクセスが提供されるわけではありません。 GetHttpContext 拡張メソッドを使用すると、ASP.NET API で基となる HTTP/2 メッセージを表す HttpContext にフル アクセスできます。

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

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

その他の技術情報