1[![Nuget](https://img.shields.io/nuget/v/Grpc.svg)](http://www.nuget.org/packages/Grpc/) 2gRPC C# 3======= 4 5A C# implementation of gRPC based on the native gRPC Core library. 6 7The implementation in this directory is the original implementation of gRPC for C# (i.e. `Grpc.Core` nuget package) 8and it is currently in maintenance mode. We plan to deprecate it in the future 9in favor of the [grpc-dotnet](https://github.com/grpc/grpc-dotnet) implementation. 10See [blogpost](https://grpc.io/blog/grpc-csharp-future/) for more details. 11 12The following documentation is for the original gRPC C# implementation only (the `Grpc.Core` nuget package). 13 14SUPPORTED PLATFORMS 15------------------ 16 17- [.NET Core](https://dotnet.github.io/) on Linux, Windows and Mac OS X 18- .NET Framework 4.5+ (Windows) 19- Mono 4+ on Linux, Windows and Mac OS X 20 21PREREQUISITES 22-------------- 23 24When using gRPC C# under .NET Core you only need to [install .NET Core](https://www.microsoft.com/net/core). 25 26In addition to that, you can also use gRPC C# with these runtimes / IDEs 27- Windows: .NET Framework 4.5+, Visual Studio 2013 or newer, Visual Studio Code 28- Linux: Mono 4+, Visual Studio Code 29- Mac OS X: Mono 4+, Visual Studio Code, Visual Studio for Mac 30 31HOW TO USE 32-------------- 33 34**Windows, Linux, Mac OS X** 35 36- Open Visual Studio and start a new project/solution (alternatively, you can create a new project from command line with `dotnet` SDK) 37 38- Add the [Grpc](https://www.nuget.org/packages/Grpc/) NuGet package as a dependency (Project options -> Manage NuGet Packages). 39 40- To be able to generate code from Protocol Buffer (`.proto`) file definitions, add the [Grpc.Tools](https://www.nuget.org/packages/Grpc.Tools/) NuGet package which provides [code generation integrated into your build](BUILD-INTEGRATION.md). 41 42**Xamarin.Android and Xamarin.iOS (Experimental only)** 43 44See [Experimentally supported platforms](experimental) for instructions. 45 46**Unity (Experimental only)** 47 48See [Experimentally supported platforms](experimental) for instructions. 49 50NUGET DEVELOPMENT FEED (NIGHTLY BUILDS) 51-------------- 52 53In production, you should use officially released stable packages available on http://nuget.org, but if you want to test the newest upstream bug fixes and features early, you can use the development nuget feed where new nuget builds are uploaded nightly. 54 55Feed URL (NuGet v2): https://grpc.jfrog.io/grpc/api/nuget/grpc-nuget-dev 56 57Feed URL (NuGet v3): https://grpc.jfrog.io/grpc/api/nuget/v3/grpc-nuget-dev 58 59The same development nuget packages and packages for other languages can also be found at https://packages.grpc.io/ 60 61BUILD FROM SOURCE 62----------------- 63 64You only need to go through these steps if you are planning to develop gRPC C#. 65If you are a user of gRPC C#, go to Usage section above. 66 67**Prerequisites for contributors** 68 69- [dotnet SDK](https://www.microsoft.com/net/core) 70- [Mono 4+](https://www.mono-project.com/) (only needed for Linux and MacOS) 71- Prerequisites mentioned in [BUILDING.md](../../BUILDING.md#pre-requisites) 72 to be able to compile the native code. 73 74**Windows, Linux or Mac OS X** 75 76- The easiest way to build is using the `run_tests.py` script that will take care of building the `grpc_csharp_ext` native library. 77 78 ``` 79 # NOTE: make sure all necessary git submodules with dependencies 80 # are available by running "git submodule update --init" 81 82 # from the gRPC repository root 83 $ python tools/run_tests/run_tests.py -l csharp -c dbg --build_only 84 ``` 85 86- Use Visual Studio 2017 (on Windows) to open the solution `Grpc.sln` or use Visual Studio Code with C# extension (on Linux and Mac). gRPC C# code has been migrated to 87 dotnet SDK `.csproj` projects that are much simpler to maintain, but are not yet supported by Xamarin Studio or Monodevelop (the NuGet packages still 88 support both `net45` and `netstandard` and can be used in all IDEs). 89 90RUNNING TESTS 91------------- 92 93gRPC C# is using NUnit as the testing framework. 94 95Under Visual Studio, make sure NUnit test adapter is installed (under "Extensions and Updates"). 96Then you should be able to run all the tests using Test Explorer. 97 98gRPC team uses a Python script to facilitate running tests for 99different languages. 100 101``` 102# from the gRPC repository root 103$ python tools/run_tests/run_tests.py -l csharp -c dbg 104``` 105 106DOCUMENTATION 107------------- 108- [.NET Build Integration](BUILD-INTEGRATION.md) 109- [API Reference][] 110- [Helloworld Example][] 111- [RouteGuide Tutorial][] 112 113PERFORMANCE 114----------- 115 116For best gRPC C# performance, use [.NET Core](https://dotnet.github.io/) and the Server GC mode `"System.GC.Server": true` for your applications. 117 118THE NATIVE DEPENDENCY 119--------------- 120 121Internally, gRPC C# uses a native library written in C (gRPC C core) and invokes its functionality via P/Invoke. The fact that a native library is used should be fully transparent to the users and just installing the `Grpc.Core` NuGet package is the only step needed to use gRPC C# on all supported platforms. 122 123[API Reference]: https://grpc.io/grpc/csharp/api/Grpc.Core.html 124[Helloworld Example]: ../../examples/csharp/Helloworld 125[RouteGuide Tutorial]: https://grpc.io/docs/languages/csharp/basics 126