README.md

Create a new project using the AI Web Chat template

⏱️ Estimated Time: 35-50 minutes

In this workshop

In this workshop, you'll create a new project using the AI Web Chat template in Visual Studio. You'll configure GitHub Models as the AI service provider, set up the connection string, and run and explore the application.

Create the project using Visual Studio

Create a new project using the AI Web Chat template as follows:

1. Open Visual Studio 2022

2. Click "Create a new project"

3. Search for and select "AI Chat Web App" template

   

4. Click "Next"

5. Configure your project:

   • Enter "GenAiLab" as the project name
   • Choose a location for your project
   • Make sure "Place solution and project in same directory" is checked
   • Click "Next"

   

6. Configure AI options:

   • Select "GitHub Models" for AI service provider
   • Select "Qdrant" for Vector store
   • Check the box for "Use keyless authentication for Azure services"
   • Check the box for "Use Aspire orchestration"
   • Click "Create"

   Alternative: Ollama Option: If you're using the Ollama development container (see Development Container Options), you can select "Ollama" as the AI service provider instead of "GitHub Models". This allows you to work with local AI models without requiring a GitHub account or internet connection.

   

7. Wait for Visual Studio to create the project and restore packages. When you see the Sign in popup, just close it.

Alternative: Create the project using the .NET CLI

If you prefer to use the command line, you can create the same project using the .NET CLI:

1. First, ensure you have the AI Chat Web App template installed:

   dotnet new install Microsoft.Extensions.AI.Templates

2. Navigate to the directory where you want to create your project:

   cd "C:\your\desired\path"

3. Create the project using the dotnet new command with the appropriate parameters:

   dotnet new aichatweb --name GenAiLab --Framework net9.0 --provider githubmodels --vector-store qdrant --aspire true

   This command creates a new AI Chat Web App with:

   • Project name: GenAiLab
   • Framework: .NET 9.0
   • AI service provider: GitHub Models
   • Vector store: Qdrant
   • .NET Aspire orchestration: enabled

   Alternative: Ollama Option: If you're using the Ollama development container, you can replace --provider githubmodels with --provider ollama to use local AI models instead.

4. Navigate into the project directory:

   cd GenAiLab

   Note for automation: The dotnet new aichatweb command creates a solution structure with multiple projects. If you need to move the generated files to a specific directory structure (like /src/start), you may need to reorganize the files after creation.

5. Open the project in your preferred editor:

   code .  # For Visual Studio Code
   # or
   start GenAiLab.sln  # For Visual Studio

Update NuGet packages

Due to recent updates in .NET Aspire 9.4 and dependency changes in AI packages, you need to update all NuGet packages in the solution to their latest versions (including prerelease packages) before running the application:

Using Visual Studio

1. In the Solution Explorer, right-click on the solution file (GenAiLab.sln) and select "Manage NuGet Packages for Solution..."

   

2. In the NuGet Package Manager, click on the "Updates" tab

3. Check the "Include prerelease" checkbox to include preview versions of AI packages

4. Click "Update All" to update all packages to their latest versions

   

5. Review and accept any license agreements that appear

6. Wait for all packages to be updated and restored

Using the .NET CLI

If you prefer to use the command line, you can update all packages using the dotnet outdated tool:

1. First, install the dotnet outdated global tool if you haven't already:

   dotnet tool install --global dotnet-outdated-tool

2. Navigate to the solution directory (if not already there):

   cd GenAiLab

3. Update all packages in the solution, including prerelease versions:

   dotnet outdated GenAiLab.sln --upgrade --pre-release Always

4. After the update completes, restore and build the solution to ensure everything is working:

   dotnet restore
   dotnet build

Set the GitHub Models connection string

For GitHub Models to work, you need to set up a connection string with a GitHub token:

Note: This step requires a GitHub account. If you don't have one yet, please follow the instructions in Part 1: Setup to create a GitHub account.

