Local development

• 1: IDE support
• 1.1: Visual Studio Code integration with Dapr
• 1.1.1: Dapr Visual Studio Code extension overview
• 1.1.2: How-To: Debug Dapr applications with Visual Studio Code
• 1.1.3: Developing Dapr applications with Dev Containers
• 1.2: IntelliJ
• 2: Multi-App Run
• 2.1: Multi-App Run overview
• 2.2: How to: Use the Multi-App Run template file
• 3: How to: Use the gRPC interface in your Dapr application
• 4: Serialization in Dapr's SDKs

1 - IDE support

1.1 - Visual Studio Code integration with Dapr

1.1.1 - Dapr Visual Studio Code extension overview

Dapr offers a preview Dapr Visual Studio Code extension for local development which enables users a variety of features related to better managing their Dapr applications and debugging of your Dapr applications for all supported Dapr languages which are .NET, Go, PHP, Python and Java.

Open in VSCode

Features

Scaffold Dapr debugging tasks

The Dapr extension helps you debug your applications with Dapr using Visual Studio Code’s built-in debugging capability.

Using the Dapr: Scaffold Dapr Tasks Command Palette operation, you can update your existing task.json and launch.json files to launch and configure the Dapr sidecar when you begin debugging.

1. Make sure you have a launch configuration set for your app. (Learn more)
2. Open the Command Palette with Ctrl+Shift+P
3. Select Dapr: Scaffold Dapr Tasks
4. Run your app and the Dapr sidecar with F5 or via the Run view.

Scaffold Dapr components

When adding Dapr to your application, you may want to have a dedicated components directory, separate from the default components initialized as part of dapr init.

To create a dedicated components folder with the default statestore, pubsub, and zipkin components, use the Dapr: Scaffold Dapr Components Command Palette operation.

1. Open your application directory in Visual Studio Code
2. Open the Command Palette with Ctrl+Shift+P
3. Select Dapr: Scaffold Dapr Components
4. Run your application with dapr run --resources-path ./components -- ...

View running Dapr applications

The Applications view shows Dapr applications running locally on your machine.

Invoke Dapr applications

Within the Applications view, users can right-click and invoke Dapr apps via GET or POST methods, optionally specifying a payload.

Publish events to Dapr applications

Within the Applications view, users can right-click and publish messages to a running Dapr application, specifying the topic and payload.

Users can also publish messages to all running applications.

Additional resources

Debugging multiple Dapr applications at the same time

Using the VS Code extension, you can debug multiple Dapr applications at the same time with Multi-target debugging.

Community call demo

Watch this video on how to use the Dapr VS Code extension:

1.1.2 - How-To: Debug Dapr applications with Visual Studio Code

Manual debugging

When developing Dapr applications, you typically use the Dapr CLI to start your daprized service similar to this:

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

One approach to attaching the debugger to your service is to first run daprd with the correct arguments from the command line and then launch your code and attach the debugger. While this is a perfectly acceptable solution, it does require a few extra steps and some instruction to developers who might want to clone your repo and hit the “play” button to begin debugging.

If your application is a collection of microservices, each with a Dapr sidecar, it will be useful to debug them together in Visual Studio Code. This page will use the hello world quickstart to showcase how to configure VSCode to debug multiple Dapr application using VSCode debugging.

Prerequisites

• Install the Dapr extension. You will be using the tasks it offers later on.
• Optionally clone the hello world quickstart

Step 1: Configure launch.json

The file .vscode/launch.json contains launch configurations for a VS Code debug run. This file defines what will launch and how it is configured when the user begins debugging. Configurations are available for each programming language in the Visual Studio Code marketplace.

In the case of the hello world quickstart, two applications are launched, each with its own Dapr sidecar. One is written in Node.JS, and the other in Python. You’ll notice each configuration contains a daprd run preLaunchTask and a daprd stop postDebugTask.

