dotnet tool NuGet v1.0.0 MIT

MetaEngine.CSharp.Protobuf.HttpClient.Tool

Protobuf 3 → an idiomatic C# gRPC-Connect client and System.Text.Json record models — HttpClient-based services over Connect-over-HTTP with a typed GrpcException, or binary gRPC clients (Grpc.Net.Client + protobuf-net) via --grpc-binary. Ships as a NuGet library plus a dotnet tool CLI.

Protobuf 3.xMetaEngine IRC# · HttpClient
Try the interactive converter
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

dotnet toolPrimaryMetaEngine.CSharp.Protobuf.HttpClient.Tool
$dotnet tool install --global MetaEngine.CSharp.Protobuf.HttpClient.Tool
v1.0.0
NuGetMetaEngine.CSharp.Protobuf.HttpClient
$dotnet add package MetaEngine.CSharp.Protobuf.HttpClient
v1.0.0
Usage

Drive it from the CLI or programmatically

dotnet tool ships a zero-config CLI. NuGet ships the same generator as a C# fluent API — same options, same output.

NuGet · dotnet tool · CI-friendly

After install, point the CLI at your schema. It writes the generated tree to your chosen output directory.

Basic syntax
terminal
metaengine-protobuf-csharp-httpclient <input> <output> <namespace> [options]

Generates an HttpClient gRPC-Connect client (System.Text.Json record models) from Protobuf 3 .proto files, or binary gRPC clients with --grpc-binary. Connect errors are always parsed into a typed GrpcException (gRPC status code + message) — there is no error-handling flag. Install with: dotnet tool install --global MetaEngine.CSharp.Protobuf.HttpClient.Tool

Quick examples
Install the dotnet tool
dotnet tool install --global MetaEngine.CSharp.Protobuf.HttpClient.Tool
Generate from a .proto file
metaengine-protobuf-csharp-httpclient ./service.proto ./Generated MyApp.Api.Client
XML docs + DI registration
metaengine-protobuf-csharp-httpclient ./service.proto ./Generated MyApp.Api.Client \
  --documentation \
  --dependency-injection
Bearer auth, retries and a tenant header from env vars
metaengine-protobuf-csharp-httpclient ./service.proto ./Generated MyApp.Api.Client \
  --bearer-auth \
  --retries 3 \
  --custom-header X-Tenant-ID=TENANT_ID
Binary gRPC clients (Grpc.Net.Client + protobuf-net)
metaengine-protobuf-csharp-httpclient ./service.proto ./Generated MyApp.Api.Client \
  --grpc-binary \
  --clean
CLI options
Option
Description
--documentation
Generate XML doc comments from proto comments
--middleware
Generate middleware infrastructure (ApiDelegatingHandler + ServiceCollectionExtensions)
--validation-annotations
Emit DataAnnotations attributes on models from protovalidate (buf.validate) constraints
--bearer-auth [ENV]
Bearer token from env var (default API_TOKEN) — adds an Authorization header to all requests
--basic-auth
Basic auth from env vars (API_USERNAME / API_PASSWORD)
--retries [N]
Enable retries with exponential backoff; optional value sets max attempts
--custom-header <H=ENV>
Static header from an env var. Repeatable. Format: <header-name>=<env-var-name>
--grpc-binary
Generate binary gRPC clients (Grpc.Net.Client + protobuf-net) instead of Connect-RPC JSON over HttpClient
--dependency-injection
Generate IServiceCollection extension methods for DI registration of typed HttpClients
--type-mapping <T=Clr>
Override a protobuf well-known type mapping. Repeatable. Format: <protobuf.Type>=<FullyQualifiedDotNetType>
--include-types <names>
Only generate these proto types (comma-separated message / enum names)
--clean
Clean the destination directory before generating
--verbose
Enable verbose logging
Options reference

Every knob, documented

Every option is available on the C# fluent API as a method, and most are also exposed as CLI flags. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

C# Output

3
  • WithMiddleware()Generate middleware infrastructure (ApiDelegatingHandler + ServiceCollectionExtensions) so auth / headers ride a DelegatingHandler
  • WithValidationAnnotations()Emit System.ComponentModel.DataAnnotations attributes on models from protovalidate (buf.validate) constraints
  • WithMethodNames(Func)Custom method naming rule with access to operation context

Auth · Headers · Resilience

9
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds an Authorization header to all requests
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token from an env var with a custom header name (e.g. X-Api-Key)
  • WithBasicAuth()HTTP Basic auth from the default env vars (API_USERNAME / API_PASSWORD)
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars, sent as a Base64 Authorization header
  • WithCustomHeader(string, string)Static header read from an env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithRetries()Retries with exponential backoff (default max 3 attempts, base delay 0.5s, max delay 30s, retry on 429 / 503)
  • WithRetries(int)Retries with a custom max-attempts count (default base 0.5s / max 30s, status 429 / 503)
  • WithRetries(int, double, double, int[])Retries with full custom settings: max attempts, base delay, max delay, and the HTTP status codes that trigger a retry

Protobuf Options

5
  • WithDocumentation()Generate XML doc comments (///) from .proto field and service descriptions
  • WithDependencyInjection()Generate IServiceCollection extension methods for DI registration of the typed HttpClients
  • WithGrpcBinary()Generate binary gRPC clients (Grpc.Net.Client + protobuf-net, [ProtoContract] / [ProtoMember] models, GrpcChannel + CallInvoker) instead of Connect-RPC JSON over HttpClient
  • WithTypeFilter(Func)Filter extracted proto types (messages + enums) before registration — only types returning true are generated
  • WithTypeMapping(string, Type)Override the .NET mapping for a protobuf well-known type by fully-qualified name (e.g. google.protobuf.Timestamp → System.DateTime)

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

2
  • Verbose()Enable verbose logging
  • WithLogger(Action<string>)Route generation log output to a custom sink
Features

Why this package is different

Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Flexible naming
Case conventions are configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed operations = major. Never a surprise in your lockfile.