1. Create a GitHub token for accessing GitHub Models:

   • Go to https://github.com/settings/personal-access-tokens/new
   • Click "Generate new token" (fine-grained token)
   • Enter a name for the token, such as "AI Models Access"
   • Under Permissions, set Models to Access: Read-only
   • Click "Generate token" at the bottom of the page
   • Copy the generated token (you won't be able to see it again)

   Note: For additional guidance on configuring GitHub Models access, see the Microsoft documentation quickstart.

2. In the Solution Explorer, right-click on the GenAiLab.AppHost project and select "Manage User Secrets"

3. In the secrets.json file that opens, add the following connection string:

   {
      "ConnectionStrings:openai": "Endpoint=https://models.inference.ai.azure.com;Key=YOUR-API-KEY"
   }

   Replace YOUR-API-KEY with the GitHub token you created in step 1.

4. Save the secrets.json file.

Run the application

Now let's run the application and explore its features:

1. Make sure that Docker Desktop is running. This is required to run containerized resources like Qdrant.

2. Make sure the GenAiLab.AppHost project is set as the startup project.

3. Press F5 or click the "Start Debugging" button in Visual Studio.

   Note: When running the application for the first time, Visual Studio may display a prompt asking you to trust the IIS Developer certificate. This prompt sometimes appears beneath the browser window. If the aichatweb-app resource doesn't start, check for this certificate prompt and click "Yes" to accept it. The application won't run until you've accepted this certificate.

   

4. The .NET Aspire dashboard will open in your browser first, displaying all the services in your application.

5. Shortly after, the web application will launch in another browser tab.

If you run into issues running the Qdrant container, stop debugging and start it again.

Review the services in the .NET Aspire dashboard

Explore the .NET Aspire dashboard to understand the architecture of your application:

1. You'll see several services running:

   • aichatweb-app: The main web application
   • vectordb: The Qdrant vector database service

2. Click on each service to see more details:

   • Explore the endpoints tab to see service URLs
   • Check the logs tab to monitor service activity
   • View the environment variables to understand service configuration

3. Notice how .NET Aspire orchestrates all these services together, making it easy to develop distributed applications.

Test the application

Let's test the AI functionality of the application:

1. Launch the aiwebchat-app by clicking on the hyperlinked URL listed in the Endpoints column in the .NET Aspire dashboard. You should see the web app launch in a seprate tab with a chat interface.

   

2. Type a message like "What PDF documents do you have information about?" and press Enter.

3. The AI will respond with information about the PDF documents that have been ingested.

4. Ask another question like "Tell me about survival kits" and observe how the AI uses information from the ingested documents to provide a response.

5. Notice how the chat history is maintained and displayed on the left sidebar.

What You've Learned

• How to create a new project using the AI Web Chat template in Visual Studio
• How to update NuGet packages in a solution to get the latest AI and Aspire components
• How to configure GitHub Models as the AI service provider
• How to set up the connection string for AI services
• How to use .NET Aspire to orchestrate multiple services
• How to interact with an AI-powered chat application

Troubleshooting

Common Issues and Solutions

Issue: Certificate Trust Prompt

Problem: Application doesn't start, appears to hang during launch.

Solution: Look for the IIS Developer certificate trust prompt (may be hidden behind the browser). Click "Yes" to accept the certificate.

Alternative Solution: If the certificate dialog has been dismissed or doesn't show, you can manually trust the development certificate using the .NET CLI:

dotnet dev-certs https --trust

This command will regenerate and trust the ASP.NET Core HTTPS development certificate. For more information, see Trust the ASP.NET Core HTTPS development certificate.

Issue: Build Errors After Template Creation

Problem: Build fails with static asset conflicts or package restore issues.

Solution:

dotnet clean
dotnet restore
dotnet build

Issue: GitHub Models Connection Fails

Problem: Authentication errors or "unauthorized" messages when testing chat.

Solution:

1. Verify your GitHub token has the correct permissions
2. Check that the token is correctly placed in secrets.json
3. Ensure the connection string format is correct: "Endpoint=https://models.inference.ai.azure.com;Key=YOUR_TOKEN"

Issue: Template Not Found

Problem: Can't find the AI Web Chat template in Visual Studio.

Solution:

1. Verify the template is installed: dotnet new list | Select-String aichatweb
2. If not found, install it: dotnet new install Microsoft.Extensions.AI.Templates
3. Restart Visual Studio after template installation

🎯 Next Steps

Excellent work! Your AI application is running successfully. Time to dive deeper into the code!

Continue to → Part 3: Explore the Template Code

In Part 3, you'll learn how to:

• 🏗️ Understand the application architecture and structure
• 🔍 Explore the AI integration patterns
• 📊 Learn about vector database usage
• 🧩 Discover how components work together