Addressing several issues (#1702)

IEvangelist · web-flow · commit 3ff1e3b5fa0f · 2024-09-27T12:01:06.000-05:00
* Fixes #1152 * Added note about MacOS and Safari. Fixes #1519 * Fixes #1108 * Remove code fence * Correct branding per Scott Addie
diff --git a/docs/azureai/azureai-openai-integration.md b/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)
diff --git a/docs/fundamentals/app-host-overview.md b/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)
diff --git a/docs/fundamentals/external-parameters.md b/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":::
 
diff --git a/docs/get-started/aspire-overview.md b/docs/get-started/aspire-overview.md
@@ -1,7 +1,7 @@
 ---
 title: .NET Aspire overview
 description: Learn about .NET Aspire, an application stack designed to improve the experience of building cloud-native applications.
-ms.date: 08/12/2024
+ms.date: 09/27/2024
 ---
 
 # .NET Aspire overview
@@ -27,7 +27,7 @@ A _distributed application_ is one that uses computational _resources_ across mu
 
 - [**Orchestration**](#orchestration): .NET Aspire provides features for running and connecting multi-project applications and their dependencies for [local development environments](../fundamentals/networking-overview.md).
 - [**Integrations**](#net-aspire-integrations): .NET Aspire integrations are NuGet packages for commonly used services, such as Redis or Postgres, with standardized interfaces ensuring they connect consistently and seamlessly with your app.
-- [**Tooling**](#project-templates-and-tooling): .NET Aspire comes with project templates and tooling experiences for Visual Studio, Visual Studio Code, and the [dotnet CLI](/dotnet/core/tools/) to help you create and interact with .NET Aspire projects.
+- [**Tooling**](#project-templates-and-tooling): .NET Aspire comes with project templates and tooling experiences for Visual Studio, Visual Studio Code, and the [.NET CLI](/dotnet/core/tools/) to help you create and interact with .NET Aspire projects.
 
 ## Orchestration
 
@@ -36,7 +36,7 @@ In .NET Aspire, orchestration primarily focuses on enhancing the _local developm
 .NET Aspire orchestration assists with the following concerns:
 
 - **App composition**: Specify the .NET projects, containers, executables, and cloud resources that make up the application.
-- **Service discovery and connection string management**: The app host manages injecting the right connection strings or network configurations and service discovery information to simplify the developer experience.
+- **Service discovery and connection string management**: The app host manages to inject the right connection strings or network configurations and service discovery information to simplify the developer experience.
 
 For example, using .NET Aspire, the following code creates a local Redis container resource and configures the appropriate connection string in the `"frontend"` project with only two helper method calls:
 
@@ -55,11 +55,14 @@ builder.AddProject<Projects.MyFrontend>("frontend")
 
 For more information, see [.NET Aspire orchestration overview](../fundamentals/app-host-overview.md).
 
+> [!IMPORTANT]
+> The call to `AddRedis` creates a new Redis container in your local dev environment. If you'd rather use an existing Redis instance, you can use the `AddConnectionString` method to reference an existing connection string. For more information, see [Reference existing resources](../fundamentals/app-host-overview.md#reference-existing-resources).
+
 ## .NET Aspire integrations
 
 [.NET Aspire integrations](../fundamentals/integrations-overview.md) are NuGet packages designed to simplify connections to popular services and platforms, such as Redis or PostgreSQL. .NET Aspire integrations handle many cloud-native concerns for you through standardized configuration patterns, such as adding health checks and telemetry. Integrations are two-fold, in that one side represents the service you're connecting to, and the other side represents the client or consumer of that service. In other words, for each hosting package there's a corresponding client package that handles the service connection.
 
-Each integration is designed to work with .NET Aspire orchestration, and their configurations are injected automatically by simply referencing named resources. In other words, if _Example.ServiceFoo_ references _Example.ServiceBar_, _Example.ServiceFoo_ inherits the integration's required configurations to allow them to communicate with each other automatically.
+Each integration is designed to work with .NET Aspire orchestration, and their configurations are injected automatically by [referencing named resources](../fundamentals/app-host-overview.md#reference-resources). In other words, if _Example.ServiceFoo_ references _Example.ServiceBar_, _Example.ServiceFoo_ inherits the integration's required configurations to allow them to communicate with each other automatically.
 
 For example, consider the following code using the .NET Aspire Service Bus integration:
 
@@ -71,24 +74,13 @@ The <xref:Microsoft.Extensions.Hosting.AspireServiceBusExtensions.AddAzureServic
 
 - Registers a <xref:Azure.Messaging.ServiceBus.ServiceBusClient> as a singleton in the DI container for connecting to Azure Service Bus.
 - Applies `ServiceBusClient` configurations either inline through code or through configuration.
-- Enables corresponding health checks, logging and telemetry specific to the Azure Service Bus usage.
+- Enables corresponding health checks, logging, and telemetry specific to the Azure Service Bus usage.
 
 A full list of available integrations is detailed on the [.NET Aspire integrations](../fundamentals/integrations-overview.md) overview page.
 
 ## Project templates and tooling
 
-.NET Aspire projects follow a standardized structure designed around the default .NET Aspire project templates. Most .NET Aspire projects have at least three projects:
-
-- **MyFirstAspireApp**: Your starter app, which could be any common .NET project such as a Blazor UI or Minimal API. You can add more projects to your app as it expands and manage orchestration between them using the **.AppHost** and **.ServiceDefaults** project.
-- **MyFirstAspireApp.AppHost**: The **.AppHost** project is used to manage the high level orchestration concerns of the app. Orchestration involves putting together various parts of your app, like APIs, service containers, and executables, and setting up how they find and communicate with each other.
-- **MyFirstAspireApp.ServiceDefaults**: The **.ServiceDefaults** project contains default .NET Aspire project configurations that can be extended and customized as needed. These configurations include concerns such as setting up health checks, OpenTelemetry settings, and more.
-
-There are currently two .NET Aspire starter templates available to help you get started with this structure:
-
-- **.NET Aspire Application**: A basic starter template that only includes the **AspireSample.AppHost** and **AspireSample.ServiceDefaults** projects. This template is designed to only provide the essentials for you to build off of.
-- **.NET Aspire Starter Application**: This template includes the **AspireSample.AppHost** and **AspireSample.ServiceDefaults** projects, but also includes boilerplate UI and API projects. These projects are pre-configured with service discovery and other basic examples of common .NET Aspire functionality.
-
-For more information, see [.NET Aspire setup and tooling](../fundamentals/setup-tooling.md).
+.NET Aspire provides a set of project templates and tooling experiences for Visual Studio, Visual Studio Code, and the [.NET CLI](/dotnet/core/tools/). These templates are designed to help you create and interact with .NET Aspire projects. The templates are opinionated and come with a set of defaults that help you get started quickly. They include boilerplate code and configurations that are common to cloud-native apps, such as telemetry, health checks, and service discovery. For more information, see [.NET Aspire project templates](../fundamentals/setup-tooling.md#net-aspire-project-templates).
 
 .NET Aspire templates also include boilerplate extension methods that handle common service configurations for you:
 
diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md
diff --git a/docs/toc.yml b/docs/toc.yml
