VCP Dapr Integration

This document assumes that you are already familiar with Dapr and you want to use it in your VCP based applications.

Dapr (Distributed Application Runtime) provides APIs that simplify microservice connectivity. It is an open source project that is mainly backed by Microsoft. It is also a CNCF (Cloud Native Computing Foundation) project and trusted by the community.

VCP and Dapr have some intersecting features like service-to-service communication, distributed message bus and distributed locking. However their purposes are totally different. VCP's goal is to provide an end-to-end developer experience by offering an opinionated architecture and providing the necessary infrastructure libraries, reusable modules and tools to implement that architecture properly. Dapr's purpose, on the other hand, is to provide a runtime to decouple common microservice communication patterns from your application logic.

VCP and Dapr can perfectly work together in the same application. VCP offers some packages to provide better integration where Dapr features intersect with VCP. You can use other Dapr features with no VCP integration packages based on its own documentation.

VCP Dapr Integration Packages

VCP provides the following NuGet packages for the Dapr integration:

Verto.Vcp.Dapr: The main Dapr integration package. All other packages depend on this package.
Verto.Vcp.Http.Client.Dapr: Integration package for VCP's dynamic and static C# API Client Proxies systems with Dapr's service invocation building block.
Verto.Vcp.EventBus.Dapr: Implements VCP's distributed event bus with Dapr's publish & subscribe building block. With this package, you can send events, but can not receive.
Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus: Provides the endpoints to receive events from Dapr's publish & subscribe building block. Use this package to send and receive events.
Verto.Vcp.DistributedLocking.Dapr: Uses Dapr's distributed lock building block for distributed locking service of the VCP.

In the following sections, we will see how to use these packages to use Dapr in your VCP based solutions.

Basics

Installation

This section explains how to add Verto.Vcp.Dapr, the core Dapr integration package to your project. If you are using one of the other Dapr integration packages, you can skip this section since this package will be indirectly added.

Use the VCP CLI to add the Verto.Vcp.Dapr NuGet package to your project:

Install the VCP CLI if you haven't installed it before.
Open a command line (terminal) in the directory of the .csproj file you want to add the Verto.Vcp.Dapr package.
Run the vcp add-package Verto.Vcp.Dapr command.

If you want to do it manually, install the Verto.Vcp.Dapr NuGet package to your project and add [DependsOn(typeof(VcpDaprModule))] to the VCP module class inside your project.

VcpDaprOptions

VcpDaprOptions is the main options class that you can configure the global Dapr settings with. All settings are optional and you mostly don't need to configure them. If you need, you can configure it in the ConfigureServices method of your module class:

Configure<VcpDaprOptions>(options =>
{
    // ...
});

Available properties of the VcpDaprOptions class:

HttpEndpoint (optional): HTTP endpoint that is used while creating a DaprClient object. If you don't specify, the default value is used.
GrpcEndpoint (optional): The gRPC endpoint that is used while creating a DaprClient object. If you don't specify, the default value is used.
DaprApiToken (optional): The Dapr API token that is used while sending requests from the application to Dapr. It is filled from the DAPR_API_TOKEN environment variable by default (which is set by Dapr once it is configured). See the Security section in this document for details.
AppApiToken (optional): The App API token that is used to validate requests coming from Dapr. It is filled from the APP_API_TOKEN environment variable by default (which is set by Dapr once it is configured). See the Security section in this document for details.

Alternatively, you can configure the options in the Dapr section of your appsettings.json file. Example:

"Dapr": {
  "HttpEndpoint": "http://localhost:3500/"
}

IVcpDaprClientFactory

IVcpDaprClientFactory can be used to create DaprClient or HttpClient objects to perform operations on Dapr. It uses VcpDaprOptions, so you can configure the settings in a central place.

Example usages:

public class MyService : ITransientDependency
{
    private readonly IVcpDaprClientFactory _daprClientFactory;

    public MyService(IVcpDaprClientFactory daprClientFactory)
    {
        _daprClientFactory = daprClientFactory;
    }

    public async Task DoItAsync()
    {
        // Create a DaprClient object with default options
        DaprClient daprClient = await _daprClientFactory.CreateAsync();
        
        /* Create a DaprClient object with configuring
         * the DaprClientBuilder object */
        DaprClient daprClient2 = await _daprClientFactory
            .CreateAsync(builder =>
            {
                builder.UseDaprApiToken("...");
            });
        
        // Create an HttpClient object
        HttpClient httpClient = await _daprClientFactory.CreateHttpClientAsync("target-app-id");
    }
}

CreateHttpClientAsync method also gets optional daprEndpoint and daprApiToken parameters.

You can use Dapr API to create client objects in your application. Using IVcpDaprClientFactory is recommended, but not required.

