

Chapter 1: Introducing Dapr

PREV NEXT
⏮ ⏭
Section 1: Introduction to Dapr Chapter 2: Debugging Dapr Solutions
 🔎

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 sim-

plifies the adoption of a 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 mi-
croservice architectures. 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
https://github.com/PacktPublishing/Practical-Microservices-with-Dapr-
and-.NET/tree/main/chapter01.

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

Please refer to the Setting up Dapr section for a complete guide to 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, is still in active
development.

Being event-driven, which is emphasized in the definition of Dapr, plays an

important role in microservices as an 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 also be deployed to the edge, or it can run on
Kubernetes.

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

Figure 1.1 – Dapr architecture

Portability does also extend beyond the hosting environment—while Dapr is

an initiative that was started by Microsoft, it can also run on Kubernetes on-
premises or in the cloud, with Microsoft Azure, Amazon Web Services
(AWS), Google Cloud Platform (GCP), or any other cloud vendor.

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

Dapr offers developers an approach to design the tools to build and the run-
time to operate applications, based on a microservice architecture style.

Microservices offer a vast array of benefits balanced by increased complexi-

ties 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 thus ease your
operations?

This diagram shows the two Dapr hosting modes:

Figure 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 pro-
cesses are run locally in your development environment or as containers in a
Pod on Kubernetes.

From an application perspective, Dapr is an application programming inter-

face (API) that can be directly reached via HyperText Transfer Protocol
(HTTP) or gRPC Remote Procedure Call (gRPC) calls or, even more simply,
via any of the software development kits (SDKs) available. At the time of
writing this book, these SDKs are .NET, 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 has informed and intrigued you enough to
spend 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 elimi-
nate any misconceptions we may have about what Dapr does, as follows:

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 errors Dapr might return if there is a conflict or an
intermittent issue: whether raising an error back to the client,
compensating an operation, or adopting a retry policy (maybe leveraging
Polly in .NET), these are explicit choices 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 better on Azure than on any other
Kubernetes environment in the cloud. I would hope to convince you that
Azure Kubernetes Service (AKS) is the best-managed Kubernetes offer-
ing in the cloud space, but this is a different conversation for another time.

Important note

While this book is heavily skewed toward .NET, Dapr does provide the
same benefits to Python developers (just as an example) 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.

Here is a complete list of the tools and components of Dapr:

The Dapr command-line interface (CLI): A cross-platform command-line

tool to configure, manage, and monitor the Dapr environment. It is also
the tool used 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 that implements the API. If
you are curious, you can take a look at how it is developed in Go at Dapr's
repository: https://github.com/dapr/dapr.

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, this 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 (CA) to issue and manage

certificates used by Dapr to provide transparent mutual Transport Layer
Security (mTLS).

Dapr provides several building blocks that microservice application develop-

ers can adopt selectively, based on their needs. These are outlined here:

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 (KVP), relieving your stateful or stateless
services of the need to support different backends. Dapr provides many
state stores, which include Redis, Azure Cosmos DB, Azure SQL Server,
and PostgreSQL, which can be plugged in via configuration.

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

