C# を使用した gRPC サービス
Note
これは、この記事の最新バージョンではありません。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
警告
このバージョンの ASP.NET Core はサポート対象から除外されました。 詳細については、「.NET および .NET Core サポート ポリシー」を参照してください。 現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
重要
この情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft はここに示されている情報について、明示か黙示かを問わず、一切保証しません。
現在のリリースについては、この記事の .NET 8 バージョンを参照してください。
このドキュメントでは、C# で gRPC アプリを作成するために必要な概念を説明します。 ここで取り上げるトピックは、C-coreベースと ASP.NET Core ベースの両方の gRPC アプリに適用されます。
proto ファイル
gRPC では、API 開発に対してコントラクト優先のアプローチが使われます。 プロトコル バッファー (protobuf) は、既定でインターフェイス定義言語 (IDL) として使用されます。 .proto ファイルには、次のものが含まれます。
- gRPC サービスの定義。
- クライアントとサーバー間で送信されるメッセージ。
protobuf ファイルの構文の詳細については、「.NET アプリの Protobuf メッセージを作成する」を参照してください。
たとえば、gRPC サービスの概要に関するページで使用されている greet.proto ファイルについて考えてみます。
Greeterサービスを定義します。GreeterサービスでSayHello呼び出しを定義します。SayHelloでは、HelloRequestメッセージを送信し、HelloReplyメッセージを受信します。
syntax = "proto3";
option csharp_namespace = "GrpcGreeter";
package greet;
// The greeting service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply);
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings.
message HelloReply {
string message = 1;
}
コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。
C# アプリに .proto ファイルを追加する
.proto ファイルは、<Protobuf> 項目グループにそれを追加することで、プロジェクトに含まれます。
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
既定で、<Protobuf> 参照によって、具象クライアントとサービス基本クラスが生成されます。 参照要素の GrpcServices 属性を使用して、C# アセットの生成を制限できます。 有効な GrpcServices オプションは次のとおりです。
Both(存在しない場合の既定値)ServerClientNone
.proto ファイルに対する C# のツールのサポート
.proto ファイルから C# アセットを生成するには、ツール パッケージ Grpc.Tools が必要です。 生成されるアセット (ファイル) は:
- プロジェクトがビルドされるたびに、必要に応じて生成されます。
- プロジェクトに追加されないか、ソース管理にチェックインされません。
- obj ディレクトリに格納されるビルド成果物です。
このパッケージは、サーバー プロジェクトとクライアント プロジェクトの両方で必要です。 Grpc.AspNetCore メタパッケージには、Grpc.Tools への参照が含まれます。 サーバー プロジェクトでは、Visual Studio の Package Manager を使用するか、プロジェクト ファイルに <PackageReference> を追加することによって、Grpc.AspNetCore を追加できます。
<PackageReference Include="Grpc.AspNetCore" Version="2.32.0" />
クライアント プロジェクトでは、gRPC クライアントを使用するために必要なその他のパッケージと共に、Grpc.Tools を直接参照する必要があります。 ツール パッケージは実行時に不要であるため、依存関係に PrivateAssets="All" でマークが付けられます。
<PackageReference Include="Google.Protobuf" Version="3.18.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.52.0" />
<PackageReference Include="Grpc.Tools" Version="2.40.0">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
生成された C# アセット
ツール パッケージは、含まれている .proto ファイルに定義されたメッセージを表す C# 型を生成します。
サーバー側アセットの場合、抽象サービスの基本型が生成されます。 基本型には、 .proto ファイルに含まれるすべての gRPC 呼び出しの定義が含まれます。 この基本型から派生し、gRPC 呼び出しのロジックを実装する具象サービス実装を作成します。 greet.proto の場合、前述の例では、仮想 SayHello メソッドを含む抽象 GreeterBase 型が生成されます。 具象実装 GreeterService は、メソッドをオーバーライドし、gRPC 呼び出しを処理するロジックを実装します。
public class GreeterService : Greeter.GreeterBase
{
private readonly ILogger<GreeterService> _logger;
public GreeterService(ILogger<GreeterService> logger)
{
_logger = logger;
}
public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
クライアント側アセットの場合、具象クライアント型が生成されます。 .proto ファイル内の gRPC 呼び出しは、具象型のメソッドに変換され、これを呼び出すことができます。 greet.proto の場合、前述の例では、具象 GreeterClient 型が生成されます。 GreeterClient.SayHelloAsync を呼び出して、サーバーへの gRPC 呼び出しを開始します。
// The port number must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:7042");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
既定で、<Protobuf> 項目グループに含まれている各 .proto ファイルに対して、サーバーとクライアントのアセットが生成されます。 サーバー プロジェクトでサーバー アセットのみが生成されるようにするには、GrpcServices 属性を Server に設定します。
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
同様に、クライアントプロジェクトでは属性を Client に設定します。
その他の技術情報
このドキュメントでは、C# で gRPC アプリを作成するために必要な概念を説明します。 ここで取り上げるトピックは、C-coreベースと ASP.NET Core ベースの両方の gRPC アプリに適用されます。
proto ファイル
gRPC では、API 開発に対してコントラクト優先のアプローチが使われます。 プロトコル バッファー (protobuf) は、既定でインターフェイス定義言語 (IDL) として使用されます。 .proto ファイルには、次のものが含まれます。
- gRPC サービスの定義。
- クライアントとサーバー間で送信されるメッセージ。
protobuf ファイルの構文の詳細については、「.NET アプリの Protobuf メッセージを作成する」を参照してください。
たとえば、gRPC サービスの概要に関するページで使用されている greet.proto ファイルについて考えてみます。
Greeterサービスを定義します。GreeterサービスでSayHello呼び出しを定義します。SayHelloでは、HelloRequestメッセージを送信し、HelloReplyメッセージを受信します。
syntax = "proto3";
option csharp_namespace = "GrpcGreeter";
package greet;
// The greeting service definition.
service Greeter {
// Sends a greeting
rpc SayHello (HelloRequest) returns (HelloReply);
}
// The request message containing the user's name.
message HelloRequest {
string name = 1;
}
// The response message containing the greetings.
message HelloReply {
string message = 1;
}
コードのコメントを英語以外の言語に翻訳し表示したい場合、こちらの GitHub ディスカッション イシューにてお知らせください。
C# アプリに .proto ファイルを追加する
.proto ファイルは、<Protobuf> 項目グループにそれを追加することで、プロジェクトに含まれます。
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
既定で、<Protobuf> 参照によって、具象クライアントとサービス基本クラスが生成されます。 参照要素の GrpcServices 属性を使用して、C# アセットの生成を制限できます。 有効な GrpcServices オプションは次のとおりです。
Both(存在しない場合の既定値)ServerClientNone
.proto ファイルに対する C# のツールのサポート
.proto ファイルから C# アセットを生成するには、ツール パッケージ Grpc.Tools が必要です。 生成されるアセット (ファイル) は:
- プロジェクトがビルドされるたびに、必要に応じて生成されます。
- プロジェクトに追加されないか、ソース管理にチェックインされません。
- obj ディレクトリに格納されるビルド成果物です。
このパッケージは、サーバー プロジェクトとクライアント プロジェクトの両方で必要です。 Grpc.AspNetCore メタパッケージには、Grpc.Tools への参照が含まれます。 サーバー プロジェクトでは、Visual Studio の Package Manager を使用するか、プロジェクト ファイルに <PackageReference> を追加することによって、Grpc.AspNetCore を追加できます。
<PackageReference Include="Grpc.AspNetCore" Version="2.28.0" />
クライアント プロジェクトでは、gRPC クライアントを使用するために必要なその他のパッケージと共に、Grpc.Tools を直接参照する必要があります。 ツール パッケージは実行時に不要であるため、依存関係に PrivateAssets="All" でマークが付けられます。
<PackageReference Include="Google.Protobuf" Version="3.11.4" />
<PackageReference Include="Grpc.Net.Client" Version="2.52.0" />
<PackageReference Include="Grpc.Tools" Version="2.28.1">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>
生成された C# アセット
ツール パッケージは、含まれている .proto ファイルに定義されたメッセージを表す C# 型を生成します。
サーバー側アセットの場合、抽象サービスの基本型が生成されます。 基本型には、 .proto ファイルに含まれるすべての gRPC 呼び出しの定義が含まれます。 この基本型から派生し、gRPC 呼び出しのロジックを実装する具象サービス実装を作成します。 greet.proto の場合、前述の例では、仮想 SayHello メソッドを含む抽象 GreeterBase 型が生成されます。 具象実装 GreeterService は、メソッドをオーバーライドし、gRPC 呼び出しを処理するロジックを実装します。
public class GreeterService : Greeter.GreeterBase
{
private readonly ILogger<GreeterService> _logger;
public GreeterService(ILogger<GreeterService> logger)
{
_logger = logger;
}
public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
{
return Task.FromResult(new HelloReply
{
Message = "Hello " + request.Name
});
}
}
クライアント側アセットの場合、具象クライアント型が生成されます。 .proto ファイル内の gRPC 呼び出しは、具象型のメソッドに変換され、これを呼び出すことができます。 greet.proto の場合、前述の例では、具象 GreeterClient 型が生成されます。 GreeterClient.SayHelloAsync を呼び出して、サーバーへの gRPC 呼び出しを開始します。
static async Task Main(string[] args)
{
// The port number(5001) must match the port of the gRPC server.
using var channel = GrpcChannel.ForAddress("https://localhost:5001");
var client = new Greeter.GreeterClient(channel);
var reply = await client.SayHelloAsync(
new HelloRequest { Name = "GreeterClient" });
Console.WriteLine("Greeting: " + reply.Message);
Console.WriteLine("Press any key to exit...");
Console.ReadKey();
}
既定で、<Protobuf> 項目グループに含まれている各 .proto ファイルに対して、サーバーとクライアントのアセットが生成されます。 サーバー プロジェクトでサーバー アセットのみが生成されるようにするには、GrpcServices 属性を Server に設定します。
<ItemGroup>
<Protobuf Include="Protos\greet.proto" GrpcServices="Server" />
</ItemGroup>
同様に、クライアントプロジェクトでは属性を Client に設定します。
その他の技術情報
ASP.NET Core