Add CosmosDB parent-child relationship bits. (#2912)

* Add CosmosDB parent-child relationship bits. Part of #2907

* A few fixes

* Update docs/database/azure-cosmos-db-integration.md

Co-authored-by: Safia Abdalla <[email protected]>

* Update docs/database/azure-cosmos-db-integration.md

Co-authored-by: Safia Abdalla <[email protected]>

* A few updates based on feedback

* Add a few more bits

* Add more details about the web pubsub.

* Apply suggestions from code review

Co-authored-by: Safia Abdalla <[email protected]>

---------

Co-authored-by: Safia Abdalla <[email protected]>

Author: IEvangelist

docs/database/azure-cosmos-db-entity-framework-integration.md

@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire Cosmos DB Entity Framework Core integration
 description: Learn how to install and configure the .NET Aspire Cosmos DB Entity Framework Core integration to connect to existing Cosmos DB instances or create new instances from .NET with the Azure Cosmos DB emulator.
-ms.date: 02/26/2025
+ms.date: 04/01/2025
 uid: dotnet/aspire/azure-cosmos-db-entity-framework-integration
 ---
 
@@ -42,12 +42,18 @@ dotnet add package Aspire.Microsoft.EntityFrameworkCore.Cosmos
 
 ### Add Cosmos DB context
 
-In the :::no-loc text="Program.cs"::: file of your client-consuming project, call the <xref:Microsoft.Extensions.Hosting.AspireAzureEFCoreCosmosExtensions.AddCosmosDbContext%2A> extension method to register a <xref:System.Data.Entity.DbContext?displayProperty=fullName> for use via the dependency injection container. The method takes a connection name parameter.
+In the :::no-loc text="Program.cs"::: file of your client-consuming project, call the <xref:Microsoft.Extensions.Hosting.AspireAzureEFCoreCosmosExtensions.AddCosmosDbContext%2A> extension method to register a <xref:System.Data.Entity.DbContext?displayProperty=fullName> for use via the dependency injection container. The method takes a connection name parameter and a database name parameter.
 
 ```csharp
 builder.AddCosmosDbContext<MyDbContext>("cosmosdb", "databaseName");
 ```
 
+Alternatively, the database name can be inferred from the connection when there's a single database in the connection string. In this case, you can omit the database name parameter:
+
+```csharp
+builder.AddCosmosDbContext<MyDbContext>("cosmosdb");
+```
+
 > [!TIP]
 > The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the app host project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmosdb` that same name should be used when calling `AddCosmosDbContext`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource).
 

docs/database/azure-cosmos-db-integration.md

@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire Azure Cosmos DB integration
 description: Learn how to install and configure the .NET Aspire Azure Cosmos DB integration to connect to existing Cosmos DB instances or create new instances from .NET with the Azure Cosmos DB emulator.
-ms.date: 02/26/2025
+ms.date: 04/01/2025
 uid: dotnet/aspire/azure-cosmos-db-integration
 ---
 
@@ -11,6 +11,8 @@ uid: dotnet/aspire/azure-cosmos-db-integration
 
 [Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db/) is a fully managed NoSQL database service for modern app development. The .NET Aspire Azure Cosmos DB integration enables you to connect to existing Cosmos DB instances or create new instances from .NET with the Azure Cosmos DB emulator.
 
+If you're looking for the Entity Framework Core integration, see [.NET Aspire Cosmos DB Entity Framework Core integration](azure-cosmos-db-entity-framework-integration.md).
+
 ## Hosting integration
 
 [!INCLUDE [cosmos-app-host](includes/cosmos-app-host.md)]
@@ -51,7 +53,7 @@ builder.AddAzureCosmosClient(connectionName: "cosmos-db");
 > [!TIP]
 > The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the app host project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmos-db` that same name should be used when calling `AddAzureCosmosClient`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource).
 
