grpc / grpc-dotnet

gRPC for .NET

gRPC – An RPC library and framework

gRPC is a modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere. gRPC enables client and server applications to communicate transparently, and simplifies the building of connected systems.

Homepage:	grpc.io
Mailing List:	[email protected]

To start using gRPC

To maximize usability, gRPC supports the standard method for adding dependencies to a user's chosen language (if there is one). In most languages, the gRPC runtime comes as a package available in a user's language package manager.

For instructions on how to use the language-specific gRPC runtime for a project, please refer to these documents

• C++: follow the instructions under the src/cpp directory
• C#/.NET: NuGet packages Grpc.Net.Client, Grpc.AspNetCore.Server
• Dart: pub package grpc
• Go: go get google.golang.org/grpc
• Java: Use JARs from Maven Central Repository
• Kotlin: Use JARs from Maven Central Repository
• Node: npm install @grpc/grpc-js
• Objective-C: Add gRPC-ProtoRPC dependency to podspec
• PHP: pecl install grpc
• Python: pip install grpcio
• Ruby: gem install grpc
• WebJS: follow the grpc-web instructions

Per-language quickstart guides and tutorials can be found in the documentation section on the grpc.io website. Code examples are available in the examples directory.

Precompiled bleeding-edge package builds of gRPC master branch's HEAD are uploaded daily to packages.grpc.io.

To start developing gRPC

Contributions are welcome!

Please read How to contribute which will guide you through the entire workflow of how to build the source code, how to run the tests, and how to contribute changes to the gRPC codebase. The "How to contribute" document also contains info on how the contribution process works and contains best practices for creating contributions.

Troubleshooting

Sometimes things go wrong. Please check out the Troubleshooting guide if you are experiencing issues with gRPC.

Performance

See the Performance dashboard for performance numbers of master branch daily builds.

Concepts

See gRPC Concepts

About This Repository

This repository contains source code for gRPC libraries implemented in multiple languages written on top of a shared C++ core library src/core.

Libraries in different languages may be in various states of development. We are seeking contributions for all of these libraries:

Language	Source
Shared C++ [core library]	src/core
C++	src/cpp
Ruby	src/ruby
Python	src/python
PHP	src/php
C# (core library based)	src/csharp
Objective-C	src/objective-c

