Add missing code, and add flexible PostgreSQL (#1046)

* Ok, I got a little carried away, but these were missing. Also, fixes #428 * Added a few words about execution context * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Apply suggestions from code review --------- Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
dotnet · Jun 6, 2024 · 7cccb53 · 7cccb53
1 parent 7cb6c07
commit 7cccb53
Show file tree

Hide file tree

Showing 28 changed files with 176 additions and 81 deletions.
diff --git a/docs/azureai/azureai-openai-component.md b/docs/azureai/azureai-openai-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire Azure AI OpenAI component
 description: Learn how to use the .NET Aspire Azure AI OpenAI component.
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire Azure AI OpenAI component
@@ -74,12 +74,12 @@ dotnet add package Aspire.Hosting.Azure.CognitiveServices
 In your app host project, register an Azure AI OpenAI resource using the following methods, such as <xref:Aspire.Hosting.AzureOpenAIExtensions.AddAzureOpenAI%2A>:
 
 ```csharp
-// Service registration
+var builder = DistributedApplication.CreateBuilder(args);
+
 var openai = builder.ExecutionContext.IsPublishMode
  ? builder.AddAzureOpenAI("openAiConnectionName")
  : builder.AddConnectionString("openAiConnectionName");
 
-// Service consumption
 builder.AddProject<Projects.ExampleProject>()
  .WithReference(openai);
 ```

diff --git a/docs/azureai/azureai-search-document-component.md b/docs/azureai/azureai-search-document-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire Azure AI Search Documents component
 description: Learn how to use the .NET Aspire Azure AI Search Documents component.
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire Azure AI Search Documents component
@@ -95,6 +95,8 @@ dotnet add package Aspire.Hosting.Azure.CognitiveServices
 In the _:::no-loc text="Program.cs":::_ file of `AppHost`, add an Azure Search service and consume the connection using the following methods:
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var search = builder.ExecutionContext.IsPublishMode
  ? builder.AddAzureSearch("search")
  : builder.AddConnectionString("search");

diff --git a/docs/caching/stackexchange-redis-component.md b/docs/caching/stackexchange-redis-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire StackExchange Redis component
 description: This article describes the .NET Aspire StackExchange Redis component features and capabilities
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire StackExchange Redis component
@@ -52,10 +52,10 @@ public class ExampleService(IConnectionMultiplexer connectionMultiplexer)
 [!INCLUDE [redis-app-host](includes/redis-app-host.md)]
 
 ```csharp
-// Service registration
+var builder = DistributedApplication.CreateBuilder(args);
+
 var redis = builder.AddRedis("redis");
 
-// Service consumption
 builder.AddProject<Projects.ExampleProject>()
  .WithReference(redis)
 ```

diff --git a/docs/caching/stackexchange-redis-distributed-caching-component.md b/docs/caching/stackexchange-redis-distributed-caching-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire StackExchange Redis distributed caching component
 description: This article describes the .NET Aspire StackExchange Redis distributed caching component features and capabilities
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire StackExchange Redis distributed caching component
@@ -52,10 +52,10 @@ public class ExampleService(IDistributedCache cache)
 [!INCLUDE [redis-app-host](includes/redis-app-host.md)]
 
 ```csharp
-// Service registration
+var builder = DistributedApplication.CreateBuilder(args);
+
 var redis = builder.AddRedis("redis");
 
-// Service consumption
 builder.AddProject<Projects.ExampleProject>()
  .WithReference(redis)
 ```

diff --git a/docs/caching/stackexchange-redis-output-caching-component.md b/docs/caching/stackexchange-redis-output-caching-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire StackExchange Redis output caching Component
 description: This article describes the .NET Aspire StackExchange Redis output caching component features and capabilities
 ms.topic: how-to
-ms.date: 04/29/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire StackExchange Redis output caching component
@@ -59,10 +59,10 @@ For apps with controllers, apply the `[OutputCache]` attribute to the action met
 [!INCLUDE [redis-app-host](includes/redis-app-host.md)]
 
 ```csharp
-// Service registration
+var builder = DistributedApplication.CreateBuilder(args);
+
 var redis = builder.AddRedis("redis");
 
-// Service consumption
 var basket = builder.AddProject<Projects.ExampleProject>()
  .WithReference(redis)
 ```

diff --git a/docs/database/azure-cosmos-db-component.md b/docs/database/azure-cosmos-db-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire Azure Cosmos DB component
 description: This article describes the .NET Aspire Azure Cosmos DB component features and capabilities.
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire Azure Cosmos DB component
@@ -71,11 +71,11 @@ dotnet add package Aspire.Hosting.Azure.CosmosDB
 In your app host project, register the .NET Aspire Azure Cosmos DB component and consume the service using the following methods:
 
 ```csharp
-// Service registration
+var builder = DistributedApplication.CreateBuilder(args);
+
 var cosmos = builder.AddAzureCosmosDB("cosmos");
 var cosmosdb = cosmos.AddDatabase("cosmosdb");
 
-// Service consumption
 var exampleProject = builder.AddProject<Projects.ExampleProject>()
  .WithReference(cosmosdb);
 ```

diff --git a/docs/database/azure-cosmos-db-entity-framework-component.md b/docs/database/azure-cosmos-db-entity-framework-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire Microsoft Entity Framework Core Cosmos DB component
 description: This article describes the .NET Aspire Microsoft Entity Framework Core Cosmos DB component features and capabilities.
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire Microsoft Entity Framework Core Cosmos DB component
@@ -71,11 +71,11 @@ dotnet add package Aspire.Hosting.Azure.CosmosDB
 In your app host project, register the .NET Aspire Microsoft Entity Framework Core Cosmos DB component and consume the service using the following methods:
 
 ```csharp
-// Service registration
+var builder = DistributedApplication.CreateBuilder(args);
+
 var cosmos = builder.AddAzureCosmosDB("cosmos");
 var cosmosdb = cosmos.AddDatabase("cosmosdb");
 
-// Service consumption
 var exampleProject = builder.AddProject<Projects.ExampleProject>()
  .WithReference(cosmosdb);
 ```

diff --git a/docs/database/includes/postgresql-flexible-server.md b/docs/database/includes/postgresql-flexible-server.md
@@ -0,0 +1,34 @@
+### Azure app host usage
+
+To deploy your PostgreSQL resources to Azure, you need to install the appropriate .NET Aspire hosting package:
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Aspire.Hosting.Azure.PostgreSQL
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include="Aspire.Hosting.Azure.PostgreSQL"
+ Version="[SelectVersion]" />
+```
+
+---
+
+After you've installed this package, you specify that your PostgreSQL resources will be hosted in Azure by calling the <xref:Aspire.Hosting.AzurePostgresExtensions.PublishAsAzurePostgresFlexibleServer%2A> extension method in your app host project:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var postgres = builder.AddPostgres("postgres")
+ .PublishAsAzurePostgresFlexibleServer();
+
+var postgresdb = postgres.AddDatabase("postgresdb");
+
+var exampleProject = builder.AddProject<Projects.ExampleProject>()
+ .WithReference(postgresdb);
+```
+
+The preceding call to `PublishAsAzurePostgresFlexibleServer` configures Postgres Server resource to be deployed as Azure Postgres Flexible Server. For more information, see [Azure Postgres Flexible Server](/azure/postgresql/flexible-server/overview).
diff --git a/docs/database/mongodb-component.md b/docs/database/mongodb-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire MongoDB database component
 description: This article describes the .NET Aspire MongoDB database component.
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire MongoDB database component
@@ -79,6 +79,8 @@ dotnet add package Aspire.Hosting.MongoDB
 In your app host project, register the MongoDB database and consume the connection method and consume the service using the following methods:
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var mongo = builder.AddMongoDB("mongo");
 var mongodb = mongo.AddDatabase("mongodb");
 

diff --git a/docs/database/mysql-component.md b/docs/database/mysql-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire MySQL database component
 description: This article describes the .NET Aspire MySQL database component.
 ms.topic: how-to
-ms.date: 06/03/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire MySQL database component
@@ -62,6 +62,8 @@ After adding a `MySqlDataSource`, you can require the `MySqlDataSource` instance
 [!INCLUDE [mysql-app-host](includes/mysql-app-host.md)]
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var mysql = builder.AddMySql("mysql");
 var mysqldb = mysql.AddDatabase("mysqldb");
 

diff --git a/docs/database/mysql-entity-framework-component.md b/docs/database/mysql-entity-framework-component.md
@@ -1,7 +1,7 @@
 ---
 title: MySQL Entity Framework Component
 description: MySQL Entity Framework Component
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire Pomelo MySQL Entity Framework Component
@@ -61,6 +61,8 @@ builder.EnrichMySqlDbContext<MyDbContext>();
 [!INCLUDE [mysql-app-host](includes/mysql-app-host.md)]
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var mysql = builder.AddMySql("mysql");
 var mysqldb = mysql.AddDatabase("mysqldb");
 

diff --git a/docs/database/oracle-entity-framework-component.md b/docs/database/oracle-entity-framework-component.md
@@ -79,6 +79,8 @@ dotnet add package Aspire.Hosting.Oracle
 In your app host project, register an Oracle container and consume the connection using the following methods:
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var oracle = builder.AddOracle("oracle");
 var oracledb = oracle.AddDatabase("oracledb");
 

diff --git a/docs/database/postgresql-component.md b/docs/database/postgresql-component.md
@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire PostgreSQL component
 description: This article describes the .NET Aspire PostgreSQL component.
-ms.date: 06/03/2024
+ms.date: 06/05/2024
 ms.topic: how-to
 ---
 
@@ -51,6 +51,8 @@ public class ExampleService(NpgsqlDataSource dataSource)
 [!INCLUDE [postgresql-app-host](includes/postgresql-app-host.md)]
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var postgres = builder.AddPostgres("postgres");
 var postgresdb = postgres.AddDatabase("postgresdb");
 
@@ -60,6 +62,8 @@ var exampleProject = builder.AddProject<Projects.ExampleProject>()
 
 [!INCLUDE [postgresql-explicit-username-password](includes/postgresql-explicit-username-password.md)]
 
+[!INCLUDE [postgresql-flexible-server](includes/postgresql-flexible-server.md)]
+
 ## Configuration
 
 The .NET Aspire PostgreSQL component provides multiple configuration approaches and options to meet the requirements and conventions of your project.

diff --git a/docs/database/postgresql-entity-framework-component.md b/docs/database/postgresql-entity-framework-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire PostgreSQL Entity Framework Core component
 description: This article describes the .NET Aspire PostgreSQL Entity Framework Core component.
 ms.topic: how-to
-ms.date: 06/03/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire PostgreSQL Entity Framework Core component
@@ -65,6 +65,8 @@ public class ExampleService(YourDbContext context)
 [!INCLUDE [postgresql-app-host](includes/postgresql-app-host.md)]
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var postgres = builder.AddPostgres("postgres");
 var postgresdb = postgres.AddDatabase("postgresdb");
 
@@ -74,6 +76,8 @@ var myService = builder.AddProject<Projects.MyService>()
 
 [!INCLUDE [postgresql-explicit-username-password](includes/postgresql-explicit-username-password.md)]
 
+[!INCLUDE [postgresql-flexible-server](includes/postgresql-flexible-server.md)]
+
 ## Configuration
 
 The .NET Aspire PostgreSQL Entity Framework Core component provides multiple configuration approaches and options to meet the requirements and conventions of your project.

diff --git a/docs/database/qdrant-component.md b/docs/database/qdrant-component.md
@@ -69,6 +69,8 @@ dotnet add package Aspire.Hosting.Qdrant
 In your app host project, register a Qdrant server and consume the connection using the following methods:
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var qdrant = builder.AddQdrant("qdrant");
 
 var myService = builder.AddProject<Projects.MyService>()

diff --git a/docs/database/sql-server-component.md b/docs/database/sql-server-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire SQL Server component
 description: This article describes the .NET Aspire SQL Server component.
 ms.topic: how-to
-ms.date: 06/03/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire SQL Server component
@@ -64,6 +64,8 @@ After adding a `SqlConnection`, you can get the scoped [SqlConnection](/dotnet/a
 [!INCLUDE [sql-app-host](includes/sql-app-host.md)]
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var sql = builder.AddSqlServer("sql");
 var sqldb = sql.AddDatabase("sqldb");
 

diff --git a/docs/database/sql-server-entity-framework-component.md b/docs/database/sql-server-entity-framework-component.md
@@ -2,7 +2,7 @@
 title: .NET Aspire SqlServer Entity Framework Core component
 description: This article describes the .NET Aspire SQL Server Entity Framework Core component.
 ms.topic: how-to
-ms.date: 05/14/2024
+ms.date: 06/05/2024
 ---
 
 # .NET Aspire SqlServer Entity Framework Core component
@@ -61,6 +61,8 @@ public class ExampleService(YourDbContext client)
 [!INCLUDE [sql-app-host](includes/sql-app-host.md)]
 
 ```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
 var sql = builder.AddSqlServer("sql");
 var sqldb = sql.AddDatabase("sqldb");
 

diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md
@@ -256,6 +256,33 @@ Beyond the base resource types, <xref:Aspire.Hosting.ApplicationModel.ProjectRes
 
 For more information, see [GitHub: Aspire.Hosting.AWS library](https://github.com/dotnet/aspire/tree/main/src/Aspire.Hosting.AWS).
 
+## Execution context
+
+The <xref:Aspire.Hosting.IDistributedApplicationBuilder> exposes an execution context (<xref:Aspire.Hosting.DistributedApplicationExecutionContext>), which provides information about the current execution of the app host. This context can be used to evaluate whether or not the app host is executing as "run" mode, or as part of a publish operation. Consider the following:
+
+- <xref:Aspire.Hosting.DistributedApplicationExecutionContext.IsRunMode%2A>: Returns `true` if the current operation is running.
+- <xref:Aspire.Hosting.DistributedApplicationExecutionContext.IsPublishMode%2A>: Returns `true` if the current operation is publishing.
+
+This information can be useful when you want to conditionally execute code based on the current operation. Consider the following example that demonstrates using the `IsRunMode` property. In this case, an extension method is used to generate a stable node name for RabbitMQ for local development runs.
+
+```csharp
+private static IResourceBuilder<RabbitMQServerResource> RunWithStableNodeName(
+ this IResourceBuilder<RabbitMQServerResource> builder)
+{
+ if (builder.ApplicationBuilder.ExecutionContext.IsRunMode)
+ {
+ builder.WithEnvironment(context =>
+ {
+ // Set a stable node name so queue storage is consistent between sessions
+ var nodeName = $"{builder.Resource.Name}@localhost";
+ context.EnvironmentVariables["RABBITMQ_NODENAME"] = nodeName;
+ });
+ }
+
+ return builder;
+}
+```
+
 ## See also
 
 - [.NET Aspire components overview](components-overview.md)