C# API Client Proxies Integration

VCP can dynamically or statically generate proxy classes to invoke your HTTP APIs from a Dotnet client application. It makes perfect sense to consume HTTP APIs in a distributed system. The Verto.Vcp.Http.Client.Dapr package configures the client-side proxies system, so it uses Dapr's service invocation building block for the communication between your applications.

Installation

Use the VCP CLI to add the Verto.Vcp.Http.Client.Dapr NuGet package to your project (to the client side):

Install the VCP CLI if you haven't installed before.
Open a command line (terminal) in the directory of the .csproj file you want to add the Verto.Vcp.Http.Client.Dapr package to.
Run the vcp add-package Verto.Vcp.Http.Client.Dapr command.

If you want to do it manually, install the Verto.Vcp.Http.Client.Dapr NuGet package to your project and add [DependsOn(typeof(VcpHttpClientDaprModule))] to the VCP module class inside your project.

Configuration

Once you install the Verto.Vcp.Http.Client.Dapr NuGet package, all you need to do is to configure VCP's remote services option either in appsettings.json or using the VcpRemoteServiceOptions options class.

Example:

{
  "RemoteServices": {
    "Default": {
      "BaseUrl": "http://dapr-httpapi/"
    }
  }
}

dapr-httpapi in this example is the application id of the server application in your Dapr configuration.

The remote service name (Default in this example) should match the remote service name specified in the AddHttpClientProxies call for dynamic client proxies or the AddStaticHttpClientProxies call for static client proxies. Using Default is fine if your client communicates to a single server. However, if your client uses multiple servers, you typically have multiple keys in the RemoteServices configuration. Once you configure the remote service endpoints as Dapr application ids, it will automatically work and make the HTTP calls through Dapr when you use VCP's client proxy system.

See the dynamic and static client proxy documents for details about the VCP's client proxy system.

Distributed Event Bus Integration

VCP's distributed event bus system provides a convenient abstraction to allow applications to communicate asynchronously via events. VCP has integration packages with various distributed messaging systems, like RabbitMQ, Kafka, and Azure. Dapr also has a publish & subscribe building block for the same purpose: distributed messaging / events.

VCP's Verto.Vcp.EventBus.Dapr and Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus packages make it possible to use the Dapr infrastructure for VCP's distributed event bus.

The Verto.Vcp.EventBus.Dapr package can be used by any type of application (e.g., a Console or ASP.NET Core application) to publish events through Dapr. To be able to receive messages (by subscribing to events), you need to have the Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus package installed, and your application should be an ASP.NET Core application.

Installation

If your application is an ASP.NET Core application and you want to send and receive events, you need to install the Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus package as described below:

Install the VCP CLI if you haven't installed it before.
Open a command line (terminal) in the directory of the .csproj file you want to add the Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus package to.
Run the vcp add-package Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus command.

If you want to do it manually, install the Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus NuGet package to your project and add [DependsOn(typeof(VcpAspNetCoreMvcDaprEventBusModule))] to the VCP module class inside your project.

If you install the Verto.Vcp.AspNetCore.Mvc.Dapr.EventBus package, you don't need to install the Verto.Vcp.EventBus.Dapr package, because the first one already has a reference to the latter one.