Language	Source repo
Java	grpc-java
Kotlin	grpc-kotlin
Go	grpc-go
NodeJS	grpc-node
WebJS	grpc-web
Dart	grpc-dart
.NET (pure C# impl.)	grpc-dotnet
Swift	grpc-swift

grpc-dotnet's Issues

Setting up infrastructure to build and test

cc @jtattermusch can you help us set this up?

Use pipelines instead of request/response streams

Reading and writing messages with pipelines should provide a performance benefit over using the traditional streams on HttpRequest/HttpResponse.

This is currently blocked. Pipelines will be available with preview 2 - dotnet/aspnetcore#3973

Support poco class as dto without proto file.

Add marker service for AddGrpc to provide a good error message when it is not called

Handle scenario of user not calling AddGrpc. Refer to how SignalR/MVC do this.

Set up benchmark scenarios

This issue will track the work needed to set up benchmarking scenarios on our side for grpc-dotnet. More details to follow. This will help us compare performance metrics against existing implementation as well as track improvements when we optimize the implementation.

cc @shirhatti @JamesNK

Design decision: Singleton vs per request service

Current grpc .NET implementation has a singleton service
ASP.NET Core creates endpoint instances per request, e.g. controllers and service hub

We would prefer per request to support scoped DI scenarios, e.g. DB context

Make a design decision.

Create grpc templates

• Identify what templates. Initial proposal: client, client/server, server
• Decide on languages supported. C# only or add F#
• Create new templates (in aspnet/templates?)
• Decide on default proto file location
• How are proto files referenced by client project (e.g. service reference?)

grpc sandbox cleanup - Invoking method performance

Sandbox currently invokes service method using reflection.

Should reuse ASP.NET Core infrastructure (it is used by MVC and SignalR to invoke actions/methods. Well tested, good performance, handles async)

Create nightly feed for upstream packages

To share updates between grpc/grpc and grpc/grpc-dotnet, we should create a nightly NuGet feed where upstream changes are pushed as part of the build. This is one proposal, but we're open to other ideas

Evaluate design time compilation performance

Determine whether design time compilation is feasible for realistic/large projects. The recommendation is to test using the proto files from Google's repo: https://github.com/googleapis/googleapis/tree/master/google.

Support gRPC timeout

gRPC supports timeouts

https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md - grpc-timeout

https://grpc.io/blog/deadlines

Exposed as ServerCallContext.Deadline. Will need to populate from the header.

Accessing HttpContext in a gRPC service call

gRPC C# offers the ServerCallContext with information about the current call. Currently there is no way access the underlying HttpContext from service methods.

• Decide if HttpContext should be accessible
  • Service base class?
  • Service interface?
  • Include it as part of ServerCallContext. Get with extension method?
• Implementation

Support compression

The ASP.NET Core prototype does not support compression.

https://github.com/grpc/grpc/blob/master/doc/compression.md

BindService should not require a concrete instance of the GRPC service implementation

Currently we need an instance of the service implementation to call BindService and we are creating a dummy instance to bind the service right now: https://github.com/JunTaoLuo/GrpcSandbox/blob/105f2bc65ad1b6b642a62bec31789315936c78b2/Server/Dotnet/GrpcRouteBuilderExtensions.cs#L34-L36. Since we are exploring the use of Scoped services, we may not have an instance until the request is in flight.

Fix copyright headers

We updated the required format of copyright header a while ago.

The old format

#region Copyright notice and license

// Copyright 2015 gRPC authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#endregion

The new format

#region Copyright notice and license

// Copyright 2018 The gRPC Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#endregion

Note the first line is different: Copyright 2018 The gRPC Authors.
Also the year should be the year the file was created (2019 in our case).

Support interceptors in AspNetCore.Server

https://github.com/grpc/proposal/blob/master/L12-csharp-interceptors.md

https://grpc.io/grpc/csharp/api/Grpc.Core.Interceptors.html

Test that basic interoperability tests are passing

To ensure gRPC works well cross-language, we have a set of test cases that need to pass when ran against other gRPC implementations.

https://github.com/grpc/grpc/blob/master/doc/interop-test-descriptions.md

For "basic RPC support" (originally required for "alpha" version level of gRPC) these tests need to pass:

• empty_unary
• large_unary
• client_streaming
• server_streaming
• ping_pong
• empty_stream

A more "advanced RPC support" (still necessary for the library to be useful) - mostly things like timeouts, cancellation, RPC metadata...

• custom_metadata
• status_code_and_message
• special_status_message
• unimplemented_method
• unimplemented_service
• cancel_after_begin
• cancel_after_first_response
• timeout_on_sleeping_server

The test need to also with both secure insecure connections.
on grpc/grpc repository we have a test framework that can run these interop tests cross-language once they are implemented.

There is also a bunch of "auth" tests, but those are client-side only (so not a requirement for server-side AspNetCore support).

Correlate service calls through ContextPropagationToken

We need to explore the API required to trace service call by propagating the ContextPropagationToken. The goal is to be able to trace an entire call chain, regardless of implementation.

Update to .NET Core 3.0 preview 2

Serialization API - efficiency

Consider providing an extension point allowing users to configure serialization libraries other than Google.Protobuf.

Grpc.Core already offers an abstraction layer that we can use.

Issue is for discussing improving it and Google.Protobuf (default serialization layer)

Start from #30 (comment)

determine code style to use for Grpc.AspNetCore

Grpc.Core currently has code style that's different from AspNetCore code style. What code style do we use for Grpc.AspNetCore?

Node: Grpc.Core currently doesn't have an automatic code style enforcement in place (we used to use StyleCop, but that's probably out of date now), so this might be an opportunity to adopt code style and enforcement tooling from AspNetCore.

