Practical Microservices with Dapr and .NET

By Davide Bedin
  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Chapter 1: Introducing Dapr

About this book

Over the last decade, there has been a huge shift from heavily coded monolithic applications to finer, self-contained microservices. Dapr is a new, open source project by Microsoft that provides proven techniques and best practices for developing modern applications. It offers platform-agnostic features for running your applications on public cloud, on-premises, and even on edge devices.

This book will help you get to grips with microservice architectures and how to manage application complexities with Dapr in no time. You'll understand how Dapr offers ease of implementation while allowing you to work with multiple languages and platforms. You'll also understand how Dapr's runtime, services, building blocks, and software development kits (SDKs) help you to simplify the creation of resilient and portable microservices. Dapr provides an event-driven runtime that supports the essential features you need to build microservices, including service invocation, state management, and publish/subscribe messaging. You'll explore all of those in addition to various other advanced features with this practical guide to learning Dapr.

By the end of this book, you'll be able to write microservices easily using your choice of language or framework by implementing industry best practices to solve problems related to distributed systems.

Publication date:
December 2020


Chapter 1: Introducing Dapr

This chapter will introduce you to the Distributed Application Runtime (Dapr) project to teach you the core concepts of its architecture and prepare you to develop with Dapr.

Dapr accelerates the development of new cloud-native applications and simplifies the adoption of microservice architecture.

In this chapter, we are going to cover the following main topics:

  • An overview of Dapr
  • The architecture of Dapr
  • Setting up Dapr
  • Building our first Dapr sample

At this stage, learning these topics is important with regard to obtaining a solid foundation on Dapr internals and understanding its approach to microservices architecture. These basic concepts will guide our learning throughout the rest of this book.

Our first steps into the project will start with exploring Dapr and understanding how it works.


Technical requirements

The code for this sample can be found in GitHub at

In this chapter, the working area for scripts and code is expected to be <repository path>\chapter01\. In my local environment, it is C:\Repos\dapr-samples\chapter01.

Please refer to the section Setting up Dapr for a complete guide on the tools needed to develop with Dapr and work with the samples.


An overview of Dapr

Dapr is an event-driven, portable runtime, created by Microsoft with an open source approach and, at the time of writing this book, still in active development.

Being event-driven, which is emphasized in the definition of Dapr, plays an important role in microservices as the application can be designed to efficiently react to events, from external systems or other parts of the solution, and to produce events as well, in order to inform other services of new facts or to continue processing elsewhere or at a later stage.

Dapr is portable as it can run locally on your development machine in self-hosted mode, it can be deployed to the edge, or it can run on Kubernetes.

The following diagram shows the many building blocks of Dapr architecture:

Fig 1.1 – Dapr architecture

Fig 1.1 – Dapr architecture

Portability does also extend beyond the hosting environment – while Dapr is an initiative started by Microsoft, it can also run on Kubernetes on-premise or in the cloud: Microsoft Azure, Amazon AWS, Google GCP, or any other cloud vendor.

Dapr has been built on the experiences gained by Microsoft in developing hyperscale cloud-native applications. It has been inspired by the design of Orleans and Service Fabric, which in turn enable many Microsoft Azure cloud services to operate resiliently and at large scale.

Dapr offers developers an approach to design, the tools to build, and the runtime to operate applications based on the microservices architecture style.

Microservices offer a vast array of benefits balanced by increased complexities in team and product management, usually with a significant burden on the developer and the team in order to get started.

What if you could leverage a runtime such as Dapr to help you get through the common patterns you will likely need to adopt and ease your operations?

This diagram shows the two Dapr hosting modes:

Fig 1.2. Dapr sidecar

Fig 1.2. Dapr sidecar

As depicted in Figure 1.2, the Dapr runtime operates in sidecar processes, lifting most of the complexity from the application to a separate environment, greatly simplifying development and operations as well. These sidecar processes are run locally in your development environment or as containers in a Pod on Kubernetes.

From the application perspective, Dapr is an API that can be directly reached via HTTP or gRPC calls or, even more simply, via any of the SDKs available. At the time of writing this book, these are .NET Core, Java, Go, Python, C++, JavaScript, and Rust.

As we will experience later, it is not necessary to adopt the Dapr SDK in your application: a call to a Dapr service can be as simple as an HTTP call to an endpoint such as http://localhost:3500/v1.0/invoke/<app-id>/method/<method name>. Nevertheless, using the SDK does provide many benefits if you are writing a Dapr service or leveraging the Dapr actor model.