-You can then retrieve the <xref:Azure.Cosmos.CosmosClient> instance using dependency injection. For example, to retrieve the connection from an example service:
+You can then retrieve the <xref:Azure.Cosmos.CosmosClient> instance using dependency injection. For example, to retrieve the client from an example service:
 
 ```csharp
 public class ExampleService(CosmosClient client)
@@ -87,6 +89,142 @@ public class ExampleService(
 
 For more information on keyed services, see [.NET dependency injection: Keyed services](/dotnet/core/extensions/dependency-injection#keyed-services).
 
+### Add Azure Cosmos DB database
+
+<!-- TODO: Add xref to AddAzureCosmosDatabase when available -->
+
+In the app host, the database resource  (<xref:Aspire.Hosting.AzureCosmosDBDatabaseResource>) can be added as a child resource to the parent <xref:Aspire.Hosting.AzureCosmosDBResource>. In your client-consuming project, you can deep-link to the database resource by name, registering a <xref:Microsoft.Azure.Cosmos.Database> instance for use with dependency injection. For example, consider the following code that calls `AddAzureCosmosDatabase` on an <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> instance:
+
+```csharp
+builder.AddAzureCosmosDatabase(connectionName: "customers");
+```
+
+<!-- TODO: Add xref to CosmosDatabaseBuilder when available -->
+
+The `AddAzureCosmosDatabase` API returns a `CosmosDatabaseBuilder` instance that you can use to attach multiple containers under the same database connection. All child containers share the same <xref:Azure.Cosmos.CosmosClient> and database connection and `CosmosClient` instance. This strategy is useful when associating the same <xref:Azure.Cosmos.CosmosClientOptions> with multiple containers.
+
+After calling `AddAzureCosmosDatabase`, you can then retrieve the `Database` instance using dependency injection. For example, to retrieve the database from a delegate in a <xref:Microsoft.AspNetCore.Builder.EndpointRouteBuilderExtensions.MapGet*> call consider the following code:
+
+```csharp
+app.MapGet("/api/customers", async (Database database) =>
+{
+    // Query data from database...
+});
+```
+
+### Add keyed Azure Cosmos DB database
+
+<!-- TODO: Add xref to AddKeyedAzureCosmosDatabase when available -->
+
+There's also an `AddKeyedAzureCosmosDatabase` API that returns a `CosmosDatabaseBuilder` instance that you can use to attach multiple containers under the same database connection. method that allows you to register multiple databases with different connection names. For example, consider the following code that calls `AddKeyedAzureCosmosDatabase` on an <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> instance:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.AddKeyedAzureCosmosDatabase("customers");
+builder.AddKeyedAzureCosmosDatabase("orders");
+
+var app = builder.Build();
+
+app.MapGet("/api/customers", async (
+    [FromKeyedServices("customers")] Database database) =>
+{
+    // Get container from database and query data
+});
+
+app.MapPost("/api/orders", async (
+    [FromKeyedServices("orders")] Database database,
+    [FromBody] OrderRequest order) =>
+{
+    // Get container from database and query data
+});
+
+app.Run();
+```
+
+The preceding example code demonstrates how to register two databases, `details` and `customers`. Each named database can be used to get their corresponding containers to query data.
+
+### Add Azure Cosmos DB container
+
+<!-- TODO: Add xref to AddAzureCosmosContainer when available -->
+
+When you add a Cosmos DB resource in the app host project, you can also add an Azure Cosmos DB container resource as well. The container resource is considered a child resource to the parent <xref:Aspire.Hosting.AzureCosmosDBDatabaseResource>. In your client-consuming project, you can deep-link to the container resource by name, registering a <xref:Microsoft.Azure.Cosmos.Container> instance for use with dependency injection. For example, consider the following code that calls `AddAzureCosmosContainer` on an <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> instance:
+
+```csharp
+builder.AddAzureCosmosContainer(connectionName: "details");
+```
+
+You can then retrieve the `Container` instance using dependency injection. For example, to retrieve the container from a delegate in a <xref:Microsoft.AspNetCore.Builder.EndpointRouteBuilderExtensions.MapGet*> call consider the following code:
+
+```csharp
+app.MapGet("/api/orders/{id:guid}", async (
+    Container container, 
+    [FromRoute] Guid id) =>
+{
+    // Query data from container...
+});
+```
+
+### Add keyed Azure Cosmos DB container
+
+<!-- TODO: Add xref to AddKeyedAzureCosmosContainer when available -->
+
+There's also an `AddKeyedAzureCosmosContainer` method that allows you to register multiple containers with different connection names. For example, consider the following code that calls `AddKeyedAzureCosmosContainer` on an <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> instance:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.AddKeyedAzureCosmosContainer("customers");
+
+var app = builder.Build();
+
+app.MapGet("/api/customers", async (
+    [FromKeyedServices("customers")] Container container) =>
+{
+    // Query data from container...
+});
+
+app.Run();
+```
+
+If you have multiple containers under the same database connection, you can use the `AddAzureCosmosDatabase` API to attach multiple containers under the same database connection. All child containers share the same <xref:Azure.Cosmos.CosmosClient> and database connection. This strategy is useful when associating the same <xref:Azure.Cosmos.CosmosClientOptions> with multiple containers. Consider the following alternative code, to register multiple containers under the same database connection:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.AddAzureCosmosDatabase("customers", configureClientOptions: options =>
+    {
+        options.SerializerOptions = new CosmosSerializationOptions()
+        {
+            PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
+        };
+    })
+    .AddKeyedContainer(name: "profiles");
+
+builder.AddAzureCosmosDatabase(connectionName: "orders")
+       .AddKeyedContainer(name: "details")
+       .AddKeyedContainer(name: "history");
+
+var app = builder.Build();
+
+app.MapGet("/api/customers", async (
+    [FromKeyedServices("profiles")] Container container) =>
+{
+    // Query data from container
+});
+
+app.MapGet("/api/orders", async (
+    [FromKeyedServices("details")] Container container,
+    [FromKeyedServices("history")] Container container) =>
+{
+    // Query data from container
+});
+
+app.Run();
+```
+
+The preceding example code demonstrates how to register two databases, `customers` and `orders`, each with their own containers. The `customers` database has a single container named `profiles`, while the `orders` database has two containers named `details` and `history`. Each container can be queried individually using its respective key.
+
 ### Configuration
 
 The .NET Aspire Azure Cosmos DB integration provides multiple options to configure the connection based on the requirements and conventions of your project.
