Docs: Azure Blob Storage env vars differ between local emulator and deployed environments
@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:
- Which environment variables are injected in each environment (local vs deployed)
- That
CONNECTIONSTRINGis only available with the emulator - The recommended pattern for writing code that works in both environments (e.g., check
URIfirst, fall back toCONNECTIONSTRING)
Steps To Reproduce
- Create an Aspire app with
addAzureStorage('storage').runAsEmulator().addBlobContainer('plantdata') - Reference the blob container from a Next.js/Node app
- Note
PLANTDATA_CONNECTIONSTRINGworks locally - Deploy to Azure —
PLANTDATA_CONNECTIONSTRINGis not set, onlyPLANTDATA_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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from microsoft/aspire.dev
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
microsoft/aspire.dev#1650 ·
-
Docs: Dev Tunnels "Configure dev tunnel options" examples do not compile; options table omits Region Open
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
microsoft/aspire.dev#1465 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
microsoft/aspire.dev#1464 ·
-
Difficulty 2/5 Half a day Newbie friendliness 84/100
microsoft/aspire.dev#1463 ·
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
microsoft/aspire.dev#1416 ·