{
    "version": "0.2.0",
    "configurations": [
       {
         "type": "pwa-node",
         "request": "launch",
         "name": "Nodeapp with Dapr",
         "skipFiles": [
             "<node_internals>/**"
         ],
         "program": "${workspaceFolder}/node/app.js",
         "preLaunchTask": "daprd-debug-node",
         "postDebugTask": "daprd-down-node"
       },
       {
         "type": "python",
         "request": "launch",
         "name": "Pythonapp with Dapr",
         "program": "${workspaceFolder}/python/app.py",
         "console": "integratedTerminal",
         "preLaunchTask": "daprd-debug-python",
         "postDebugTask": "daprd-down-python"
       }
    ]
}

If you’re using ports other than the default ports baked into the code, set the DAPR_HTTP_PORT and DAPR_GRPC_PORT environment variables in the launch.json debug configuration. Match with the httpPort and grpcPort in the daprd tasks.json. For example, launch.json:

{
  // Set the non-default HTTP and gRPC ports
  "env": {
      "DAPR_HTTP_PORT": "3502",
      "DAPR_GRPC_PORT": "50002"
  },
}

tasks.json:

{
  // Match with ports set in launch.json
  "httpPort": 3502,
  "grpcPort": 50002
}

Each configuration requires a request, type and name. These parameters help VSCode identify the task configurations in the .vscode/tasks.json files.

• type defines the language used. Depending on the language, it might require an extension found in the marketplace, such as the Python Extension.
• name is a unique name for the configuration. This is used for compound configurations when calling multiple configurations in your project.
• ${workspaceFolder} is a VS Code variable reference. This is the path to the workspace opened in VS Code.
• The preLaunchTask and postDebugTask parameters refer to the program configurations run before and after launching the application. See step 2 on how to configure these.

For more information on VSCode debugging parameters see VS Code launch attributes.

Step 2: Configure tasks.json

For each task defined in .vscode/launch.json , a corresponding task definition must exist in .vscode/tasks.json.

For the quickstart, each service needs a task to launch a Dapr sidecar with the daprd type, and a task to stop the sidecar with daprd-down. The parameters appId, httpPort, metricsPort, label and type are required. Additional optional parameters are available, see the reference table here.

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "daprd-debug-node",
            "type": "daprd",
            "appId": "nodeapp",
            "appPort": 3000,
            "httpPort": 3500,
            "metricsPort": 9090
        },
        {
            "label": "daprd-down-node",
            "type": "daprd-down",
            "appId": "nodeapp"
        },
        {
            "label": "daprd-debug-python",
            "type": "daprd",
            "appId": "pythonapp",
            "httpPort": 53109,
            "grpcPort": 53317,
            "metricsPort": 9091
        },
        {
            "label": "daprd-down-python",
            "type": "daprd-down",
            "appId": "pythonapp"
        }
   ]
}

Step 3: Configure a compound launch in launch.json

A compound launch configuration can defined in .vscode/launch.json and is a set of two or more launch configurations that are launched in parallel. Optionally, a preLaunchTask can be specified and run before the individual debug sessions are started.

For this example the compound configuration is:

{
   "version": "2.0.0",
   "configurations": [...],
   "compounds": [
      {
        "name": "Node/Python Dapr",
        "configurations": ["Nodeapp with Dapr","Pythonapp with Dapr"]
      }
    ]
}

Step 4: Launch your debugging session

You can now run the applications in debug mode by finding the compound command name you have defined in the previous step in the VS Code debugger:

You are now debugging multiple applications with Dapr!

Daprd parameter table

Below are the supported parameters for VS Code tasks. These parameters are equivalent to daprd arguments as detailed in this reference:

Related Links

• Visual Studio Code Extension Overview
• Visual Studio Code Debugging

1.1.3 - Developing Dapr applications with Dev Containers

The Visual Studio Code Dev Containers extension lets you use a self-contained Docker container as a complete development environment, without installing any additional packages, libraries, or utilities in your local filesystem.

Dapr has pre-built Dev Containers for C# and JavaScript/TypeScript; you can pick the one of your choice for a ready made environment. Note these pre-built containers automatically update to the latest Dapr release.

We also publish a Dev Container feature that installs the Dapr CLI inside any Dev Container.

Setup the development environment

Prerequisites

• Docker Desktop
• Visual Studio Code
• VS Code Remote Development extension pack

Add the Dapr CLI using a Dev Container feature