@@ -201,6 +339,7 @@ The .NET Aspire Azure Cosmos DB integration currently doesn't support metrics by
 ## See also
 
 - [Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db)
+- [Sample repository showing parent-child relationships](https://github.com/captainsafia/aspire-child-resources)
 - [.NET Aspire Cosmos DB Entity Framework Core integration](azure-cosmos-db-entity-framework-integration.md)
 - [.NET Aspire integrations overview](../fundamentals/integrations-overview.md)
 - [.NET Aspire Azure integrations overview](../azure/integrations-overview.md)

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

@@ -5,6 +5,8 @@ ms.topic: include
 The .NET Aspire [Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db/) hosting integration models the various Cosmos DB resources as the following types:
 
 - <xref:Aspire.Hosting.AzureCosmosDBResource>: Represents an Azure Cosmos DB resource.
+- <xref:Aspire.Hosting.Azure.AzureCosmosDBContainerResource>: Represents an Azure Cosmos DB container resource.
+- <xref:Aspire.Hosting.Azure.AzureCosmosDBDatabaseResource>: Represents an Azure Cosmos DB database resource.
 - <xref:Aspire.Hosting.Azure.AzureCosmosDBEmulatorResource>: Represents an Azure Cosmos DB emulator resource.
 
 To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package in the [app host](xref:dotnet/aspire/app-host) project.
@@ -103,13 +105,15 @@ The dependent resource can access the injected connection string by calling the
 
 ### Add Azure Cosmos DB database and container resources
 
+.NET Aspire models parent child relationships between Azure Cosmos DB resources. For example, an Azure Cosmos DB account (<xref:Aspire.Hosting.AzureCosmosDBResource>) can have multiple databases (<xref:Aspire.Hosting.Azure.AzureCosmosDBDatabaseResource>), and each database can have multiple containers (<xref:Aspire.Hosting.Azure.AzureCosmosDBContainerResource>). When you add a database or container resource, you do so on a parent resource.
+
 To add an Azure Cosmos DB database resource, call the <xref:Aspire.Hosting.AzureCosmosExtensions.AddCosmosDatabase*> method on an `IResourceBuilder<AzureCosmosDBResource>` instance:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
 var cosmos = builder.AddAzureCosmosDB("cosmos-db");
-cosmos.AddCosmosDatabase("db");
+var db = cosmos.AddCosmosDatabase("db");
 
 // After adding all resources, run the app...
 ```
@@ -125,14 +129,44 @@ var builder = DistributedApplication.CreateBuilder(args);
 
 var cosmos = builder.AddAzureCosmosDB("cosmos-db");
 var db = cosmos.AddCosmosDatabase("db");
-db.AddContainer("entries", "/id");
+var container = db.AddContainer("entries", "/id");
 
 // After adding all resources, run the app...
 ```
 
-The container is created in the database that's represented by the `AzureCosmosDBDatabaseResource` that you added earlier.
+The container is created in the database that's represented by the `AzureCosmosDBDatabaseResource` that you added earlier. For more information, see [Databases, containers, and items in Azure Cosmos DB](/azure/cosmos-db/resource-model).
+
+#### Parent child resource relationship example
+
+To better understand the parent-child relationship between Azure Cosmos DB resources, consider the following example, which demonstrates adding an Azure Cosmos DB resource along with a database and container:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var cosmos = builder.AddAzureCosmosDB("cosmos");
+
+var customers = cosmos.AddCosmosDatabase("customers");
+var profiles = customers.AddContainer("profiles", "/id");
+
+var orders = cosmos.AddCosmosDatabase("orders");
+var details = orders.AddContainer("details", "/id");
+var history = orders.AddContainer("history", "/id");
+
+builder.AddProject<Projects.Api>("api")
+       .WithReference(profiles)
+       .WithReference(details)
+       .WithReference(history);
+
+builder.Build().Run();
+```
+
+The preceding code adds an Azure Cosmos DB resource named `cosmos` with two databases: `customers` and `orders`. The `customers` database has a single container named `profiles`, while the `orders` database has two containers: `details` and `history`. The partition key for each container is `/id`.
+
+The following diagram illustrates the parent child relationship between the Azure Cosmos DB resources:
+
+:::image type="content" source="media/cosmos-resource-relationships-thumb.png" alt-text="A diagram depicting Azure Cosmos DB resource parent child relationships." lightbox="media/cosmos-resource-relationships.png":::
 
-For more information, see [Databases, containers, and items in Azure Cosmos DB](/azure/cosmos-db/resource-model).
+When your app host code expresses parent-child relationships, the client can deep-link to these resources by name. For example, the `customers` database can be referenced by name in the client project, registering a <xref:Microsoft.Azure.Cosmos.Database> instance that connects to the `customers` database. The same applies to named containers, for example, the `details` container can be referenced by name in the client project, registering a <xref:Microsoft.Azure.Cosmos.Container> instance that connects to the `details` container.
 
 ### Add Azure Cosmos DB emulator resource