Binary Store

• 1: Binary Store overview
• 2: How-To: Use the Binary Store API

1 - Binary Store overview

The Dapr Binary Store building block provides a portable API for storing, retrieving, and deleting binary files through a configured component. Applications address a file by its name and the name of the binary store component. The runtime streams file content between the application and the component instead of wrapping it in a JSON value. This avoids an additional full-file buffer in the runtime, although the selected component may buffer content or enforce its own size limits.

The Binary Store is intended for files and other opaque binary content. For small application values that are naturally represented as key/value data, use State management instead.

Features

The Binary Store building block provides:

• Component portability: use a component by its configured name and change the storage backend without changing the API calls in your application.
• Streaming: upload and download file content as a stream rather than wrapping it in a JSON payload.
• Create or replace behavior: create a file only when it does not exist, or explicitly replace an existing file.
• File operations: retrieve and delete a named file using the same component and file name.

File names can contain nested relative paths, such as reports/2026/summary.pdf. Names must not start or end with /, contain empty path segments, . or .. path segments, or include \, *, ?, [, ], or #. The runtime rejects invalid names.

Components

Binary stores are configured as Dapr components. The component’s metadata.name is the store name used in Binary Store API requests, and spec.type selects the implementation. Component-specific connection details and capabilities are configured in the component’s metadata. See the supported Binary Store components for provider configuration details, or browse the Binary Store component implementations.

The Dapr runtime includes an in-memory binary store component for local development and testing. It is not durable: files are held in the sidecar’s memory, are not shared with other sidecar instances, and are lost when the process stops. Its default maximum file size is 4 MiB and its default total store size is 512 MiB. These limits can be configured on that component; limits and durability for other stores depend on the component.

Binary Store API

The HTTP API exposes POST, PUT, GET, and DELETE operations at /v1.0-alpha1/binarystore/{storeName}/{fileName}. The request and response bodies contain raw file bytes. A POST creates a file only if it does not already exist; a PUT creates the file or replaces an existing one. A successful upload or delete returns 204 No Content, while a successful download streams the file with the application/octet-stream content type.

For endpoint parameters, response codes, and gRPC method details, see the Binary Store API reference.

Next steps

• Follow the how-to guide to configure a store and use the HTTP API.
• Review the Binary Store API reference.

2 - How-To: Use the Binary Store API

This guide shows how to configure a binary store component and use the Dapr HTTP API or .NET SDK to upload, retrieve, and delete a file. The examples use the runtime’s in-memory component for local development.

Prerequisites

• Dapr CLI installed
• An initialized Dapr environment
• A Dapr runtime that supports the Binary Store API (Dapr 1.19 or later)
• For .NET examples, the Dapr.BinaryStore NuGet package

Configure a binary store

A binary store component represents the storage backend used by Dapr. Save the following in-memory component definition as components/binary-store.yaml:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: mystore
spec:
  type: binarystore.in-memory
  version: v1
  metadata:
    - name: maxSize
      value: "16Mi"
    - name: maxTotalSize
      value: "64Mi"

The maxSize and maxTotalSize values accept either a byte count or a unit size string, such as 16Mi or 64Mi. Because component metadata values are strings, quote numeric byte counts in YAML (for example, "16777216").

The component name mystore is used in the API URL. This in-memory implementation is useful for trying the API, but it does not persist files across sidecar restarts or share files between sidecar instances. For production, configure an appropriate persistent binary store component and its required metadata.

Start a Dapr sidecar with the component directory available to it. For example, use the following command to expose the HTTP API on port 3500:

dapr run --app-id binary-store-example --resources-path ./components --dapr-http-port 3500

Each .NET tab shows the client registration and resolution needed for that example. In an application, register the singleton once at startup and inject it into your service.

Upload a file

Send the file as raw binary data. Use POST to create a file without replacing an existing one. The .NET client also creates without replacing by default:

• Bash
• .NET

curl -X POST \
  http://localhost:3500/v1.0-alpha1/binarystore/mystore/report.pdf \
  --data-binary @./report.pdf

using Dapr.BinaryStore;
using Dapr.BinaryStore.Extensions;
using System.IO;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprBinaryStoreClient();
var app = builder.Build();

var binaryStore = app.Services.GetRequiredService<DaprBinaryStoreClient>();
await using var content = File.OpenRead("./report.pdf");
await binaryStore.SetBinaryFileAsync("mystore", "report.pdf", content);

The HTTP request returns 204 No Content when successful. If report.pdf already exists, HTTP POST fails with 409 Conflict; the .NET client reports runtime failures as a DaprException.

To replace a file that already exists, use PUT. In .NET, set overwrite to true:

• Bash
• .NET

curl -X PUT \
  http://localhost:3500/v1.0-alpha1/binarystore/mystore/report.pdf \
  --data-binary @./updated-report.pdf

using Dapr.BinaryStore;
using Dapr.BinaryStore.Extensions;
using System.IO;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprBinaryStoreClient();
var app = builder.Build();

var binaryStore = app.Services.GetRequiredService<DaprBinaryStoreClient>();
await using var content = File.OpenRead("./updated-report.pdf");
await binaryStore.SetBinaryFileAsync("mystore", "report.pdf", content, overwrite: true);

An HTTP overwrite that succeeds returns 204 No Content.

Neither API requires file data to be encoded as JSON. The runtime streams the content to the component, which may enforce a maximum file size or total store capacity; configure and review the limits of the component you use. HTTP uploads are exempt from the sidecar --max-body-size limit, so a file can be larger than that limit.

Retrieve a file

The GET operation returns the file as raw binary data with the application/octet-stream content type. Use -o to write the response directly to a file. The .NET SDK can stream the content to a destination stream:

• Bash
• .NET

curl http://localhost:3500/v1.0-alpha1/binarystore/mystore/report.pdf \
  -o downloaded-report.pdf

using Dapr.BinaryStore;
using Dapr.BinaryStore.Extensions;
using System.IO;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprBinaryStoreClient();
var app = builder.Build();

var binaryStore = app.Services.GetRequiredService<DaprBinaryStoreClient>();
await using var destination = File.Create("downloaded-report.pdf");
await binaryStore.GetBinaryFileAsync("mystore", "report.pdf", destination);

If the file does not exist, the HTTP API returns 404 Not Found; the .NET client reports the runtime error as a DaprException.

Delete a file

• Bash
• .NET

curl -X DELETE \
  http://localhost:3500/v1.0-alpha1/binarystore/mystore/report.pdf

using Dapr.BinaryStore;
using Dapr.BinaryStore.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDaprBinaryStoreClient();
var app = builder.Build();

var binaryStore = app.Services.GetRequiredService<DaprBinaryStoreClient>();
await binaryStore.DeleteBinaryFileAsync("mystore", "report.pdf");

An HTTP delete returns 204 No Content when successful. The .NET client completes the operation without returning a response value.

File names and nested paths

File names are relative paths within the selected binary store. Nested paths such as images/profile.png are supported. Encode path characters as required when constructing an HTTP URL. Names with a leading or trailing slash, empty path segments, . or .. segments, or any of \, *, ?, [, ], and # are rejected by the runtime.

Next steps

• Read the Binary Store overview.
• Review the Binary Store API reference.
• See the Dapr .NET Binary Store documentation for SDK-specific usage.