You can install the Dapr CLI inside any Dev Container using Dev Container features.

To do that, edit your devcontainer.json and add two objects in the "features" section:

"features": {
    // Install the Dapr CLI
    "ghcr.io/dapr/cli/dapr-cli:0": {},
    // Enable Docker (via Docker-in-Docker)
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    // Alternatively, use Docker-outside-of-Docker (uses Docker in the host)
    //"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
}

After saving the JSON file and (re-)building the container that hosts your development environment, you will have the Dapr CLI (and Docker) available, and can install Dapr by running this command in the container:

dapr init

Example: create a Java Dev Container for Dapr

This is an example of creating a Dev Container for creating Java apps that use Dapr, based on the official Java 17 Dev Container image.

Place this in a file called .devcontainer/devcontainer.json in your project:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/java
{
	"name": "Java",
	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
	"image": "mcr.microsoft.com/devcontainers/java:0-17",

	"features": {
		"ghcr.io/devcontainers/features/java:1": {
			"version": "none",
			"installMaven": "false",
			"installGradle": "false"
		},
        // Install the Dapr CLI
        "ghcr.io/dapr/cli/dapr-cli:0": {},
        // Enable Docker (via Docker-in-Docker)
        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
        // Alternatively, use Docker-outside-of-Docker (uses Docker in the host)
        //"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
	}

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	// "forwardPorts": [],

	// Use 'postCreateCommand' to run commands after the container is created.
	// "postCreateCommand": "java -version",

	// Configure tool-specific properties.
	// "customizations": {},

	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
	// "remoteUser": "root"
}

Then, using the VS Code command palette (CTRL + SHIFT + P or CMD + SHIFT + P on Mac), select Dev Containers: Rebuild and Reopen in Container.

