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

[アーティクル]
11/30/2023

このドキュメントでは、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 サービスの概要に関するページをご覧ください。

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 が必要です。
トランスポート層セキュリティ (TLS) で保護されている必要があります。

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequest が HTTP/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.Protocols を HttpProtocols.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 サービスを開始する方法について説明します。

必須コンポーネント

Visual Studio 2022 と ASP.NET と Web 開発ワークロード。

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

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

Visual Studio
Visual Studio Code / Visual Studio for Mac

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 ディスカッションイシューにてお知らせください。

サーバーオプション

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 gRPC エンドポイント:

HTTP/2 が必要です。
トランスポート層セキュリティ (TLS) で保護されている必要があります。

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequest が 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 を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

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

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

Note

IIS

HTTP.sys

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

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

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

</Project>

次のプロジェクトファイル設定を使用して、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 との統合

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

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

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

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 サービスの概要に関するページをご覧ください。

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 ディスカッションイシューにてお知らせください。

サーバーオプション

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 gRPC エンドポイント:

HTTP/2 が必要です。
トランスポート層セキュリティ (TLS) で保護されている必要があります。

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequest が 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 を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

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

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

Note

IIS

HTTP.sys

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

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

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

</Project>

次のプロジェクトファイル設定を使用して、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 との統合

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

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

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

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 および Web 開発ワークロードを含む Visual Studio 2019 16.8 以降
.NET 5.0 SDK

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

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

Visual Studio
Visual Studio Code / Visual Studio for Mac

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 ディスカッションイシューにてお知らせください。

サーバーオプション

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 gRPC エンドポイント:

HTTP/2 が必要です。
トランスポート層セキュリティ (TLS) で保護されている必要があります。

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequest が 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 を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

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

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

Note

IIS

HTTP.sys

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

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

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

</Project>

次のプロジェクトファイル設定を使用して、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 との統合

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

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

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

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 および Web 開発ワークロードを含む Visual Studio 2019 16.4 以降
.NET Core 3.1 SDK

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

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

Visual Studio
Visual Studio Code / Visual Studio for Mac

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 ディスカッションイシューにてお知らせください。

サーバーオプション

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 gRPC エンドポイント:

HTTP/2 が必要です。
トランスポート層セキュリティ (TLS) で保護されている必要があります。

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequest が 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 を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

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

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

Note

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

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

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

</Project>

次のプロジェクトファイル設定を使用して、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 との統合

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

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

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

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 サービスの概要に関するページをご覧ください。

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 ディスカッションイシューにてお知らせください。

サーバーオプション

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 gRPC エンドポイント:

HTTP/2 が必要です。
トランスポート層セキュリティ (TLS) で保護されている必要があります。

HTTP/2

gRPC には HTTP/2 が必要です。 ASP.NET Core 用 gRPC は、HttpRequest が 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 を有効にする方法について詳しくは、Kestrel HTTPS エンドポイント構成に関するページを参照してください。

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

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

Note

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

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

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

</Project>

次のプロジェクトファイル設定を使用して、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 との統合

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

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

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

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 サービスの概要

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

gRPC を構成する

サーバー オプション

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

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

ASP.NET Core API との統合

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

その他の技術情報

必須コンポーネント

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

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

gRPC を構成する

サーバー オプション

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

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

ASP.NET Core API との統合

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

その他の技術情報

必須コンポーネント

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

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

gRPC を構成する

サーバー オプション

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

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

ASP.NET Core API との統合

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

その他の技術情報

必須コンポーネント

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

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

gRPC を構成する

サーバー オプション

Kestrel

HTTP/2

TLS

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

IIS

HTTP.sys

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

ASP.NET Core API との統合

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

その他の技術情報

必須コンポーネント

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

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

gRPC を構成する

サーバー オプション

Kestrel

HTTP/2

TLS

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

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

ASP.NET Core API との統合

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

その他の技術情報

必須コンポーネント

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

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

gRPC を構成する

サーバー オプション

Kestrel

サーバーオプション

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

サーバーオプション

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

サーバーオプション

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

サーバーオプション

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

サーバーオプション

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

サーバーオプション

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