From 3a481b2148456a2fa9adc24cd34ea9b0e4ba90bc Mon Sep 17 00:00:00 2001 From: Whit Waldo Date: Tue, 16 Jun 2026 02:18:27 -0500 Subject: [PATCH] Updating documentation to reflect new `Dapr.Metadata` package usage Signed-off-by: Whit Waldo --- .../content/en/dotnet-sdk-docs/_index.md | 1 + .../dotnet-sdk-docs/dotnet-metadata/_index.md | 13 + .../dotnet-metadata/dotnet-metadata-howto.md | 257 ++++++++++++++++++ 3 files changed, 271 insertions(+) create mode 100644 sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/_index.md create mode 100644 sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/dotnet-metadata-howto.md diff --git a/sdkdocs/dotnet/content/en/dotnet-sdk-docs/_index.md b/sdkdocs/dotnet/content/en/dotnet-sdk-docs/_index.md index d17e54afad4..ae5d38401ba 100644 --- a/sdkdocs/dotnet/content/en/dotnet-sdk-docs/_index.md +++ b/sdkdocs/dotnet/content/en/dotnet-sdk-docs/_index.md @@ -64,6 +64,7 @@ Put the Dapr .NET SDK to the test. Walk through the .NET quickstarts and tutoria | [Dapr.PluggableComponents.AspNetCore](https://www.nuget.org/packages/Dapr.PluggableComponents.AspNetCore) | | Implement pluggable components with Dapr using .NET with rich ASP.NET Core support. | | [Dapr.PluggableComponents.Protos](https://www.nuget.org/packages/Dapr.PluggableComponents.Protos) | | **Note:** Developers needn't install this package directly in their applications. | | [Dapr.Messaging](https://www.nuget.org/packages/Dapr.Messaging) | [Documentation]({{% ref dotnet-messaging %}}) | Build distributed applications using the Dapr Messaging SDK that utilize messaging components like streaming pub/sub subscriptions. | +| [Dapr.Metadata](https://www.nuget.org/packages/Dapr.Metadata) | [Documentation]({{% ref dotnet-metadata %}}) | Retrieve typed Dapr runtime metadata in .NET through the options pattern. | | [Dapr.Testcontainers](https://www.nuget.org/packages/Dapr.Testcontainers) | [Documentation]({{% ref dotnet-guidance-testcontainers.md %}}) | Run Dapr integration tests using Testcontainers-based harnesses. | | [Dapr.Workflow](https://www.nuget.org/packages/Dapr.Workflow) | [Documentation]({{% ref dotnet-workflow %}}) | Create and manage workflows that work with other Dapr APIs. | | [Dapr.Workflow.Versioning](https://www.nuget.org/packages/Dapr.Workflow.Versioning) | [Documentation]({{% ref dotnet-workflow-versioning.md %}}) | Add workflow versioning strategies for evolving long-running workflows. | diff --git a/sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/_index.md b/sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/_index.md new file mode 100644 index 00000000000..a682ca1b6ae --- /dev/null +++ b/sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/_index.md @@ -0,0 +1,13 @@ +--- +type: docs +title: "Dapr Metadata .NET SDK" +linkTitle: "Metadata" +weight: 54000 +description: 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`, +`IOptionsSnapshot`, or `IOptionsMonitor`. + +To get started, walk through the [Dapr Metadata]({{% ref dotnet-metadata-howto.md %}}) how-to guide. diff --git a/sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/dotnet-metadata-howto.md b/sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/dotnet-metadata-howto.md new file mode 100644 index 00000000000..c76fd7abaab --- /dev/null +++ b/sdkdocs/dotnet/content/en/dotnet-sdk-docs/dotnet-metadata/dotnet-metadata-howto.md @@ -0,0 +1,257 @@ +--- +type: docs +title: "How to: Retrieve Dapr runtime metadata with the .NET SDK" +linkTitle: "How to: Retrieve runtime metadata" +weight: 54010 +description: 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`, `IOptionsSnapshot`, or `IOptionsMonitor` +- 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 +- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) +- [Initialized Dapr environment](https://docs.dapr.io/getting-started/install-dapr-selfhost) +- [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0), + [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0), or + [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) installed +- [Dapr.Metadata](https://www.nuget.org/packages/Dapr.Metadata) NuGet package installed to your project + +## Install the package + +Install the Dapr Metadata package: + +```sh +dotnet add package Dapr.Metadata +``` + +## Register Dapr Metadata with dependency injection + +Register the metadata service during application startup with `AddDaprMetadata()`: + +```csharp +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` + +Use `IOptions` when a singleton-style view of the metadata is sufficient: + +```csharp +using Dapr.Metadata.Abstractions; +using Microsoft.Extensions.Options; + +public sealed class MetadataReporter(IOptions metadata) +{ + public void PrintRuntimeDetails() + { + var value = metadata.Value; + + Console.WriteLine($"App ID: {value.AppId}"); + Console.WriteLine($"Runtime version: {value.RuntimeVersion}"); + } +} +``` + +### Use `IOptionsSnapshot` + +Use `IOptionsSnapshot` in scoped services, such as request handlers or MVC controllers: + +```csharp +using Dapr.Metadata.Abstractions; +using Microsoft.AspNetCore.Mvc; +using Microsoft.Extensions.Options; + +[ApiController] +[Route("metadata")] +public sealed class MetadataController(IOptionsSnapshot 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` + +Use `IOptionsMonitor` 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: + +```csharp +using Dapr.Metadata.Abstractions; +using Microsoft.Extensions.Options; + +public sealed class ComponentHealthReporter(IOptionsMonitor metadata) +{ + public IReadOnlyCollection GetLoadedComponentNames() + { + return metadata.CurrentValue.Components + .Select(component => component.Name) + .OfType() + .Where(name => !string.IsNullOrWhiteSpace(name)) + .ToArray(); + } +} +``` + +## Read metadata values + +The `DaprMetadata` type represents the response from the Dapr runtime metadata endpoint. + +| Property | Description | +| -------- | ----------- | +| `AppId` | The application ID registered with Dapr. | +| `RuntimeVersion` | The Dapr runtime version. | +| `EnabledFeatures` | Named features enabled by Dapr configuration. | +| `Actors` | Registered actor types and counts. | +| `CustomAttributes` | Custom metadata attributes exposed by the runtime. | +| `Components` | Loaded component names, types, versions, and capabilities. | +| `HttpEndpoints` | Registered HTTP endpoint metadata. | +| `Subscriptions` | Pub/sub subscription metadata, including rules and dead letter topics. | +| `AppConnectionProperties` | App port, protocol, channel address, max concurrency, and health probe settings. | +| `SchedulerMetadata` | Connected scheduler host addresses. | +| `Workflows` | Workflow runtime metadata, including connected worker count. | + +For example, you can inspect subscriptions and app connection properties: + +```csharp +using Dapr.Metadata.Abstractions; +using Microsoft.Extensions.Options; + +public sealed class RuntimeMetadataService(IOptions 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: + +| Key | Description | +| --- | ----------- | +| `DAPR_HTTP_ENDPOINT` | The HTTP endpoint for the Dapr sidecar. | +| `DAPR_HTTP_PORT` | The HTTP port for the local Dapr sidecar when `DAPR_HTTP_ENDPOINT` is not set. | +| `DAPR_API_TOKEN` | The API token for authenticating with the Dapr sidecar. | + +These values can come from environment variables or any registered `IConfiguration` source. + +### Configuration via `ConfigurationBuilder` + +```csharp +using Dapr.Metadata.Extensions; + +var builder = WebApplication.CreateBuilder(args); + +builder.Configuration.AddInMemoryCollection(new Dictionary +{ + ["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. + +| Key | Value | +| --- | ----- | +| `DAPR_HTTP_ENDPOINT` | `http://localhost:3500` | +| `DAPR_API_TOKEN` | `abc123` | + +```csharp +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: + +| Key | Value | +| --- | ----- | +| `myapp_DAPR_HTTP_ENDPOINT` | `http://localhost:3500` | +| `myapp_DAPR_API_TOKEN` | `abc123` | + +```csharp +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: + +```sh +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.