What Dapr is not

While I hope the overview of Dapr informed and intrigued you enough to spend your time on this book, when I have the chance to talk about Dapr, I often find myself in need of clarifying what Dapr is not. This makes it easier to eliminate any misconceptions we may have about what Dapr does:

  • Dapr's goal is not to force the developer to embrace a programming model with strict rules and constraints. On the contrary, while the application developer is freed by Dapr of the many complexities of a microservice architecture, the developer is not mandated on how to write the application. As an example, the management of the connection pooling to the database where the state is stored is a responsibility of Dapr and, as we will see in the following chapters, it is transparent to the microservice application code.
  • Dapr is not a service mesh. While many similarities can be found in the general objectives of Dapr and service meshes, Dapr does provide these benefits at the application level while a service mesh operates on the infrastructure. For instance, Dapr applies retry logic in its interaction with state stores and services, but it is the developer's responsibility to decide how to handle the error Dapr might return if there is a conflict or an intermittent issue: whether raising the error back to the client, compensating the operation, or adopting a retry policy (maybe leveraging Polly in .NET Core) – it is an explicit choice only the developer can make. Dapr is meant to be integrated with service meshes, such as Istio, which is out of the scope of this book.
  • Dapr is not a Microsoft cloud service: it does help the developer build microservice applications in the cloud, and it surely provides many integrations with Azure cloud services, but it also has as many components for AWS, GCP, and other services.

    It is also true that Dapr does not run on Azure better than on any other Kubernetes environment in the cloud. I would like to convince you that Azure Kubernetes Service is the best managed Kubernetes offering in the cloud space, but this is a different conversation for another time.

    Important note

    While this book is heavily skewed toward .NET Core, Dapr does provide the same benefits to Python (just as an example) developers, as it provides SDKs for Dapr and Dapr actor, working on macOS and with Kubernetes as the deployment target: Dapr welcomes all developers in a vendor-neutral and open approach.

The next section will be dedicated to understanding the architectures that Dapr can enable.


The architecture of Dapr

Dapr has been designed from the ground up as a set of pluggable building blocks: developers can create an application counting on the support of many facilities while operators can adapt applications to the hosting environment by simply intervening in the configuration.

The following is a complete list of the tools and components of Dapr:

  • The Dapr CLI: A cross-platform command-line tool to configure, manage, and monitor the Dapr environment. It is also the tool to locally debug Dapr applications.
  • The Dapr API: The API that defines how an application can interact with the Dapr runtime in order to leverage its building blocks.
  • The Dapr runtime: This is the core of Dapr, which implements the API. If you are curious, you can take a look at how it is developed in Go at Dapr's repository:
  • The Dapr host: On your development machine, the host runs as a standalone process; in Kubernetes, it is a sidecar container in your application's pod.
  • The Dapr operator: Specific to Kubernetes mode, the operator manages bindings and configurations.
  • The Dapr sidecar injector: Once instructed via configuration in Kubernetes mode, it takes care of injecting the Dapr sidecar into your application pod.
  • The Dapr placement service: This service has the objective of distributing (or placing) actor instances across the Dapr pods.
  • Dapr Sentry: A built-in certificate authority to issue and manage certificates used by Dapr to provide transparent mTLS.

Dapr provides several building blocks that microservice application developers can adopt selectively, based on their needs:

  • Service invocation: Service-to-service invocation enables your code to call other services located in the same hosting environment while taking care of the retry policy.

    This building block is presented in more detail in Chapter 3, Service-to-Service Invocation.

  • State management: This is to efficiently manage the application state as a simple key/value pair, relieving your stateful or stateless services of the need to support different backends. Dapr provides many state stores, which include Redis, Azure CosmosDB, Azure SQL Server, PostgreSQL, which can be plugged in via configuration.

    You can learn about this building block in Chapter 4, Introducing State Management.

  • Publish and subscribe messaging: The publish/subscribe pattern enables decoupled communication between microservices by exchanging messages, counting on the presence of a service bus, which can route messages between producers and consumers.

    A discussion of this building block is presented in Chapter 5, Publish and Subscribe.

  • Resource bindings: This is where the event-driven nature of Dapr shines: with bindings, your application can be triggered by an SMS sent via Twilio (just to name a popular service in this area).

    This building block is presented in more detail in Chapter 6, Resource Bindings.

  • Actors: The actor pattern aims to simplify highly concurrent scenarios by splitting the overall requests load between a large number of computation units (the actors), which take care of the job in their smaller, but independent, scope by processing requests to a single actor one at a time: Dapr provides great benefits in this space.

    You can learn about this building block in Chapter 7, Using Actors.

  • Observability: Dapr enables the developer and operator to observe the behavior of the system services and applications without having to instrument them.

    This building block is presented in more detail in Chapter 9, Tracing Dapr Applications.

  • Secrets: It is a common requirement and a healthy practice to keep secrets at a safe distance from the code, even if only to prevent unintended access in a development environment to the connection string intended for the production environment. Dapr enables you to store secrets and to reference these from other Dapr components, in Kubernetes or Azure Key Vault, among many options.

