fix quickstart (#46003)

Author: gewarren

docs/ai/index.yml

@@ -21,20 +21,20 @@ landingContent:
   # Card
   - title: Get started
     linkLists:
-      - linkListType: get-started
+      - linkListType: overview
         links:
           - text: Develop .NET apps with AI features
             url: overview.md
-          - text: Connect to and prompt an AI model
-            url: quickstarts/prompt-model.md
           - text: Microsoft.Extensions.AI libraries
             url: microsoft-extensions-ai.md
+      - linkListType: get-started
+        links:
+          - text: Connect to and prompt an AI model
+            url: quickstarts/prompt-model.md
           - text: Build an Azure AI chat app
-            url: quickstarts/get-started-openai.md
-          - text: Summarize text using an Azure OpenAI chat app
-            url: quickstarts/quickstart-openai-summarize-text.md
+            url: quickstarts/build-chat-app.md
           - text: Generate images using Azure AI
-            url: quickstarts/quickstart-openai-generate-images.md
+            url: quickstarts/generate-images.md
 
   # Card
   - title: Essential concepts

docs/ai/quickstarts/evaluate-ai-response.md

@@ -11,7 +11,9 @@ ms.custom: devx-track-dotnet, devx-track-dotnet-ai
 In this quickstart, you create an MSTest app to evaluate the chat response of an OpenAI model. The test app uses the [Microsoft.Extensions.AI.Evaluation](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation) libraries.
 
 > [!NOTE]
-> This quickstart demonstrates the simplest usage of the evaluation API. Notably, it doesn't demonstrate use of the [response caching](../conceptual/evaluation-libraries.md#cached-responses) and [reporting](../conceptual/evaluation-libraries.md#reporting) functionality, which are important if you're authoring unit tests that run as part of an "offline" evaluation pipeline. The scenario shown in this quickstart is suitable in use cases such as "online" evaluation of AI responses within production code and logging scores to telemetry, where caching and reporting aren't relevant. For a tutorial that demonstrates the caching and reporting functionality, see [Tutorial: Evaluate a model's response with response caching and reporting](../tutorials/evaluate-with-reporting.md)
+>
+> - The `Microsoft.Extensions.AI.Evaluation` library is currently in Preview.
+> - This quickstart demonstrates the simplest usage of the evaluation API. Notably, it doesn't demonstrate use of the [response caching](../conceptual/evaluation-libraries.md#cached-responses) and [reporting](../conceptual/evaluation-libraries.md#reporting) functionality, which are important if you're authoring unit tests that run as part of an "offline" evaluation pipeline. The scenario shown in this quickstart is suitable in use cases such as "online" evaluation of AI responses within production code and logging scores to telemetry, where caching and reporting aren't relevant. For a tutorial that demonstrates the caching and reporting functionality, see [Tutorial: Evaluate a model's response with response caching and reporting](../tutorials/evaluate-with-reporting.md)
 
 ## Prerequisites
 

docs/ai/quickstarts/generate-images.md

@@ -98,7 +98,7 @@ Complete the following steps to create a .NET console app to connect to an AI mo
 
 ## Add the app code
 
-1. In the **Program.cs** file, add the following code to connect and authenticate to the AI model.
+1. In the `Program.cs` file, add the following code to connect and authenticate to the AI model.
 
     :::zone target="docs" pivot="azure-openai"
 
@@ -117,12 +117,12 @@ Complete the following steps to create a .NET console app to connect to an AI mo
 
     The preceding code:
 
-    - Reads essential configuration values from the project user secrets to connect to the AI model
-    - Creates an `ImageClient` to connect to the AI model
-    - Sends a prompt to the model that describes the desired image
-    - Prints the URL of the generated image to the console output
+    - Reads essential configuration values from the project user secrets to connect to the AI model.
+    - Creates an `OpenAI.Images.ImageClient` to connect to the AI model.
+    - Sends a prompt to the model that describes the desired image.
+    - Prints the URL of the generated image to the console output.
 