Design experience review

Organize design experience review once we have a MVP

Maximum request and response message size settings

https://grpc.io/grpc/csharp/api/Grpc.Core.ChannelOptions.html#Grpc_Core_ChannelOptions_MaxReceiveMessageLength

https://grpc.io/grpc/csharp/api/Grpc.Core.ChannelOptions.html#Grpc_Core_ChannelOptions_MaxSendMessageLength

Server logging

Ensure we have sufficient server logging with appropriate log levels

Distribution and sharing of proto files between servers and clients

Splitting off the service reference consideration from #5. Service reference is a mechanism that could be leveraged to better support .proto file sharing between servers and clients. We may want to use this as part of #8 to illustrate its use for client and server templates.

Managed client using HttpClient

This issue tracks the work required to provide a complete managed end to end experience. This is going to be blocked on Core support for trailing response header support. cc @shirhatti for an expected timeframe.

Also, I'm not certain we need to change the code gen to implement this feature. I think we can pass in an HttpClient based call invoker to the constructor of the client. I don't have a client I can prototype this with yet so I'm not 100% certain but is there any reason this wouldn't work @jtattermusch @JamesNK ?

Use IAsyncEnumerable instead of IAsyncStreamReader

We should consider using the new C# 8 feature IAsyncEnumerable for streaming RPC calls.

This may need some changes in the Grpc.Core and Grpc.Core.Api packages as well cc @jtattermusch

Investigate building a language server for proto files for GRPC

This would be in addition to syntax highlighting and grammar. This would allow us to have intellisense-like language support such as auto-completion for imported message types.

Explore supporting other .NET languages

F#? VB? Let's make sure we don't paint ourselves into a corner in terms of supporting these languages while we work on the C# support.

Package signing

• Strong naming
• Authenticode signing
• nupkg signing
• Google.Protobuf nupkg/Authenticode signing

Security review

Lets review security prior to the first preview

// @blowdart

Support WriteFlags.BufferHint?

@jtattermusch Should WriteFlags.BufferHint be supported? There is no use of it in grpc/grpc

Configure MinRequestBodyDataRate when using GRPC

We need to disable MinRequestBodyDataRate rate limit checks to support streaming RPCs. We should determine what's the most natural way to do this for the Kestrel Server when GRPC services are being used.

Ensure we dispose of gRPC services that implement IDisposable

We create the service instances via https://github.com/aspnet/grpc-dotnet/blob/12678029b842f2993f8267556700ce91beba4b98/src/Grpc.AspNetCore.Server/Internal/DefaultGrpcServiceActivator.cs#L44. However, we currently don't do anything to dispose of it as the request ends.

Set up functional tests

Functional test website and unit tests

Make the ServerCallHandler Pipe aware

Current implementation at https://github.com/JunTaoLuo/GrpcSandbox/blob/105f2bc65ad1b6b642a62bec31789315936c78b2/Server/Internal/ServerCallHandler.cs uses streams, we'd like to convert this to Pipes. Related issue: dotnet/aspnetcore#4697

cc @jkotalik

Add support for Go To Definition in VS

Go To Definition on a concrete implementation on a service will take you the generated code in the obj folder.
We should investigate if there are enough hooks in the project system that'll allow us to link directly to the proto files.

Grpc.Tools changes for DesignTime Builds

One of the work items in #5. The work required to support design time compilation is listed in:
https://github.com/JunTaoLuo/GrpcSandbox/blob/master/Clients/Chatter/Chatter.csproj#L10-L14

Add instructions for building and running Grpc.AspNetCore.Server and the samples

as a README.md which has some basic instructions:

