✅ Merge main into live

.github/ISSUE_TEMPLATE/06-diagnostic-addition.yml

@@ -6,19 +6,67 @@ labels:
 - doc-idea
 - area-docs
 assignees:
-- IEvangelist
+- adegeo
 body:
+- type: markdown
+  attributes:
+    value: |
+      ```
+      ┌───────────┐
+      │ IMPORTANT ├──────────────────────────┐
+      └────────┬──┘ Please read the          │
+               │       following statement   │
+               └─────────────────────────────┘
+      ```
+      This template is for use by the product team to request new compiler warning articles.
+
+- type: dropdown
+  id: type
+  attributes:
+    label: Rule Type
+    description: "Is this considered an error or warning?"
+    options:
+      - Error
+      - Warning
+  validations:
+    required: true
+
+- type: input
+  id: version_introduced
+  attributes:
+    label: Version Introduced
+    description: "What version of .NET Aspire was this introduced with? (ex: 9.2)"
+  validations:
+    required: true
+
 - type: input
   id: diagnostic-id
   attributes:
     label: Diagnostic ID
     description: Enter the ID of the diagnostic to be added. Used for headings, i.e.; `ASPIREACADOMAINS001`.
   validations:
     required: true
+
+- type: input
+  id: title-short
+  attributes:
+    label: Short Title
+    description: "A simple title in one sentence that describes the rule. If possible, use the error/warning a user sees."
+  validations:
+    required: true
+
 - type: textarea
   id: description
   attributes:
     label: Description
-    description: Describe why the diagnostic exists and what it's used to indicate.
+    description: "Summarize what triggers this. Provide code examples if applicable."
+  validations:
+    required: true
+
+- type: textarea
+  id: fix
+  attributes:
+    label: How to fix
+    description: "Summarize what a user does to avoid triggering the rule, or what they do to fix their code. Provide an example if possible."
   validations:
     required: true

.markdownlint-cli2.jsonc

@@ -64,7 +64,8 @@
         "MD050": {
             "style": "asterisk"
         },
-        "MD051": false
+        "MD051": false,
+        "DOCSMD010": false
     },
     "ignores": [
         ".github/",
@@ -75,4 +76,4 @@
         "SECURITY.md",
         "ThirdPartyNotices.md"
     ]
-}
+}

docs/app-host/eventing.md

@@ -1,7 +1,7 @@
 ---
 title: Eventing in .NET Aspire
 description: Learn how to use the .NET eventing features with .NET Aspire.
-ms.date: 11/13/2024
+ms.date: 04/04/2025
 ---
 
 # Eventing in .NET Aspire
@@ -78,3 +78,57 @@ When events are dispatched, you can control how the events are dispatched to sub
 - <xref:Aspire.Hosting.Eventing.EventDispatchBehavior.NonBlockingConcurrent?displayProperty=nameWithType>: Fires events concurrently but doesn't block.
 
 The default behavior is `EventDispatchBehavior.BlockingSequential`. To override this behavior, when calling a publishing API such as <xref:Aspire.Hosting.Eventing.IDistributedApplicationEventing.PublishAsync*>, provide the desired behavior as an argument.