Use a pre-built Dev Container (C# and JavaScript/TypeScript)

1. Open your application workspace in VS Code
2. In the command command palette (CTRL + SHIFT + P or CMD + SHIFT + P on Mac) type and select Dev Containers: Add Development Container Configuration Files...
   
3. Type dapr to filter the list to available Dapr remote containers and choose the language container that matches your application. Note you may need to select Show All Definitions...
   
4. Follow the prompts to reopen your workspace in the container.
   

Example

Watch this video on how to use the Dapr Dev Containers with your application.

1.2 - IntelliJ

When developing Dapr applications, you typically use the Dapr CLI to start your ‘Daprized’ service similar to this:

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

This uses the default components yaml files (created on dapr init) so that your service can interact with the local Redis container. This is great when you are just getting started but what if you want to attach a debugger to your service and step through the code? This is where you can use the dapr cli without invoking an app.

One approach to attaching the debugger to your service is to first run dapr run -- from the command line and then launch your code and attach the debugger. While this is a perfectly acceptable solution, it does require a few extra steps (like switching between terminal and IDE) and some instruction to developers who might want to clone your repo and hit the “play” button to begin debugging.

This document explains how to use dapr directly from IntelliJ. As a pre-requisite, make sure you have initialized the Dapr’s dev environment via dapr init.

Let’s get started!

Add Dapr as an ‘External Tool’

First, quit IntelliJ before modifying the configurations file directly.

IntelliJ configuration file location

For versions 2020.1 and above the configuration files for tools should be located in:

• Windows
• Linux
• MacOS

%USERPROFILE%\AppData\Roaming\JetBrains\IntelliJIdea2020.1\tools\

$HOME/.config/JetBrains/IntelliJIdea2020.1/tools/

~/Library/Application\ Support/JetBrains/IntelliJIdea2020.1/tools/

The configuration file location is different for version 2019.3 or prior. See here for more details.

Change the version of IntelliJ in the path if needed.

Create or edit the file in <CONFIG PATH>/tools/External\ Tools.xml (change IntelliJ version in path if needed). The <CONFIG PATH> is OS dependent as seen above.

Add a new <tool></tool> entry:

<toolSet name="External Tools">
  ...
  <!-- 1. Each tool has its own app-id, so create one per application to be debugged -->
  <tool name="dapr for DemoService in examples" description="Dapr sidecar" showInMainMenu="false" showInEditor="false" showInProject="false" showInSearchPopup="false" disabled="false" useConsole="true" showConsoleOnStdOut="true" showConsoleOnStdErr="true" synchronizeAfterRun="true">
    <exec>
      <!-- 2. For Linux or MacOS use: /usr/local/bin/dapr -->
      <option name="COMMAND" value="C:\dapr\dapr.exe" />
      <!-- 3. Choose app, http and grpc ports that do not conflict with other daprd command entries (placement address should not change). -->
      <option name="PARAMETERS" value="run -app-id demoservice -app-port 3000 -dapr-http-port 3005 -dapr-grpc-port 52000" />
      <!-- 4. Use the folder where the `components` folder is located -->
      <option name="WORKING_DIRECTORY" value="C:/Code/dapr/java-sdk/examples" />
    </exec>
  </tool>
  ...
</toolSet>

Optionally, you may also create a new entry for a sidecar tool that can be reused across many projects:

<toolSet name="External Tools">
  ...
  <!-- 1. Reusable entry for apps with app port. -->
  <tool name="dapr with app-port" description="Dapr sidecar" showInMainMenu="false" showInEditor="false" showInProject="false" showInSearchPopup="false" disabled="false" useConsole="true" showConsoleOnStdOut="true" showConsoleOnStdErr="true" synchronizeAfterRun="true">
    <exec>
      <!-- 2. For Linux or MacOS use: /usr/local/bin/dapr -->
      <option name="COMMAND" value="c:\dapr\dapr.exe" />
      <!-- 3. Prompts user 4 times (in order): app id, app port, Dapr's http port, Dapr's grpc port. -->
      <option name="PARAMETERS" value="run --app-id $Prompt$ --app-port $Prompt$ --dapr-http-port $Prompt$ --dapr-grpc-port $Prompt$" />
      <!-- 4. Use the folder where the `components` folder is located -->
      <option name="WORKING_DIRECTORY" value="$ProjectFileDir$" />
    </exec>
  </tool>
  <!-- 1. Reusable entry for apps without app port. -->
  <tool name="dapr without app-port" description="Dapr sidecar" showInMainMenu="false" showInEditor="false" showInProject="false" showInSearchPopup="false" disabled="false" useConsole="true" showConsoleOnStdOut="true" showConsoleOnStdErr="true" synchronizeAfterRun="true">
    <exec>
      <!-- 2. For Linux or MacOS use: /usr/local/bin/dapr -->
      <option name="COMMAND" value="c:\dapr\dapr.exe" />
      <!-- 3. Prompts user 3 times (in order): app id, Dapr's http port, Dapr's grpc port. -->
      <option name="PARAMETERS" value="run --app-id $Prompt$ --dapr-http-port $Prompt$ --dapr-grpc-port $Prompt$" />
      <!-- 4. Use the folder where the `components` folder is located -->
      <option name="WORKING_DIRECTORY" value="$ProjectFileDir$" />
    </exec>
  </tool>
  ...
</toolSet>

Create or edit run configuration

Now, create or edit the run configuration for the application to be debugged. It can be found in the menu next to the main() function.

Now, add the program arguments and environment variables. These need to match the ports defined in the entry in ‘External Tool’ above.

• Command line arguments for this example: -p 3000
• Environment variables for this example: DAPR_HTTP_PORT=3005;DAPR_GRPC_PORT=52000

Start debugging

Once the one-time config above is done, there are two steps required to debug a Java application with Dapr in IntelliJ:

1. Start dapr via Tools -> External Tool in IntelliJ.

2. Start your application in debug mode.

Wrapping up

After debugging, make sure you stop both dapr and your app in IntelliJ.

Note: Since you launched the service(s) using the dapr run CLI command, the dapr list command will show runs from IntelliJ in the list of apps that are currently running with Dapr.

Happy debugging!

Related links

• Change in IntelliJ configuration directory location

2 - Multi-App Run

2.1 - Multi-App Run overview

Let’s say you want to run several applications locally to test them together, similar to a production scenario. Multi-App Run allows you to start and stop a set of applications simultaneously, either:

• Locally/self-hosted with processes, or
• By building container images and deploying to a Kubernetes cluster
  • You can use a local Kubernetes cluster (KiND) or one deploy to a Cloud (AKS, EKS, and GKE).

The Multi-App Run template file describes how to start multiple applications as if you had run many separate CLI run commands. By default, this template file is called dapr.yaml.

• Self-hosted
• Kubernetes

version: 1
apps:
  - appID: processor
    appDirPath: ../apps/processor/
    appPort: 9081
    daprHTTPPort: 3510
    command: ["go","run", "app.go"]
  - appID: emit-metrics
    appDirPath: ../apps/emit-metrics/
    daprHTTPPort: 3511
    env:
      DAPR_HOST_ADD: localhost
    command: ["go","run", "app.go"]

dapr run -k -f ./<your-preferred-file-name>.yaml

version: 1
common:
apps:
  - appID: nodeapp
    appDirPath: ./nodeapp/
    appPort: 3000
    containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest
    containerImagePullPolicy: Always
    createService: true
    env:
      APP_PORT: 3000
  - appID: pythonapp
    appDirPath: ./pythonapp/
    containerImage: ghcr.io/dapr/samples/hello-k8s-python:latest

Next steps

• Learn the Multi-App Run template file structure and its properties
• Try out the self-hosted Multi-App Run template with the Service Invocation quickstart
• Try out the Kubernetes Multi-App Run template with the hello-kubernetes tutorial

2.2 - How to: Use the Multi-App Run template file

The Multi-App Run template file is a YAML file that you can use to run multiple applications at once. In this guide, you’ll learn how to:

• Use the multi-app template
• View started applications
• Stop the multi-app template
• Structure the multi-app template file

Use the multi-app template

You can use the multi-app template file in one of the following two ways:

Execute by providing a directory path

When you provide a directory path, the CLI will try to locate the Multi-App Run template file, named dapr.yaml by default in the directory. If the file is not found, the CLI will return an error.

Execute the following CLI command to read the Multi-App Run template file, named dapr.yaml by default:

• Self-hosted
• Kubernetes

# the template file needs to be called `dapr.yaml` by default if a directory path is given

dapr run -f <dir_path>

dapr run -f <dir_path> -k 

Execute by providing a file path

If the Multi-App Run template file is named something other than dapr.yaml, then you can provide the relative or absolute file path to the command:

• Self-hosted
• Kubernetes

dapr run -f ./path/to/<your-preferred-file-name>.yaml

dapr run -f ./path/to/<your-preferred-file-name>.yaml -k 

View the started applications

Once the multi-app template is running, you can view the started applications with the following command:

• Self-hosted
• Kubernetes

dapr list

dapr list -k 

Stop the multi-app template

Stop the multi-app run template anytime with either of the following commands:

• Self-hosted
• Kubernetes

# the template file needs to be called `dapr.yaml` by default if a directory path is given

dapr stop -f <dir_path>

dapr stop -f ./path/to/<your-preferred-file-name>.yaml

# the template file needs to be called `dapr.yaml` by default if a directory path is given

dapr stop -f <dir_path> -k

dapr stop -f ./path/to/<your-preferred-file-name>.yaml -k 

Template file structure

The Multi-App Run template file can include the following properties. Below is an example template showing two applications that are configured with some of the properties.

• Self-hosted
• Kubernetes

version: 1
common: # optional section for variables shared across apps
  resourcesPath: ./app/components # any dapr resources to be shared across apps
  env:  # any environment variable shared across apps
    DEBUG: true
apps:
  - appID: webapp # optional
    appDirPath: .dapr/webapp/ # REQUIRED
    resourcesPath: .dapr/resources # deprecated
    resourcesPaths: .dapr/resources # comma separated resources paths. (optional) can be left to default value by convention.
    appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention.
    configFilePath: .dapr/config.yaml # (optional) can be default by convention too, ignore if file is not found.
    appProtocol: http
    appPort: 8080
    appHealthCheckPath: "/healthz"
    command: ["python3", "app.py"]
    appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole.
    daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file.
  - appID: backend # optional
    appDirPath: .dapr/backend/ # REQUIRED
    appProtocol: grpc
    appPort: 3000
    unixDomainSocket: "/tmp/test-socket"
    env:
      DEBUG: false
    command: ["./backend"]

version: 1
common: # optional section for variables shared across apps
  env:  # any environment variable shared across apps
    DEBUG: true
apps:
  - appID: webapp # optional
    appDirPath: .dapr/webapp/ # REQUIRED
    appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention.
    appProtocol: http
    appPort: 8080
    appHealthCheckPath: "/healthz"
    appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole.
    daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file.
    containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest # (optional) URI of the container image to be used when deploying to Kubernetes dev/test environment.
    containerImagePullPolicy: IfNotPresent # (optional), the container image is downloaded if one is not present locally, otherwise the local one is used.
    createService: true # (optional) Create a Kubernetes service for the application when deploying to dev/test environment.
  - appID: backend # optional
    appDirPath: .dapr/backend/ # REQUIRED
    appProtocol: grpc
    appPort: 3000
    unixDomainSocket: "/tmp/test-socket"
    env:
      DEBUG: false

Template properties

• Self-hosted
• Kubernetes

3 - How to: Use the gRPC interface in your Dapr application

Dapr implements both an HTTP and a gRPC API for local calls. gRPC is useful for low-latency, high performance scenarios and has language integration using the proto clients.

Find a list of auto-generated clients in the Dapr SDK documentation.

The Dapr runtime implements a proto service that apps can communicate with via gRPC.

In addition to calling Dapr via gRPC, Dapr supports service-to-service calls with gRPC by acting as a proxy. Learn more in the gRPC service invocation how-to guide.

This guide demonstrates configuring and invoking Dapr with gRPC using a Go SDK application.

Configure Dapr to communicate with an app via gRPC

• Self-hosted
• Kubernetes

dapr run --app-protocol grpc --app-port 5005 node app.js

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: default
  labels:
    app: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
      annotations:
        dapr.io/enabled: "true"
        dapr.io/app-id: "myapp"
        dapr.io/app-protocol: "grpc"
        dapr.io/app-port: "5005"
...

Invoke Dapr with gRPC

The following steps show how to create a Dapr client and call the SaveStateData operation on it.

1. Import the package:

   package main
   
   import (
   	"context"
   	"log"
   	"os"
   
   	dapr "github.com/dapr/go-sdk/client"
   )
   

2. Create the client:

   // just for this demo
   ctx := context.Background()
   data := []byte("ping")
   
   // create the client
   client, err := dapr.NewClient()
   if err != nil {
     log.Panic(err)
   }
   defer client.Close()
   

   3. Invoke the SaveState method:

   // save state with the key key1
   err = client.SaveState(ctx, "statestore", "key1", data)
   if err != nil {
     log.Panic(err)
   }
   log.Println("data saved")
   

Now you can explore all the different methods on the Dapr client.

Create a gRPC app with Dapr

The following steps will show how to create an app that exposes a server for with which Dapr can communicate.

1. Import the package:

   package main
   
   import (
   	"context"
   	"fmt"
   	"log"
   	"net"
   
   	"github.com/golang/protobuf/ptypes/any"
   	"github.com/golang/protobuf/ptypes/empty"
   
   	commonv1pb "github.com/dapr/dapr/pkg/proto/common/v1"
   	pb "github.com/dapr/dapr/pkg/proto/runtime/v1"
   	"google.golang.org/grpc"
   )
   

2. Implement the interface:

   // server is our user app
   type server struct {
        pb.UnimplementedAppCallbackServer
   }
   
   // EchoMethod is a simple demo method to invoke
   func (s *server) EchoMethod() string {
   	return "pong"
   }
   
   // This method gets invoked when a remote service has called the app through Dapr
   // The payload carries a Method to identify the method, a set of metadata properties and an optional payload
   func (s *server) OnInvoke(ctx context.Context, in *commonv1pb.InvokeRequest) (*commonv1pb.InvokeResponse, error) {
   	var response string
   
   	switch in.Method {
   	case "EchoMethod":
   		response = s.EchoMethod()
   	}
   
   	return &commonv1pb.InvokeResponse{
   		ContentType: "text/plain; charset=UTF-8",
   		Data:        &any.Any{Value: []byte(response)},
   	}, nil
   }
   
   // Dapr will call this method to get the list of topics the app wants to subscribe to. In this example, we are telling Dapr
   // To subscribe to a topic named TopicA
   func (s *server) ListTopicSubscriptions(ctx context.Context, in *empty.Empty) (*pb.ListTopicSubscriptionsResponse, error) {
   	return &pb.ListTopicSubscriptionsResponse{
   		Subscriptions: []*pb.TopicSubscription{
   			{Topic: "TopicA"},
   		},
   	}, nil
   }
   
   // Dapr will call this method to get the list of bindings the app will get invoked by. In this example, we are telling Dapr
   // To invoke our app with a binding named storage
   func (s *server) ListInputBindings(ctx context.Context, in *empty.Empty) (*pb.ListInputBindingsResponse, error) {
   	return &pb.ListInputBindingsResponse{
   		Bindings: []string{"storage"},
   	}, nil
   }
   
   // This method gets invoked every time a new event is fired from a registered binding. The message carries the binding name, a payload and optional metadata
   func (s *server) OnBindingEvent(ctx context.Context, in *pb.BindingEventRequest) (*pb.BindingEventResponse, error) {
   	fmt.Println("Invoked from binding")
   	return &pb.BindingEventResponse{}, nil
   }
   
   // This method is fired whenever a message has been published to a topic that has been subscribed. Dapr sends published messages in a CloudEvents 0.3 envelope.
   func (s *server) OnTopicEvent(ctx context.Context, in *pb.TopicEventRequest) (*pb.TopicEventResponse, error) {
   	fmt.Println("Topic message arrived")
           return &pb.TopicEventResponse{}, nil
   }
   

3. Create the server:

   func main() {
   	// create listener
   	lis, err := net.Listen("tcp", ":50001")
   	if err != nil {
   		log.Fatalf("failed to listen: %v", err)
   	}
   
   	// create grpc server
   	s := grpc.NewServer()
   	pb.RegisterAppCallbackServer(s, &server{})
   
   	fmt.Println("Client starting...")
   
   	// and start...
   	if err := s.Serve(lis); err != nil {
   		log.Fatalf("failed to serve: %v", err)
   	}
   }
   

   This creates a gRPC server for your app on port 50001.

Run the application

• Self-hosted
• Kubernetes

dapr run --app-id goapp --app-port 50001 --app-protocol grpc go run main.go

Other languages

You can use Dapr with any language supported by Protobuf, and not just with the currently available generated SDKs.

Using the protoc tool, you can generate the Dapr clients for other languages like Ruby, C++, Rust, and others.

Related Topics

• Service invocation building block
• Service invocation API specification

4 - Serialization in Dapr's SDKs

Dapr SDKs provide serialization for two use cases. First, for API objects sent through request and response payloads. Second, for objects to be persisted. For both of these cases, a default serialization method is provided in each language SDK.

Service invocation

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    await client.InvokeMethodAsync("myappid", "saySomething", "My Message");

    DaprClient client = (new DaprClientBuilder()).build();
    client.invokeMethod("myappid", "saySomething", "My Message", HttpExtension.POST).block();

In the example above, the app myappid receives a POST request for the saySomething method with the request payload as "My Message" - quoted since the serializer will serialize the input String to JSON.

POST /saySomething HTTP/1.1
Host: localhost
Content-Type: text/plain
Content-Length: 12

"My Message"

State management

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    var state = new Dictionary<string, string>
    {
      { "key": "MyKey" },
      { "value": "My Message" }
    };
    await client.SaveStateAsync("MyStateStore", "MyKey", state);

    DaprClient client = (new DaprClientBuilder()).build();
    client.saveState("MyStateStore", "MyKey", "My Message").block();

In this example, My Message is saved. It is not quoted because Dapr’s API internally parse the JSON request object before saving it.

[
    {
        "key": "MyKey",
        "value": "My Message"
    }
]

PubSub

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    await client.PublishEventAsync("MyPubSubName", "TopicName", "My Message");

public async Task<IActionResult> HandleMessage(string message) 
{
  //ASP.NET Core automatically deserializes the UTF-8 encoded bytes to a string
  return new Ok();
}

app.MapPost("/TopicName", [Topic("MyPubSubName", "TopicName")] (string message) => {
  return Results.Ok();
}

  DaprClient client = (new DaprClientBuilder()).build();
  client.publishEvent("TopicName", "My Message").block();

  @PostMapping(path = "/TopicName")
  public void handleMessage(@RequestBody(required = false) byte[] body) {
      // Dapr's event is compliant to CloudEvent.
      CloudEvent event = CloudEvent.deserialize(body);
  }

Bindings

For output bindings the object is serialized to byte[] whereas the input binding receives the raw byte[] as-is and deserializes it to the expected object type.

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    await client.InvokeBindingAsync("sample", "My Message");

  [ApiController]
  public class SampleController : ControllerBase
  {
    [HttpPost("propagate")]
    public ActionResult<string> GetValue([FromBody] int itemId)
    {
      Console.WriteLine($"Received message:  {itemId}");
      return $"itemID:{itemId}";
    }
  }

app.MapPost("value", ([FromBody] int itemId) =>
{
  Console.WriteLine($"Received message: {itemId}");
  return ${itemID:{itemId}";
});

    DaprClient client = (new DaprClientBuilder()).build();
    client.invokeBinding("sample", "My Message").block();

  @PostMapping(path = "/sample")
  public void handleInputBinding(@RequestBody(required = false) byte[] body) {
      String message = (new DefaultObjectSerializer()).deserialize(body, String.class);
      System.out.println(message);
  }

It should print:

My Message

Actor Method invocation

Object serialization and deserialization for Actor method invocation are same as for the service method invocation, the only difference is that the application does not need to deserialize the request or serialize the response since it is all done transparently by the SDK.

For Actor methods, the SDK only supports methods with zero or one parameter.

• .NET
• Java

    var proxy = this.ProxyFactory.Create(ActorId.CreateRandom(), "DemoActor");
    await proxy.SayAsync("My message");

public Task SayAsync(string message) 
{
    Console.WriteLine(message);
    return Task.CompletedTask;
}

public static void main() {
    ActorProxyBuilder builder = new ActorProxyBuilder("DemoActor");
    String result = actor.invokeActorMethod("say", "My Message", String.class).block();
}

public String say(String something) {
  System.out.println(something);
  return "OK";
}

It should print:

    My Message

Actor’s state management

Actors can also have state. In this case, the state manager will serialize and deserialize the objects using the state serializer and handle it transparently to the application.

• .NET
• Java

public Task SayAsync(string message) 
{
    // Reads state from a key
    var previousMessage = await this.StateManager.GetStateAsync<string>("lastmessage");
    
    // Sets the new state for the key after serializing it
    await this.StateManager.SetStateAsync("lastmessage", message);
    return previousMessage;
}

public String actorMethod(String message) {
    // Reads a state from key and deserializes it to String.
    String previousMessage = super.getActorStateManager().get("lastmessage", String.class).block();

    // Sets the new state for the key after serializing it.
    super.getActorStateManager().set("lastmessage", message).block();
    return previousMessage;
}

Default serializer

The default serializer for Dapr is a JSON serializer with the following expectations:

1. Use of basic JSON data types for cross-language and cross-platform compatibility: string, number, array, boolean, null and another JSON object. Every complex property type in application’s serializable objects (DateTime, for example), should be represented as one of the JSON’s basic types.
2. Data persisted with the default serializer should be saved as JSON objects too, without extra quotes or encoding. The example below shows how a string and a JSON object would look like in a Redis store.

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||message
"This is a message to be saved and retrieved."

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||mydata
{"value":"My data value."}

3. Custom serializers must serialize object to byte[].
4. Custom serializers must deserialize byte[] to object.
5. When user provides a custom serializer, it should be transferred or persisted as byte[]. When persisting, also encode as Base64 string. This is done natively by most JSON libraries.

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||message
"VGhpcyBpcyBhIG1lc3NhZ2UgdG8gYmUgc2F2ZWQgYW5kIHJldHJpZXZlZC4="

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||mydata
"eyJ2YWx1ZSI6Ik15IGRhdGEgdmFsdWUuIn0="