• one paragraph about Grpc.AspNetCore.Server (what it is).
• disclaimer that this is currently purely experimental (+ optionally what are the plans)
• installing the required ASP.NET core preview version + other prerequisites
• how to build, run tests, run example
• a very basic info how to use (one snippet is enough).

Syntax support in VS and VS Code

Determine if we want to add official grammar and syntax support for VS and VS Code in addition to the third party extensions currently available.

Split up gRPC C# package into API vs native implementation

For the asp.net core integration, we will need to depend on Grpc C# APIs, but we don't want to pull the native dependencies. We need to come up with a way to split the packages into managed-only (mostly APIs) and native interop.

Consider using grpc certs for interop testing

We may need to change our certs to those at https://github.com/grpc/grpc/tree/master/src/core/tsi/test_creds and https://github.com/grpc/grpc/tree/master/src/csharp/Grpc.IntegrationTesting/data in the future for interop testing scenarios.

Instantiation of ServerCallContext shouldn't require Grpc.Core.Testing nuget

asp.net core integration will need to create instances of ServerCallContext that will be passed to server-side method implementations,but the constructor is internal-only. Currently instantiating requires Grpc.Core.Testing nuget, which is fine as a workaround, but shouldn't be required in the future.

Pass ServerCallContext to service methods

Currently ServerCallContext passed to service methods is always null.

Tasks?

• Decouple the current ServerCallContext from native
• Create an implementation for .NET
• Construct and pass to service methods

Related: grpc/grpc#17733

Tooling design

A few questions regarding grpc/grpc#13207. I didn't read through all 192 comments but I did briefly read through the code after using it in a prototype.

1. .proto files in the project directory is not compiled by default

I found this to be a deliberate decision: https://github.com/grpc/grpc/blob/master/src/csharp/Grpc.Tools/build/_protobuf/Google.Protobuf.Tools.targets#L41-L46. What was the reason for this? I don't think that comment applies here and would rather compile .proto files by default for a more frictionless experience. MSBuild properties are not very discoverable so it's best that the user doesn't have to look up the fact that you need to set EnableDefaultProtoBufItems to true to compile .proto files.

2. Design-time build

The goal here is to enable design-time build experience in VS. Currently, the *.cs files are generated when build is called, but ideally we should be generating these files when we detect *.proto files are being edited. We can enable this via Single File Generators and using the FastUpToDateCheck mechanism in VS. I see some code to this effect that I don't see running https://github.com/grpc/grpc/blob/master/src/csharp/Grpc.Tools/build/_protobuf/Google.Protobuf.Tools.targets#L370-L383 as well as code that needs to be modified https://github.com/grpc/grpc/blob/master/src/csharp/Grpc.Tools/build/_protobuf/Google.Protobuf.Tools.targets#L250. The stretch goal here may be to write a VSCode extension to enable the same design time experience.

3. Protodep

Investigate if this file can be removed. Currently it seems like it's used to communicate which files to generate (Foo.cs and FooGrpc.cs). It may be possible to substitute with MSBuild ItemGroups which is more natural and would reduce the files that are added to the /obj folder

cc @jtattermusch @shirhatti

Support gRPC cancellation

Along with deadlines, cancellation is one of the key features.

The are some interop tests to test the basic compliance: #32, but we should check cancellation behaves as expected in general.

Also see https://grpc.io/docs/guides/concepts.html#cancelling-rpcs

Decide NuGet packages, package names and namespaces

• Lock down what packages will make up .NET grpc
• NuGet package names
• Namespaces

Add logging bindings for Microsoft.Extensions.Logging

https://www.nuget.org/packages/Microsoft.Extensions.Logging/ seem to be the standard used by ASP.NET core. gRPC C# currently uses its own logging API, we will probably need an adaptor.

Error handling

Ensure we set the correct headers on error - https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md#errors

Consider an error handling API for users to catch and inspect application errors. e.g. MVC's error filtering https://docs.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-2.2#exception-filters

Capture logging in unit testing

Should capture log files during unit testing for local and CI debugging