-1. Use the `dotnet run` command to run the app:
+1. Run the app:
 
     ```dotnetcli
     dotnet run

docs/ai/quickstarts/includes/clone-sample-repo.md

@@ -5,7 +5,7 @@ ms.date: 07/03/2024
 ms.topic: include
 ---
 
-## Clone the sample repository
+## (Optional) Clone the sample repository
 
 You can create your own app using the steps in the sections ahead, or you can clone the GitHub repository that contains the completed sample apps for all of the quickstarts. If you plan to use Azure OpenAI, the sample repo is also structured as an Azure Developer CLI template that can provision an Azure OpenAI resource for you.
 

docs/ai/quickstarts/includes/create-ai-service.md

@@ -1,12 +1,8 @@
 ## Create the AI service
 
-# [Azure Developer CLI](#tab/azd)
-
-[!INCLUDE [deploy-azd](deploy-azd.md)]
-
-# [Azure CLI](#tab/azure-cli)
+# [Azure Portal or Azure CLI](#tab/azure-cli)
 
-1. To provision an Azure OpenAI service and model using the Azure CLI, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=cli) article.
+1. To provision an Azure OpenAI service and model, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource) article.
 
 1. From a terminal or command prompt, navigate to the root of your project directory.
 
@@ -18,18 +14,8 @@
     dotnet user-secrets set AZURE_OPENAI_GPT_NAME <your-azure-openai-model-name>
     ```
 
-# [Azure Portal](#tab/azure-portal)
-
-1. To provision an Azure OpenAI service and model using the Azure portal, complete the steps in the [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource?pivots=web-portal) article.
-
-1. From a terminal or command prompt, navigate to the root of your project directory.
-
-1. Run the following commands to configure your Azure OpenAI endpoint and model name for the sample app:
+# [Azure Developer CLI](#tab/azd)
 
-    ```bash
-    dotnet user-secrets init
-    dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-openai-key>
-    dotnet user-secrets set AZURE_OPENAI_GPT_NAME <your-azure-openai-model-name>
-    ```
+[!INCLUDE [deploy-azd](deploy-azd.md)]
 
 ---

docs/ai/quickstarts/prompt-model.md

@@ -1,7 +1,7 @@
 ---
-title: Quickstart - Summarize text using an AI chat app with .NET
+title: Quickstart - Connect to and prompt an AI model with .NET
 description: Create a simple chat app using Microsoft.Extensions.AI to summarize a text.
-ms.date: 04/09/2025
+ms.date: 05/02/2025
 ms.topic: quickstart
 ms.custom: devx-track-dotnet, devx-track-dotnet-ai
 author: fboucher
@@ -10,12 +10,12 @@ zone_pivot_groups: openai-library
 # CustomerIntent: As a .NET developer new to OpenAI, I want deploy and use sample code to interact to learn from the sample code to summarize text.
 ---
 
-# Connect to and prompt an AI model using .NET
+# Connect to and prompt an AI model
 
 In this quickstart, you learn how to create a .NET console chat app to connect to and prompt an OpenAI or Azure OpenAI model. The app uses the <xref:Microsoft.Extensions.AI> library so you can write code using AI abstractions rather than a specific SDK. AI abstractions enable you to change the underlying AI model with minimal code changes.
 
 > [!NOTE]