+
+## App Host life cycle events
+
+As you have seen, eventing is the most flexible approach. However, in this section you learn about the alternative: life cycle events.
+
+The .NET Aspire app host exposes several life cycles that you can hook into by implementing the <xref:Aspire.Hosting.Lifecycle.IDistributedApplicationLifecycleHook> interface. The following lifecycle methods are available:
+
+| Order | Method | Description |
+|--|--|--|
+| **1** | <xref:Aspire.Hosting.Lifecycle.IDistributedApplicationLifecycleHook.BeforeStartAsync%2A> | Runs before the distributed application starts. |
+| **2** | <xref:Aspire.Hosting.Lifecycle.IDistributedApplicationLifecycleHook.AfterEndpointsAllocatedAsync%2A> | Runs after the orchestrator allocates endpoints for resources in the application model. |
+| **3** | <xref:Aspire.Hosting.Lifecycle.IDistributedApplicationLifecycleHook.AfterResourcesCreatedAsync%2A> | Runs after the resource was created by the orchestrator. |
+
+### Register a life cycle hook
+
+To register a life cycle hook, implement the <xref:Aspire.Hosting.Lifecycle.IDistributedApplicationLifecycleHook> interface and register the hook with the app host using the <xref:Aspire.Hosting.Lifecycle.LifecycleHookServiceCollectionExtensions.AddLifecycleHook*> API:
+
+:::code source="../fundamentals/snippets/lifecycles/AspireApp/AspireApp.AppHost/Program.cs":::
+
+The preceding code:
+
+- Implements the <xref:Aspire.Hosting.Lifecycle.IDistributedApplicationLifecycleHook> interface as a `LifecycleLogger`.
+- Registers the life cycle hook with the app host using the <xref:Aspire.Hosting.Lifecycle.LifecycleHookServiceCollectionExtensions.AddLifecycleHook*> API.
+- Logs a message for all the events.
+
+When this app host is run, the life cycle hook is executed for each event. The following output is generated:
+
+```Output
+info: LifecycleLogger[0]
+      BeforeStartAsync
+info: Aspire.Hosting.DistributedApplication[0]
+      Aspire version: 9.0.0
+info: Aspire.Hosting.DistributedApplication[0]
+      Distributed application starting.
+info: Aspire.Hosting.DistributedApplication[0]
+      Application host directory is: ..\AspireApp\AspireApp.AppHost
+info: LifecycleLogger[0]
+      AfterEndpointsAllocatedAsync
+info: Aspire.Hosting.DistributedApplication[0]
+      Now listening on: https://localhost:17043
+info: Aspire.Hosting.DistributedApplication[0]
+      Login to the dashboard at https://localhost:17043/login?t=d80f598bc8a64c7ee97328a1cbd55d72
+info: LifecycleLogger[0]
+      AfterResourcesCreatedAsync
+info: Aspire.Hosting.DistributedApplication[0]
+      Distributed application started. Press Ctrl+C to shut down.
+```
+
+The preferred way to hook into the app host life cycle is to use the eventing API. For more information, see [Eventing in .NET Aspire](#eventing-in-net-aspire).
+
+## See also
+
+- [.NET Aspire orchestration overview](../fundamentals/app-host-overview.md)
+- [Orchestrate resources in .NET Aspire](../fundamentals/orchestrate-resources.md)

docs/azure/configure-aca-environments.md

@@ -64,6 +64,32 @@ builder.Build().Run();
 
 Calling this API ensures your existing Azure resources remain consistent and prevents duplication.
 
+## Customize provisioning infrastructure
+
+All .NET Aspire Azure resources are subclasses of the <xref:Aspire.Hosting.Azure.AzureProvisioningResource> type. This enables customization of the generated Bicep by providing a fluent API to configure the Azure resources—using the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure``1(Aspire.Hosting.ApplicationModel.IResourceBuilder{``0},System.Action{Aspire.Hosting.Azure.AzureResourceInfrastructure})> API:
+
+```csharp
+var builder = DistributionApplicationBuilder.Create(args);
+
+var acaEnv = builder.AddAzureContainerAppEnvironment(Config.ContainEnvironmentName);
+
+acaEnv.ConfigureInfrastructure(config =>
+{
+    var resources = config.GetProvisionableResources();
+    var containerEnvironment = resources.OfType<ContainerAppManagedEnvironment>().FirstOrDefault();
+
+    containerEnvironment.Tags.Add("ExampleKey", "Example value");
+});
+```
+
+The preceding code:
+
+- Chains a call to the <xref:Aspire.Hosting.AzureProvisioningResourceExtensions.ConfigureInfrastructure*> API:
+  - The `infra` parameter is an instance of the <xref:Aspire.Hosting.Azure.AzureResourceInfrastructure> type.
+  - The provisionable resources are retrieved by calling the <xref:Azure.Provisioning.Infrastructure.GetProvisionableResources> method.
+  - The single <xref:Azure.Provisioning.AppContainers.ContainerAppManagedEnvironment> resource is retrieved.
+  - A tag is added to the Azure Container Apps environment resource with a key of `ExampleKey` and a value of `Example value`.
+
 ## See also
 
 - [.NET Aspire Azure integrations overview](integrations-overview.md)

docs/caching/includes/garnet-app-host.md

@@ -38,7 +38,7 @@ builder.AddProject<Projects.ExampleProject>()
 
 When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `ghcr.io/microsoft/garnet` image, it creates a new Garnet instance on your local machine. A reference to your Garnet resource (the `cache` variable) is added to the `ExampleProject`.
 
-The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/app-host-overview.md#container-resource-lifecycle).
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 > [!TIP]
 > If you'd rather connect to an existing Garnet instance, call <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> instead. For more information, see [Reference existing resources](../../fundamentals/app-host-overview.md#reference-existing-resources).

docs/caching/includes/redis-app-host.md

@@ -38,7 +38,7 @@ builder.AddProject<Projects.ExampleProject>()
 
 When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/Redis/Redis` image, it creates a new Redis instance on your local machine. A reference to your Redis resource (the `cache` variable) is added to the `ExampleProject`.
 
-The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/app-host-overview.md#container-resource-lifecycle).
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 > [!TIP]
 > If you'd rather connect to an existing Redis instance, call <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> instead. For more information, see [Reference existing resources](../../fundamentals/app-host-overview.md#reference-existing-resources).

docs/caching/includes/valkey-app-host.md

@@ -38,7 +38,7 @@ builder.AddProject<Projects.ExampleProject>()
 
 When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/valkey/valkey` image, it creates a new Valkey instance on your local machine. A reference to your Valkey resource (the `cache` variable) is added to the `ExampleProject`.
 
-The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/app-host-overview.md#container-resource-lifecycle).
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 > [!TIP]
 > If you'd rather connect to an existing Valkey instance, call <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> instead. For more information, see [Reference existing resources](../../fundamentals/app-host-overview.md#reference-existing-resources).

docs/community-toolkit/hosting-eventstore.md

@@ -50,7 +50,7 @@ builder.AddProject<Projects.ExampleProject>()
 
 When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/eventstore/eventstore` image, it creates a new EventStore instance on your local machine. A reference to your EventStore resource (the `eventstore` variable) is added to the `ExampleProject`.
 
-For more information, see [Container resource lifecycle](../fundamentals/app-host-overview.md#container-resource-lifecycle).
+For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 ### Add EventStore resource with data volume
 

docs/community-toolkit/hosting-meilisearch.md

@@ -50,7 +50,7 @@ builder.AddProject<Projects.ExampleProject>()
 
 When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/getmeili/meilisearch` image, it creates a new Meilisearch instance on your local machine. A reference to your Meilisearch resource (the `meilisearch` variable) is added to the `ExampleProject`. The Meilisearch resource includes a randomly generated `master key` using the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter*> method when a master key wasn't provided.
 
-For more information, see [Container resource lifecycle](../fundamentals/app-host-overview.md#container-resource-lifecycle).
+For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 ### Add Meilisearch resource with data volume
 

docs/community-toolkit/ollama.md

@@ -54,7 +54,7 @@ Alternatively, if you want to use a model from the [Hugging Face](https://huggin
 var llama = ollama.AddHuggingFaceModel("llama", "bartowski/Llama-3.2-1B-Instruct-GGUF:IQ4_XS");
 ```
 
-When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/ollama/ollama` image, it creates a new Ollama instance on your local machine. For more information, see [Container resource lifecycle](../fundamentals/app-host-overview.md#container-resource-lifecycle).
+When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/ollama/ollama` image, it creates a new Ollama instance on your local machine. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 ### Download the LLM
 

docs/database/includes/cosmos-app-host.md

@@ -181,11 +181,11 @@ var cosmos = builder.AddAzureCosmosDB("cosmos-db")
 // After adding all resources, run the app...
 ```
 
-When you call `RunAsEmulator`, it configures your Cosmos DB resources to run locally using an emulator. The emulator in this case is the [Azure Cosmos DB Emulator](/azure/cosmos-db/local-emulator). The Azure Cosmos DB Emulator provides a free local environment for testing your Azure Cosmos DB apps and it's a perfect companion to the .NET Aspire Azure hosting integration. The emulator isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the app host, as shown in the preceding example with the `mcr.microsoft.com/cosmosdb/emulator` image, it creates and starts the container when the app host starts. For more information, see [Container resource lifecycle](../../fundamentals/app-host-overview.md#container-resource-lifecycle).
+When you call `RunAsEmulator`, it configures your Cosmos DB resources to run locally using an emulator. The emulator in this case is the [Azure Cosmos DB Emulator](/azure/cosmos-db/local-emulator). The Azure Cosmos DB Emulator provides a free local environment for testing your Azure Cosmos DB apps and it's a perfect companion to the .NET Aspire Azure hosting integration. The emulator isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the app host, as shown in the preceding example with the `mcr.microsoft.com/cosmosdb/emulator` image, it creates and starts the container when the app host starts. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 #### Configure Cosmos DB emulator container
 
-There are various configurations available to container resources, for example, you can configure the container's ports, environment variables, it's [lifetime](../../fundamentals/app-host-overview.md#container-resource-lifetime), and more.
+There are various configurations available to container resources, for example, you can configure the container's ports, environment variables, it's [lifetime](../../fundamentals/orchestrate-resources.md#container-resource-lifetime), and more.
 
 ##### Configure Cosmos DB emulator container gateway port
 
@@ -231,7 +231,7 @@ var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
 // After adding all resources, run the app...
 ```
 
-For more information, see [Container resource lifetime](../../fundamentals/app-host-overview.md#container-resource-lifetime).
+For more information, see [Container resource lifetime](../../fundamentals/orchestrate-resources.md#container-resource-lifetime).
 
 ##### Configure Cosmos DB emulator container with data volume
 

docs/database/includes/mysql-app-host.md

@@ -41,7 +41,7 @@ var myService = builder.AddProject<Projects.ExampleProject>()
 ```
 
 > [!NOTE]
-> The SQL Server container is slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../../fundamentals/app-host-overview.md#container-resource-lifetime).
+> The SQL Server container is slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../../fundamentals/orchestrate-resources.md#container-resource-lifetime).
 
 When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `mysql` image, it creates a new MySQL instance on your local machine. A reference to your MySQL resource builder (the `mysql` variable) is used to add a database. The database is named `mysqldb` and then added to the `ExampleProject`. The MySQL resource includes default credentials with a `username` of `root` and a random `password` generated using the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter*> method.
 

docs/database/includes/postgresql-app-host.md

@@ -50,7 +50,7 @@ When adding a database resource to the app model, the database is created if it
 
 The PostgreSQL server resource includes default credentials with a `username` of `"postgres"` and randomly generated `password` using the <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.CreateDefaultPasswordParameter*> method.
 
-The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"messaging"`. For more information, see [Container resource lifecycle](../../fundamentals/app-host-overview.md#container-resource-lifecycle).
+The <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference%2A> method configures a connection in the `ExampleProject` named `"messaging"`. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle).
 
 > [!TIP]
 > If you'd rather connect to an existing PostgreSQL server, call <xref:Aspire.Hosting.ParameterResourceBuilderExtensions.AddConnectionString*> instead. For more information, see [Reference existing resources](../../fundamentals/app-host-overview.md#reference-existing-resources).

docs/database/includes/sql-app-host.md

@@ -41,7 +41,7 @@ builder.AddProject<Projects.ExampleProject>()
 ```
 
 > [!NOTE]
-> The SQL Server container is slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../../fundamentals/app-host-overview.md#container-resource-lifetime).
+> The SQL Server container is slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../../fundamentals/orchestrate-resources.md#container-resource-lifetime).
 
 When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `mcr.microsoft.com/mssql/server` image, it creates a new SQL Server instance on your local machine. A reference to your SQL Server resource builder (the `sql` variable) is used to add a database. The database is named `database` and then added to the `ExampleProject`.