grpc
/
grpc.io
mirror of https://github.com/grpc/grpc.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
grpc.io/public/docs/quickstart/dart/index.html

361 lines
20 KiB
HTML
Raw Blame History

<!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>
Dart Quickstart &ndash; 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/" >C#</a>
<a href="https://cjyabraham.github.io/docs/quickstart/dart/" class="active">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;">Dart Quickstart</h3>
<p class="lead">This guide gets you started with gRPC in Dart with a simple
working example.</p>
<div id="toc"></div>
<h3 id="prerequisites">Prerequisites</h3>
<h4 id="dart-sdk">Dart SDK</h4>
<p>gRPC requires Dart SDK version 2.0 or higher. Dart gRPC supports Flutter and Server platforms.</p>
<p>For installation instructions, follow this guide: <a href="https://www.dartlang.org/install">Install Dart</a></p>
<h4 id="install-protocol-buffers-v3">Install Protocol Buffers v3</h4>
<p>While not mandatory to use gRPC, gRPC applications usually leverage Protocol
Buffers v3 for service definitions and data serialization, and our example code
uses Protocol Buffers as well as gRPC.</p>
<p>The simplest way to install the protoc compiler is to download pre-compiled
binaries for your operating system (<code>protoc-&lt;version&gt;-&lt;os&gt;.zip</code>) from here:
<a href="https://github.com/google/protobuf/releases">https://github.com/google/protobuf/releases</a></p>
<ul>
<li>Unzip this file.</li>
<li>Update the environment variable <code>PATH</code> to include the path to the protoc
binary file.</li>
</ul>
<p>Next, install the protoc plugin for Dart</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">$ pub global activate protoc_plugin</code></pre></div>
<p>The compiler plugin, <code>protoc-gen-dart</code>, is installed in <code>$HOME/.pub-cache/bin</code>.
It must be in your $PATH for the protocol compiler, protoc, to find it.</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">$ export PATH<span style="color:#f92672">=</span>$PATH:$HOME/.pub-cache/bin</code></pre></div>
<h3 id="download-the-example">Download the example</h3>
<p>You&rsquo;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 at the latest release to get the example code:</span>
$ git clone https://github.com/grpc/grpc-dart
$ <span style="color:#75715e"># Navigate to the &#34;Hello World&#34; Dart example:</span>
$ cd grpc-dart/example/helloworld</code></pre></div>
<h3 id="run-a-grpc-application">Run a gRPC application</h3>
<p>From the <code>example/helloworld</code> directory:</p>
<ol>
<li>Download package dependencies</li>
</ol>
<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"> $ pub get</code></pre></div>
<ol>
<li>Run the server</li>
</ol>
<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"> $ dart bin/server.dart</code></pre></div>
<ol>
<li>In another terminal, run the client</li>
</ol>
<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"> $ dart bin/client.dart</code></pre></div>
<p>Congratulations! You&rsquo;ve just run a client-server application with gRPC.</p>
<h3 id="update-a-grpc-service">Update a gRPC service</h3>
<p>Now let&rsquo;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/dart/">gRPC Basics: Dart</a>. For now all you need to know is that both the
server and the client &ldquo;stub&rdquo; have a <code>SayHello</code> RPC method that takes a
<code>HelloRequest</code> parameter from the client and returns a <code>HelloReply</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-dart" data-lang="dart"><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&#39;s name.
</span><span style="color:#75715e"></span>message HelloRequest {
string name <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;
}
<span style="color:#75715e">// The response message containing the greetings
</span><span style="color:#75715e"></span>message HelloReply {
string message <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;
}</code></pre></div>
<p>Let&rsquo;s update this so that the <code>Greeter</code> service has two methods. Edit
<code>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-dart" data-lang="dart"><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&#39;s name.
</span><span style="color:#75715e"></span>message HelloRequest {
string name <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;
}
<span style="color:#75715e">// The response message containing the greetings
</span><span style="color:#75715e"></span>message HelloReply {
string message <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;
}</code></pre></div>
<p>(Don&rsquo;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>From the <code>example/helloworld</code> directory, run:</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">$ protoc --dart_out<span style="color:#f92672">=</span>grpc:lib/src/generated -Iprotos protos/helloworld.proto</code></pre></div>
<p>This regenerates the files in <code>lib/src/generated</code> which contain our generated
request and response classes, and client and server classes.</p>
<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>In the same directory, open <code>bin/server.dart</code>. Implement 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-dart" data-lang="dart"><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">GreeterService</span> <span style="color:#66d9ef">extends</span> GreeterServiceBase {
<span style="color:#960050;background-color:#1e0010">@</span>override
Future<span style="color:#f92672">&lt;</span>HelloReply<span style="color:#f92672">&gt;</span> sayHello(ServiceCall call, HelloRequest request) <span style="color:#66d9ef">async</span> {
<span style="color:#66d9ef">return</span> <span style="color:#66d9ef">new</span> HelloReply()..message <span style="color:#f92672">=</span> <span style="color:#e6db74">&#39;Hello, </span><span style="color:#e6db74">${</span>request.name<span style="color:#e6db74">}</span><span style="color:#e6db74">!&#39;</span>;
}
<span style="color:#960050;background-color:#1e0010">@</span>override
Future<span style="color:#f92672">&lt;</span>HelloReply<span style="color:#f92672">&gt;</span> sayHelloAgain(
ServiceCall call, HelloRequest request) <span style="color:#66d9ef">async</span> {
<span style="color:#66d9ef">return</span> <span style="color:#66d9ef">new</span> HelloReply()..message <span style="color:#f92672">=</span> <span style="color:#e6db74">&#39;Hello again, </span><span style="color:#e6db74">${</span>request.name<span style="color:#e6db74">}</span><span style="color:#e6db74">!&#39;</span>;
}
}
...</code></pre></div>
<h4 id="update-the-client">Update the client</h4>
<p>In the same directory, open <code>bin/client.dart</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-dart" data-lang="dart">Future<span style="color:#f92672">&lt;</span>Null<span style="color:#f92672">&gt;</span> main(List<span style="color:#f92672">&lt;</span><span style="color:#66d9ef">String</span><span style="color:#f92672">&gt;</span> args) <span style="color:#66d9ef">async</span> {
<span style="color:#66d9ef">final</span> channel <span style="color:#f92672">=</span> <span style="color:#66d9ef">new</span> ClientChannel(<span style="color:#e6db74">&#39;localhost&#39;</span>,
port: <span style="color:#ae81ff">50051</span>,
options: <span style="color:#66d9ef">const</span> ChannelOptions(
credentials: <span style="color:#66d9ef">const</span> ChannelCredentials.insecure()));
<span style="color:#66d9ef">final</span> stub <span style="color:#f92672">=</span> <span style="color:#66d9ef">new</span> GreeterClient(channel);
<span style="color:#66d9ef">final</span> name <span style="color:#f92672">=</span> args.isNotEmpty <span style="color:#f92672">?</span> args[<span style="color:#ae81ff">0</span>] <span style="color:#f92672">:</span> <span style="color:#e6db74">&#39;world&#39;</span>;
<span style="color:#66d9ef">try</span> {
<span style="color:#66d9ef">var</span> response <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> stub.sayHello(<span style="color:#66d9ef">new</span> HelloRequest()..name <span style="color:#f92672">=</span> name);
print(<span style="color:#e6db74">&#39;Greeter client received: </span><span style="color:#e6db74">${</span>response.message<span style="color:#e6db74">}</span><span style="color:#e6db74">&#39;</span>);
response <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> stub.sayHelloAgain(<span style="color:#66d9ef">new</span> HelloRequest()..name <span style="color:#f92672">=</span> name);
print(<span style="color:#e6db74">&#39;Greeter client received: </span><span style="color:#e6db74">${</span>response.message<span style="color:#e6db74">}</span><span style="color:#e6db74">&#39;</span>);
} <span style="color:#66d9ef">catch</span> (e) {
print(<span style="color:#e6db74">&#39;Caught error: </span><span style="color:#e6db74">$</span>e<span style="color:#e6db74">&#39;</span>);
}
<span style="color:#66d9ef">await</span> channel.shutdown();
}</code></pre></div>
<h4 id="run">Run!</h4>
<p>Just like we did before, from the <code>example/helloworld</code> directory:</p>
<ol>
<li>Run the server</li>
</ol>
<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"> $ dart bin/server.dart</code></pre></div>
<ol>
<li>In another terminal, run the client</li>
</ol>
<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"> $ dart bin/client.dart</code></pre></div>
<h3 id="what-s-next">What&rsquo;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/dart/">gRPC Basics: Dart</a></li>
</ul>
<h3 id="reporting-issues">Reporting issues</h3>
<p>Should you encounter an issue, please help us out by
<a href="https://github.com/grpc/grpc-dart/issues/new">filing issues</a>
in our issue tracker.</p></p>
</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>
Reference in New Issue View Git Blame Copy Permalink