src/csharp/README.md

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