1# .NET Aspire Projects
2 
3> ⛔ **CRITICAL - READ THIS FIRST**
4>
5> For .NET Aspire projects, **NEVER manually create azure.yaml or infra/ files.**
6> Always use `azd init --from-code` which auto-detects the AppHost and generates everything correctly.
7>
8> **Failure to follow this causes:** "Could not find a part of the path 'infra\main.bicep'" error.
9 
10Guidance for preparing .NET Aspire applications for Azure deployment.
11 
12**📖 For detailed AZD workflow:** See [recipes/azd/aspire.md](recipes/azd/aspire.md)
13 
14## What is .NET Aspire?
15 
16.NET Aspire is an opinionated, cloud-ready stack for building observable, production-ready distributed applications. Aspire projects use an AppHost orchestrator to define and configure the application's components, services, and dependencies.
17 
18## Detection
19 
20A .NET Aspire project is identified by:
21 
22| Indicator | Description |
23|-----------|-------------|
24| `*.AppHost.csproj` | AppHost orchestrator project file |
25| `Aspire.Hosting` package | Core Aspire hosting package reference |
26| `Aspire.Hosting.AppHost` | Alternative Aspire hosting package |
27 
28**Example project structure:**
29```
30orleans-voting/
31├── OrleansVoting.sln
32├── OrleansVoting.AppHost/
33│   └── OrleansVoting.AppHost.csproj   ← AppHost indicator
34├── OrleansVoting.Web/
35├── OrleansVoting.Api/
36└── OrleansVoting.Grains/
37```
38 
39## Azure Preparation Workflow
40 
41### Step 1: Detection
42 
43When scanning the codebase (per [scan.md](scan.md)), detect Aspire by:
44 
45```bash
46# Check for AppHost project
47find . -name "*.AppHost.csproj"
48 
49# Or check for Aspire.Hosting package reference
50grep -r "Aspire.Hosting" . --include="*.csproj"
51```
52 
53### ⛔ Step 1a: Pre-Check for Custom/Non-Deployable Resources (MANDATORY)
54 
55**Before running `azd init --from-code`, scan the AppHost source code to understand whether the app may contain local-only custom resources.**
56 
57```bash
58# Find the AppHost project and scan only its source directory
59APPHOST_PROJECT=$(find . -name "*.AppHost.csproj" | head -1)
60APPHOST_DIR=$(dirname "$APPHOST_PROJECT")
61grep -r "ExcludeFromManifest" "$APPHOST_DIR" --include="*.cs" | head -20
62```
63 
64**PowerShell:**
65```powershell
66# Find the AppHost project and scan only its source directory
67$appHostProject = Get-ChildItem -Recurse -Filter "*.AppHost.csproj" | Select-Object -First 1
68$appHostDir = $appHostProject.DirectoryName
69Get-ChildItem -Path $appHostDir -Recurse -Filter "*.cs" | Select-String "ExcludeFromManifest" | Select-Object -First 20
70```
71 
72This scan is informational. `.ExcludeFromManifest()` can appear alongside deployable resources, so a positive match does **not** immediately block deployment. What matters is the final `azure.yaml` output after `azd init --from-code` completes:
73 
74- If `azd init` **fails** with `unsupported resource type` → see Step 2 error guidance below.
75- If `azd init` **succeeds** but `azure.yaml` has an empty or missing `services` section → see Step 4a below.
76 
77> 💡 **Why scan early:** Knowing that `.ExcludeFromManifest()` is present gives useful context when azd errors or generates an empty manifest — it confirms the app intentionally targets local development rather than Azure deployment.
78 
79### Step 2: Initialize with azd
80 
81**CRITICAL: For Aspire projects, use `azd init --from-code -e <environment-name>` instead of creating azure.yaml manually.**
82 
83**⚠️ ALWAYS include the `-e <environment-name>` flag:** Without it, `azd init` will fail in non-interactive environments (agents, CI/CD) with the error: `no default response for prompt 'Enter a unique environment name:'`
84 
85The `--from-code` flag:
86- Auto-detects the AppHost orchestrator
87- Reads the Aspire service definitions
88- Generates appropriate `azure.yaml` and infrastructure
89- Works in non-interactive/CI environments when combined with `-e` flag
90 
91```bash
92# Non-interactive initialization for Aspire projects (REQUIRED for agents)
93ENV_NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | tr ' _' '-')-dev"
94azd init --from-code -e "$ENV_NAME"
95```
96 
97**Why both flags are required:**
98- `--from-code`: Tells azd to detect the AppHost automatically (no "How do you want to initialize?" prompt)
99- `-e <name>`: Provides environment name upfront (no "Enter environment name:" prompt)
100- Together, they enable fully non-interactive operation essential for automation, agents, and CI/CD pipelines
101 
102**⛔ If `azd init --from-code` fails with "unsupported resource type":**
103 
104This error means the AppHost contains custom Aspire resource types that azd cannot process for Azure deployment:
105 
1061. ⛔ **Do NOT attempt to fix this error by modifying source code** — do not add `.ExcludeFromManifest()` calls or otherwise patch the AppHost
1072. ⛔ **Do NOT proceed with deployment** — the application is designed for local development only
1083. ✅ Record a blocker: "AppHost contains custom Aspire resource types (`unsupported resource type`) that cannot be deployed to Azure"
1094. ✅ Inform the user: this application uses custom Aspire resource authoring patterns intended for local tooling, not cloud deployment
110 
111> ⚠️ **Why modifying source code is forbidden:** Adding `.ExcludeFromManifest()` may suppress the error and allow `azd init` to succeed, but the deployment outcome will not reflect the application's actual intent. The custom resources are deliberately designed to be local-only.
112 
113### Step 3: Configure Subscription and Location
114 
115> **⛔ CRITICAL**: After `azd init --from-code` completes, you **MUST** immediately set the user-confirmed subscription and location.
116>
117> **DO NOT** skip this step or delay it until validation. The `azd init` command creates an environment but does NOT inherit the Azure CLI's subscription. If you skip this step, azd will use its own default subscription, which may differ from the user's confirmed choice.
118 
119**Set the subscription and location immediately after initialization:**
120 
121```bash
122# Set the user-confirmed subscription ID
123azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
124 
125# Set the location
126azd env set AZURE_LOCATION <location>
127```
128 
129**Verify the configuration:**
130 
131```bash
132azd env get-values
133```
134 
135Confirm that `AZURE_SUBSCRIPTION_ID` and `AZURE_LOCATION` match the user's confirmed choices from [Azure Context](azure-context.md).
136 
137### Step 4: What azd Generates
138 
139`azd init --from-code` creates:
140 
141| Artifact | Location | Description |
142|----------|----------|-------------|
143| `azure.yaml` | Project root | Service definitions from AppHost |
144| `infra/` | Project root | Bicep templates for Azure resources |
145| `.azure/` | Project root | Environment configuration |
146 
147### ⛔ Step 4a: Validate Generated Output
148 
149**MANDATORY: After `azd init --from-code` completes, verify the generated `azure.yaml` contains deployable services.**
150 
151```bash
152# Check if azure.yaml has a non-empty services section
153cat azure.yaml
154```
155 
156**If the `services` section is empty or missing:** The AppHost has no deployable resources. This happens when all resources use `.ExcludeFromManifest()` (e.g., custom resource demonstrations, local-only tooling). In this case:
157 
1581. ⛔ **Do NOT proceed with deployment** — there is nothing to deploy
1592. ✅ Keep the plan status in a valid state (for example, leave it as **Planning**) and record a blocker in the plan body with the reason: "Application contains only custom/demo Aspire resources with no Azure-deployable services"
1603. ✅ Inform the user that this application is designed for local development and cannot be meaningfully deployed to Azure
1614. ⛔ Do NOT manually create Bicep, Dockerfiles, or azure.yaml to work around this — the absence of services is the correct result
162 
163**Example generated azure.yaml:**
164```yaml
165name: orleans-voting
166# metadata section is auto-generated by azd init --from-code
167 
168services:
169  web:
170    project: ./OrleansVoting.Web
171    language: dotnet
172    host: containerapp
173 
174  api:
175    project: ./OrleansVoting.Api
176    language: dotnet
177    host: containerapp
178```
179 
180### ⛔ Step 4b: Fix Azure Functions Secret Storage (MANDATORY for Aspire + Functions)
181 
182**MANDATORY: After `azd init --from-code` succeeds, check if the AppHost contains Azure Functions and fix secret storage configuration.**
183 
184This step **MUST** run BEFORE `azd up` or `azd provision`. Skipping it causes a runtime failure: `Secret initialization from Blob storage failed`.
185 
186**1. Detect Azure Functions in the AppHost:**
187 
188```bash
189APPHOST_DIR=$(dirname "$(find . -name '*.AppHost.csproj' | head -1)")
190grep -n "AddAzureFunctionsProject" "$APPHOST_DIR"/*.cs
191```
192 
193**PowerShell:**
194```powershell
195$appHostDir = (Get-ChildItem -Recurse -Filter "*.AppHost.csproj" | Select-Object -First 1).DirectoryName
196Get-ChildItem -Path $appHostDir -Filter "*.cs" | Select-String "AddAzureFunctionsProject"
197```
198 
199**If `AddAzureFunctionsProject` is NOT found → skip this step.**
200 
201**2. Check if `AzureWebJobsSecretStorageType` is already configured:**
202 
203```bash
204grep -n "AzureWebJobsSecretStorageType" "$APPHOST_DIR"/*.cs
205```
206 
207**PowerShell:**
208```powershell
209Get-ChildItem -Path $appHostDir -Filter "*.cs" | Select-String "AzureWebJobsSecretStorageType"
210```
211 
212**If already present → skip this step.**
213 
214**3. Add the environment variable to the Functions builder chain:**
215 
216Use the `edit` tool to add `.WithEnvironment("AzureWebJobsSecretStorageType", "Files")` to the `AddAzureFunctionsProject` builder chain in the AppHost source file.
217 
218**Before:**
219```csharp
220var functions = builder.AddAzureFunctionsProject<Projects.MyFunctions>("functions")
221    .WithHostStorage(storage)
222    .WithReference(queues);
223```
224 
225**After:**
226```csharp
227var functions = builder.AddAzureFunctionsProject<Projects.MyFunctions>("functions")
228    .WithHostStorage(storage)
229    .WithEnvironment("AzureWebJobsSecretStorageType", "Files")
230    .WithReference(queues);
231```
232 
233> 💡 **Tip:** Place `.WithEnvironment(...)` immediately after `.WithHostStorage(...)` for clarity.
234 
235> ⚠️ **Why this is required:** When Aspire uses `WithHostStorage(storage)`, it configures identity-based storage URIs (e.g., `AzureWebJobsStorage__blobServiceUri`). Azure Functions' secret/key manager does **not** support these identity-based URIs — it requires either a connection string or file-based storage. Setting `AzureWebJobsSecretStorageType=Files` switches to file-system key storage, bypassing the incompatible blob dependency.
236 
237See [aspire-functions-secrets reference](services/functions/aspire-containerapps.md) for additional details.
238 
239## Flags Reference
240 
241### azd init for Aspire
242 
243| Flag | Required | Description |
244|------|----------|-------------|
245| `--from-code` | ✅ Yes | Auto-detect AppHost, no interactive prompts |
246| `-e <name>` | ✅ Yes | Environment name (required for non-interactive) |
247| `--no-prompt` | Optional | Skip additional confirmations |
248 
249**Complete initialization sequence:**
250```bash
251# 1. Initialize the environment
252ENV_NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | tr ' _' '-')-dev"
253azd init --from-code -e "$ENV_NAME"
254 
255# 2. IMMEDIATELY set the user-confirmed subscription
256azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
257 
258# 3. Set the location
259azd env set AZURE_LOCATION <location>
260 
261# 4. Verify configuration
262azd env get-values
263```
264 
265## Common Aspire Samples
266 
267| Sample | Repository | Notes |
268|--------|------------|-------|
269| orleans-voting | [dotnet/aspire-samples](https://github.com/dotnet/aspire-samples/tree/main/samples/orleans-voting) | Orleans cluster with voting app |
270| AspireYarp | [dotnet/aspire-samples](https://github.com/dotnet/aspire-samples/tree/main/samples/AspireYarp) | YARP reverse proxy |
271| AspireWithDapr | [dotnet/aspire-samples](https://github.com/dotnet/aspire-samples/tree/main/samples/AspireWithDapr) | Dapr integration |
272| eShop | [dotnet/eShop](https://github.com/dotnet/eShop) | Reference microservices app |
273 
274## Troubleshooting
275 
276### Error: "no default response for prompt 'Enter a unique environment name:'"
277 
278**Cause:** Missing `-e` flag when running `azd init --from-code` in non-interactive environment  
279**Solution:** Always include the `-e <environment-name>` flag
280 
281```bash
282# ❌ Wrong - fails in non-interactive environments (agents, CI/CD)
283azd init --from-code
284 
285# ✅ Correct - provides environment name upfront
286ENV_NAME="$(basename "$PWD" | tr '[:upper:]' '[:lower:]' | tr ' _' '-')-dev"
287azd init --from-code -e "$ENV_NAME"
288```
289 
290**Important:** This error typically occurs when:
291- Running in an agent or automation context
292- No TTY is available for interactive prompts
293- The `-e` flag was omitted
294 
295### Error: "no default response for prompt 'How do you want to initialize your app?'"
296 
297**Cause:** Missing `--from-code` flag  
298**Solution:** Add `--from-code` to the `azd init` command
299 
300```bash
301# ❌ Wrong - requires interactive prompt
302azd init -e "my-env"
303 
304# ✅ Correct - auto-detects AppHost
305azd init --from-code -e "my-env"
306```
307 
308### No AppHost detected
309 
310**Symptoms:** `azd init --from-code` doesn't find the AppHost
311 
312**Solutions:**
3131. Verify AppHost project exists: `find . -name "*.AppHost.csproj"`
3142. Check project builds: `dotnet build`
3153. Ensure Aspire.Hosting package is referenced in AppHost project
316 
317### Error: "unsupported resource type" during manifest generation
318 
319**Symptoms:** `azd init --from-code` fails with output like:
320```
321error: unsupported resource type: <custom-resource-type>
322```
323or the manifest generation step errors on child resources (e.g., ClockHand, or other custom resource types defined in the AppHost).
324 
325**Cause:** The AppHost contains custom Aspire resource types that azd cannot convert to Azure deployable resources. These custom types are typically:
326- Demonstration resources showing developers how to build Aspire extensions for local tooling
327- Resources that wrap local services without Azure equivalents
328- Custom child resources (e.g., subcomponents of a custom Aspire integration)
329 
330**Resolution:**
331 
3321. ⛔ **Do NOT attempt to fix this error by modifying source code** — do not add `.ExcludeFromManifest()` calls or otherwise patch the AppHost
3332. ⛔ **Do NOT proceed with deployment** — this is a deployment blocker, not a recoverable error
3343. ✅ Record a blocker in the deployment plan: "AppHost contains custom Aspire resource types not supported for Azure deployment (unsupported resource type)"
3354. ✅ Inform the user that this application is designed for local development and cannot be meaningfully deployed to Azure
336 
337> ⚠️ **Why this is a hard stop:** Custom resource types that produce "unsupported resource type" errors are intentionally not deployable. Adding `.ExcludeFromManifest()` to suppress the error may allow `azd init` to succeed, but the resulting deployment would not represent the application's actual functionality.
338 
339### Azure Functions: Secret initialization from Blob storage failed
340 
341**Symptoms:** Azure Functions app fails at startup with error:
342```
343System.InvalidOperationException: Secret initialization from Blob storage failed due to missing both
344an Azure Storage connection string and a SAS connection uri.
345```
346 
347**Cause:** When using `AddAzureFunctionsProject` with `WithHostStorage(storage)`, Aspire configures identity-based storage access (managed identity). However, Azure Functions' internal secret management does not support identity-based URIs and requires file-based secret storage for Container Apps deployments.
348 
349**Solution:** Add `AzureWebJobsSecretStorageType=Files` environment variable to the Functions resource in the AppHost **before running `azd up`**:
350 
351```csharp
352var functions = builder.AddAzureFunctionsProject<Projects.ImageGallery_Functions>("functions")
353                       .WithReference(queues)
354                       .WithReference(blobs)
355                       .WaitFor(storage)
356                       .WithRoleAssignments(storage, ...)
357                       .WithHostStorage(storage)
358                       .WithEnvironment("AzureWebJobsSecretStorageType", "Files")  // Required for Container Apps
359                       .WithUrlForEndpoint("http", u => u.DisplayText = "Functions App");
360```
361 
362> 💡 **Why this is required:**
363> - `WithHostStorage(storage)` sets identity-based URIs like `AzureWebJobsStorage__blobServiceUri`
364> - This is correct and secure for runtime storage operations
365> - However, Functions' secret/key management doesn't support these URIs
366> - File-based secrets are mandatory for Container Apps deployments
367 
368> ⚠️ **Important:** This is required when:
369> - Using `AddAzureFunctionsProject` in Aspire
370> - Using `WithHostStorage()` with identity-based storage
371> - Deploying to Azure Container Apps (the default for Aspire Functions)
372 
373**Generated Infrastructure Note:**
374 
375If you need to modify the generated Container Apps infrastructure directly, ensure the Functions container app has this environment variable:
376 
377```bicep
378resource functionsContainerApp 'Microsoft.App/containerApps@2024-03-01' = {
379  properties: {
380    template: {
381      containers: [
382        {
383          env: [
384            {
385              name: 'AzureWebJobsSecretStorageType'
386              value: 'Files'
387            }
388            // ... other environment variables
389          ]
390        }
391      ]
392    }
393  }
394}
395```
396 
397### Error: azd uses wrong subscription despite user confirmation
398 
399**Symptoms:** `azd provision --preview` shows a different subscription than the one the user confirmed
400 
401**Cause:** The `AZURE_SUBSCRIPTION_ID` was not set immediately after `azd init --from-code`. The Azure CLI and azd can have different default subscriptions.
402 
403**Solution:** Always set the subscription immediately after initialization:
404 
405```bash
406# After azd init --from-code completes:
407azd env set AZURE_SUBSCRIPTION_ID <user-confirmed-subscription-id>
408azd env set AZURE_LOCATION <location>
409 
410# Verify before proceeding:
411azd env get-values
412```
413 
414**Prevention:** Follow the complete initialization sequence in the [Flags Reference](#azd-init-for-aspire) section above.
415 
416## References
417 
418- [.NET Aspire Documentation](https://learn.microsoft.com/en-us/dotnet/aspire/)
419- [Azure Developer CLI (azd)](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/)
420- [Aspire Samples Repository](https://github.com/dotnet/aspire-samples)
421- [azd + Aspire Integration](https://learn.microsoft.com/en-us/dotnet/aspire/deployment/azure/aca-deployment-azd-in-depth)
422 
423## Next Steps
424 
425After `azd init --from-code`:
4261. Review generated `azure.yaml` and `infra/` files (if present)
4272. Set AZURE_SUBSCRIPTION_ID and AZURE_LOCATION with `azd env set`
4283. Customize infrastructure as needed
4294. Proceed to **azure-validate** skill
4305. Deploy with **azure-deploy** skill
431 
432> ⚠️ **Important for Container Apps:** If using Aspire with Container Apps, azure-validate will check and help set up required environment variables after provisioning.
433