Publish and subscribe (pub/sub) messaging: The pub/sub 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 a Short
Message Service (SMS) message sent via Twilio (just one of the popular
services 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 request 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, 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, used with Visual Studio Code (VS 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 a .NET 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 https://docs.dapr.io/.

Important note: Updated to production-ready version

The Dapr runtime reached the v1.0 production-ready version in February

2021, as announced in the Dapr blog:
https://blog.dapr.io/posts/2021/02/17/announcing-dapr-v1.0/.

The samples and scripts in this book have been updated and tested with v1.1
of Dapr.

Docker
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 container mode.

You can find detailed instructions for running Docker at

https://docs.docker.com/install/.

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
https://github.com/dapr/cli.
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 environ-
ment variable so that the tools can be found from the command line:

powershell -Command "iwr -useb

https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"

The previous command installs a release candidate (RC) version of the Dapr
CLI. Please refer to https://docs.dapr.io/getting-started/install-dapr-cli/ for
more details.

We still need to initialize Dapr on the development machine, which we will do

later in this chapter.

.NET
To install .NET 5, please refer to https://dotnet.microsoft.com/download for the
link to the latest binaries.

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

PS C:Reposdapr-sampleschapter01> dotnet --info

.NET SDK (reflecting any global.json):

Version:   5.0.202

Commit:    db7cc87d51

Runtime Environment:

OS Name:     Windows

OS Version:  10.0.19042

OS Platform: Windows

RID:         win10-x64

Base Path:   C:Program Filesdotnetsdk5.0.202

Host (useful for support):

  Version: 5.0.5

  Commit:  2f740adc14

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

VS Code
VS Code is a great multiplatform source code editor by Microsoft. You can in-
stall it for free by following the instructions at
https://code.visualstudio.com/docs/setup/windows.

THE DAPR EXTENSION

Dapr has an extension for VS Code that helps with navigating the Dapr local
environment and eases the debugging configuration—I highly recommend it.
Please follow the instructions at https://docs.dapr.io/developing-
applications/ides/vscode/.

Windows Terminal
I really love the new Windows Terminal (https://aka.ms/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 in-
tends 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
them accordingly.

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

PS C:Reposdapr-sampleschapter01> 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:Usersdabedin.daprin.

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: https://aka.ms/dapr-

getting-started
To check your newly initialized Dapr environment, you can use docker ps, as
follows:

PS C:Reposdapr-sampleschapter01> docker ps --format "{{.ID}}: {{.Image}} -

{{.Ports}} - {{.Names}}"

2082b7f0eda4: daprio/dapr - 0.0.0.0:6050->50005/tcp - dapr_placement

6c68d869cea7: redis - 0.0.0.0:6379->6379/tcp - dapr_redis

e4c8eae6992d: openzipkin/zipkin - 9410/tcp, 0.0.0.0:9411->9411/tcp -

dapr_zipkin

The output shows the Docker container running on my machine.

Installing Dapr on Kubernetes

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

dapr init -k

Alternatively, you can install Dapr on Kubernetes with a Helm v3 chart. You
can find more details at https://docs.dapr.io/getting-started/install-dapr-
kubernetes/#install-with-helm-advanced.

Important note

If you intend to define a continuous integration/continuous deployment

(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:

PS C:Reposdapr-sampleschapter01> powershell -Command "iwr -useb

https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"

WARNING: Dapr is detected - c:daprdapr.exe

CLI version: 1.0.1

Runtime version: 1.0.0

Reinstalling Dapr...
Creating c:dapr directory

Downloading https://api.github.com/repos/dapr/cli/releases/assets/34341976
...

Extracting c:daprdapr_windows_amd64.zip...

CLI version: 1.1.0

Runtime version: 1.0.0

Clean up c:daprdapr_windows_amd64.zip...

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 https://docs.dapr.io/getting-started/ .

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, as follows:

PS C:Reposdapr-sampleschapter01> dapr uninstall

Removing Dapr from your machine...

Removing directory: C…

Removing container: dapr_placement

Dapr has been removed successfully

After we execute dapr init, checking the Dapr version, we can see it has now
moved forward from 1.0 to 1.1 for both the CLI and the runtime, as illustrated
in the following code snippet:

PS C:Reposdapr-sampleschapter01> dapr --version

CLI version: 1.1.0

Runtime version: 1.1.1

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

Building our first Dapr sample

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:Reposdapr-
samples folder, and I created a C:Reposdapr-sampleschapter01 folder for
this first sample. We'll take the following steps:
1. Let's start by creating a Web API .NET project, as follows:

PS C:Reposdapr-sampleschapter01> dotnet new webapi -o

dapr.microservice.webapi

2. Then, we add the reference to the Dapr SDK for ASP.NET. The
current version is 1.1.0. You can look for the package versions on
NuGet at https://www.nuget.org/packages/Dapr.Actors.AspNetCore
with the dotnet add package command, as illustrated in the following
code snippet:

PS C:Reposdapr-sampleschapter01> dotnet add package

Dapr.AspNetCore --version 1.1.0

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, I made a few changes to the code. In
Startup.cs, I changed the ConfigureServices method to
services.AddControllers().AddDapr();.

In Configure, I also added endpoints.MapSubscribeHandler();.

This is not necessary for our 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();.

Here is the modified code of the Startup.cs class:

using Microsoft.AspNetCore.Builder;

using Microsoft.AspNetCore.Hosting;

using Microsoft.Extensions.Configuration;

using Microsoft.Extensions.DependencyInjection;

using Microsoft.Extensions.Hosting;

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 services)

        {

            services.AddControllers().AddDapr();

        }

        // This method gets called by the runtime. Use //this method to
configure the HTTP request pipeline.

        public void Configure(IApplicationBuilder app,

          IWebHostEnvironment env)

        {

            if (env.IsDevelopment())

            {

                app.UseDeveloperExceptionPage();

            }

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>

            {

                endpoints.MapSubscribeHandler();

                endpoints.MapControllers();

            });

        }

    }

In the preceding code block, I instructed Dapr to leverage the model-

view-controller (MVC) pattern in ASP.NET. Keep in mind there is an
alternate approach for Dapr in ASP.NET, which does rely on routing
with MapGet(...) and MapPost(...). You can see an example at
https://github.com/dapr/dotnet-
sdk/tree/master/examples/AspNetCore/RoutingSample.
5. Finally, I added a controller named HelloWorldController, as
illustrated in the following code snippet:

using Dapr;

using Microsoft.AspNetCore.Mvc;

using System;

namespace dapr.microservice.webapi.Controllers

    [ApiController]

    public class HelloWorldController : ControllerBase

    {

        [HttpGet("hello")]

        public ActionResult<string> Get()

        {

            Console.WriteLine("Hello, World.");

            return "Hello, World";

        }

    }

In the preceding code snippet, you can see [HttpGet("hello")]: this

ASP.NET 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 default port as 5000 but I changed the Dapr HTTP
port to 5010. The following command line launches the Dapr
application:

PS C:Reposdapr-sampleschapter01dapr.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 avail-
able 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 is responding locally on port 5000 and Dapr is

responding on port 5010. In order to test Dapr, let's invoke a curl com-
mand, as follows. Using the browser is equally fine:

PS C:Reposdapr-sampleschapter01> 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 Web API framework. You
should also see it logged as Console.WriteLine sends its output to
the Dapr window, as follows:

== 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, like this:

PS C:WindowsSystem32> dapr dashboard

Dapr Dashboard running on http://localhost:8080

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

the following screen:

Figure 1.3 – Dapr dashboard application

The Dapr dashboard shown in Figure 1.3 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, along with the other components.

The Dapr dashboard also displays the configured components in the hosting
environment, as we can see here:

Figure 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 de-
ployment of Zipkin.

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

Summary
In this chapter, you have learned about the Dapr project, with its components,
building blocks, and the sidecar approach. All of these concepts will be ex-
plored 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 neces-
sary tools to make this experience easier.

You have also learned how to create a simple ASP.NET project and how to
configure and check Dapr, and we have had a glimpse of the Dapr dashboard
where we can 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.