From f1b2a84dba784f0eff1299f57ee521ad077d267d Mon Sep 17 00:00:00 2001 From: James Newton-King Date: Fri, 19 May 2023 20:29:59 +0800 Subject: [PATCH] Add docs for using Grpc.Tools on unsupport platforms (#29314) Co-authored-by: Eric Erhardt Co-authored-by: Rick Anderson <3605364+Rick-Anderson@users.noreply.github.com> --- aspnetcore/grpc/troubleshoot.md | 44 +++++++++++++++++++ .../troubleshoot/includes/troubleshoot3-7.md | 44 +++++++++++++++++++ 2 files changed, 88 insertions(+) diff --git a/aspnetcore/grpc/troubleshoot.md b/aspnetcore/grpc/troubleshoot.md index 11c80aa0df..e1dbdfd9ad 100644 --- a/aspnetcore/grpc/troubleshoot.md +++ b/aspnetcore/grpc/troubleshoot.md @@ -284,6 +284,50 @@ var reply = await client.SayHelloAsync(new HelloRequest { Name = ".NET" }); Alternatively, a client factory can be configured with `Http3Handler` by using . +## Building gRPC on Alpine Linux + +The `Grpc.Tools` package [generates .NET types from `.proto` files](xref:grpc/basics#generated-c-assets) using a bundled native binary called `protoc`. Additional steps are required to build gRPC apps on platforms that aren't supported by the native binaries in `Grpc.Tools`, such as Alpine Linux. + +### Generate code ahead of time + +One solution is to generate code ahead of time. + +1. Move `.proto` files and the `Grpc.Tools` package reference to a new project. +1. Publish the project as a NuGet package and upload it to a NuGet feed. +1. Update the app to reference the NuGet package. + +With the preceding steps, the app no longer requires `Grpc.Tools` to build because code is generated ahead of time. + +### Customize `Grpc.Tools` native binaries + +`Grpc.Tools` supports using custom native binaries. This feature allows gRPC tooling to run in environments its bundled native binaries don't support. + +Build or acquire `protoc` and `grpc_csharp_plugin` native binaries and configure `Grpc.Tools` to use them. Configure native binaries by setting the following environment variables: + +* `PROTOBUF_PROTOC` - Full path to the protocol buffers compiler +* `GRPC_PROTOC_PLUGIN` - Full path to the grpc_csharp_plugin + +For Alpine Linux, there are community-provided packages for the protocol buffers compiler and gRPC plugins at [https://pkgs.alpinelinux.org/](https://pkgs.alpinelinux.org/packages?name=grpc-plugins). + +```sh +# Build or install the binaries for your architecture. + +# e.g. for Alpine Linux the grpc-plugins package can be used +# See https://pkgs.alpinelinux.org/package/edge/community/x86_64/grpc-plugins +apk add grpc-plugins # Alpine Linux specific package installer + +# Set environment variables for the built/installed protoc +# and grpc_csharp_plugin binaries +export PROTOBUF_PROTOC=/usr/bin/protoc +export GRPC_PROTOC_PLUGIN=/usr/bin/grpc_csharp_plugin + +# When dotnet build runs, the Grpc.Tools NuGet package +# uses the binaries pointed to by the environment variables. +dotnet build +``` + +For more information about using `Grpc.Tools` with unsupported architectures, see the [gRPC build integration documentation](https://github.com/grpc/grpc/blob/master/src/csharp/BUILD-INTEGRATION.md#using-grpctools-with-unsupported-architectures). + :::moniker-end [!INCLUDE[](~/grpc/troubleshoot/includes/troubleshoot3-7.md)] diff --git a/aspnetcore/grpc/troubleshoot/includes/troubleshoot3-7.md b/aspnetcore/grpc/troubleshoot/includes/troubleshoot3-7.md index 73da77bab1..26da0d44eb 100644 --- a/aspnetcore/grpc/troubleshoot/includes/troubleshoot3-7.md +++ b/aspnetcore/grpc/troubleshoot/includes/troubleshoot3-7.md @@ -277,6 +277,50 @@ var reply = await client.SayHelloAsync(new HelloRequest { Name = ".NET" }); Alternatively, a client factory can be configured with `Http3Handler` by using . +## Building gRPC on Alpine Linux + +The `Grpc.Tools` package [generates .NET types from `.proto` files](xref:grpc/basics#generated-c-assets) using a bundled native binary called `protoc`. Additional steps are required to build gRPC apps on platforms that aren't supported by the native binaries in `Grpc.Tools`, such as Alpine Linux. + +### Generate code ahead of time + +One solution is to generate code ahead of time. + +1. Move `.proto` files and the `Grpc.Tools` package reference to a new project. +1. Publish the project as a NuGet package and upload it to a NuGet feed. +1. Update the app to reference the NuGet package. + +With the preceding steps, the app no longer requires `Grpc.Tools` to build because code is generated ahead of time. + +### Customize `Grpc.Tools` native binaries + +`Grpc.Tools` supports using custom native binaries. This feature allows gRPC tooling to run in environments its bundled native binaries don't support. + +Build or acquire `protoc` and `grpc_csharp_plugin` native binaries and configure `Grpc.Tools` to use them. Configure native binaries by setting the following environment variables: + +* `PROTOBUF_PROTOC` - Full path to the protocol buffers compiler +* `GRPC_PROTOC_PLUGIN` - Full path to the grpc_csharp_plugin + +For Alpine Linux, there are community-provided packages for the protocol buffers compiler and gRPC plugins at [https://pkgs.alpinelinux.org/](https://pkgs.alpinelinux.org/packages?name=grpc-plugins). + +```sh +# Build or install the binaries for your architecture. + +# e.g. for Alpine Linux the grpc-plugins package can be used +# See https://pkgs.alpinelinux.org/package/edge/community/x86_64/grpc-plugins +apk add grpc-plugins # Alpine Linux specific package installer + +# Set environment variables for the built/installed protoc +# and grpc_csharp_plugin binaries +export PROTOBUF_PROTOC=/usr/bin/protoc +export GRPC_PROTOC_PLUGIN=/usr/bin/grpc_csharp_plugin + +# When dotnet build runs, the Grpc.Tools NuGet package +# uses the binaries pointed to by the environment variables. +dotnet build +``` + +For more information about using `Grpc.Tools` with unsupported architectures, see the [gRPC build integration documentation](https://github.com/grpc/grpc/blob/master/src/csharp/BUILD-INTEGRATION.md#using-grpctools-with-unsupported-architectures). + :::moniker-end :::moniker range=">= aspnetcore-5.0 < aspnetcore-6.0"