After learning about Dapr architecture and components, and before we can start using them, we need to set up Dapr in our development environment, which will be the topic of the next section.


Setting up Dapr

Dapr is a runtime for every platform and every language. The focus of this book is on C# in .NET Core, used from Visual Studio Code. The code snippets in the book can be appreciated by developers from any background, but nevertheless, you will get the most out of it from the .NET Core perspective.

The development environment I use is Windows 10, as you will be able to tell from the screenshots we use in the book. While the CLI, configuration, and files will be the same, if you need more details on how to perform a particular action on Linux or a macOS development machine, I encourage you to check the Dapr documentation at

Important note: roadmap to v1.0

The Dapr runtime is getting closer to being released as the v1.0 production-ready version.

The samples and scripts in this book have been tested with the first release candidate (RC) of Dapr, version v1.0.0.0-rc.1.


Dapr requires Docker locally on your development environment, therefore make sure you have it installed. If your development machine is Windows, Docker must be running in Linux containers mode.

You can find detailed instructions for running Docker at

The Dapr CLI

We will immediately start working with Dapr; therefore, you need to install all the necessary tools. The Dapr runtime and its tools can be found at

On Windows, it is suggested to use the following command to install the CLI in the %USERPROFILE%\.dapr\ folder and add it to the user PATH environment variable so the tools can be found from the command line:

powershell -Command "$script=iwr -useb; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList 1.0.0-rc.2"

The previous command installs a release candidate version of the Dapr CLI. Please refer to for details.

We still need to initialize Dapr on the development machine, which we will do later in this chapter.

.NET Core

To install .NET Core, please refer to for the link to the latest binaries.

On a development machine, it makes sense to install the full SDK, which includes the runtime. Once the install is complete, open a new Command Prompt and run the command dotnet --info. You should see the following output:

PS C:\Repos\dapr-samples\chapter01> dotnet --info
.NET Core SDK (reflecting any global.json):
 Version:   3.1.200
 Commit:    c5123d973b
Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.19041
 OS Platform: Windows
 RID:         win10-x64
 Base Path:   C:\Program Files\dotnet\sdk\3.1.200\

This proves dotnet has been recognized and the framework is working fine.

Visual Studio Code

Visual Studio Code (also referred to as VS Code throughout the book) is a great multiplatform source code editor by Microsoft. You can install it for free by following the instructions at

The Dapr extension

Dapr has an extension for Visual Studio Code that helps with navigating the Dapr local environment and eases the debugging configuration – I highly recommend it. Please follow the instructions at

Windows Terminal