If your application is not an ASP.NET Core application, you can't receive events from Dapr, at least with VCP's integration packages (see Dapr's document if you want to receive events in a different type of application). However, you can still publish messages using the Verto.Vcp.EventBus.Dapr package. In this case, follow the steps below to install that package to your project:

Install the VCP CLI if you haven't installed it before.
Open a command line (terminal) in the directory of the .csproj file you want to add the Verto.Vcp.EventBus.Dapr package to.
Run the vcp add-package Verto.Vcp.EventBus.Dapr command.

If you want to do it manually, install the Verto.Vcp.EventBus.Dapr NuGet package to your project and add [DependsOn(typeof(VcpEventBusDaprModule))] to the VCP module class inside your project.

Configuration

You can configure the VcpDaprEventBusOptions options class for Dapr configuration:

Configure<VcpDaprEventBusOptions>(options =>
{
    options.PubSubName = "pubsub";
});

Available properties of the VcpDaprEventBusOptions class:

PubSubName (optional): The pubsubName parameter while publishing messages through the DaprClient.PublishEventAsync method. Default value: pubsub.

The VCP Subscription Endpoints

VCP provides the following endpoints to receive events from Dapr:

dapr/subscribe: Dapr uses this endpoint to get a list of subscriptions from the application. VCP automatically returns all the subscriptions for your distributed event handler classes and custom controller actions with the Topic attribute.
api/vcp/dapr/event: The unified endpoint to receive all the events from Dapr. VCP dispatches the events to your event handlers based on the topic name.

Since VCP will call MapSubscribeHandler internally, you should not manually call it anymore. You can use the app.UseCloudEvents() middleware in your ASP.NET Core pipeline if you want to support the CloudEvents standard.

Usage

The VCP Way

You can follow VCP's distributed event bus documentation to learn how to publish and subscribe to events in the VCP way. No change required in your application code to use Dapr pub-sub. VCP will automatically subscribe to Dapr for your event handler classes (that implement the IDistributedEventHandler interface).

VCP provides api/vcp/dapr/event

Example: Publish an event using the IDistributedEventBus service

public class MyService : ITransientDependency
{
    private readonly IDistributedEventBus _distributedEventBus;

    public MyService(IDistributedEventBus distributedEventBus)
    {
        _distributedEventBus = distributedEventBus;
    }

    public async Task DoItAsync()
    {
        await _distributedEventBus.PublishAsync(new StockCountChangedEto
        {
            ProductCode = "AT837234",
            NewStockCount = 42 
        });
    }
}

Example: Subscribe to an event by implementing the IDistributedEventHandler interface

public class MyHandler : 
    IDistributedEventHandler<StockCountChangedEto>,
    ITransientDependency
{
    public async Task HandleEventAsync(StockCountChangedEto eventData)
    {
        var productCode = eventData.ProductCode;
        // ...
    }
}

See VCP's distributed event bus documentation to learn the details.

Using the Dapr API

In addition to VCP's standard distributed event bus system, you can also use Dapr's API to publish events.

If you directly use the Dapr API to publish events, you may not benefit from VCP's standard distributed event bus features, like the outbox/inbox pattern implementation.

Example: Publish an event using DaprClient

public class MyService : ITransientDependency
{
    private readonly DaprClient _daprClient;

    public MyService(DaprClient daprClient)
    {
        _daprClient = daprClient;
    }

    public async Task DoItAsync()
    {
        await _daprClient.PublishEventAsync(
            "pubsub", // pubsub name
            "StockChanged", // topic name 
            new StockCountChangedEto // event data
            {
                ProductCode = "AT837234",
                NewStockCount = 42
            }
        );
    }
}

Example: Subscribe to an event by creating an ASP.NET Core controller

public class MyController : VcpController
{
    [HttpPost("/stock-changed")]
    [Topic("pubsub", "StockChanged")]
    public async Task<IActionResult> TestRouteAsync([FromBody] StockCountChangedEto model)
    {
        HttpContext.ValidateDaprAppApiToken();
        
        // Do something with the event
        return Ok();
    }
}

HttpContext.ValidateDaprAppApiToken() extension method is provided by VCP to check if the request is coming from Dapr. This is optional. You should configure Dapr to send the App API token to your application if you want to enable the validation. If not configured, ValidateDaprAppApiToken() does nothing. See Dapr's App API Token document for more information. Also see the VcpDaprOptions and Security sections in this document.

See the Dapr documentation to learn the details of sending & receiving events with the Dapr API.

Distributed Lock

Dapr's distributed lock feature is currently in the Alpha stage and may not be stable yet. It is not suggested to replace VCP's distributed lock with Dapr in that point.

VCP provides a Distributed Locking abstraction to control access to a shared resource by multiple applications. Dapr also has a distributed lock building block. The Verto.Vcp.DistributedLocking.Dapr package makes VCP use Dapr's distributed locking system.

Installation

Use the VCP CLI to add the Verto.Vcp.DistributedLocking.Dapr NuGet package to your project (to the client side):

Install the VCP CLI if you haven't installed it before.
Open a command line (terminal) in the directory of the .csproj file you want to add the Verto.Vcp.DistributedLocking.Dapr package to.
Run the vcp add-package Verto.Vcp.DistributedLocking.Dapr command.

If you want to do it manually, install the Verto.Vcp.DistributedLocking.Dapr NuGet package to your project and add [DependsOn(typeof(VcpDistributedLockingDaprModule))] to the VCP module class inside your project.

Configuration

You can use the VcpDistributedLockDaprOptions options class in the ConfigureServices method of your module to configure the Dapr distributed lock:

Configure<VcpDistributedLockDaprOptions>(options =>
{
    options.StoreName = "mystore";
});

The following options are available:

StoreName (required): The store name used by Dapr. Lock key names are scoped in the same store. That means different applications can acquire the same lock name in different stores. Use the same store name for the same resources you want to control the access of.
Owner (optional): The owner value used by the DaprClient.Lock method. If you don't specify, VCP uses a random value, which is fine in general.
DefaultExpirationTimeout (optional): Default value of the time after which the lock gets expired. Default value: 2 minutes.

Usage

You can inject and use the IVcpDistributedLock service, just like explained in the Distributed Locking document.

Example:

public class MyService : ITransientDependency
{
    private readonly IVcpDistributedLock _distributedLock;
    
    public MyService(IVcpDistributedLock distributedLock)
    {
        _distributedLock = distributedLock;
    }
    
    public async Task MyMethodAsync()
    {
        await using (var handle = 
                     await _distributedLock.TryAcquireAsync("MyLockName"))
        {
            if (handle != null)
            {
                // your code that access the shared resource
            }
        }   
    }
}

There are two points we should mention about the TryAcquireAsync method, as different from VCP's standard usage:

The timeout parameter is currently not used (even if you specify it), because Dapr doesn't support waiting to obtain the lock.
Dapr uses the expiration timeout system (that means the lock is automatically released after that timeout even if you don't release the lock by disposing the handler). However, VCP's TryAcquireAsync method has no such a parameter. Currently, you can set VcpDistributedLockDaprOptions.DefaultExpirationTimeout as a global value in your application.

As mentioned first, Dapr's distributed lock feature is currently in the Alpha stage and its API is a candidate to change. You should use it as is if you want, but be ready for the changes in the future. For now, we are recommending to use the DistributedLock library as explained in VCP's Distributed Locking document.

Security

If you are using Dapr, most or all the incoming and outgoing requests in your application pass through Dapr. Dapr uses two kinds of API tokens to secure the communication between your application and Dapr.

Dapr API Token

This token is automatically set by default and generally you don't care about it.

The Enable API token authentication in Dapr document describes what the Dapr API token is and how it is configured. Please read that document if you want to enable it for your application.

If you enable the Dapr API token, you should send that token in every request to Dapr from your application. VcpDaprOptions defines a DaprApiToken property as a central point to configure the Dapr API token in your application.

The default value of the DaprApiToken property is set from the DAPR_API_TOKEN environment variable and that environment variable is set by Dapr when it runs. So, most of the time, you don't need to configure VcpDaprOptions.DaprApiToken in your application. However, if you need to configure (or override) it, you can do in the ConfigureServices method of your module class as shown in the following code block:

Configure<VcpDaprOptions>(options =>
{
    options.DaprApiToken = "...";
});

Or you can set it in your appsettings.json file:

"Dapr": {
  "DaprApiToken": "..."
}

Once you set it, it is used when you use IVcpDaprClientFactory. If you need that value in your application, you can inject IDaprApiTokenProvider and use its GetDaprApiToken() method.

App API Token

Enabling App API token validation is strongly recommended. Otherwise, for example, any client can directly call your event subscription endpoint, and your application acts like an event has occurred (if there is no other security policy in your event subscription endpoint).

The Authenticate requests from Dapr using token authentication document describes what the App API token is and how it is configured. Please read that document if you want to enable it for your application.

If you enable the App API token, you can validate it to ensure that the request is coming from Dapr. VCP provides useful shortcuts to validate it.

Example: Validate the App API token in an event handling HTTP API

public class MyController : VcpController
{
    [HttpPost("/stock-changed")]
    [Topic("pubsub", "StockChanged")]
    public async Task<IActionResult> TestRouteAsync([FromBody] StockCountChangedEto model)
    {
        // Validate the App API token!
        HttpContext.ValidateDaprAppApiToken();
        
        // Do something with the event
        return Ok();
    }
}

HttpContext.ValidateDaprAppApiToken() is an extension method provided by the VCP. It throws an VcpAuthorizationException if the token was missing or wrong in the HTTP header (the header name is dapr-api-token). You can also inject IDaprAppApiTokenValidator and use its methods to validate the token in any service (not only in a controller class).

You can configure VcpDaprOptions.AppApiToken if you want to set (or override) the App API token value. The default value is set by the APP_API_TOKEN environment variable. You can change it in the ConfigureServices method of your module class as shown in the following code block:

Configure<VcpDaprOptions>(options =>
{
    options.AppApiToken = "...";
});

Or you can set it in your appsettings.json file:

"Dapr": {
  "AppApiToken": "..."
}

If you need that value in your application, you can inject IDaprApiTokenProvider and use its GetAppApiToken() method.

VCP Dapr Integration

VCP Dapr Integration Packages

Basics

Installation

VcpDaprOptions

IVcpDaprClientFactory

C# API Client Proxies Integration

Installation

Configuration

Distributed Event Bus Integration

Installation

Configuration

The VCP Subscription Endpoints

Usage

The VCP Way

Using the Dapr API

Distributed Lock

Installation

Configuration

Usage

Security

Dapr API Token

App API Token

See Also

In this document