-> The [`Microsoft.Extensions.AI`](https://www.nuget.org/packages/Microsoft.Extensions.AI/) library is currently in Preview.
+> The <xref:Microsoft.Extensions.AI> library is currently in Preview.
 
 :::zone target="docs" pivot="openai"
 
@@ -54,9 +54,9 @@ Complete the following steps to create a .NET console app to connect to an AI mo
     :::zone target="docs" pivot="azure-openai"
 
     ```bash
-    dotnet add package Azure.Identity
     dotnet add package Azure.AI.OpenAI
-    dotnet add package Microsoft.Extensions.AI.OpenAI
+    dotnet add package Azure.Identity
+    dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
     dotnet add package Microsoft.Extensions.Configuration
     dotnet add package Microsoft.Extensions.Configuration.UserSecrets
     ```
@@ -67,18 +67,14 @@ Complete the following steps to create a .NET console app to connect to an AI mo
 
     ```bash
     dotnet add package OpenAI
-    dotnet add package Microsoft.Extensions.AI.OpenAI
+    dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
     dotnet add package Microsoft.Extensions.Configuration
     dotnet add package Microsoft.Extensions.Configuration.UserSecrets
     ```
 
     :::zone-end
 
-1. Open the app in Visual Studio code or your editor of choice
-
-    ```bash
-    code .
-    ```
+1. Open the app in Visual Studio Code or your editor of choice.
 
 :::zone target="docs" pivot="azure-openai"
 
@@ -94,50 +90,52 @@ Complete the following steps to create a .NET console app to connect to an AI mo
 
 1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
 
-    ```bash
-    dotnet user-secrets init
-    dotnet user-secrets set OpenAIKey <your-openai-key>
-    dotnet user-secrets set ModelName <your-openai-model-name>
-    ```
+   ```bash
+   dotnet user-secrets init
+   dotnet user-secrets set OpenAIKey <your-openai-key>
+   dotnet user-secrets set ModelName <your-openai-model-name>
+   ```
 
 :::zone-end
 
 ## Add the app code
 
 The app uses the [`Microsoft.Extensions.AI`](https://www.nuget.org/packages/Microsoft.Extensions.AI/) package to send and receive requests to the AI model.
 
-1. In the **Program.cs** file, add the following code to connect and authenticate to the AI model.
+1. Copy the [benefits.md](https://raw.githubusercontent.com/dotnet/docs/refs/heads/main/docs/ai/quickstarts/snippets/prompt-completion/azure-openai/benefits.md) file to your project directory. Configure the project to copy this file to the output directory. If you're using Visual Studio, right-click on the file in Solution Explorer, select **Properties**, and then set **Copy to Output Directory** to **Copy if newer**.
 
-    :::zone target="docs" pivot="azure-openai"
+1. In the `Program.cs` file, add the following code to connect and authenticate to the AI model.
 
-    :::code language="csharp" source="snippets/prompt-completion/azure-openai/program.cs" range="1-12":::
+   :::zone target="docs" pivot="azure-openai"
 
-    > [!NOTE]
-    > <xref:Azure.Identity.DefaultAzureCredential> searches for authentication credentials from your local tooling. If you aren't using the `azd` template to provision the Azure OpenAI resource, you'll need to assign the `Azure AI Developer` role to the account you used to sign-in to Visual Studio or the Azure CLI. For more information, see [Authenticate to Azure AI services with .NET](../azure-ai-services-authentication.md).
+   :::code language="csharp" source="snippets/prompt-completion/azure-openai/program.cs" id="CreateChatClient":::
 
-    :::zone-end
+   > [!NOTE]
+   > <xref:Azure.Identity.DefaultAzureCredential> searches for authentication credentials from your local tooling. If you aren't using the `azd` template to provision the Azure OpenAI resource, you'll need to assign the `Azure AI Developer` role to the account you used to sign-in to Visual Studio or the Azure CLI. For more information, see [Authenticate to Azure AI services with .NET](../azure-ai-services-authentication.md).
 
-    :::zone target="docs" pivot="openai"
+   :::zone-end
 
-    :::code language="csharp" source="snippets/prompt-completion/openai/program.cs" range="1-11":::
+   :::zone target="docs" pivot="openai"
 
-    :::zone-end
+   :::code language="csharp" source="snippets/prompt-completion/openai/program.cs" id="CreateChatClient":::
 
-1. Read the *benefits.md* file content and use it to create a prompt for the model. The prompt instructs the model to summarize the file text content.
+   :::zone-end
 
-    :::code language="csharp" source="snippets/prompt-completion/openai/program.cs" range="13-19":::
+1. Add code to read the `benefits.md` file content and then create a prompt for the model. The prompt instructs the model to summarize the file's text content in 20 words or less.
 
-1. Call the `InvokePromptAsync` function to send the prompt to the model to generate a response.
+   :::code language="csharp" source="snippets/prompt-completion/openai/program.cs" id="CreatePrompt":::
 
-    :::code language="csharp" source="snippets/prompt-completion/openai/program.cs" range="21-23":::
+1. Call the `GetResponseAsync` method to send the prompt to the model to generate a response.
 
-1. Use the `dotnet run` command to run the app:
+   :::code language="csharp" source="snippets/prompt-completion/openai/program.cs" id="GetResponse":::
 
-    ```dotnetcli
-    dotnet run
-    ```
+1. Run the app:
+
+   ```dotnetcli
+   dotnet run
+   ```
 
-    The app prints out the completion response from the AI model. Customize the text content of the `benefits.md` file or the length of the summary to see the differences in the responses.
+   The app prints out the completion response from the AI model. Customize the text content of the `benefits.md` file or the length of the summary to see the differences in the responses.
 
 :::zone target="docs" pivot="azure-openai"
 

docs/ai/quickstarts/snippets/image-generation/azure-openai/benefits.md

@@ -1,25 +1,33 @@
-using Microsoft.Extensions.Configuration;
+// <SnippetCreateChatClient>
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.AI;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 
-var config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
+var config = new ConfigurationBuilder()
+    .AddUserSecrets<Program>()
+    .Build();
 string endpoint = config["AZURE_OPENAI_ENDPOINT"];
 string deployment = config["AZURE_OPENAI_GPT_NAME"];
 
 IChatClient client =
     new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
         .GetChatClient(deployment)
         .AsIChatClient();
+// </SnippetCreateChatClient>
 
-// Create and print out the prompt
+// <SnippetCreatePrompt>
+string text = File.ReadAllText("benefits.md");
 string prompt = $"""
-    summarize the the following text in 20 words or less:
-    {File.ReadAllText("benefits.md")}
+    Summarize the the following text in 20 words or less:
+    {text}
     """;
+// </SnippetCreatePrompt>
 
-Console.WriteLine($"user >>> {prompt}");
-
-// Submit the prompt and print out the response
-ChatResponse response = await client.GetResponseAsync(prompt, new ChatOptions { MaxOutputTokens = 400 });
-Console.WriteLine($"assistant >>> {response}");
+// <SnippetGetResponse>
+// Submit the prompt and print out the response.
+ChatResponse response = await client.GetResponseAsync(
+    prompt,
+    new ChatOptions { MaxOutputTokens = 400 });
+Console.WriteLine(response);
+// </SnippetGetResponse>

docs/ai/quickstarts/snippets/image-generation/openai/benefits.md

@@ -1,23 +1,30 @@
-using Microsoft.Extensions.AI;
+// <SnippetCreateChatClient>
+using Microsoft.Extensions.AI;
 using Microsoft.Extensions.Configuration;
 using OpenAI;
 
-IConfigurationRoot config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
+IConfigurationRoot config = new ConfigurationBuilder()
+    .AddUserSecrets<Program>()
+    .Build();
 string? model = config["ModelName"];
 string? key = config["OpenAIKey"];
 
-// Create the IChatClient
 IChatClient client =
     new OpenAIClient(key).GetChatClient(model).AsIChatClient();
+// </SnippetCreateChatClient>
 
-// Create and print out the prompt
+// <SnippetCreatePrompt>
+string text = File.ReadAllText("benefits.md");
 string prompt = $"""
-    summarize the the following text in 20 words or less:
-    {File.ReadAllText("benefits.md")}
+    Summarize the the following text in 20 words or less:
+    {text}
     """;
+// </SnippetCreatePrompt>
 
-Console.WriteLine($"user >>> {prompt}");
-
-// Submit the prompt and print out the response
-ChatResponse response = await client.GetResponseAsync(prompt, new ChatOptions { MaxOutputTokens = 400 });
-Console.WriteLine($"assistant >>> {response}");
+// <SnippetGetResponse>
+// Submit the prompt and print out the response.
+ChatResponse response = await client.GetResponseAsync(
+    prompt,
+    new ChatOptions { MaxOutputTokens = 400 });
+Console.WriteLine(response);
+// </SnippetGetResponse>