Skip to content
Snippets Groups Projects
Commit da5507b9 authored by Tim Emiola's avatar Tim Emiola
Browse files

Merge pull request #3481 from jtattermusch/beta_update_docs

Update c# docs for release 0.11
parents a25facb0 3fcbdef6
No related branches found
No related tags found
No related merge requests found
...@@ -39,7 +39,7 @@ Libraries in different languages are in different state of development. We are s ...@@ -39,7 +39,7 @@ Libraries in different languages are in different state of development. We are s
* Ruby Library: [src/ruby] (src/ruby) : Early adopter ready - Alpha. * Ruby Library: [src/ruby] (src/ruby) : Early adopter ready - Alpha.
* NodeJS Library: [src/node] (src/node) : Early adopter ready - Alpha. * NodeJS Library: [src/node] (src/node) : Early adopter ready - Alpha.
* Python Library: [src/python] (src/python) : Early adopter ready - Alpha. * Python Library: [src/python] (src/python) : Early adopter ready - Alpha.
* C# Library: [src/csharp] (src/csharp) : Early adopter ready - Alpha. * C# Library: [src/csharp] (src/csharp) : Beta.
* Objective-C Library: [src/objective-c] (src/objective-c): Early adopter ready - Alpha. * Objective-C Library: [src/objective-c] (src/objective-c): Early adopter ready - Alpha.
* PHP Library: [src/php] (src/php) : Pre-Alpha. * PHP Library: [src/php] (src/php) : Pre-Alpha.
......
...@@ -3,49 +3,52 @@ gRPC in 3 minutes (C#) ...@@ -3,49 +3,52 @@ gRPC in 3 minutes (C#)
BACKGROUND BACKGROUND
------------- -------------
For this sample, we've already generated the server and client stubs from `helloworld.proto`. For this sample, we've already generated the server and client stubs from [helloworld.proto][].
Example projects depend on NuGet packages `Grpc` and `Google.ProtocolBuffers` which have been already added to the project for you.
Example projects depend on the [Grpc](https://www.nuget.org/packages/Grpc/)
and [Google.Protobuf](https://www.nuget.org/packages/Google.Protobuf/) NuGet packages
which have been already added to the project for you.
PREREQUISITES PREREQUISITES
------------- -------------
**Windows** **Windows**
- .NET 4.5+ - .NET 4.5+
- VS 2013 (with NuGet plugin installed) - Visual Studio 2013 or 2015
**Linux (Mono)** **Linux**
- Mono - Mono
- Monodevelop 5.9 with NuGet Add-in installed (older versions might work) - Monodevelop 5.9 with NuGet Add-in installed
**MacOS (Mono)** **Mac OS X**
- Xamarin Studio (with NuGet plugin installed) - Xamarin Studio (with NuGet plugin installed)
- [homebrew][]
BUILD BUILD
------- -------
**Windows** **Windows**
- Clone this repository.
- Open solution `Greeter.sln` with Visual Studio - Open solution `Greeter.sln` with Visual Studio
- Build the solution (this will automatically download NuGet dependencies) - Build the solution (this will automatically download NuGet dependencies)
**Linux (Mono)** **Linux (Debian)**
- Clone this repository.
- Install gRPC C core and C# native extension using [How to use gRPC C#][] instructions
- Install gRPC C Core using instructions in https://github.com/grpc/homebrew-grpc - Open solution `Greeter.sln` in MonoDevelop.
- gRPC C# depends on native shared library `libgrpc_csharp_ext.so`. To make it visible - Build the solution (you need to manually restore dependencies by using `mono nuget.exe restore` if you don't have NuGet add-in)
to Mono runtime, follow instructions in [Using gRPC C# on Linux](https://github.com/grpc/grpc/tree/master/src/csharp#usage-linux-mono)
- Open solution `Greeter.sln` in MonoDevelop (you need to manually restore dependencies by using `mono nuget.exe restore` if you don't have NuGet add-in) **Mac OS X**
- Build the solution. - Install gRPC C core and C# native extension using [How to use gRPC C#][] instructions
**MacOS (Mono)** - Open solution `Greeter.sln` with Xamarin Studio
- See [Using gRPC C# on MacOS](https://github.com/grpc/grpc/tree/master/src/csharp#usage-macos-mono) for more info
on MacOS support.
Try it! - Build the solution (this will automatically download NuGet dependencies)
Try it!
------- -------
- Run the server - Run the server
...@@ -69,4 +72,9 @@ On Linux or Mac, use `mono GreeterServer.exe` and `mono GreeterClient.exe` to ru ...@@ -69,4 +72,9 @@ On Linux or Mac, use `mono GreeterServer.exe` and `mono GreeterClient.exe` to ru
Tutorial Tutorial
-------- --------
You can find a more detailed tutorial in [gRPC Basics: C#](route_guide/README.md) You can find a more detailed tutorial in [gRPC Basics: C#][]
[homebrew]:http://brew.sh
[helloworld.proto]:../../protos/helloworld.proto
[How to use gRPC C#]:../../../src/csharp#how-to-use
[gRPC Basics: C#]:http://www.grpc.io/docs/tutorials/basic/csharp.html
...@@ -6,65 +6,73 @@ A C# implementation of gRPC. ...@@ -6,65 +6,73 @@ A C# implementation of gRPC.
Status Status
------ ------
Alpha : Ready for early adopters. Beta
Usage: Windows PREREQUISITES
-------------- --------------
- Prerequisites: .NET Framework 4.5+, Visual Studio 2013 with NuGet extension installed (VS2015 should work). - Windows: .NET Framework 4.5+, Visual Studio 2013 or 2015.
- Linux: Mono 3.2.8+, MonoDevelop 5.9 with NuGet add-in installed.
- Mac OS X: [homebrew][], Xamarin Studio with NuGet add-in installed.
HOW TO USE
--------------
**Windows**
- Open Visual Studio and start a new project/solution. - Open Visual Studio and start a new project/solution.
- Add NuGet package `Grpc` as a dependency (Project options -> Manage NuGet Packages). - Add NuGet package `Grpc` as a dependency (Project options -> Manage NuGet Packages).
That will also pull all the transitive dependencies (including the native libraries that That will also pull all the transitive dependencies (including the native libraries that
gRPC C# is internally using). gRPC C# is using internally).
- Helloworld project example can be found in https://github.com/grpc/grpc/tree/master/examples/csharp.
Usage: Linux (Mono) **Linux (Debian)**
--------------
- Prerequisites: Mono 3.2.8+, MonoDevelop 5.9 with NuGet add-in installed.
- Install Linuxbrew and gRPC C Core using instructions in https://github.com/grpc/homebrew-grpc - Add [Debian jessie-backports][] to your `sources.list` file. Example:
- gRPC C# depends on native shared library libgrpc_csharp_ext.so (Unix flavor of grpc_csharp_ext.dll). ```sh
This library will be installed to `~/.linuxbrew/lib` by the previous step. echo "deb http://http.debian.net/debian jessie-backports main" | \
To make it visible to mono, you need to: sudo tee -a /etc/apt/sources.list
```
- (preferred approach) add `libgrpc_csharp_ext.so` to `/etc/ld.so.cache` by running: - Install the gRPC Debian package
```sh ```sh
$ echo "$HOME/.linuxbrew/lib" | sudo tee /etc/ld.so.conf.d/zzz_brew_lib.conf sudo apt-get update
$ sudo ldconfig sudo apt-get install libgrpc0
``` ```
- (adhoc approach) set `LD_LIBRARY_PATH` environment variable to point to directory containing `libgrpc_csharp_ext.so`: - gRPC C# depends on native shared library `libgrpc_csharp_ext.so` (Unix flavor of grpc_csharp_ext.dll).
This library is not part of the base gRPC debian package and needs to be installed manually from
a `.deb` file. Download the debian package `libgrpc_csharp_ext` from corresponding gRPC release on GitHub
and install it using `dpkg`.
```sh ```sh
$ export LD_LIBRARY_PATH=$HOME/.linuxbrew/lib:${LD_LIBRARY_PATH} # choose version corresponding to the version of libgrpc you've installed.
``` wget https://github.com/grpc/grpc/releases/download/release-0_11_0/libgrpc-csharp-ext0_0.11.0.0-1_amd64.deb
- (if you are contributor) installing gRPC from sources using `sudo make install_grpc_csharp_ext` also works. dpkg -i libgrpc-csharp-ext0_0.11.0.0-1_amd64.deb
```
- Open MonoDevelop and start a new project/solution. - Open MonoDevelop and start a new project/solution.
- Add NuGet package `Grpc` as a dependency (Project -> Add NuGet packages). - Add NuGet package `Grpc` as a dependency (Project -> Add NuGet packages).
- Helloworld project example can be found in https://github.com/grpc/grpc/tree/master/examples/csharp. **Mac OS X**
Usage: MacOS (Mono)
--------------
- WARNING: As of now gRPC C# only works on 64bit version of Mono (because we don't compile - WARNING: As of now gRPC C# only works on 64bit version of Mono (because we don't compile
the native extension for C# in 32bit mode yet). That means your development experience the native extension for C# in 32bit mode yet). That means your development experience
with Xamarin Studio on MacOS will not be great, as you won't be able to run your with Xamarin Studio on MacOS will not be great, as you won't be able to run your
code directly from Xamarin Studio (which requires 32bit version of Mono). code directly from Xamarin Studio (which requires 32bit version of Mono).
- Prerequisites: Xamarin Studio with NuGet add-in installed. - Install [homebrew][]. Run the following command to install gRPC C# native dependencies.
- Install Homebrew and gRPC C Core using instructions in https://github.com/grpc/homebrew-grpc ```sh
$ curl -fsSL https://goo.gl/getgrpc | bash -
```
This will download and run the [gRPC install script][], then install the latest version of gRPC C core and native C# extension.
It also installs Protocol Buffers compiler (_protoc_) and the gRPC _protoc_ plugin for ruby.
- Install 64-bit version of mono with command `brew install mono` (assumes you've already installed Homebrew). - Install 64-bit version of mono with command `brew install mono`.
- Open Xamarin Studio and start a new project/solution. - Open Xamarin Studio and start a new project/solution.
...@@ -73,35 +81,27 @@ Usage: MacOS (Mono) ...@@ -73,35 +81,27 @@ Usage: MacOS (Mono)
- *You will be able to build your project in Xamarin Studio, but to run or test it, - *You will be able to build your project in Xamarin Studio, but to run or test it,
you will need to run it under 64-bit version of Mono.* you will need to run it under 64-bit version of Mono.*
- Helloworld project example can be found in https://github.com/grpc/grpc/tree/master/examples/csharp. BUILD FROM SOURCE
Building: Windows
----------------- -----------------
You only need to go through these steps if you are planning to develop gRPC C#. You only need to go through these steps if you are planning to develop gRPC C#.
If you are a user of gRPC C#, go to Usage section above. If you are a user of gRPC C#, go to Usage section above.
- Prerequisites for development: NET Framework 4.5+, Visual Studio 2013 (with NuGet and NUnit extensions installed). **Windows**
- The grpc_csharp_ext native library needs to be built so you can build the Grpc C# solution. You can - The grpc_csharp_ext native library needs to be built so you can build the gRPC C# solution. You can
either build the native solution in `vsprojects/grpc.sln` from Visual Studio manually, or you can use either build the native solution in `vsprojects/grpc.sln` from Visual Studio manually, or you can use
a convenience batch script that builds everything for you. a convenience batch script that builds everything for you.
``` ```
> REM From src/csharp directory
> buildall.bat > buildall.bat
``` ```
- Open Grpc.sln using Visual Studio 2013. NuGet dependencies will be restored - Open Grpc.sln using Visual Studio. NuGet dependencies will be restored
upon build (you need to have NuGet add-in installed). upon build (you need to have NuGet add-in installed).
**Linux**
Building: Linux (Mono)
----------------------
You only need to go through these steps if you are planning to develop gRPC C#.
If you are a user of gRPC C#, go to Usage section above.
- Prerequisites for development: Mono 3.2.8+, MonoDevelop 5.9 with NuGet and NUnit add-ins installed.
```sh ```sh
$ sudo apt-get install mono-devel $ sudo apt-get install mono-devel
...@@ -123,8 +123,8 @@ don't support NuGet add-in. ...@@ -123,8 +123,8 @@ don't support NuGet add-in.
- Build the solution & run all the tests from test view. - Build the solution & run all the tests from test view.
Tests RUNNING TESTS
----- -------------
gRPC C# is using NUnit as the testing framework. gRPC C# is using NUnit as the testing framework.
...@@ -136,12 +136,25 @@ Then you should be able to run all the test from the Test View. ...@@ -136,12 +136,25 @@ Then you should be able to run all the test from the Test View.
After building the solution, you can also run the tests from command line After building the solution, you can also run the tests from command line
using nunit-console tool. using nunit-console tool.
```sh ```sh
# from Grpc.Core.Test/bin/Debug directory # from Grpc.Core.Test/bin/Debug directory
$ nunit-console Grpc.Core.Tests.dll $ nunit-console Grpc.Core.Tests.dll
``` ```
Contents gRPC team uses a Python script to simplify facilitate running tests for
different languages.
```
tools/run_tests/run_tests.py -l csharp
```
DOCUMENTATION
-------------
- the gRPC C# reference documentation is available online at [grpc.io][]
- [Helloworld example][]
CONTENTS
-------- --------
- ext: - ext:
...@@ -159,7 +172,7 @@ Contents ...@@ -159,7 +172,7 @@ Contents
- Grpc.IntegrationTesting: - Grpc.IntegrationTesting:
Cross-language gRPC implementation testing (interop testing). Cross-language gRPC implementation testing (interop testing).
Troubleshooting TROUBLESHOOTING
--------------- ---------------
### Problem: Unable to load DLL 'grpc_csharp_ext.dll' ### Problem: Unable to load DLL 'grpc_csharp_ext.dll'
...@@ -170,8 +183,17 @@ Internally, gRPC C# uses a native library written in C (gRPC C core) and invokes ...@@ -170,8 +183,17 @@ Internally, gRPC C# uses a native library written in C (gRPC C core) and invokes
- If you are running your application that is using gRPC on Windows machine that doesn't have Visual Studio installed, you might need to install [Visual C++ 2013 redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=40784) that contains some system .dll libraries that `grpc_csharp_ext.dll` depends on (see #905 for more details). - If you are running your application that is using gRPC on Windows machine that doesn't have Visual Studio installed, you might need to install [Visual C++ 2013 redistributable](https://www.microsoft.com/en-us/download/details.aspx?id=40784) that contains some system .dll libraries that `grpc_csharp_ext.dll` depends on (see #905 for more details).
- On Linux (or Docker), you need to first install gRPC C core and `libgrpc_csharp_ext.so` shared libraries. Currently, the libraries can be installed by `make install_grpc_csharp_ext` or using Linuxbrew (a Debian package is coming soon). Installation on a machine where your application is going to be deployed is no different. - On Linux (or Docker), you need to first install gRPC C core and `libgrpc_csharp_ext.so` shared libraries.
See [How to Use](#how-to-use) section for details how to install it.
Installation on a machine where your application is going to be deployed is no different.
- On Mac, you need to first install gRPC C core and `libgrpc_csharp_ext.dylib` shared libraries using Homebrew. See above for installation instruction. Installation on a machine where your application is going to be deployed is no different. - On Mac, you need to first install gRPC C core and `libgrpc_csharp_ext.dylib` shared libraries using Homebrew. See above for installation instruction.
Installation on a machine where your application is going to be deployed is no different.
- Possible cause for the problem is that the `grpc_csharp_ext` library is installed, but it has different bitness (32/64bit) than your C# runtime (in case you are using mono) or C# application. - Possible cause for the problem is that the `grpc_csharp_ext` library is installed, but it has different bitness (32/64bit) than your C# runtime (in case you are using mono) or C# application.
[homebrew]:http://brew.sh
[gRPC install script]:https://raw.githubusercontent.com/grpc/homebrew-grpc/master/scripts/install
[grpc.io]: http://www.grpc.io/docs/installation/csharp.html
[Debian jessie-backports]:http://backports.debian.org/Instructions/
[Helloworld example]:../../examples/csharp/helloworld
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment