Docs: Azure Blob Storage env vars differ between local emulator and deployed environments

Open
#728 1 comment 1 reaction 1 assignee View on GitHub

@IEvangelist is already working on this.

Since Jun 2, 2026.

Assessment

This issue has not been assessed yet.

Description

Is there an existing issue for this?

  • I have searched the existing issues

Describe the bug

When using Azure Blob Storage with Aspire (addAzureStorage + addBlobContainer), the environment variables injected into the consuming app differ between local development (Azurite emulator) and deployed (Azure) environments, but this is not documented.

Local (Azurite emulator):

  • PLANTDATA_CONNECTIONSTRING ✅ (full Azurite connection string)
  • PLANTDATA_URI ❌ (not set)
  • PLANTDATA_BLOBCONTAINERNAME

Deployed (Azure):

  • PLANTDATA_CONNECTIONSTRING ❌ (not set)
  • PLANTDATA_URI ✅ (blob endpoint URI)
  • PLANTDATA_BLOBCONTAINERNAME

This means code that works locally with PLANTDATA_CONNECTIONSTRING breaks in production, and vice versa. The app needs to check for both and handle each case differently, but there's no documentation explaining this asymmetry.

Expected Behavior

The docs for Azure Blob Storage integration should clearly document:

  1. Which environment variables are injected in each environment (local vs deployed)
  2. That CONNECTIONSTRING is only available with the emulator
  3. The recommended pattern for writing code that works in both environments (e.g., check URI first, fall back to CONNECTIONSTRING)

Steps To Reproduce

  1. Create an Aspire app with addAzureStorage('storage').runAsEmulator().addBlobContainer('plantdata')
  2. Reference the blob container from a Next.js/Node app
  3. Note PLANTDATA_CONNECTIONSTRING works locally
  4. Deploy to Azure — PLANTDATA_CONNECTIONSTRING is not set, only PLANTDATA_URI

Aspire Version

Latest Aspire CLI + TypeScript AppHost (Node.js)

Additional Context

Found during #AspiriFridays stream while building a Next.js garden journal app. Our workaround is to check for PLANTDATA_URI first (production) and fall back to PLANTDATA_CONNECTIONSTRING (local), using DefaultAzureCredential for the URI path and BlobServiceClient.fromConnectionString() for the connection string path.

Dominant language
MDX
Stars
195
Forks
87
Avg merge
1d 22h
Merged PRs (30d)
73

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/aspire.dev

All issues in microsoft/aspire.dev

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.