I really love the new Windows Terminal ( for its ease of use and configurability. In the following chapters, we will often have to run multiple commands and tools in parallel. Therefore, the tabs feature of Windows Terminal is just one of the reasons why I suggest you adopt it too.

Installing self-hosted Dapr

Dapr can be initialized in two modes: self-hosted (or standalone) and Kubernetes.

As it is intended to be used only for a development environment, the self-hosted mode locally installs Redis, the Dapr placement services, and Zipkin. The following command initializes Dapr on your local environment:

dapr init

In a local development environment, it might happen that the ports Dapr intends to use for Redis, for example, are already in use. In this case, you should identify which processes or containers are using the ports and change it accordingly.

Once you launch the init, this is the output you should expect:

PS C:\dapr> dapr init
Making the jump to hyperspace...
Downloading binaries and setting up components...
Downloaded binaries and completed components set up.
daprd binary has been installed to C:\Users\dabedin\.dapr\bin.
dapr_placement container is running.
dapr_redis container is running.
dapr_zipkin container is running.
Use `docker ps` to check running containers.
Success! Dapr is up and running. To get started, go here:

To check your newly initialized Dapr environment, you can use docker ps:

PS C:\dapr> docker ps --format "{{.ID}}: {{.Image}} - {{.Ports}} - {{.Names}}"
2082b7f0eda4: daprio/dapr ->50005/tcp - dapr_placement
6c68d869cea7: redis ->6379/tcp - dapr_redis
e4c8eae6992d: openzipkin/zipkin - 9410/tcp,>9411/tcp - dapr_zipkin

The output shows the Docker container running on my machine.

Installing Dapr in Kubernetes

Dapr is specifically intended to be executed on Kubernetes. From your development machine, on which you have the Dapr CLI installed, you can set up Dapr on the Kubernetes cluster currently configured:

dapr init -k 

Alternatively, you can install Dapr on Kubernetes with a Helm v3 chart. You can find more details at

Important note

If you intend to define a CI/CD pipeline that takes care of the Dapr installation on the Kubernetes cluster too, this can also work, although it is out of scope for the present setup.

To verify the installation completed successfully, execute this command:

kubectl get pods --namespace dapr-system

The command should display the pods in the dapr-system namespace.

Updating the Dapr version

On a development Windows machine, on which a previous version of Dapr was already present, this is the output of an update of the CLI:

powershell -Command "$script=iwr -useb; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList 1.0.0-rc.2"
WARNING: Dapr is detected - c:\dapr\dapr.exe
CLI version: 0.11.0
Runtime version: n/a
Reinstalling Dapr...
Creating c:\dapr directory
Downloading ...
Extracting c:\dapr\
CLI version: 1.0.0-rc.2
Runtime version: n/a
Clean up c:\dapr\
Try to add c:\dapr to User Path Environment variable...
Skipping to add c:\dapr to User Path - … omitted …
Dapr CLI is installed successfully.
To get started with Dapr, please visit .
Ensure that Docker Desktop is set to Linux containers mode when you run Dapr in self hosted mode.

The process to update the Dapr runtime is similar to the initialization, but first, we will need to uninstall Dapr from your machine:

PS C:\dapr> dapr uninstall
Removing Dapr from your machine...
Removing directory: C…
Removing container: dapr_placement
Dapr has been removed successfully

After we execute dapr init, if we check the Dapr version, we can see it is now moved forward from 0.8.0 to 0.10.0 for both the CLI and the runtime:

PS C:\dapr> dapr --version
CLI version: 1.0.0-rc.2
Runtime version: 1.0.0-rc.1

Our Dapr test environment is up and running: we are now ready to try it with the first sample.


Building our first Dapr example

It is time to see Dapr in action: we are going to build a web API that returns a hello world message. I chose to base all my samples in the C:\Repos\dapr-samples\ folder, and I created a C:\Repos\dapr-samples\chapter01 folder for this first example:

  1. Let's start by creating a WebAPI .NET Core project:
    PS C:\Repos\dapr-samples\chapter01> dotnet new webapi -o dapr.microservice.webapi
  2. Then we add the reference to the Dapr SDK for ASP.NET Core. The current version is 0.12.0-preview01. You can look for the package versions on NuGet at with the dotnet add package command:
    PS C:\Repos\dapr-samples\chapter01> dotnet add package Dapr.AspNetCore --version 0.12.0-preview01
  3. We need to apply some changes to the template we used to create the project. These are going to be much easier to do via VS Code, with the <directory>\code. command We open it in the scope of the project folder.
  4. To support Dapr in ASP.NET Core, I made a few changes to the code. In Startup.cs, I changed the method ConfigureServices to services.AddControllers().AddDapr();.

    In Configure, I also added endpoints.MapSubscribeHandler();. This is not necessary for this sample as we will not use the pub/sub features of Dapr. Nevertheless, it is better to have it in mind as the base set of changes you need to apply to a default ASP.NET project.

    Finally, in order to simplify the code, I removed app.UseHttpsRedirection();.

    The following is the modified code of the Startup.cs class:

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Hosting;
    using Microsoft.AspNetCore.HttpsPolicy;
    using Microsoft.AspNetCore.Mvc;
    using Microsoft.Extensions.Configuration;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Hosting;
    using Microsoft.Extensions.Logging;
    namespace dapr.microservice.webapi
        public class Startup
            public Startup(IConfiguration configuration)
                Configuration = configuration;
            public IConfiguration Configuration { get; }
            // This method gets called by the runtime. Use 
               this method to add services to the container.
            public void ConfigureServices(IServiceCollection 
            // This method gets called by the runtime. Use 
               this method to configure the HTTP request 
            public void Configure(IApplicationBuilder app, 
            IWebHostEnvironment env)
                if (env.IsDevelopment())
                app.UseEndpoints(endpoints =>

    In the preceding code, I instructed Dapr to leverage the MVC pattern in ASP.NET Core. Keep in mind there is an alternate approach for Dapr in ASP.NET Core, which does rely on ASP.NET Core routing with MapGet(...) and MapPost(...). You can see an example at

  5. Finally, I added a controller named HelloWorldController:
    using Dapr;
    using Microsoft.AspNetCore.Mvc;
    using System;
    namespace dapr.microservice.webapi.Controllers
        public class HelloWorldController : ControllerBase
            public ActionResult<string> Get()
                Console.WriteLine("Hello, World.");
                return "Hello, World";

    In the preceding code, you can see [HttpGet("hello")]: this ASP.NET Core attribute is evaluated by Dapr to identify the method name.

  6. In order to run a Dapr application, you use the following format:
    dapr run –app-id <your app id> --app-port <port of the application> --dapr-http-port <port in Dapr> dotnet run

    I left the ASP.NET Core default port 5000 but I changed the Dapr HTTP port to 5010. The following command line launches the Dapr application:

    PS C:\Repos\dapr-samples\chapter01\dapr.microservice.webapi> dapr run --app-id hello-world --app-port 5000 --dapr-http-port 5010 dotnet run
    Starting Dapr with id hello-world. HTTP Port: 5010. gRPC Port: 52443

    The initial message informs you that Dapr is going to use port 5010 for HTTP as specified, while for gRPC it is going to auto-select an available port.

    The log from Dapr is full of information. To confirm your application is running correctly in the context of the Dapr runtime, you can look for this part:

    Updating metadata for app command: dotnet run
    You're up and running! Both Dapr and your app logs will appear here.

    At this stage, ASP.NET Core is responding locally on port 5000 and Dapr is responding on 5010. In order to test Dapr, let's invoke a curl command. Using the browser is equally fine:

    PS C:\Windows\System32> curl http://localhost:5010/v1.0/invoke/hello-world/method/hello
    Hello, World

    This exciting response has been returned by Dapr, which passed our (the client's) initial request to the ASP.NET Core Web API. You should also see it logged, as Console.WriteLine sends its output to the Dapr window:

    == APP == Hello, World.
  7. From another window, let's verify our Dapr service details: instead of using the dapr list command, let's open the Dapr dashboard:
    PS C:\Windows\System32> dapr dashboard
    Dapr Dashboard running on http://localhost:8080

We can open the dashboard by navigating to http://localhost:8080:

Fig. 1.3 – Dapr dashboard application

Fig. 1.3 – Dapr dashboard application

The Dapr dashboard shown in the figure illustrates the details of our hello-world application.

In this case, the Dapr dashboard shows only this sample application we are running on the development machine. In a Kubernetes environment, it would show all the microservices running and the other components.

The Dapr dashboard also displays the configured components in the hosting environment:

Fig. 1.4 – Dapr dashboard components

Fig. 1.4 – Dapr dashboard components

In Figure 1.4, the Dapr dashboard shows us that the local installation of Redis is configured as state store and pub/sub components, in addition to the deployment of Zipkin.

This ends our introductory section where we were able to build our first Dapr sample.



In this chapter, you have learned about the Distributed Application Runtime project, with its components, building blocks, and the sidecar approach. All of these concepts will be explored individually in further depth in the following chapters. You are now able to set up Dapr on your local development machine and prepare all the necessary tools to make this experience easier.

You have also learned how to create a simple ASP.NET Core project, how to configure and check Dapr, and we have had a glimpse of the Dapr dashboard to gain a complete and immediate view of the Dapr environment.

In the next chapter, we will use the newly created environment to learn how to debug Dapr.

About the Author

  • Davide Bedin

    Davide Bedin is a cloud-native architecture enthusiast, with strong and relevant experience with cloud platforms. As CTO of an ISV, Davide led its significant transformational process with the objective of creating new solutions based on the Microsoft Azure cloud. Davide particularly focused on the evolution of distributed computing to service-oriented architectures, and ultimately microservices, spending most of his developer career creating web services. As a cloud solution architect at Microsoft, Davide is responsible for the guidance and support of enterprise customers in embracing the cloud paradigm, a key enabler of their digital transformation; lately, he also plays with Dapr.

    Browse publications by this author
Book Title
Access this book, plus 7,500 other titles for FREE
Access now