mirror of https://github.com/grpc/grpc.io.git
393 lines
19 KiB
HTML
393 lines
19 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
|
|
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
|
|
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400" rel="stylesheet">
|
|
<link rel="stylesheet" type="text/css" href="/css/style.css">
|
|
<title>
|
|
C# Quick Start – gRPC
|
|
</title>
|
|
|
|
|
|
<link rel="apple-touch-icon" href="/favicons/apple-touch-icon.png" sizes="180x180">
|
|
<link rel="icon" type="image/png" href="/favicons/android-chrome-192x192.png" sizes="192x192" >
|
|
<link rel="icon" type="image/png" href="/favicons/favicon-32x32.png" sizes="32x32">
|
|
<link rel="icon" type="image/png" href="/favicons/favicon-16x16.png" sizes="16x16">
|
|
<link rel="manifest" href="/favicons/manifest.json">
|
|
<link rel="mask-icon" href="/favicons/safari-pinned-tab.svg" color="#2DA6B0">
|
|
<meta name="msapplication-TileColor" content="#ffffff">
|
|
<meta name="msapplication-TileImage" content="/favicons/mstile-150x150.png">
|
|
|
|
|
|
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-60127042-1"></script>
|
|
<script>
|
|
window.dataLayer = window.dataLayer || [];
|
|
function gtag(){dataLayer.push(arguments);}
|
|
gtag('js', new Date());
|
|
|
|
gtag('config', 'UA-60127042-1');
|
|
</script>
|
|
|
|
</head>
|
|
<body>
|
|
<div id="landing-content">
|
|
<div class="row">
|
|
<div class="topbannersub">
|
|
<nav class="navbar navbar-expand-md navbar-dark topnav">
|
|
<a class="navbar-brand" href="https://cjyabraham.github.io/">
|
|
<img src="https://cjyabraham.github.io/img/grpc-logo.png" width="114" height="50">
|
|
</a>
|
|
|
|
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
|
|
<span class="navbar-toggler-icon"></span>
|
|
</button>
|
|
|
|
<div class="topnav, collapse navbar-collapse" id="navbarSupportedContent" style="float:right !important">
|
|
<ul class="navbar-nav ml-auto">
|
|
<li class="nav-item ">
|
|
<a class="nav-link" href="https://cjyabraham.github.io/about/">About</a>
|
|
</li>
|
|
<li class="nav-item dropdown active">
|
|
<a class="nav-link dropdown-toggle" href="https://cjyabraham.github.io/docs/" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
|
|
Docs
|
|
</a>
|
|
|
|
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
|
|
|
|
|
|
<a class="dropdown-item" href="/docs">
|
|
Overview
|
|
</a>
|
|
|
|
|
|
<a class="dropdown-item" href="/docs/quickstart/">
|
|
Quick Start
|
|
</a>
|
|
|
|
|
|
<a class="dropdown-item" href="/docs/guides/">
|
|
Guides
|
|
</a>
|
|
|
|
|
|
<a class="dropdown-item" href="/docs/tutorials/">
|
|
Tutorials
|
|
</a>
|
|
|
|
|
|
<a class="dropdown-item" href="/docs/reference/">
|
|
Reference
|
|
</a>
|
|
|
|
|
|
<a class="dropdown-item" href="/docs/samples/">
|
|
Samples
|
|
</a>
|
|
|
|
|
|
<a class="dropdown-item" href="/docs/talks">
|
|
Presentations
|
|
</a>
|
|
|
|
</div>
|
|
</li>
|
|
<li class="nav-item ">
|
|
<a class="nav-link" href="/blog">
|
|
Blog
|
|
</a>
|
|
</li>
|
|
<li class="nav-item ">
|
|
<a class="nav-link" href="/community">Community</a>
|
|
</li>
|
|
<li class="nav-item">
|
|
<a class="nav-link" href="https://packages.grpc.io/">
|
|
Packages
|
|
</a>
|
|
</li>
|
|
<li class="nav-item ">
|
|
<a class="nav-link" href="https://cjyabraham.github.io/faq/">FAQ</a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</nav>
|
|
|
|
|
|
<div class="headertext">Documentation</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="subnav d-none d-md-block">
|
|
<a href="https://cjyabraham.github.io/docs/" >Overview</a>
|
|
| <a href="https://cjyabraham.github.io/docs/quickstart/" class="active">Quick Start</a>
|
|
| <a href="https://cjyabraham.github.io/docs/guides/" >Guides</a>
|
|
| <a href="https://cjyabraham.github.io/docs/tutorials/" >Tutorials</a>
|
|
| <a href="https://cjyabraham.github.io/docs/reference/" >Reference</a>
|
|
| <a href="https://cjyabraham.github.io/docs/samples/" >Samples</a>
|
|
| <a href="https://cjyabraham.github.io/docs/talks/" >Presentations</a>
|
|
</div>
|
|
|
|
|
|
<div class="quickstartcols">
|
|
|
|
<div class="quickstartcol1">
|
|
|
|
<h8>Quick Start</h8>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/cpp/" >C++</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/csharp/" class="active">C#</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/dart/" >Dart</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/go/" >Go</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/java/" >Java</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/android/" >Android Java</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/node/" >Node.js</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/objective-c/" >Objective-C</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/php/" >PHP</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/python/" >Python</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/ruby/" >Ruby</a>
|
|
<a href="https://cjyabraham.github.io/docs/quickstart/web/" >Web</a>
|
|
</div>
|
|
|
|
<div class="quickstartcol2" style="margin-top:4%">
|
|
<h3 style="margin-top:0px;">C# Quick Start</h3>
|
|
|
|
|
|
|
|
<p class="lead">This guide gets you started with gRPC in C# with a simple
|
|
working example.</p>
|
|
|
|
<div id="toc"></div>
|
|
|
|
<h3 id="before-you-begin">Before you begin</h3>
|
|
|
|
<h4 id="prerequisites">Prerequisites</h4>
|
|
|
|
<p>Whether you’re using Windows, OS X, or Linux, you can follow this
|
|
example by using either an IDE and its build tools,
|
|
or by using the the .NET Core SDK command line tools.</p>
|
|
|
|
<p>First, make sure you have installed the
|
|
<a href="https://github.com/grpc/grpc/blob/v1.20.0/src/csharp/README.md#prerequisites">gRPC C# prerequisites</a>.
|
|
You will also need Git to download the sample code.</p>
|
|
|
|
<h3 id="download-the-example">Download the example</h3>
|
|
|
|
<p>You’ll need a local copy of the example code to work through this quickstart.
|
|
Download the example code from our GitHub repository (the following command
|
|
clones the entire repository, but you just need the examples for this quickstart
|
|
and other tutorials):</p>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ <span style="color:#75715e"># Clone the repository to get the example code:</span>
|
|
$ git clone -b v1.20.0 https://github.com/grpc/grpc
|
|
$ cd grpc</code></pre></div>
|
|
<p>This document will walk you through the “Hello World” example.
|
|
The projects and source files can be found in the <code>examples/csharp/Helloworld</code> directory.</p>
|
|
|
|
<p>The example in this walkthrough already adds the necessary
|
|
dependencies for you (<code>Grpc</code>, <code>Grpc.Tools</code> and <code>Google.Protobuf</code> NuGet packages).</p>
|
|
|
|
<h3 id="build-the-example">Build the example</h3>
|
|
|
|
<h4 id="using-visual-studio-or-visual-studio-for-mac">Using Visual Studio (or Visual Studio for Mac)</h4>
|
|
|
|
<ul>
|
|
<li>Open the solution <code>Greeter.sln</code> with Visual Studio</li>
|
|
<li>Build the solution</li>
|
|
</ul>
|
|
|
|
<h4 id="using-net-core-sdk-from-the-command-line">Using .NET Core SDK from the command line</h4>
|
|
|
|
<p>From the <code>examples/csharp/Helloworld</code> directory:</p>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">> dotnet build Greeter.sln</code></pre></div>
|
|
<p><em>NOTE: If you want to use gRPC C# from a project that uses the “classic” .csproj files (supported by Visual Studio 2013, 2015 and older versions of Mono), please refer to the
|
|
<a href="https://github.com/grpc/grpc/blob/v1.20.0/examples/csharp/HelloworldLegacyCsproj/README.md">Greeter using “classic” .csproj</a> example.</em></p>
|
|
|
|
<h3 id="run-a-grpc-application">Run a gRPC application</h3>
|
|
|
|
<p>From the <code>examples/csharp/Helloworld</code> directory:</p>
|
|
|
|
<ul>
|
|
<li>Run the server</li>
|
|
</ul>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">> cd GreeterServer
|
|
> dotnet run -f netcoreapp2.1</code></pre></div>
|
|
<ul>
|
|
<li>In another terminal, run the client</li>
|
|
</ul>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">> cd GreeterClient
|
|
> dotnet run -f netcoreapp2.1</code></pre></div>
|
|
<p>Congratulations! You’ve just run a client-server application with gRPC.</p>
|
|
|
|
<h3 id="update-a-grpc-service">Update a gRPC service</h3>
|
|
|
|
<p>Now let’s look at how to update the application with an extra method on the
|
|
server for the client to call. Our gRPC service is defined using protocol
|
|
buffers; you can find out lots more about how to define a service in a <code>.proto</code>
|
|
file in <a href="/docs/tutorials/basic/csharp/">gRPC Basics: C#</a>. For now all you need to know is that both the
|
|
server and the client “stub” have a <code>SayHello</code> RPC method that takes a
|
|
<code>HelloRequest</code> parameter from the client and returns a <code>HelloResponse</code> from the
|
|
server, and that this method is defined like this:</p>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-C#" data-lang="C#"><span style="color:#75715e">// The greeting service definition.
|
|
</span><span style="color:#75715e"></span>service Greeter {
|
|
<span style="color:#75715e">// Sends a greeting
|
|
</span><span style="color:#75715e"></span> rpc SayHello (HelloRequest) returns (HelloReply) {}
|
|
}
|
|
|
|
<span style="color:#75715e">// The request message containing the user's name.
|
|
</span><span style="color:#75715e"></span>message HelloRequest {
|
|
<span style="color:#66d9ef">string</span> name = <span style="color:#ae81ff">1</span>;
|
|
}
|
|
|
|
<span style="color:#75715e">// The response message containing the greetings
|
|
</span><span style="color:#75715e"></span>message HelloReply {
|
|
<span style="color:#66d9ef">string</span> message = <span style="color:#ae81ff">1</span>;
|
|
}
|
|
</code></pre></div>
|
|
<p>Let’s update this so that the <code>Greeter</code> service has two methods. Edit
|
|
<code>examples/protos/helloworld.proto</code> and update it with a new <code>SayHelloAgain</code>
|
|
method, with the same request and response types:</p>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-C#" data-lang="C#"><span style="color:#75715e">// The greeting service definition.
|
|
</span><span style="color:#75715e"></span>service Greeter {
|
|
<span style="color:#75715e">// Sends a greeting
|
|
</span><span style="color:#75715e"></span> rpc SayHello (HelloRequest) returns (HelloReply) {}
|
|
<span style="color:#75715e">// Sends another greeting
|
|
</span><span style="color:#75715e"></span> rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
|
|
}
|
|
|
|
<span style="color:#75715e">// The request message containing the user's name.
|
|
</span><span style="color:#75715e"></span>message HelloRequest {
|
|
<span style="color:#66d9ef">string</span> name = <span style="color:#ae81ff">1</span>;
|
|
}
|
|
|
|
<span style="color:#75715e">// The response message containing the greetings
|
|
</span><span style="color:#75715e"></span>message HelloReply {
|
|
<span style="color:#66d9ef">string</span> message = <span style="color:#ae81ff">1</span>;
|
|
}
|
|
</code></pre></div>
|
|
<p>(Don’t forget to save the file!)</p>
|
|
|
|
<h3 id="generate-grpc-code">Generate gRPC code</h3>
|
|
|
|
<p>Next we need to update the gRPC code used by our application to use the new service definition.</p>
|
|
|
|
<p>The <code>Grpc.Tools</code> NuGet package contains the protoc and protobuf C# plugin binaries needed
|
|
to generate the code. Starting from version 1.17 the package also integrates with
|
|
MSBuild to provide <a href="https://github.com/grpc/grpc/blob/master/src/csharp/BUILD-INTEGRATION.md">automatic C# code generation</a>
|
|
from <code>.proto</code> files.</p>
|
|
|
|
<p>This example project already depends on the <code>Grpc.Tools.1.20.0</code> NuGet package so just re-building the solution
|
|
is enough to regenerate the code from our modified <code>.proto</code> file.</p>
|
|
|
|
<p>You can rebuild just like we first built the original
|
|
example by running <code>dotnet build Greeter.sln</code> or by clicking “Build” in Visual Studio.</p>
|
|
|
|
<p>The build regenerates the following files
|
|
under the <code>Greeter/obj/Debug/TARGET_FRAMEWORK</code> directory:</p>
|
|
|
|
<ul>
|
|
<li><code>Helloworld.cs</code> contains all the protocol buffer code to populate,
|
|
serialize, and retrieve our request and response message types</li>
|
|
<li><code>HelloworldGrpc.cs</code> provides generated client and server classes,
|
|
including:
|
|
|
|
<ul>
|
|
<li>an abstract class <code>Greeter.GreeterBase</code> to inherit from when defining
|
|
Greeter service implementations</li>
|
|
<li>a class <code>Greeter.GreeterClient</code> that can be used to access remote Greeter
|
|
instances
|
|
<br /></li>
|
|
</ul></li>
|
|
</ul>
|
|
|
|
<h3 id="update-and-run-the-application">Update and run the application</h3>
|
|
|
|
<p>We now have new generated server and client code, but we still need to implement
|
|
and call the new method in the human-written parts of our example application.</p>
|
|
|
|
<h4 id="update-the-server">Update the server</h4>
|
|
|
|
<p>With the <code>Greeter.sln</code> open in your IDE, open <code>GreeterServer/Program.cs</code>.
|
|
Implement the new method by editing the GreeterImpl class like this:</p>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-C#" data-lang="C#"><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">GreeterImpl</span> : Greeter.GreeterBase
|
|
{
|
|
<span style="color:#75715e">// Server side handler of the SayHello RPC
|
|
</span><span style="color:#75715e"></span> <span style="color:#66d9ef">public</span> <span style="color:#66d9ef">override</span> Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
|
|
{
|
|
<span style="color:#66d9ef">return</span> Task.FromResult(<span style="color:#66d9ef">new</span> HelloReply { Message = <span style="color:#e6db74">"Hello "</span> + request.Name });
|
|
}
|
|
|
|
<span style="color:#75715e">// Server side handler for the SayHelloAgain RPC
|
|
</span><span style="color:#75715e"></span> <span style="color:#66d9ef">public</span> <span style="color:#66d9ef">override</span> Task<HelloReply> SayHelloAgain(HelloRequest request, ServerCallContext context)
|
|
{
|
|
<span style="color:#66d9ef">return</span> Task.FromResult(<span style="color:#66d9ef">new</span> HelloReply { Message = <span style="color:#e6db74">"Hello again "</span> + request.Name });
|
|
}
|
|
}
|
|
</code></pre></div>
|
|
<h4 id="update-the-client">Update the client</h4>
|
|
|
|
<p>With the same <code>Greeter.sln</code> open in your IDE, open <code>GreeterClient/Program.cs</code>.
|
|
Call the new method like this:</p>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-C#" data-lang="C#"><span style="color:#66d9ef">public</span> <span style="color:#66d9ef">static</span> <span style="color:#66d9ef">void</span> Main(<span style="color:#66d9ef">string</span><span style="color:#a6e22e">[]</span> args)
|
|
{
|
|
Channel channel = <span style="color:#66d9ef">new</span> Channel(<span style="color:#e6db74">"127.0.0.1:50051"</span>, ChannelCredentials.Insecure);
|
|
|
|
<span style="color:#66d9ef">var</span> client = <span style="color:#66d9ef">new</span> Greeter.GreeterClient(channel);
|
|
String user = <span style="color:#e6db74">"you"</span>;
|
|
|
|
<span style="color:#66d9ef">var</span> reply = client.SayHello(<span style="color:#66d9ef">new</span> HelloRequest { Name = user });
|
|
Console.WriteLine(<span style="color:#e6db74">"Greeting: "</span> + reply.Message);
|
|
|
|
<span style="color:#66d9ef">var</span> secondReply = client.SayHelloAgain(<span style="color:#66d9ef">new</span> HelloRequest { Name = user });
|
|
Console.WriteLine(<span style="color:#e6db74">"Greeting: "</span> + secondReply.Message);
|
|
|
|
channel.ShutdownAsync().Wait();
|
|
Console.WriteLine(<span style="color:#e6db74">"Press any key to exit..."</span>);
|
|
Console.ReadKey();
|
|
}
|
|
</code></pre></div>
|
|
<h4 id="rebuild-the-modified-example">Rebuild the modified example</h4>
|
|
|
|
<p>Rebuild the newly modified example just like we first built the original
|
|
example by running <code>dotnet build Greeter.sln</code> or by clicking “Build” in Visual Studio.</p>
|
|
|
|
<h4 id="run">Run!</h4>
|
|
|
|
<p>Just like we did before, from the <code>examples/csharp/Helloworld</code> directory:</p>
|
|
|
|
<ul>
|
|
<li>Run the server</li>
|
|
</ul>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">> cd GreeterServer
|
|
> dotnet run -f netcoreapp2.1</code></pre></div>
|
|
<ul>
|
|
<li>In another terminal, run the client</li>
|
|
</ul>
|
|
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">> cd GreeterClient
|
|
> dotnet run -f netcoreapp2.1</code></pre></div>
|
|
<h3 id="what-s-next">What’s next</h3>
|
|
|
|
<ul>
|
|
<li>Read a full explanation of how gRPC works in <a href="/docs/guides/">What is gRPC?</a>
|
|
and <a href="/docs/guides/concepts/">gRPC Concepts</a></li>
|
|
<li>Work through a more detailed tutorial in <a href="/docs/tutorials/basic/csharp/">gRPC Basics: C#</a></li>
|
|
<li>Explore the gRPC C# core API in its <a href="/grpc/csharp/api/Grpc.Core.html">reference
|
|
documentation</a></li>
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
|
|
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
|
|
|
|
</body>
|
|
</html>
|