This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Dapr Metadata .NET SDK

Get up and running with the Dapr Metadata .NET SDK

With the Dapr Metadata package, you can retrieve typed metadata from the Dapr runtime in a .NET application. The package integrates with the .NET options pattern so metadata can be injected through IOptions<DaprMetadata>, IOptionsSnapshot<DaprMetadata>, or IOptionsMonitor<DaprMetadata>.

To get started, walk through the Dapr Metadata how-to guide.

1 - How to: Retrieve Dapr runtime metadata with the .NET SDK

Learn how to retrieve Dapr runtime metadata using the Dapr Metadata .NET SDK

Let’s walk through how to retrieve Dapr runtime metadata using the Dapr.Metadata package. The package registers a hosted service that retrieves metadata from the Dapr sidecar during application startup, then exposes the typed DaprMetadata value through the .NET options pattern. In this guide, you will:

  • Install and register the Dapr Metadata .NET SDK
  • Inject metadata through IOptions<DaprMetadata>, IOptionsSnapshot<DaprMetadata>, or IOptionsMonitor<DaprMetadata>
  • Read runtime metadata, component metadata, subscriptions, actors, workflow, scheduler, and app connection details
  • Configure the Dapr HTTP endpoint and API token used to retrieve metadata

Prerequisites

Install the package

Install the Dapr Metadata package:

dotnet add package Dapr.Metadata

Register Dapr Metadata with dependency injection

Register the metadata service during application startup with AddDaprMetadata():

using Dapr.Metadata.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDaprMetadata();

var app = builder.Build();

The registration adds the metadata options type and an internal hosted service that retrieves metadata from the Dapr runtime when the application starts.

Inject metadata with the options pattern

The Dapr.Metadata package exposes runtime metadata as DaprMetadata through the .NET options pattern. Choose the options interface that matches the lifetime of the service consuming the metadata.

Use IOptions<DaprMetadata>

Use IOptions<DaprMetadata> when a singleton-style view of the metadata is sufficient:

using Dapr.Metadata.Abstractions;
using Microsoft.Extensions.Options;

public sealed class MetadataReporter(IOptions<DaprMetadata> metadata)
{
    public void PrintRuntimeDetails()
    {
        var value = metadata.Value;

        Console.WriteLine($"App ID: {value.AppId}");
        Console.WriteLine($"Runtime version: {value.RuntimeVersion}");
    }
}

Use IOptionsSnapshot<DaprMetadata>

Use IOptionsSnapshot<DaprMetadata> in scoped services, such as request handlers or MVC controllers:

using Dapr.Metadata.Abstractions;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;

[ApiController]
[Route("metadata")]
public sealed class MetadataController(IOptionsSnapshot<DaprMetadata> metadata) : ControllerBase
{
    [HttpGet("components")]
    public IActionResult GetComponents()
    {
        var components = metadata.Value.Components.Select(component => new
        {
            component.Name,
            component.Type,
            component.Version,
            component.Capabilities
        });

        return Ok(components);
    }
}

Use IOptionsMonitor<DaprMetadata>

Use IOptionsMonitor<DaprMetadata> when your application uses configuration hot reload, or when you want to ensure the consumer reads the latest metadata values in case they have changed since application startup. This is the preferred approach when freshness matters, with the tradeoff that retrieving the current value can introduce a brief delay while the metadata value is loaded:

using Dapr.Metadata.Abstractions;
using Microsoft.Extensions.Options;

public sealed class ComponentHealthReporter(IOptionsMonitor<DaprMetadata> metadata)
{
    public IReadOnlyCollection<string> GetLoadedComponentNames()
    {
        return metadata.CurrentValue.Components
            .Select(component => component.Name)
            .OfType<string>()
            .Where(name => !string.IsNullOrWhiteSpace(name))
            .ToArray();
    }
}

Read metadata values

The DaprMetadata type represents the response from the Dapr runtime metadata endpoint.

PropertyDescription
AppIdThe application ID registered with Dapr.
RuntimeVersionThe Dapr runtime version.
EnabledFeaturesNamed features enabled by Dapr configuration.
ActorsRegistered actor types and counts.
CustomAttributesCustom metadata attributes exposed by the runtime.
ComponentsLoaded component names, types, versions, and capabilities.
HttpEndpointsRegistered HTTP endpoint metadata.
SubscriptionsPub/sub subscription metadata, including rules and dead letter topics.
AppConnectionPropertiesApp port, protocol, channel address, max concurrency, and health probe settings.
SchedulerMetadataConnected scheduler host addresses.
WorkflowsWorkflow runtime metadata, including connected worker count.

For example, you can inspect subscriptions and app connection properties:

using Dapr.Metadata.Abstractions;
using Microsoft.Extensions.Options;

public sealed class RuntimeMetadataService(IOptions<DaprMetadata> metadata)
{
    public void PrintSubscriptions()
    {
        foreach (var subscription in metadata.Value.Subscriptions)
        {
            Console.WriteLine($"{subscription.PubSubName}: {subscription.Topic} ({subscription.Type})");

            foreach (var rule in subscription.Rules)
            {
                Console.WriteLine($"  {rule.Match} -> {rule.Path}");
            }
        }
    }

    public void PrintAppConnection()
    {
        var appConnection = metadata.Value.AppConnectionProperties;

        Console.WriteLine($"Protocol: {appConnection.Protocol}");
        Console.WriteLine($"Address: {appConnection.ChannelAddress}:{appConnection.Port}");
        Console.WriteLine($"Max concurrency: {appConnection.MaxConcurrency}");
        Console.WriteLine($"Health path: {appConnection.Health?.HealthCheckPath}");
    }
}

Configure the Dapr endpoint

The metadata service retrieves metadata from the Dapr HTTP endpoint. By default, it uses the same Dapr configuration values used by other .NET SDK clients:

KeyDescription
DAPR_HTTP_ENDPOINTThe HTTP endpoint for the Dapr sidecar.
DAPR_HTTP_PORTThe HTTP port for the local Dapr sidecar when DAPR_HTTP_ENDPOINT is not set.
DAPR_API_TOKENThe API token for authenticating with the Dapr sidecar.

These values can come from environment variables or any registered IConfiguration source.

Configuration via ConfigurationBuilder

using Dapr.Metadata.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddInMemoryCollection(new Dictionary<string, string?>
{
    ["DAPR_HTTP_ENDPOINT"] = "http://localhost:3500",
    ["DAPR_API_TOKEN"] = "abc123"
});

builder.Services.AddDaprMetadata();

Configuration via environment variables

Application settings can be accessed from environment variables available to your application.

KeyValue
DAPR_HTTP_ENDPOINThttp://localhost:3500
DAPR_API_TOKENabc123
using Dapr.Metadata.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddEnvironmentVariables();
builder.Services.AddDaprMetadata();

Configuration via prefixed environment variables

In shared-host scenarios, you can source prefixed environment variables into IConfiguration and register metadata normally:

KeyValue
myapp_DAPR_HTTP_ENDPOINThttp://localhost:3500
myapp_DAPR_API_TOKENabc123
using Dapr.Metadata.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddEnvironmentVariables(prefix: "myapp_");
builder.Services.AddDaprMetadata();

Run locally

Start the application with a Dapr sidecar. The sidecar HTTP port must match your configured endpoint or port:

dapr run --app-id metadata-example --dapr-http-port 3500 -- dotnet run

Dapr listens for HTTP requests at http://localhost:3500.

When the application starts, the metadata service retrieves metadata from the sidecar and makes the typed value available through the registered options interfaces.