✅ Merge main into live

docs/azureai/azureai-openai-integration.md

@@ -1,22 +1,22 @@
 ---
-title: .NET Aspire Azure AI OpenAI integration
-description: Learn how to use the .NET Aspire Azure AI OpenAI integration.
+title: .NET Aspire Azure OpenAI integration
+description: Learn how to use the .NET Aspire Azure OpenAI integration.
 ms.topic: how-to
-ms.date: 08/12/2024
+ms.date: 09/27/2024
 ---
 
-# .NET Aspire Azure AI OpenAI integration
+# .NET Aspire Azure OpenAI integration
 
-In this article, you learn how to use the .NET Aspire Azure AI OpenAI client. The `Aspire.Azure.AI.OpenAI` library is used to register an `OpenAIClient` in the dependency injection (DI) container for consuming Azure AI OpenAI or OpenAI functionality. It enables corresponding logging and telemetry.
+In this article, you learn how to use the .NET Aspire Azure OpenAI client. The `Aspire.Azure.AI.OpenAI` library is used to register an `OpenAIClient` in the dependency injection (DI) container for consuming Azure OpenAI or OpenAI functionality. It enables corresponding logging and telemetry.
 
 For more information on using the `OpenAIClient`, see [Quickstart: Get started generating text using Azure OpenAI Service](/azure/ai-services/openai/quickstart?tabs=command-line%2Cpython&pivots=programming-language-csharp).
 
 ## Get started
 
 - Azure subscription: [create one for free](https://azure.microsoft.com/free/).
-- Azure AI OpenAI or OpenAI account: [create an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource).
+- Azure OpenAI or OpenAI account: [create an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource).
 
-To get started with the .NET Aspire Azure AI OpenAI integration, install the [Aspire.Azure.AI.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.OpenAI) NuGet package in the client-consuming project, i.e., the project for the application that uses the Azure AI OpenAI client.
+To get started with the .NET Aspire Azure OpenAI integration, install the [Aspire.Azure.AI.OpenAI](https://www.nuget.org/packages/Aspire.Azure.AI.OpenAI) NuGet package in the client-consuming project, i.e., the project for the application that uses the Azure OpenAI client.
 
 ### [.NET CLI](#tab/dotnet-cli)
 
@@ -54,7 +54,7 @@ public class ExampleService(OpenAIClient client)
 
 ## App host usage
 
-To add Azure AI hosting support to your <xref:Aspire.Hosting.IDistributedApplicationBuilder>, install the [Aspire.Hosting.Azure.CognitiveServices](https://www.nuget.org/packages/Aspire.Hosting.Azure.CognitiveServices) NuGet package in the [app host](xref:aspire/app-host) project.
+To add Azure hosting support to your <xref:Aspire.Hosting.IDistributedApplicationBuilder>, install the [Aspire.Hosting.Azure.CognitiveServices](https://www.nuget.org/packages/Aspire.Hosting.Azure.CognitiveServices) NuGet package in the [app host](xref:aspire/app-host) project.
 
 ### [.NET CLI](#tab/dotnet-cli)
 
@@ -71,7 +71,7 @@ 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>:
+In your app host project, register an Azure OpenAI resource using the following methods, such as <xref:Aspire.Hosting.AzureOpenAIExtensions.AddAzureOpenAI%2A>:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
@@ -92,7 +92,7 @@ builder.AddAzureAIOpenAI("openAiConnectionName");
 
 ## Configuration
 
-The .NET Aspire Azure AI OpenAI integration provides multiple options to configure the connection based on the requirements and conventions of your project.
+The .NET Aspire Azure OpenAI integration provides multiple options to configure the connection based on the requirements and conventions of your project.
 
 ### Use a connection string
 
@@ -106,7 +106,7 @@ The connection string is retrieved from the `ConnectionStrings` configuration se
 
 #### Account endpoint
 
-The recommended approach is to use an `Endpoint`, which works with the `AzureOpenAISettings.Credential` property to establish a connection. If no credential is configured, the <xref:Azure.Identity.DefaultAzureCredential> is used.
+The recommended approach is to use an **Endpoint**, which works with the `AzureOpenAISettings.Credential` property to establish a connection. If no credential is configured, the <xref:Azure.Identity.DefaultAzureCredential> is used.
 
 ```json
 {
@@ -116,6 +116,8 @@ The recommended approach is to use an `Endpoint`, which works with the `AzureOpe
 }
 ```
 
+For more information, see [Use Azure OpenAI without keys](/azure/developer/ai/keyless-connections).
+
 #### Connection string
 
 Alternatively, a custom connection string can be used.
@@ -132,7 +134,7 @@ In order to connect to the non-Azure OpenAI service, drop the `Endpoint` propert
 
 ### Use configuration providers
 
-The .NET Aspire Azure AI OpenAI integration supports <xref:Microsoft.Extensions.Configuration>. It loads the `AzureOpenAISettings` from configuration by using the `Aspire:Azure:AI:OpenAI` key. Example _:::no-loc text="appsettings.json":::_ that configures some of the options:
+The .NET Aspire Azure OpenAI integration supports <xref:Microsoft.Extensions.Configuration>. It loads the `AzureOpenAISettings` from configuration by using the `Aspire:Azure:AI:OpenAI` key. Example _:::no-loc text="appsettings.json":::_ that configures some of the options:
 
 ```json
 {
@@ -171,14 +173,14 @@ builder.AddAzureAIOpenAI(
 
 ### Logging
 
-The .NET Aspire Azure AI OpenAI integration uses the following log categories:
+The .NET Aspire Azure OpenAI integration uses the following log categories:
 
 - `Azure`
 - `Azure.Core`
 - `Azure.Identity`
 
 ## See also
 
-- [Azure AI OpenAI docs](/azure/ai-services/openai/overview)
+- [Azure OpenAI docs](/azure/ai-services/openai/overview)
 - [.NET Aspire integrations](../fundamentals/integrations-overview.md)
 - [.NET Aspire GitHub repo](https://github.com/dotnet/aspire)

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

@@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac
 In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the <xref:Microsoft.Extensions.Hosting.AspireMicrosoftAzureCosmosExtensions.AddAzureCosmosClient%2A> extension to register a <xref:Microsoft.Azure.Cosmos.CosmosClient?displayProperty=fullName> for use via the dependency injection container.
 
 ```csharp
-builder.AddAzureCosmosClient("cosmosdb");
+builder.AddAzureCosmosClient("cosmosConnectionName");
 ```
 
 You can then retrieve the `CosmosClient` instance using dependency injection. For example, to retrieve the client from a service:
@@ -51,7 +51,7 @@ For more information on using the <xref:Microsoft.Azure.Cosmos.CosmosClient>, se
 
 ## App host usage
 
-To add Azure Cosmos DB hosting support to your <xref:Aspire.Hosting.IDistributedApplicationBuilder>, install the [Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package in the [app host](xref:aspire/app-host) project.
+To add Azure Cosmos DB hosting support to your <xref:Aspire.Hosting.IDistributedApplicationBuilder>, install the [Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package in the [app host](xref:aspire/app-host) project. This is helpful if you want Aspire to provision a new Azure Cosmos DB account for you, or if you want to use the Azure Cosmos DB emulator. If you want to use an Azure Cosmos DB account that is already provisioned, there's no need to add it to the app host project.
 
 ### [.NET CLI](#tab/dotnet-cli)
 
@@ -73,8 +73,8 @@ In your app host project, register the .NET Aspire Azure Cosmos DB integration a
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
-var cosmos = builder.AddAzureCosmosDB("cosmos");
-var cosmosdb = cosmos.AddDatabase("cosmosdb");
+var cosmos = builder.AddAzureCosmosDB("myNewCosmosAccountName");
+var cosmosdb = cosmos.AddDatabase("myCosmosDatabaseName");
 
 var exampleProject = builder.AddProject<Projects.ExampleProject>()
                             .WithReference(cosmosdb);
@@ -89,14 +89,14 @@ var exampleProject = builder.AddProject<Projects.ExampleProject>()
 
 ## Configuration
 
-The .NET Aspire Azure Cosmos DB library provides multiple options to configure the Azure Cosmos DB connection based on the requirements and conventions of your project.
+The .NET Aspire Azure Cosmos DB library provides multiple options to configure the `CosmosClient` connection based on the requirements and conventions of your project.
 
 ### Use a connection string
 
-When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddAzureCosmosDB`:
+When using a connection string from the `ConnectionStrings` configuration section, you can provide the name of the connection string when calling `builder.AddAzureCosmosClient`:
 
 ```csharp
-builder.AddAzureCosmosDB("cosmosConnectionName");
+builder.AddAzureCosmosClient("cosmosConnectionName");
 ```
 
 And then the connection string will be retrieved from the `ConnectionStrings` configuration section:
@@ -152,15 +152,15 @@ The .NET Aspire Azure Cosmos DB integration supports <xref:Microsoft.Extensions.
 You can also pass the `Action<MicrosoftAzureCosmosSettings >` delegate to set up some or all the options inline, for example to disable tracing from code:
 
 ```csharp
-builder.AddAzureCosmosDB(
+builder.AddAzureCosmosClient(
     "cosmosConnectionName",
     static settings => settings.DisableTracing = true);
 ```
 
-You can also set up the <xref:Microsoft.Azure.Cosmos.CosmosClientOptions?displayProperty=fullName> using the optional `Action<CosmosClientOptions> configureClientOptions` parameter of the `AddAzureCosmosDB` method. For example to set the <xref:Microsoft.Azure.Cosmos.CosmosClientOptions.ApplicationName?displayProperty=nameWithType> user-agent header suffix for all requests issues by this client:
+You can also set up the <xref:Microsoft.Azure.Cosmos.CosmosClientOptions?displayProperty=fullName> using the optional `Action<CosmosClientOptions> configureClientOptions` parameter of the `AddAzureCosmosClient` method. For example to set the <xref:Microsoft.Azure.Cosmos.CosmosClientOptions.ApplicationName?displayProperty=nameWithType> user-agent header suffix for all requests issues by this client:
 
 ```csharp
-builder.AddAzureCosmosDB(
+builder.AddAzureCosmosClient(
     "cosmosConnectionName",
     configureClientOptions:
         clientOptions => clientOptions.ApplicationName = "myapp");
@@ -178,12 +178,36 @@ The .NET Aspire Azure Cosmos DB integration uses the following log categories:
 
 - Azure-Cosmos-Operation-Request-Diagnostics
 
+In addition to getting Azure Cosmos DB request diagnostics for failed requests, you can configure latency thresholds to determine which successful Azure Cosmos DB request diagnostics will be logged. The default values are 100 ms for point operations and 500 ms for non point operations.
+
+```csharp
+builder.AddAzureCosmosClient(
+    "cosmosConnectionName",
+    configureClientOptions:
+        clientOptions => {
+            clientOptions.CosmosClientTelemetryOptions = new()
+            {
+                CosmosThresholdOptions = new()
+                {
+                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
+                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
+                }
+            };
+        });
+```
+
 ### Tracing
 
 The .NET Aspire Azure Cosmos DB integration will emit the following tracing activities using OpenTelemetry:
 
 - Azure.Cosmos.Operation
 
+Azure Cosmos DB tracing is currently in preview, so you must set the experimental switch to ensure traces are emitted. [Learn more about tracing in Azure Cosmos DB.](/azure/cosmos-db/nosql/sdk-observability#trace-attributes)
+
+```csharp
+AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
+```
+
 ### Metrics
 
 The .NET Aspire Azure Cosmos DB integration currently doesn't support metrics by default due to limitations with the Azure SDK.

docs/fundamentals/app-host-overview.md

@@ -243,6 +243,28 @@ private static IResourceBuilder<RabbitMQServerResource> RunWithStableNodeName(
 }
 ```
 
+The execution context is often used to conditionally add resources or connection strings that point to existing resources. Consider the following example that demonstrates conditionally adding Redis or a connection string based on the execution context:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var redis = builder.ExecutionContext.IsRunMode
+    ? builder.AddRedis("redis")
+    : builder.AddConnectionString("redis");
+
+builder.AddProject<Projects.WebApplication>("api")
+       .WithReference(redis);
+
+builder.Build().Run();
+```
+
+In the preceding code:
+
+- If the app host is running in "run" mode, a Redis container resource is added.
+- If the app host is running in "publish" mode, a connection string is added.
+
+This logic can easily be inverted to connect to an existing Redis resource when you're running locally, and create a new Redis resource when you're publishing.
+
 ## See also
 
 - [.NET Aspire integrations overview](integrations-overview.md)

docs/fundamentals/external-parameters.md

@@ -2,7 +2,7 @@
 title: External parameters
 description: Learn how to express parameters such as secrets, connection strings, and other configuration values that might vary between environments.
 ms.topic: how-to
-ms.date: 08/20/2024
+ms.date: 09/27/2024
 ---
 
 # External parameters
@@ -11,7 +11,7 @@ Environments provide context for the application to run in. Parameters express t
 
 ## Parameter values
 
-Parameter values are read from the `Parameters` section of the app host's configuration and are used to provide values to the app while running locally. When deploying the app, the value will be asked for the parameter value.
+Parameter values are read from the `Parameters` section of the app host's configuration and are used to provide values to the app while running locally. When you publish the app, if the value isn't available you're prompted to provide it.
 
 Consider the following app host _:::no-loc text="Program.cs":::_ example file:
 
@@ -55,7 +55,7 @@ Parameters are represented in the manifest as a new primitive called `parameter.
 
 ## Secret values
 
-Parameters can be used to model secrets. When a parameter is marked as a secret, this is a hint to the manifest that the value should be treated as a secret. When deploying, the value will be prompted for and stored in a secure location. When running locally, the value will be read from the `Parameters` section of the app host configuration.
+Parameters can be used to model secrets. When a parameter is marked as a secret, it serves as a hint to the manifest that the value should be treated as a secret. When you publish the app, the value is prompted for and stored in a secure location. When you run the app locally, the value is read from the `Parameters` section of the app host configuration.
 
 Consider the following app host _:::no-loc text="Program.cs":::_ example file:
 
@@ -102,7 +102,7 @@ The manifest representation is as follows:
 
 ## Connection string values
 
-Parameters can be used to model connection strings. When deploying, the value will be prompted for and stored in a secure location. When running locally, the value will be read from the `ConnectionStrings` section of the app host configuration.
+Parameters can be used to model connection strings. When you publish the app, the value is prompted for and stored in a secure location. When you run the app locally, the value is read from the `ConnectionStrings` section of the app host configuration.
 
 > [!NOTE]
 > Connection strings are used to represent a wide range of connection information including database connections, message brokers, and other services. In .NET Aspire nomenclature, the term "connection string" is used to represent any kind of connection information.
@@ -114,7 +114,7 @@ var builder = DistributedApplication.CreateBuilder(args);
 
 var redis = builder.AddConnectionString("redis");
 
-builder.AddProject<Projects.WebApplication1>("api")
+builder.AddProject<Projects.WebApplication>("api")
        .WithReference(redis);
 
 builder.Build().Run();
@@ -151,7 +151,7 @@ The value for the `insertionRows` parameter is read from the `Parameters` sectio
 
 :::code language="json" source="snippets/params/Parameters.AppHost/appsettings.json":::
 
-The `Parameters_ApiService` project consumes the `insertionRows` parameter, consider the _:::no-loc text="Program.cs":::_ example file:
+The `Parameters_ApiService` project consumes the `insertionRows` parameter. Consider the _:::no-loc text="Program.cs":::_ example file:
 
 :::code source="snippets/params/Parameters.ApiService/Program.cs":::