Dart Quick Start

This guide gets you started with gRPC in Dart with a simple working example.

Prerequisites

• Dart SDK version 2.2 or higher. For installation instructions, seeInstallDart.

Note

Dart gRPC supports the Flutter and Server platforms.

Protocol Buffers v3

While not mandatory, gRPC applications usually leverageProtocol Buffersv3 for service definitions and data serialization, and the example codeuses Protocol Buffers.

• macOS:

$ brew install protobuf

• Any OS:

  • Download a zip file of the latest version of pre-compiled binaries foryour operating system fromgithub.com/google/protobuf/releases(protoc-<version>-<os>.zip).
  • Unzip the file.
  • Update your environment’s path variable to include the path to theprotoc executable.

Next, install the protoc plugin for Dart

$ pub global activate protoc_plugin

The compiler plugin, protoc-gen-dart, is installed in $HOME/.pub-cache/bin.It must be in your PATH for the protocol compiler, protoc, to find it.

$ export PATH=$PATH:$HOME/.pub-cache/bin

Download the example

You’ll need a local copy of the example code to work through this quick start.Download the example code from our GitHub repository (the following commandclones the entire repository, but you just need the examples for this quick startand other tutorials):

# Clone the repository at the latest release to get the example code:
$ git clone https://github.com/grpc/grpc-dart
# Navigate to the "Hello World" Dart example:
$ cd grpc-dart/example/helloworld

Run a gRPC application

From the example/helloworld directory:

• Download package dependencies

$ pub get

• Run the server:

$ dart bin/server.dart

• From another terminal, run the client:

$ dart bin/client.dart

Congratulations! You’ve just run a client-server application with gRPC.

Update a gRPC service

In this section you’ll update the application with an extra server method.The gRPC service is defined using protocol buffers.To learn more about how to define a service in a .protofile seegRPC Basics: Dart.For now, all you need to know is that both theserver and the client “stub” have a SayHello() RPC method that takes aHelloRequest parameter from the client and returns a HelloReply from theserver, and that this method is defined like this:

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}
// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Edit protos/helloworld.proto and add a new SayHelloAgain() method, with thesame request and response types:

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
  // Sends another greeting
  rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
}
// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}
// The response message containing the greetings
message HelloReply {
  string message = 1;
}

Remember to save the file!

Generate gRPC code

Before you can use the new service method, you need to recompile the updatedproto file.

From the example/helloworld directory, run:

$ protoc --dart_out=grpc:lib/src/generated -Iprotos protos/helloworld.proto

You’ll find the regenerated request and response classes, and client and serverclasses in the lib/src/generated directory.

Update and run the application

You have new generated server and client code, but you still need to implementand call the new method in the human-written parts of our example application.

Update the server

In the same directory, open bin/server.dart. Add the followingsayHelloAgain() method to the GreeterService class:

class GreeterService extends GreeterServiceBase {
  @override
  Future<HelloReply> sayHello(ServiceCall call, HelloRequest request) async {
    return HelloReply()..message = 'Hello, ${request.name}!';
  }
  @override
  Future<HelloReply> sayHelloAgain(ServiceCall call, HelloRequest request) async {
    return HelloReply()..message = 'Hello again, ${request.name}!';
  }
}

Update the client

Add a call to sayHelloAgain() in bin/client.dart like this:

Future<void> main(List<String> args) async {
  final channel = ClientChannel(
    'localhost',
    port: 50051,
    options: const ChannelOptions(credentials: ChannelCredentials.insecure()),
  );
  final stub = GreeterClient(channel);
  final name = args.isNotEmpty ? args[0] : 'world';
  try {
    var response = await stub.sayHello(HelloRequest()..name = name);
    print('Greeter client received: ${response.message}');
    response = await stub.sayHelloAgain(HelloRequest()..name = name);
    print('Greeter client received: ${response.message}');
  } catch (e) {
    print('Caught error: $e');
  }
  await channel.shutdown();
}

Run!

Run the client and server like you did before. Execute the following commandsfrom the example/helloworld directory:

• Run the server:

$ dart bin/server.dart

• From another terminal, run the client. This time, add a name as a command-lineargument:

$ dart bin/client.dart Alice

You’ll see the following output:

Greeter client received: Hello, Alice!
Greeter client received: Hello again, Alice!

What’s next

• Read a full explanation of how gRPC works inWhat is gRPC?andgRPC Concepts.
• Work through a more detailed tutorial ingRPC Basics: Dart.
• Explore theDart gRPC API reference.

Reporting issues

If you find a problem with Dart gRPC, pleasefile an issuein our issue tracker.