---
title: Agents
description: Introduction to agents
author: luisquintanilla
ms.author: luquinta
ms.date: 12/10/2025
ms.topic: concept-article
---

# Agents

This article introduces the core concepts behind agents, why they matter, and how they fit into workflows, setting you up to get started building agents in .NET.

## What are agents?

**Agents are systems that accomplish objectives.**


Agents become more capable when equipped with the following:

- **Reasoning and decision-making**: Powered by LLMs, search algorithms, or planning and decision-making systems.
- **Tool usage**: Access to Model Context Protocol (MCP) servers, code execution, and external APIs.
- **Context awareness**: Informed by chat history, threads, vector stores, enterprise data, or knowledge graphs.

These capabilities allow agents to operate more autonomously, adaptively, and intelligently.

## What are workflows?

As objectives grow in complexity, they need to be broken down into manageable steps. That's where workflows come in.

**Workflows define the sequence of steps required to achieve an objective.**

Imagine you're launching a new feature on your business website. If it's a simple update, you might go from idea to production in a few hours. But for more complex initiatives, the process might include:

- Requirement gathering
- Design and architecture
- Implementation
- Testing
- Deployment

A few important observations:

- Each step might contain subtasks.
- Different specialists might own different phases.
- Progress isn’t always linear. Bugs found during testing might send you back to implementation.
- Success depends on planning, orchestration, and communication across stakeholders.

### Agents + workflows = agentic workflows

Workflows don't require agents, but agents can supercharge them.

When agents are equipped with reasoning, tools, and context, they can optimize workflows.

This is the foundation of multi-agent systems, where agents collaborate within workflows to achieve complex goals.

### Workflow orchestration

Agentic workflows can be orchestrated in a variety of ways. The following are a few of the most common:

- [Sequential](#sequential)
- [Concurrent](#concurrent)
- [Handoff](#handoff)
- [Group chat](#group-chat)
- [Magentic](#magentic)

#### Sequential

Agents process tasks one after another, passing results forward.


#### Concurrent

Agents work in parallel, each handling different aspects of the task.


#### Handoff

Responsibility shifts from one agent to another based on conditions or outcomes.


#### Group chat

Agents collaborate in a shared conversation, exchanging insights in real-time.


#### Magentic

A lead agent directs other agents.

## How can I get started building agents in .NET?

The building blocks in <xref:Microsoft.Extensions.AI> and <xref:Microsoft.Extensions.VectorData> supply the foundations for agents by providing modular components for AI models, tools, and data.

These components serve as the foundation for Microsoft Agent Framework. For more information, see [Microsoft Agent Framework](/agent-framework/overview/agent-framework-overview).

---
title: "AI tool calling"
description: "Understand how tool calling lets you integrate external tools with AI models across providers using Microsoft.Extensions.AI."
ms.topic: concept-article
ms.date: 03/03/2026
ai-usage: ai-assisted
---

# AI tool calling

*Tool calling* is an AI model capability that lets you describe available tools to an AI model so the model can request that your application invoke them. Tools can be .NET methods, calls to external APIs, interactions with [Model Context Protocol (MCP)](../get-started-mcp.md) servers, or any other executable operation. Instead of directly executing those tools, the model returns a structured output describing which tools to call and with what arguments. Your application invokes those tools and sends the results back to the model, enabling it to build a more accurate and grounded response.

<xref:Microsoft.Extensions.AI> (MEAI) provides provider-agnostic abstractions for tool calling that work across AI services, including Azure OpenAI, OpenAI, Ollama, and others. You write your tool-calling logic once, and it works regardless of which underlying model or provider you use.

## Why use tool calling

Tool calling simplifies how you connect external tools to AI models. You describe each tool to the model as part of the conversation. The model then decides which tools to invoke based on the user's question. After your application invokes the requested tools and returns the results, the model uses those results to construct a more complete and accurate response.

Common use cases for tool calling include:

- Answering questions by calling external APIs. For example, checking the weather forecast, or sending email.
- Retrieving information from internal data stores. For example, aggregating sales data to answer, "What are my best-selling products?"
- Producing structured data from unstructured text. For example, constructing a user profile from chat history.

## Call AI functions in MEAI

The general flow for calling AI functions with <xref:Microsoft.Extensions.AI.IChatClient> is:

1. Define .NET methods as functions and configure them on a <xref:Microsoft.Extensions.AI.ChatOptions> instance.
1. Send the user's message to the model. The model decides which functions, if any, to call. It returns a structured response that lists the function calls and their arguments.

   > [!NOTE]
   > Models might hallucinate arguments that weren't described in your function definitions.

1. Parse the model's response and invoke the requested functions with the specified arguments.
1. Send another request that includes the function results as new messages in the conversation history.
1. The model responds with more function call requests or a final answer to the user's question. Continue invoking requested functions until the model provides a final response.

MEAI's <xref:Microsoft.Extensions.AI.FunctionInvokingChatClient> handles steps 3 through 5 automatically, so you don't need to manage the invocation loop yourself.

## Key types

MEAI provides the following types to support function calling:

- <xref:Microsoft.Extensions.AI.AIFunction>: Represents a function that can be described to an AI model, and invoked. This is the core abstraction for a function in MEAI.
- <xref:Microsoft.Extensions.AI.AIFunctionFactory>: Provides factory methods for creating `AIFunction` instances from .NET methods. Use `AIFunctionFactory` to wrap existing methods as functions without writing boilerplate description or argument-parsing code.
- <xref:Microsoft.Extensions.AI.FunctionInvokingChatClient>: Wraps any `IChatClient` and adds automatic function-invocation capabilities. When the model requests a function call, `FunctionInvokingChatClient` invokes the corresponding `AIFunction`, collects the result, and continues the conversation—all transparently.

## Parallel function calling

Some models support *parallel function calling*, where the model requests multiple function invocations in a single response. Your application invokes each function and returns all results together in one follow-up message. Parallel function calling reduces the number of round trips to the model, which lowers latency and API usage. `FunctionInvokingChatClient` supports parallel function calling automatically.

## Cross-provider support

One of the key benefits of using MEAI for function calling is provider independence. The `AIFunction`, `AIFunctionFactory`, and `FunctionInvokingChatClient` types work with any `IChatClient` implementation, including:

- Azure OpenAI
- OpenAI
- Ollama
- Any other provider that implements `IChatClient`

Because function calling support varies across models and providers, check your provider's documentation to confirm whether a specific model supports function calling or parallel function calling.

## Token considerations

Tool descriptions are included in the request sent to the model and count against the model's token limit. This means tool definitions contribute to both token consumption and request cost.

If your request approaches the model's token limit, consider these adjustments:

- Reduce the number of tools registered for the conversation.
- Shorten the method names and descriptions used to generate tool definitions.
- Limit tool registration to only the tools relevant for a given conversation context.

## Related content

- [Invoke .NET functions using an AI model](../quickstarts/use-function-calling.md)
- [Use the IChatClient interface](../ichatclient.md)
- [Understanding tokens](understanding-tokens.md)
- [Prompt engineering](prompt-engineering-dotnet.md)

---
title: "Chain of thought prompting - .NET"
description: "Learn how chain of thought prompting can simplify prompt engineering."
ms.topic: concept-article #Don't change.
ms.date: 03/04/2026
ai-usage: ai-assisted

#customer intent: As a .NET developer, I want to understand what chain-of-thought prompting is and how it can help me save time and get better completions out of prompt engineering.

---

# Chain of thought prompting

GPT model performance and response quality benefit from *prompt engineering*, which is the practice of providing instructions and examples to a model to prime or refine its output. As they process instructions, models make more reasoning errors when they try to answer right away rather than taking time to work out an answer. Help the model reason its way toward correct answers more reliably by asking the model to include its chain of thought—that is, the steps it took to follow an instruction, along with the results of each step.

*Chain of thought prompting* is the practice of prompting a model to perform a task step-by-step and to present each step and its result in order in the output. This simplifies prompt engineering by offloading some execution planning to the model, and makes it easier to connect any problem to a specific step so you know where to focus further efforts.

It's generally simpler to instruct the model to include its chain of thought, but you can also use examples to show the model how to break down tasks. The following sections show both ways.

## Use chain of thought prompting in instructions

To use an instruction for chain of thought prompting, include a directive that tells the model to perform the task step-by-step and to output the result of each step.

```csharp
prompt= """Instructions: Compare the pros and cons of EVs and petroleum-fueled vehicles.
Break the task into steps, and output the result of each step as you perform it."""; 
```

## Use chain of thought prompting in examples

Use examples to indicate the steps for chain of thought prompting, which the model interprets to mean it should also output step results. Steps can include formatting cues.

```csharp
prompt= """
        Instructions: Compare the pros and cons of EVs and petroleum-fueled vehicles.

        Differences between EVs and petroleum-fueled vehicles:
        - 

        Differences ordered according to overall impact, highest-impact first: 
        1. 
        
        Summary of vehicle type differences as pros and cons:
        Pros of EVs
        1.
        Pros of petroleum-fueled vehicles
        1. 
        """;
```

## Related content

- [Prompt engineering techniques](/azure/ai-services/openai/concepts/advanced-prompt-engineering)

---
title: Data ingestion
description: Introduction to data ingestion
author: luisquintanilla
ms.author: luquinta
ms.date: 12/02/2025
ms.topic: concept-article
ai-usage: ai-assisted
---

# Data ingestion

Data ingestion is the process of collecting, reading, and preparing data from different sources such as files, databases, APIs, or cloud services so it can be used in downstream applications. In practice, this process follows the Extract-Transform-Load (ETL) workflow:

- **Extract** data from its original source, whether that is a PDF, Word document, audio file, or web API.
- **Transform** the data by cleaning, chunking, enriching, or converting formats.
- **Load** the data into a destination like a database, vector store, or AI model for retrieval and analysis.

For AI and machine learning scenarios, especially Retrieval-Augmented Generation (RAG), data ingestion is not just about converting data from one format to another. It is about making data usable for intelligent applications. This means representing documents in a way that preserves their structure and meaning, splitting them into manageable chunks, enriching them with metadata or embeddings, and storing them so they can be retrieved quickly and accurately.

## Why data ingestion matters for AI applications

Imagine you're building a RAG-powered chatbot to help employees find information across your company's vast collection of documents. These documents might include PDFs, Word files, PowerPoint presentations, and web pages scattered across different systems.

Your chatbot needs to understand and search through thousands of documents to provide accurate, contextual answers. But raw documents aren't suitable for AI systems. You need to transform them into a format that preserves meaning while making them searchable and retrievable.

This is where data ingestion becomes critical. You need to extract text from different file formats, break large documents into smaller chunks that fit within AI model limits, enrich the content with metadata, generate embeddings for semantic search, and store everything in a way that enables fast retrieval. Each step requires careful consideration of how to preserve the original meaning and context.

## The Microsoft.Extensions.DataIngestion library

The [📦 Microsoft.Extensions.DataIngestion package](https://www.nuget.org/packages/Microsoft.Extensions.DataIngestion) provides foundational .NET building blocks for data ingestion. It enables developers to read, process, and prepare documents for AI and machine learning workflows, especially Retrieval-Augmented Generation (RAG) scenarios.

With these building blocks, you can create robust, flexible, and intelligent data ingestion pipelines tailored for your application needs:

- **Unified document representation:** Represent any file type (for example, PDF, Image, or Microsoft Word) in a consistent format that works well with large language models.
- **Flexible data ingestion:** Read documents from both cloud services and local sources using multiple built-in readers, making it easy to bring in data from wherever it lives.
- **Built-in AI enhancements:** Automatically enrich content with summaries, sentiment analysis, keyword extraction, and classification, preparing your data for intelligent workflows.
- **Customizable chunking strategies:** Split documents into chunks using token-based, section-based, or semantic-aware approaches, so you can optimize for your retrieval and analysis needs.
- **Production-ready storage:** Store processed chunks in popular vector databases and document stores, with support for embedding generation, making your pipelines ready for real-world scenarios.
- **End-to-end pipeline composition:** Chain together readers, processors, chunkers, and writers with the <xref:Microsoft.Extensions.DataIngestion.IngestionPipeline`1> API, reducing boilerplate and making it easy to build, customize, and extend complete workflows.
- **Performance and scalability:** Designed for scalable data processing, these components can handle large volumes of data efficiently, making them suitable for enterprise-grade applications.

All of these components are open and extensible by design. You can add custom logic and new connectors, and extend the system to support emerging AI scenarios. By standardizing how documents are represented, processed, and stored, .NET developers can build reliable, scalable, and maintainable data pipelines without "reinventing the wheel" for every project.

### Built on stable foundations


These data ingestion building blocks are built on top of proven and extensible components in the .NET ecosystem, ensuring reliability, interoperability, and seamless integration with existing AI workflows:

- **Microsoft.ML.Tokenizers:** Tokenizers provide the foundation for chunking documents based on tokens. This enables precise splitting of content, which is essential for preparing data for large language models and optimizing retrieval strategies.
- **Microsoft.Extensions.AI:** This set of libraries powers enrichment transformations using large language models. It enables features like summarization, sentiment analysis, keyword extraction, and embedding generation, making it easy to enhance your data with intelligent insights.
- **Microsoft.Extensions.VectorData:** This set of libraries offers a consistent interface for storing processed chunks in a wide variety of vector stores, including Qdrant, Azure SQL, CosmosDB, MongoDB, ElasticSearch, and many more. This ensures your data pipelines are ready for production and can scale across different storage backends.

In addition to familiar patterns and tools, these abstractions build on already extensible components. Plug-in capability and interoperability are paramount, so as the rest of the .NET AI ecosystem grows, the capabilities of the data ingestion components grow as well. This approach empowers developers to easily integrate new connectors, enrichments, and storage options, keeping their pipelines future-ready and adaptable to evolving AI scenarios.

## Data ingestion building blocks

The [Microsoft.Extensions.DataIngestion](https://www.nuget.org/packages/Microsoft.Extensions.DataIngestion) library is built around several key components that work together to create a complete data processing pipeline. This section explores each component and how they fit together.

### Documents and document readers

At the foundation of the library is the <xref:Microsoft.Extensions.DataIngestion.IngestionDocument> type, which provides a unified way to represent any file format without losing important information. `IngestionDocument` is Markdown-centric because large language models work best with Markdown formatting.

The <xref:Microsoft.Extensions.DataIngestion.IngestionDocumentReader> abstraction handles loading documents from various sources, whether local files or streams. A few readers are available:

- **[MarkItDown](https://www.nuget.org/packages/Microsoft.Extensions.DataIngestion.MarkItDown)**
- **[Markdig](https://www.nuget.org/packages/Microsoft.Extensions.DataIngestion.Markdig/)**

More readers (including **LlamaParse** and **Azure Document Intelligence**) will be added in the future.

This design means you can work with documents from different sources using the same consistent API, making your code more maintainable and flexible.

### Document processing

Document processors apply transformations at the document level to enhance and prepare content. The library provides the <xref:Microsoft.Extensions.DataIngestion.ImageAlternativeTextEnricher> class as a built-in processor that uses large language models to generate descriptive alternative text for images within documents.

### Chunks and chunking strategies

Once you have a document loaded, you typically need to break it down into smaller pieces called chunks. Chunks represent subsections of a document that can be efficiently processed, stored, and retrieved by AI systems. This chunking process is essential for retrieval-augmented generation scenarios where you need to find the most relevant pieces of information quickly.

The library provides several chunking strategies to fit different use cases:

- **Header-based chunking** to split on headers.
- **Section-based chunking** to split on sections (for example, pages).
- **Semantic-aware chunking** to preserve complete thoughts.

These chunking strategies build on the Microsoft.ML.Tokenizers library to intelligently split text into appropriately sized pieces that work well with large language models. The right chunking strategy depends on your document types and how you plan to retrieve information.

```csharp
Tokenizer tokenizer = TiktokenTokenizer.CreateForModel("gpt-5");
IngestionChunkerOptions options = new(tokenizer)
{
    MaxTokensPerChunk = 2000,
    OverlapTokens = 0
};
IngestionChunker<string> chunker = new HeaderChunker(options);
```

### Chunk processing and enrichment

After documents are split into chunks, you can apply processors to enhance and enrich the content. Chunk processors work on individual pieces and can perform:

- **Content enrichment** including automatic summaries (`SummaryEnricher`), sentiment analysis (`SentimentEnricher`), and keyword extraction (`KeywordEnricher`).
- **Classification** for automated content categorization based on predefined categories (`ClassificationEnricher`).

These processors use [Microsoft.Extensions.AI.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.AI.Abstractions) to leverage large language models for intelligent content transformation, making your chunks more useful for downstream AI applications.

### Document writer and storage

<xref:Microsoft.Extensions.DataIngestion.IngestionChunkWriter`1> stores processed chunks into a data store for later retrieval. Using Microsoft.Extensions.AI and [Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions), the library provides the <xref:Microsoft.Extensions.DataIngestion.VectorStoreWriter`1> class that supports storing chunks in any vector store supported by Microsoft.Extensions.VectorData.

Vector stores include popular options like [Qdrant](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Qdrant), [SQL Server](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.SqlServer), [CosmosDB](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.CosmosNoSQL), [MongoDB](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.MongoDB), [ElasticSearch](https://www.nuget.org/packages/Elastic.SemanticKernel.Connectors.Elasticsearch), and many more. The writer can also automatically generate embeddings for your chunks using Microsoft.Extensions.AI, readying them for semantic search and retrieval scenarios.

```csharp
OpenAIClient openAIClient = new(
    new ApiKeyCredential(Environment.GetEnvironmentVariable("GITHUB_TOKEN")!),
    new OpenAIClientOptions { Endpoint = new Uri("https://models.github.ai/inference") });

IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator =
    openAIClient.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator();

using SqliteVectorStore vectorStore = new(
    "Data Source=vectors.db;Pooling=false",
    new()
    {
        EmbeddingGenerator = embeddingGenerator
    });

// The writer requires the embedding dimension count to be specified.
// For OpenAI's `text-embedding-3-small`, the dimension count is 1536.
using VectorStoreWriter<string> writer = new(vectorStore, dimensionCount: 1536);
```

### Document processing pipeline

The <xref:Microsoft.Extensions.DataIngestion.IngestionPipeline`1> API allows you to chain together the various data ingestion components into a complete workflow. You can combine:

- **Readers** to load documents from various sources.
- **Processors** to transform and enrich document content.
- **Chunkers** to break documents into manageable pieces.
- **Writers** to store the final results in your chosen data store.

This pipeline approach reduces boilerplate code and makes it easy to build, test, and maintain complex data ingestion workflows.

```csharp
using IngestionPipeline<string> pipeline = new(reader, chunker, writer, loggerFactory: loggerFactory)
{
    DocumentProcessors = { imageAlternativeTextEnricher },
    ChunkProcessors = { summaryEnricher }
};

await foreach (var result in pipeline.ProcessAsync(new DirectoryInfo("."), searchPattern: "*.md"))
{
    Console.WriteLine($"Completed processing '{result.DocumentId}'. Succeeded: '{result.Succeeded}'.");
}
```

A single document ingestion failure shouldn't fail the whole pipeline. That's why <xref:Microsoft.Extensions.DataIngestion.IngestionPipeline`1.ProcessAsync*?displayProperty=nameWithType> implements partial success by returning `IAsyncEnumerable<IngestionResult>`. The caller is responsible for handling any failures (for example, by retrying failed documents or stopping on first error).

---
title: "How Embeddings Extend Your AI Model's Reach"
description: "Learn how embeddings extend the limits and capabilities of AI models in .NET."
ms.topic: concept-article #Don't change.
ms.date: 03/04/2026
ai-usage: ai-assisted

#customer intent: As a .NET developer, I want to understand how embeddings extend LLM limits and capabilities in .NET so that I have more semantic context and better outcomes for my AI apps.

---
# Embeddings in .NET

Embeddings are the way LLMs capture semantic meaning. They're numeric representations of non-numeric data that an LLM can use to determine relationships between concepts. Use embeddings to help an AI model understand the meaning of inputs so that it can perform comparisons and transformations, such as summarizing text or creating images from text descriptions. LLMs can use embeddings immediately, and you can store embeddings in vector databases to provide semantic memory for LLMs as needed.

## Use cases for embeddings

### Use your own data to improve completion relevance

Use your own databases to generate embeddings for your data and integrate it with an LLM to make it available for completions. This use of embeddings is an important component of [retrieval-augmented generation](rag.md).

### Increase the amount of text you can fit in a prompt

Use embeddings to increase the amount of context you can fit in a prompt without increasing the number of tokens required.

For example, suppose you want to include 500 pages of text in a prompt. The number of tokens for that much raw text exceeds the input token limit, making it impossible to directly include in a prompt. You can use embeddings to summarize and break down large amounts of that text into pieces that are small enough to fit in one input, and then assess the similarity of each piece to the entire raw text. Then you can choose a piece that best preserves the semantic meaning of the raw text and use it in your prompt without hitting the token limit.

### Perform text classification, summarization, or translation

Use embeddings to help a model understand the meaning and context of text, and then classify, summarize, or translate that text. For example, you can use embeddings to help models classify texts as positive or negative, spam or not spam, or news or opinion.

### Generate and transcribe audio

Use audio embeddings to process audio files or inputs in your app.

For example, [Azure Speech in Foundry Tools](/azure/ai-services/speech-service/) supports a range of audio embeddings, including [speech to text](/azure/ai-services/speech-service/speech-to-text) and [text to speech](/azure/ai-services/speech-service/text-to-speech). You can process audio in real-time or in batches.

### Turn text into images or images into text

Semantic image processing requires image embeddings, which most LLMs can't generate. Use an image-embedding model such as [ViT](https://huggingface.co/docs/transformers/main/en/model_doc/vit) to create vector embeddings for images. Then you can use those embeddings with an image generation model to create or modify images using text or vice versa. For example, you can [use the DALL·E model to generate images](/azure/ai-services/openai/dall-e-quickstart?tabs=dalle3%2Ccommand-line&pivots=programming-language-csharp) such as logos, faces, animals, and landscapes.

### Generate or document code

Use embeddings to help a model create code from text or vice versa, by converting different code or text expressions into a common representation. For example, you can use embeddings to help a model generate or document code in C# or Python.

## Choose an embedding model

You generate embeddings for your raw data by using an AI embedding model, which can encode non-numeric data into a vector (a long array of numbers). The model can also decode an embedding into non-numeric data that has the same or similar meaning as the original, raw data. OpenAI's `text-embedding-3-small` and `text-embedding-3-large` are the currently recommended embedding models, replacing the older `text-embedding-ada-002`. For more examples, see the list of [Embedding models available on Azure OpenAI](/azure/ai-services/openai/concepts/models#embeddings).

### Store and process embeddings in a vector database

After you generate embeddings, you need a way to store them so you can later retrieve them with calls to an LLM. Vector databases are designed to store and process vectors, so they're a natural home for embeddings. Different vector databases offer different processing capabilities. Choose one based on your raw data and your goals. For information about your options, see [Vector databases for .NET + AI](vector-databases.md).

### Using embeddings in your LLM solution

When building LLM-based applications, you can use Agent Framework to integrate embedding models and vector stores, so you can quickly pull in text data, and generate and store embeddings. This lets you use a vector database solution to store and retrieve semantic memories.

## Related content

- [How GenAI and LLMs work](how-genai-and-llms-work.md)
- [Retrieval-augmented generation](rag.md)
- [Training: Develop an AI agent with Microsoft Agent Framework](/training/modules/develop-ai-agent-with-semantic-kernel/)

---
title: "How Generative AI and LLMs work"
description: "Understand how Generative AI and large language models (LLMs) work and how they might be useful in your .NET projects."
ms.topic: concept-article
ms.date: 03/04/2026
ai-usage: ai-assisted

#customer intent: As a .NET developer, I want to understand how Generative AI and large language models (LLMs) work and how they may be useful in my .NET projects.

---

# How generative AI and LLMs work

Generative AI is a type of artificial intelligence that can create original content, such as natural language, images, audio, and code. The output depends on the inputs you provide. Users commonly interact with generative AI through chat applications that use natural language as input. ChatGPT, developed by OpenAI, is a popular example. Generative AI applications that use natural language as input are powered by large language models (LLMs) to perform natural language processing (NLP).

## How generative AI works

All generative AI is built on models. These models are trained with large sets of data in the form of content, such as natural language, images, audio, and code. Generative AI models use the patterns identified in the training data to produce new, statistically similar content.

The AI model uses your input to build an output. The model first parses the input into a form it can understand. The model then uses that data to identify matching patterns from its training that it combines to build the final output. Generative AI models are designed to produce unique content, so they won't generate the same output for identical inputs.

Generative AI applications that support natural language as input or output use LLMs to do so. The LLM performs NLP, which classifies the input text and determines its sentiment. The generative AI model uses that classification and sentiment analysis to identify patterns and build the output. If the output is text, the LLM alone generates it. If the output is audio or images, additional models provide the data and patterns for generating outputs in that format.

## Common uses of generative AI

Generative AI applications support a variety of use cases and outputs, described in the following sections.

### Natural language generation

Some generative AI applications can produce natural language outputs, such as:

- Professionally worded summaries for a LinkedIn profile
- Rich descriptions of items in an online storefront
- Ideas for healthy meals

For example, given the user input *Give me three ideas for a healthy breakfast including peppers*, a generative AI application might produce the following output:

*OK, here are three healthy breakfasts that include peppers:*

1. *Egg and Pepper Scramble: Dice up some bell peppers and sauté them in a pan until they're slightly softened. Then, add in some beaten eggs and scramble everything together. Serve with whole-grain toast for a nutritious breakfast.*

2. *Pepper and Avocado Toast: Toast a slice of whole-grain bread and top it with sliced bell peppers, mashed avocado, and a sprinkle of salt and pepper. This is a great way to get some healthy fats from the avocado along with the vitamin C from the peppers.*

3. *Breakfast Burrito with Peppers: Sauté some diced bell peppers, onions, and scrambled eggs together in a pan. Then, spoon the mixture onto a whole-grain tortilla and top with some salsa or hot sauce. Roll it up and enjoy a satisfying and nutritious breakfast.*

### Image generation

Some generative AI applications produce image outputs from natural language inputs. Depending on the application and its models, users might be able to specify:

- The people or things to appear in the image
- The artistic style to create the image in
- References for generating similar images

Image generation can create virtual avatars for online accounts, design logos for a business, or provide artistic inspiration for creators. For example, a user might input the request, *Create an image of an elephant eating a burger*. A generative AI application might produce the following output:


### Audio generation

Some generative AI applications produce audio outputs from natural language inputs. Depending on the application and its models, users might be able to:

- Synthesize natural sounding voices from input text
- Create music in a specific style or featuring certain instruments
- Modify input audio files based on set criteria provided in natural language

Audio generation can provide spoken responses from digital voice assistants, add backing instruments to songs for music production, or reproduce a user's original voice from reference recordings.

### Code generation

Some generative AI applications produce code from natural language inputs. Depending on the application and its models, users might be able to generate code that:

- Is in the language of their choice
- Accepts a specific input and output structure
- Uses specific technologies based on their reference documentation

Code generation can provide quick implementations of common operations, such as sort or filter data, speed up translating code from one language to another, or answer questions about a technology based on specified reference documentation. For example, given the input "Show me how to code a game of tic-tac-toe with C#", a generative AI application might produce the following output:

*Here's a simple example of how you can code a game of tic-tac-toe in C#:*

```csharp
using System;

namespace TicTacToe
{
    class Program
    {
        static char[] board = { '1', '2', '3', '4', '5', '6', '7', '8', '9' };
        static int player = 1; // Player 1 will start
        static int choice; // The number the player chooses
        static int flag = 0; // Set the flag value to 0

        // Check if the position is already marked or not
        private static int CheckPosition(char mark)
        {
            for (int i = 0; i < 9; i++)
            {
                if (board[i] == mark)
                {
                    return 1;
                }
            }
            return 0;
        }

        // The rest of the generated code has been omitted for brevity
        // ...
    }
}
```

*This code creates a simple console-based tic-tac-toe game in C#. It uses a single-dimensional array to represent the board and checks for a win or draw after each move.*

## How LLMs work

When training an LLM, the training text is first broken down into [tokens](understanding-tokens.md). Each token identifies a unique text value. A token can be a distinct word, a partial word, or a combination of words and punctuation. Each token is assigned an ID, which enables the text to be represented as a sequence of token IDs.

After the text has been broken down into tokens, a contextual vector, known as an [embedding](embeddings.md), is assigned to each token. These embedding vectors are multi-valued numeric data where each element of a token's vector represents a semantic attribute of the token. The elements of a token's vector are determined based on how commonly tokens are used together or in similar contexts.

The goal is to predict the next token in the sequence based on the preceding tokens. The model assigns a weight to each token in the existing sequence, representing its relative influence on the next token. The model then uses the preceding tokens' weights and embeddings to calculate and predict the next vector value. The model then selects the most probable token to continue the sequence based on the predicted vector.

This process continues iteratively for each token in the sequence, with the output sequence being used regressively as the input for the next iteration. The output is built one token at a time. This strategy is analogous to how auto-complete works, where suggestions are based on what's been typed so far and updated with each new input.

During training, the model knows the complete token sequence but ignores all tokens after the one currently being considered. The model compares the predicted vector value to the actual value and calculates the loss. Training then incrementally adjusts the weights to reduce the loss and improve the model.

## Related content

- [Understand Tokens](understanding-tokens.md)
- [Prompt engineering](prompt-engineering-dotnet.md)
- [Large language models](/training/modules/fundamentals-generative-ai/3-language%20models)

---
title: Prompt engineering concepts
description: Learn basic prompt engineering concepts and how to implement them using .NET tools such as Microsoft Agent Framework.
ms.topic: concept-article
ms.date: 03/04/2026
ai-usage: ai-assisted
---

# Prompt engineering in .NET

In this article, you explore essential prompt engineering concepts. Many AI models are prompt-based, meaning they respond to user input text (a *prompt*) with a response generated by predictive algorithms (a *completion*). Newer models also often support completions in chat form, with messages based on roles (system, user, assistant) and chat history to preserve conversations.

## Work with prompts

Models that support chat-based apps use three roles to organize completions: a *system* role that controls the chat, a *user* role to represent user input, and an *assistant* role for responding to users. Divide your prompts into messages for each role:

- [*System messages*](/azure/ai-services/openai/concepts/advanced-prompt-engineering?pivots=programming-language-chat-completions#system-message) give the model instructions about the assistant. A prompt can have only one system message, and it must be the first message.
- *User messages* include prompts from the user, examples, or instructions for the assistant. An example chat completion must have at least one user message.
- *Assistant messages* show example or historical completions and must contain a response to the preceding user message. Assistant messages aren't required, but if you include one, it must be paired with a user message to form an example.

## Use instructions to improve the completion

An *instruction* is text that tells the model how to respond. An instruction can be a *directive* or an *imperative*:

- *Directives* tell the model how to behave but aren't simple commands—think character setup for an improv actor: **"You're helping students learn about U.S. history, so talk about the U.S. unless they specifically ask about other countries or regions."**
- *Imperatives* are unambiguous commands for the model to follow. **"Translate to Tagalog:"**

## Use examples to guide the model

An example is text that shows the model how to respond by providing sample user input and model output. The model uses examples to infer what to include in completions. Examples can come either before or after the instructions in an engineered prompt, but the two shouldn't be interspersed.

An example starts with a prompt and can optionally include a completion. A completion in an example doesn't have to include the verbatim response—it might just contain a formatted word, the first bullet in an unordered list, or something similar to indicate how each completion should start.

Classify examples as [zero-shot learning](zero-shot-learning.md#zero-shot-learning) or [few-shot learning](zero-shot-learning.md#few-shot-learning) based on whether they contain verbatim completions.

- **Zero-shot learning** examples include a prompt with no verbatim completion. This approach tests a model's responses without giving it example data output. Zero-shot prompts can have completions that include cues, such as indicating the model should output an ordered list by including **"1."** as the completion.
- **Few-shot learning** examples include several pairs of prompts with verbatim completions. Few-shot learning can change the model's behavior by adding to its existing knowledge.

## Cues

A *cue* is text that conveys the desired structure or format of output. Like an instruction, a cue isn't processed by the model as if it were user input. Like an example, a cue shows the model what you want instead of telling it what to do. Add as many cues as you want to iterate toward the result you want. Use cues with an instruction or an example, and place them at the end of the prompt.

## Example prompt using .NET

.NET provides various tools to prompt and chat with different AI models. Use [Agent Framework](/agent-framework/) to connect to a wide variety of AI models and services. Agent Framework includes tools to create agents with system instructions and maintain conversation state across multiple turns.

Consider the following code example:


The preceding code:

- Creates an Azure OpenAI client with an endpoint and API key.
- Gets a chat client for the GPT-4o model and converts it to an AI agent.
- Creates an agent session to maintain conversation state across multiple turns.
- Accepts user input in a loop to allow for different types of prompts.
- Asynchronously streams the AI response and displays it to the console.

## Related content

- [Prompt engineering techniques](/azure/ai-foundry/openai/concepts/prompt-engineering)
- [System message design](/azure/ai-services/openai/concepts/advanced-prompt-engineering)

---
title: "Integrate Your Data into AI Apps with Retrieval-Augmented Generation"
description: "Learn how retrieval-augmented generation lets you use your data with LLMs to generate better completions in .NET."
ms.topic: concept-article
ms.date: 12/10/2025
---

# Retrieval-augmented generation (RAG) provides LLM knowledge

This article describes how retrieval-augmented generation lets LLMs treat your data sources as knowledge without having to train.

LLMs have extensive knowledge bases through training. For most scenarios, you can select an LLM that is designed for your requirements, but those LLMs still require additional training to understand your specific data. Retrieval-augmented generation lets you make your data available to LLMs without training them on it first.

## How RAG works

To perform retrieval-augmented generation, you create embeddings for your data along with common questions about it. You can do this on the fly or you can create and store the embeddings by using a vector database solution.

When a user asks a question, the LLM uses your embeddings to compare the user's question to your data and find the most relevant context. This context and the user's question then go to the LLM in a prompt, and the LLM provides a response based on your data.

### Basic RAG process

To perform RAG, you must process each data source that you want to use for retrievals. The basic process is as follows:

1. Chunk large data into manageable pieces.
1. Convert the chunks into a searchable format.
1. Store the converted data in a location that allows efficient access. Additionally, it's important to store relevant metadata for citations or references when the LLM provides responses.
1. Feed your converted data to LLMs in prompts.


- **Source data**: This is where your data exists. It could be a file/folder on your machine, a file in cloud storage, an Azure Machine Learning data asset, a Git repository, or an SQL database.
- **Data chunking**: The data in your source needs to be converted to plain text. For example, word documents or PDFs need to be cracked open and converted to text. The text is then chunked into smaller pieces.
- **Converting the text to vectors**: These are embeddings. Vectors are numerical representations of concepts converted to number sequences, which make it easy for computers to understand the relationships between those concepts.
- **Links between source data and embeddings**: This information is stored as metadata on the chunks you created, which are then used to help the LLMs generate citations while generating responses.

## See also

- [Data ingestion](data-ingestion.md)

---
title: "Understanding tokens"
description: "Understand how large language models (LLMs) use tokens to analyze semantic relationships and generate natural language outputs"
ms.topic: concept-article
ms.date: 03/04/2026
ai-usage: ai-assisted
#customer intent: As a .NET developer, I want understand how large language models (LLMs) use tokens so I can add semantic analysis and text generation capabilities to my .NET projects.
---
# Understand tokens

When you work with a large language model (LLM), text is first broken into units called *tokens*, which are words, character sets, or combinations of words and punctuation, by a tokenizer. During training, tokenization runs as the first step. The LLM analyzes the semantic relationships between tokens, such as how commonly they're used together or whether they're used in similar contexts. After training, the LLM uses those patterns and relationships to generate a sequence of output tokens based on the input sequence.

## Turn text into tokens

The set of unique tokens that an LLM is trained on is known as its _vocabulary_.

For example, consider the following sentence:

> `I heard a dog bark loudly at a cat`

This text could be tokenized as:

- `I`
- `heard`
- `a`
- `dog`
- `bark`
- `loudly`
- `at`
- `a`
- `cat`

By having a sufficiently large set of training text, tokenization can compile a vocabulary of many thousands of tokens.

## Common tokenization methods

The specific tokenization method varies by LLM. Common tokenization methods include:

- **Word** tokenization (text is split into individual words based on a delimiter)
- **Character** tokenization (text is split into individual characters)
- **Subword** tokenization (text is split into partial words or character sets)

For example, the GPT models, developed by OpenAI, use a type of subword tokenization that's known as _Byte-Pair Encoding_ (BPE). OpenAI provides [a tool to visualize how text will be tokenized](https://platform.openai.com/tokenizer).

Each tokenization method has benefits and disadvantages:

| Token size                                         | Pros | Cons |
|----------------------------------------------------|------|------|
| Smaller tokens (character or subword tokenization) | - Enables the model to handle a wider range of inputs, such as unknown words, typos, or complex syntax.<br>- Might allow the vocabulary size to be reduced, requiring fewer memory resources. | - A given text is broken into more tokens, requiring additional computational resources while processing.<br>- Given a fixed token limit, the maximum size of the model's input and output is smaller. |
| Larger tokens (word tokenization)                  | - A given text is broken into fewer tokens, requiring fewer computational resources while processing.<br>- Given the same token limit, the maximum size of the model's input and output is larger. | - Might cause an increased vocabulary size, requiring more memory resources.<br>- Can limit the model's ability to handle unknown words, typos, or complex syntax. |

## How LLMs use tokens

After the LLM completes tokenization, it assigns an ID to each unique token.

Consider this example sentence:

> `I heard a dog bark loudly at a cat`

After the model uses a word tokenization method, it could assign token IDs as follows:

- `I` (1)
- `heard` (2)
- `a` (3)
- `dog` (4)
- `bark` (5)
- `loudly` (6)
- `at` (7)
- `a` (the "a" token is already assigned an ID of 3)
- `cat` (8)

By assigning IDs, text can be represented as a sequence of token IDs. The example sentence would be represented as [1, 2, 3, 4, 5, 6, 7, 3, 8]. The sentence "`I heard a cat`" would be represented as [1, 2, 3, 8].

As training continues, the model adds any new tokens in the training text to its vocabulary and assigns each one an ID. For example:

- `meow` (9)
- `run` (10)

These token ID sequences reveal the semantic relationships between tokens. Multi-valued numeric vectors, known as [embeddings](embeddings.md), represent these relationships. The model assigns an embedding to each token based on how commonly it's used together with, or in similar contexts to, the other tokens.

After it's trained, a model can calculate an embedding for text that contains multiple tokens. The model tokenizes the text, then calculates an overall embeddings value based on the learned embeddings of the individual tokens. Use this technique for semantic document searches or to add vector stores to an AI.

During output generation, the model predicts a vector value for the next token in the sequence. The model then selects the next token from its vocabulary based on this vector value. In practice, the model calculates multiple vectors by using various elements of the previous tokens' embeddings. The model then evaluates all potential tokens from these vectors and selects the most probable one to continue the sequence.

Output generation is an iterative operation. The model appends the predicted token to the sequence so far and uses that as the input for the next iteration, building the final output one token at a time.

### Token limits

LLMs have a maximum number of tokens for input and output. This limit is often expressed as a combined maximum _context window_ that covers both input and output tokens together. Taken together, a model's token limit and tokenization method determine the maximum length of text that can be provided as input or generated as output.

For example, consider a model that has a maximum context window of 100 tokens. The model processes the example sentences as input text:

> `I heard a dog bark loudly at a cat`

By using a word-based tokenization method, the input is nine tokens. This leaves 91 **word** tokens available for the output.

By using a character-based tokenization method, the input is 34 tokens (including spaces). This leaves only 66 **character** tokens available for the output.

### Token-based pricing and rate limiting

Generative AI services often use token-based pricing. The cost of each request depends on the number of input and output tokens. Pricing might differ between input and output. For example, see [Azure OpenAI Service pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/).

Generative AI services also enforce a maximum number of tokens per minute (TPM). These rate limits can vary depending on the service region and LLM. For more information about specific regions, see [Azure OpenAI Service quotas and limits](/azure/ai-services/openai/quotas-limits#regional-quota-limits).

## Related content

- [Use Microsoft.ML.Tokenizers for text tokenization](../how-to/use-tokenizers.md)
- [How generative AI and LLMs work](how-genai-and-llms-work.md)
- [Understand embeddings](embeddings.md)
- [Work with vector databases](vector-databases.md)

---
title: "Using Vector Databases to Extend LLM Capabilities"
description: "Learn how vector databases extend LLM capabilities by storing and processing embeddings in .NET."
ms.topic: concept-article
ms.date: 03/04/2026
ai-usage: ai-assisted
---

# Vector databases for .NET + AI

Vector databases are designed to store and manage vector [embeddings](embeddings.md). Embeddings are numeric representations of non-numeric data that preserve semantic meaning. You can vectorize words, documents, images, audio, and other data types. Use embeddings to help an AI model understand the meaning of inputs so that it can perform comparisons and transformations, such as summarizing text, finding contextually related data, or creating images from text descriptions.

For example, you can use a vector database to:

- Identify similar images, documents, and songs based on their contents, themes, sentiments, and styles.
- Identify similar products based on their characteristics, features, and user groups.
- Recommend content, products, or services based on user preferences.
- Identify the best potential options from a large pool of choices to meet complex requirements.
- Identify data anomalies or fraudulent activities that are dissimilar from predominant or normal patterns.

## Understand vector search

Vector databases provide vector search capabilities to find similar items based on their data characteristics rather than by exact matches on a property field. Vector search works by analyzing the vector representations of your data that you created using an AI embedding model such as the [Azure OpenAI embedding models](/azure/ai-services/openai/concepts/models#embeddings-models). The search process measures the distance between the data vectors and your query vector. The data vectors that are closest to your query vector are the ones that are found to be most similar semantically.

Some services such as [Azure Cosmos DB for MongoDB vCore](/azure/cosmos-db/mongodb/vcore/vector-search) provide native vector search capabilities for your data. Other databases can be enhanced with vector search by indexing the stored data using a service such as Azure AI Search, which can scan and index your data to provide vector search capabilities.

## Vector search workflows with .NET and OpenAI

Vector databases and their search features are especially useful in [RAG pattern](rag.md) workflows with Azure OpenAI. This pattern lets you augment your AI model with additional semantically rich knowledge of your data. A common AI workflow using vector databases includes these steps:

1. Create embeddings for your data using an OpenAI embedding model.
1. Store and index the embeddings in a vector database or search service.
1. Convert user prompts from your application to embeddings.
1. Run a vector search across your data, comparing the user prompt embedding to the embeddings in your database.
1. Use a language model such as GPT-4o to assemble a user-friendly completion from the vector search results.

Visit the [Implement Azure OpenAI with RAG using vector search in a .NET app](../tutorials/tutorial-ai-vector-search.md) tutorial for a hands-on example of this flow.

Other benefits of the RAG pattern include:

- Generate contextually relevant and accurate responses to user prompts from AI models.
- Overcome LLM token limits—the database vector search does the heavy lifting.
- Reduce the costs from frequent fine-tuning on updated data.

## Related content

- [Implement Azure OpenAI with RAG using vector search in a .NET app](../tutorials/tutorial-ai-vector-search.md)

---
title: "Zero-shot and few-shot learning"
description: "Learn the use cases for zero-shot and few-shot learning in prompt engineering."
ms.topic: concept-article #Don't change.
ms.date: 03/04/2026
ai-usage: ai-assisted

#customer intent: As a .NET developer, I want to understand how zero-shot and few-shot learning techniques can help me improve my prompt engineering.

---

# Zero-shot and few-shot learning

This article explains zero-shot learning and few-shot learning for prompt engineering in .NET, including their primary use cases.

GPT model performance benefits from *prompt engineering*, the practice of providing instructions and examples to a model to refine its output. Zero-shot learning and few-shot learning are techniques you can use when providing examples.

## Zero-shot learning

Zero-shot learning is the practice of passing prompts that aren't paired with verbatim completions, although you can include completions that consist of cues. Zero-shot learning relies entirely on the model's existing knowledge to generate responses, which reduces the number of tokens created and can help you control costs. However, zero-shot learning doesn't add to the model's knowledge or context.

Here's an example zero-shot prompt that tells the model to evaluate user input to determine which of four possible intents the input represents, and then to preface the response with **"Intent: "**.

```csharp
prompt = $"""
Instructions: What is the intent of this request?
If you don't know the intent, don't guess; instead respond with "Unknown".
Choices: SendEmail, SendMessage, CompleteTask, CreateDocument, Unknown.
User Input: {request}
Intent: 
""";
```

Zero-shot learning has two primary use cases:

- **Work with fine-tuned LLMs** - Because it relies on the model's existing knowledge, zero-shot learning isn't as resource-intensive as few-shot learning, and it works well with LLMs that have already been fine-tuned on instruction datasets. You might be able to rely solely on zero-shot learning and keep costs relatively low.
- **Establish performance baselines** - Zero-shot learning can help you simulate how your app performs for actual users. This lets you evaluate various aspects of your model's current performance, such as accuracy or precision. In this case, you typically use zero-shot learning to establish a performance baseline and then experiment with few-shot learning to improve performance.

## Few-shot learning

Few-shot learning is the practice of passing prompts paired with verbatim completions (few-shot prompts) to show your model how to respond. Compared to zero-shot learning, this means few-shot learning produces more tokens and causes the model to update its knowledge, which can make few-shot learning more resource-intensive. However, few-shot learning also helps the model produce more relevant responses.

```csharp
prompt = $"""
Instructions: What is the intent of this request?
If you don't know the intent, don't guess; instead respond with "Unknown".
Choices: SendEmail, SendMessage, CompleteTask, CreateDocument, Unknown.

User Input: Can you send a very quick approval to the marketing team?
Intent: SendMessage

User Input: Can you send the full update to the marketing team?
Intent: SendEmail

User Input: {request}
Intent:
""";
```

Few-shot learning has two primary use cases:

- **Tuning an LLM** - Because it can add to the model's knowledge, few-shot learning can improve a model's performance. It also causes the model to create more tokens than zero-shot learning does, which can eventually become prohibitively expensive or even infeasible. However, if your LLM isn't fine-tuned yet, you won't always get good performance with zero-shot prompts, and few-shot learning is warranted.
- **Fixing performance issues** - You can use few-shot learning as a follow-up to zero-shot learning. In this case, you use zero-shot learning to establish a performance baseline, and then experiment with few-shot learning based on the zero-shot prompts you used. This lets you add to the model's knowledge after seeing how it currently responds, so you can iterate and improve performance while minimizing the number of tokens you introduce.  

### Caveats

- Example-based learning doesn't work well for complex reasoning tasks. However, adding instructions can help address this.
- Few-shot learning requires creating lengthy prompts. Prompts with a large number of tokens can increase computation and latency. This typically means increased costs. There's also a limit to the length of the prompts.
- When you use several examples, the model can learn false patterns, such as "Sentiments are twice as likely to be positive than negative."

## Related content

- [Prompt engineering techniques](/azure/ai-services/openai/concepts/advanced-prompt-engineering)
- [How GenAI and LLMs work](how-genai-and-llms-work.md)

---
title: Quickstart - Evaluate the quality of a model's response
description: Learn how to create an MSTest app to evaluate the AI chat response of a language model.
ms.date: 03/18/2025
ms.topic: quickstart
---

# Quickstart: Evaluate response quality

In this quickstart, you create an MSTest app to evaluate the quality of a chat response from 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](libraries.md#cached-responses) and [reporting](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](evaluate-with-reporting.md)

## Prerequisites

- [.NET 8 or a later version](https://dotnet.microsoft.com/download)
- [Visual Studio Code](https://code.visualstudio.com/) (optional)

## Configure the AI service

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. In the "Deploy a model" step, select the `gpt-5` model.

## Create the test app

Complete the following steps to create an MSTest project that connects to an AI model.

1. In a terminal window, navigate to the directory where you want to create your app, and create a new MSTest app with the `dotnet new` command:

    ```dotnetcli
    dotnet new mstest -o TestAI
    ```

1. Navigate to the `TestAI` directory, and add the necessary packages to your app:

    ```dotnetcli
    dotnet add package Azure.AI.OpenAI
    dotnet add package Azure.Identity
    dotnet add package Microsoft.Extensions.AI.Abstractions
    dotnet add package Microsoft.Extensions.AI.Evaluation
    dotnet add package Microsoft.Extensions.AI.Evaluation.Quality
    dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    ```

1. Run the following commands to add [app secrets](/aspnet/core/security/app-secrets) for your Azure OpenAI endpoint and tenant ID:

    ```bash
    dotnet user-secrets init
    dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
    dotnet user-secrets set AZURE_TENANT_ID <your-tenant-ID>
    ```

   (Depending on your environment, the tenant ID might not be needed. In that case, remove it from the code that instantiates the <xref:Azure.Identity.DefaultAzureCredential>.)

1. Open the new app in your editor of choice.

## Add the test app code

1. Rename the *Test1.cs* file to *MyTests.cs*, and then open the file and rename the class to `MyTests`.
1. Add the private <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration> and chat message and response members to the `MyTests` class. The `s_messages` field is a list that contains two <xref:Microsoft.Extensions.AI.ChatMessage> objects&mdash;one instructs the behavior of the chat bot, and the other is the question from the user.


1. Add the `InitializeAsync` method to the `MyTests` class.


    This method accomplishes the following tasks:

   - Sets up the <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration>.
   - Sets the <xref:Microsoft.Extensions.AI.ChatOptions>, including the <xref:Microsoft.Extensions.AI.ChatOptions.Temperature> and the <xref:Microsoft.Extensions.AI.ChatOptions.ResponseFormat>.
   - Fetches the response to be evaluated by calling <xref:Microsoft.Extensions.AI.IChatClient.GetResponseAsync(System.Collections.Generic.IEnumerable{Microsoft.Extensions.AI.ChatMessage},Microsoft.Extensions.AI.ChatOptions,System.Threading.CancellationToken)>, and stores it in a static variable.

1. Add the `GetAzureOpenAIChatConfiguration` method, which creates the <xref:Microsoft.Extensions.AI.IChatClient> that the evaluator uses to communicate with the model.


1. Add a test method to evaluate the model's response.


   This method does the following:

   - Invokes the <xref:Microsoft.Extensions.AI.Evaluation.Quality.CoherenceEvaluator> to evaluate the *coherence* of the response. The <xref:Microsoft.Extensions.AI.Evaluation.IEvaluator.EvaluateAsync(System.Collections.Generic.IEnumerable{Microsoft.Extensions.AI.ChatMessage},Microsoft.Extensions.AI.ChatResponse,Microsoft.Extensions.AI.Evaluation.ChatConfiguration,System.Collections.Generic.IEnumerable{Microsoft.Extensions.AI.Evaluation.EvaluationContext},System.Threading.CancellationToken)> method returns an <xref:Microsoft.Extensions.AI.Evaluation.EvaluationResult> that contains a <xref:Microsoft.Extensions.AI.Evaluation.NumericMetric>. A `NumericMetric` contains a numeric value that's typically used to represent numeric scores that fall within a well-defined range.
   - Retrieves the coherence score from the <xref:Microsoft.Extensions.AI.Evaluation.EvaluationResult>.
   - Validates the *default interpretation* for the returned coherence metric. Evaluators can include a default interpretation for the metrics they return. You can also change the default interpretation to suit your specific requirements, if needed.
   - Validates that no diagnostics are present on the returned coherence metric. Evaluators can include diagnostics on the metrics they return to indicate errors, warnings, or other exceptional conditions encountered during evaluation.

## Run the test/evaluation

Run the test using your preferred test workflow, for example, by using the CLI command `dotnet test` or through [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer).

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and GPT-4 model deployment.

1. In the [Azure portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

## Next steps

- Evaluate the responses from different OpenAI models.
- Add response caching and reporting to your evaluation code. For more information, see [Tutorial: Evaluate a model's response with response caching and reporting](evaluate-with-reporting.md).

---
title: Tutorial - Evaluate response safety with caching and reporting
description: Create an MSTest app that evaluates the content safety of a model's response using the evaluators in the Microsoft.Extensions.AI.Evaluation.Safety package and with caching and reporting.
ms.date: 05/12/2025
ms.topic: tutorial
---

# Tutorial: Evaluate response safety with caching and reporting

In this tutorial, you create an MSTest app to evaluate the *content safety* of a response from an OpenAI model. Safety evaluators check for presence of harmful, inappropriate, or unsafe content in a response. The test app uses the safety evaluators from the [Microsoft.Extensions.AI.Evaluation.Safety](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Safety) package to perform the evaluations. These safety evaluators use the [Microsoft Foundry](/azure/ai-foundry/) Evaluation service to perform evaluations.

## Prerequisites

- .NET 8.0 SDK or higher - [Install the .NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0).
- An Azure subscription - [Create one for free](https://azure.microsoft.com/free).

## Configure the AI service

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. In the "Deploy a model" step, select the `gpt-5` model.

> [!TIP]
> The previous configuration step is only required to fetch the response to be evaluated. To evaluate the safety of a response you already have in hand, you can skip this configuration.

The evaluators in this tutorial use the Foundry Evaluation service, which requires some additional setup:

- [Create a resource group](/azure/azure-resource-manager/management/manage-resource-groups-portal#create-resource-groups) within one of the Azure [regions that support Foundry Evaluation service](/azure/ai-foundry/how-to/develop/evaluate-sdk#region-support).
- [Create a Foundry hub](/azure/ai-foundry/how-to/create-azure-ai-resource?tabs=portal#create-a-hub-in-azure-ai-foundry-portal) in the resource group you just created.
- Finally, [create a Foundry project](/azure/ai-foundry/how-to/create-projects?tabs=ai-studio#create-a-project) in the hub you just created.

## Create the test app

Complete the following steps to create an MSTest project.

1. In a terminal window, navigate to the directory where you want to create your app, and create a new MSTest app with the `dotnet new` command:

   ```dotnetcli
   dotnet new mstest -o EvaluateResponseSafety
   ```

1. Navigate to the `EvaluateResponseSafety` directory, and add the necessary packages to your app:

   ```dotnetcli
   dotnet add package Azure.AI.OpenAI
   dotnet add package Azure.Identity
   dotnet add package Microsoft.Extensions.AI.Abstractions
   dotnet add package Microsoft.Extensions.AI.Evaluation
   dotnet add package Microsoft.Extensions.AI.Evaluation.Reporting
   dotnet add package Microsoft.Extensions.AI.Evaluation.Safety --prerelease
   dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
   dotnet add package Microsoft.Extensions.Configuration
   dotnet add package Microsoft.Extensions.Configuration.UserSecrets
   ```

1. Run the following commands to add [app secrets](/aspnet/core/security/app-secrets) for your Azure OpenAI endpoint, tenant ID, subscription ID, resource group, and project:

   ```bash
   dotnet user-secrets init
   dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
   dotnet user-secrets set AZURE_TENANT_ID <your-tenant-ID>
   dotnet user-secrets set AZURE_SUBSCRIPTION_ID <your-subscription-ID>
   dotnet user-secrets set AZURE_RESOURCE_GROUP <your-resource-group>
   dotnet user-secrets set AZURE_AI_PROJECT <your-Azure-AI-project>
   ```

   (Depending on your environment, the tenant ID might not be needed. In that case, remove it from the code that instantiates the <xref:Azure.Identity.DefaultAzureCredential>.)

1. Open the new app in your editor of choice.

## Add the test app code

1. Rename the `Test1.cs` file to `MyTests.cs`, and then open the file and rename the class to `MyTests`. Delete the empty `TestMethod1` method.
1. Add the necessary `using` directives to the top of the file.


1. Add the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> property to the class.


1. Add the scenario and execution name fields to the class.


   The [scenario name](xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRun.ScenarioName) is set to the fully qualified name of the current test method. However, you can set it to any string of your choice. Here are some considerations for choosing a scenario name:

   - When using disk-based storage, the scenario name is used as the name of the folder under which the corresponding evaluation results are stored.
   - By default, the generated evaluation report splits scenario names on `.` so that the results can be displayed in a hierarchical view with appropriate grouping, nesting, and aggregation.

   The [execution name](xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration.ExecutionName) is used to group evaluation results that are part of the same evaluation run (or test run) when the evaluation results are stored. If you don't provide an execution name when creating a <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration>, all evaluation runs will use the same default execution name of `Default`. In this case, results from one run will be overwritten by the next.

1. Add a method to gather the safety evaluators to use in the evaluation.


1. Add a <xref:Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfiguration> object, which configures the connection parameters that the safety evaluators need to communicate with the Foundry Evaluation service.


1. Add a method that creates an <xref:Microsoft.Extensions.AI.IChatClient> object, which will be used to get the chat response to evaluate from the LLM.


1. Set up the reporting functionality. Convert the <xref:Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfiguration> to a <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration>, and then pass that to the method that creates a <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration>.


   Response caching functionality is supported and works the same way regardless of whether the evaluators talk to an LLM or to the Foundry Evaluation service. The response will be reused until the corresponding cache entry expires (in 14 days by default), or until any request parameter, such as the LLM endpoint or the question being asked, is changed.

   > [!NOTE]
   > This code example passes the LLM <xref:Microsoft.Extensions.AI.IChatClient> as `originalChatClient` to <xref:Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfigurationExtensions.ToChatConfiguration(Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfiguration,Microsoft.Extensions.AI.IChatClient)>. The reason to include the LLM chat client here is to enable getting a chat response from the LLM, and notably, to enable response caching for it. (If you don't want to cache the LLM's response, you can create a separate, local <xref:Microsoft.Extensions.AI.IChatClient> to fetch the response from the LLM.) Instead of passing a <xref:Microsoft.Extensions.AI.IChatClient>, if you already have a <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration> for an LLM from another reporting configuration, you can pass that instead, using the <xref:Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfigurationExtensions.ToChatConfiguration(Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfiguration,Microsoft.Extensions.AI.Evaluation.ChatConfiguration)> overload.
   >
   > Similarly, if you configure both [LLM-based evaluators](libraries.md#quality-evaluators) and [Foundry Evaluation service&ndash;based evaluators](libraries.md#safety-evaluators) in the reporting configuration, you also need to pass the LLM <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration> to <xref:Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfigurationExtensions.ToChatConfiguration(Microsoft.Extensions.AI.Evaluation.Safety.ContentSafetyServiceConfiguration,Microsoft.Extensions.AI.Evaluation.ChatConfiguration)>. Then it returns a <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration> that can talk to both types of evaluators.

1. Add a method to define the [chat options](xref:Microsoft.Extensions.AI.ChatOptions) and ask the model for a response to a given question.


   The test in this tutorial evaluates the LLM's response to an astronomy question. Since the <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration> has response caching enabled, and since the supplied <xref:Microsoft.Extensions.AI.IChatClient> is always fetched from the <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRun> created using this reporting configuration, the LLM response for the test is cached and reused.

1. Add a method to validate the response.


   > [!TIP]
   > Some of the evaluators, for example, <xref:Microsoft.Extensions.AI.Evaluation.Safety.ViolenceEvaluator>, might produce a warning diagnostic that's shown [in the report](#generate-a-report) if you only evaluate the response and not the message. Similarly, if the data you pass to <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRunExtensions.EvaluateAsync*> contains two consecutive messages with the same <xref:Microsoft.Extensions.AI.ChatRole> (for example, <xref:Microsoft.Extensions.AI.ChatRole.User> or <xref:Microsoft.Extensions.AI.ChatRole.Assistant>), it might also produce a warning. However, even though an evaluator might produce a warning diagnostic in these cases, it still proceeds with the evaluation.

1. Finally, add the [test method](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute) itself.


   This test method:

   - Creates the <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRun>. The use of `await using` ensures that the `ScenarioRun` is correctly disposed and that the results of this evaluation are correctly persisted to the result store.
   - Gets the LLM's response to a specific astronomy question. The same <xref:Microsoft.Extensions.AI.IChatClient> that will be used for evaluation is passed to the `GetAstronomyConversationAsync` method in order to get *response caching* for the primary LLM response being evaluated. (In addition, this enables response caching for the responses that the evaluators fetch from the Foundry Evaluation service as part of performing their evaluations.)
   - Runs the evaluators against the response. Like the LLM response, on subsequent runs, the evaluation is fetched from the (disk-based) response cache that was configured in `s_safetyReportingConfig`.
   - Runs some safety validation on the evaluation result.

## Run the test/evaluation

Run the test using your preferred test workflow, for example, by using the CLI command `dotnet test` or through [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer).

## Generate a report

To generate a report to view the evaluation results, see [Generate a report](evaluate-with-reporting.md#generate-a-report).

## Next steps

This tutorial covers the basics of evaluating content safety. As you create your test suite, consider the following next steps:

- Configure additional evaluators, such as the [quality evaluators](libraries.md#quality-evaluators). For an example, see the AI samples repo [quality and safety evaluation example](https://github.com/dotnet/ai-samples/blob/main/src/microsoft-extensions-ai-evaluation/api/reporting/ReportingExamples.Example10_RunningQualityAndSafetyEvaluatorsTogether.cs).
- Evaluate the content safety of generated images. For an example, see the AI samples repo [image response example](https://github.com/dotnet/ai-samples/blob/main/src/microsoft-extensions-ai-evaluation/api/reporting/ReportingExamples.Example09_RunningSafetyEvaluatorsAgainstResponsesWithImages.cs).
- In real-world evaluations, you might not want to validate individual results, since the LLM responses and evaluation scores can vary over time as your product (and the models used) evolve. You might not want individual evaluation tests to fail and block builds in your CI/CD pipelines when this happens. Instead, in such cases, it might be better to rely on the generated report and track the overall trends for evaluation scores across different scenarios over time (and only fail individual builds in your CI/CD pipelines when there's a significant drop in evaluation scores across multiple different tests).

---
title: Tutorial - Evaluate response quality with caching and reporting
description: Create an MSTest app to evaluate the response quality of a language model, add a custom evaluator, and learn how to use the caching and reporting features of Microsoft.Extensions.AI.Evaluation.
ms.date: 05/09/2025
ms.topic: tutorial
---

# Tutorial: Evaluate response quality with caching and reporting

In this tutorial, 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 to perform the evaluations, cache the model responses, and create reports. The tutorial uses both built-in and custom evaluators. The built-in quality evaluators (from the [Microsoft.Extensions.AI.Evaluation.Quality package](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Quality)) use an LLM to perform evaluations; the custom evaluator does not use AI.

## Prerequisites

- [.NET 8 or a later version](https://dotnet.microsoft.com/download)
- [Visual Studio Code](https://code.visualstudio.com/) (optional)

## Configure the AI service

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. In the "Deploy a model" step, select the `gpt-5` model.

## Create the test app

Complete the following steps to create an MSTest project that connects to an AI model.

1. In a terminal window, navigate to the directory where you want to create your app, and create a new MSTest app with the `dotnet new` command:

   ```dotnetcli
   dotnet new mstest -o TestAIWithReporting
   ```

1. Navigate to the `TestAIWithReporting` directory, and add the necessary packages to your app:

   ```dotnetcli
   dotnet add package Azure.AI.OpenAI
   dotnet add package Azure.Identity
   dotnet add package Microsoft.Extensions.AI.Abstractions
   dotnet add package Microsoft.Extensions.AI.Evaluation
   dotnet add package Microsoft.Extensions.AI.Evaluation.Quality
   dotnet add package Microsoft.Extensions.AI.Evaluation.Reporting
   dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
   dotnet add package Microsoft.Extensions.Configuration
   dotnet add package Microsoft.Extensions.Configuration.UserSecrets
   ```

1. Run the following commands to add [app secrets](/aspnet/core/security/app-secrets) for your Azure OpenAI endpoint and tenant ID:

   ```bash
   dotnet user-secrets init
   dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
   dotnet user-secrets set AZURE_TENANT_ID <your-tenant-ID>
   ```

   (Depending on your environment, the tenant ID might not be needed. In that case, remove it from the code that instantiates the <xref:Azure.Identity.DefaultAzureCredential>.)

1. Open the new app in your editor of choice.

## Add the test app code

1. Rename the *Test1.cs* file to *MyTests.cs*, and then open the file and rename the class to `MyTests`. Delete the empty `TestMethod1` method.
1. Add the necessary `using` directives to the top of the file.


1. Add the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestContext> property to the class.


1. Add the `GetAzureOpenAIChatConfiguration` method, which creates the <xref:Microsoft.Extensions.AI.IChatClient> that the evaluator uses to communicate with the model.


1. Set up the reporting functionality.


   **Scenario name**

   The [scenario name](xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRun.ScenarioName) is set to the fully qualified name of the current test method. However, you can set it to any string of your choice when you call <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration.CreateScenarioRunAsync(System.String,System.String,System.Collections.Generic.IEnumerable{System.String},System.Collections.Generic.IEnumerable{System.String},System.Threading.CancellationToken)>. Here are some considerations for choosing a scenario name:

   - When using disk-based storage, the scenario name is used as the name of the folder under which the corresponding evaluation results are stored. So it's a good idea to keep the name reasonably short and avoid any characters that aren't allowed in file and directory names.
   - By default, the generated evaluation report splits scenario names on `.` so that the results can be displayed in a hierarchical view with appropriate grouping, nesting, and aggregation. This is especially useful in cases where the scenario name is set to the fully qualified name of the corresponding test method, since it allows the results to be grouped by namespaces and class names in the hierarchy. However, you can also take advantage of this feature by including periods (`.`) in your own custom scenario names to create a reporting hierarchy that works best for your scenarios.

   **Execution name**

   The execution name is used to group evaluation results that are part of the same evaluation run (or test run) when the evaluation results are stored. If you don't provide an execution name when creating a <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration>, all evaluation runs will use the same default execution name of `Default`. In this case, results from one run will be overwritten by the next and you lose the ability to compare results across different runs.

   This example uses a timestamp as the execution name. If you have more than one test in your project, ensure that results are grouped correctly by using the same execution name in all reporting configurations used across the tests.

   In a more real-world scenario, you might also want to share the same execution name across evaluation tests that live in multiple different assemblies and that are executed in different test processes. In such cases, you could use a script to update an environment variable with an appropriate execution name (such as the current build number assigned by your CI/CD system) before running the tests. Or, if your build system produces monotonically increasing assembly file versions, you could read the <xref:System.Reflection.AssemblyFileVersionAttribute> from within the test code and use that as the execution name to compare results across different product versions.

   **Reporting configuration**

   A <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration> identifies:

   - The set of evaluators that should be invoked for each <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRun> that's created by calling <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration.CreateScenarioRunAsync(System.String,System.String,System.Collections.Generic.IEnumerable{System.String},System.Collections.Generic.IEnumerable{System.String},System.Threading.CancellationToken)>.
   - The LLM endpoint that the evaluators should use (see <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration.ChatConfiguration?displayProperty=nameWithType>).
   - How and where the results for the scenario runs should be stored.
   - How LLM responses related to the scenario runs should be cached.
   - The execution name that should be used when reporting results for the scenario runs.

   This test uses a disk-based reporting configuration.

1. In a separate file, add the `WordCountEvaluator` class, which is a custom evaluator that implements <xref:Microsoft.Extensions.AI.Evaluation.IEvaluator>.


   The `WordCountEvaluator` counts the number of words present in the response. Unlike some evaluators, it isn't based on AI. The `EvaluateAsync` method returns an <xref:Microsoft.Extensions.AI.Evaluation.EvaluationResult> includes a <xref:Microsoft.Extensions.AI.Evaluation.NumericMetric> that contains the word count.

   The `EvaluateAsync` method also attaches a default interpretation to the metric. The default interpretation considers the metric to be good (acceptable) if the detected word count is between 6 and 100. Otherwise, the metric is considered failed. This default interpretation can be overridden by the caller, if needed.

1. Back in `MyTests.cs`, add a method to gather the evaluators to use in the evaluation.


1. Add a method to add a system prompt <xref:Microsoft.Extensions.AI.ChatMessage>, define the [chat options](xref:Microsoft.Extensions.AI.ChatOptions), and ask the model for a response to a given question.


   The test in this tutorial evaluates the LLM's response to an astronomy question. Since the <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration> has response caching enabled, and since the supplied <xref:Microsoft.Extensions.AI.IChatClient> is always fetched from the <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRun> created using this reporting configuration, the LLM response for the test is cached and reused. The response will be reused until the corresponding cache entry expires (in 14 days by default), or until any request parameter, such as the the LLM endpoint or the question being asked, is changed.

1. Add a method to validate the response.


    > [!TIP]
    > The metrics each include a `Reason` property that explains the reasoning for the score. The reason is included in the [generated report](#generate-a-report) and can be viewed by clicking on the information icon on the corresponding metric's card.

1. Finally, add the [test method](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute) itself.


   This test method:

   - Creates the <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ScenarioRun>. The use of `await using` ensures that the `ScenarioRun` is correctly disposed and that the results of this evaluation are correctly persisted to the result store.
   - Gets the LLM's response to a specific astronomy question. The same <xref:Microsoft.Extensions.AI.IChatClient> that will be used for evaluation is passed to the `GetAstronomyConversationAsync` method in order to get *response caching* for the primary LLM response being evaluated. (In addition, this enables response caching for the LLM turns that the evaluators use to perform their evaluations internally.) With response caching, the LLM response is fetched either:
     - Directly from the LLM endpoint in the first run of the current test, or in subsequent runs if the cached entry has expired (14 days, by default).
     - From the (disk-based) response cache that was configured in `s_defaultReportingConfiguration` in subsequent runs of the test.
   - Runs the evaluators against the response. Like the LLM response, on subsequent runs, the evaluation is fetched from the (disk-based) response cache that was configured in `s_defaultReportingConfiguration`.
   - Runs some basic validation on the evaluation result.

     This step is optional and mainly for demonstration purposes. In real-world evaluations, you might not want to validate individual results since the LLM responses and evaluation scores can change over time as your product (and the models used) evolve. You might not want individual evaluation tests to "fail" and block builds in your CI/CD pipelines when this happens. Instead, it might be better to rely on the generated report and track the overall trends for evaluation scores across different scenarios over time (and only fail individual builds when there's a significant drop in evaluation scores across multiple different tests). That said, there is some nuance here and the choice of whether to validate individual results or not can vary depending on the specific use case.

   When the method returns, the `scenarioRun` object is disposed and the evaluation result for the evaluation is stored to the (disk-based) result store that's configured in `s_defaultReportingConfiguration`.

## Run the test/evaluation

Run the test using your preferred test workflow, for example, by using the CLI command `dotnet test` or through [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer).

## Generate a report

1. Install the [Microsoft.Extensions.AI.Evaluation.Console](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Console) .NET tool by running the following command from a terminal window:

   ```dotnetcli
   dotnet tool install --local Microsoft.Extensions.AI.Evaluation.Console
   ```

    > [!TIP]
    > You might need to create a manifest file first. For more information about that and installing local tools, see [Local tools](../../core/tools/dotnet-tool-install.md#local-tools).

1. Generate a report by running the following command:

   ```dotnetcli
   dotnet tool run aieval report --path <path\to\your\cache\storage> --output report.html
   ```

1. Open the `report.html` file. It should look something like this.


## Next steps

- Navigate to the directory where the test results are stored (which is `C:\TestReports`, unless you modified the location when you created the <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration>). In the `results` subdirectory, notice that there's a folder for each test run named with a timestamp (`ExecutionName`). Inside each of those folders is a folder for each scenario name&mdash;in this case, just the single test method in the project. That folder contains a JSON file with the all the data including the messages, response, and evaluation result.
- Expand the evaluation. Here are a couple ideas:
  - Add an additional custom evaluator, such as [an evaluator that uses AI to determine the measurement system](https://github.com/dotnet/ai-samples/blob/main/src/microsoft-extensions-ai-evaluation/api/evaluation/Evaluators/MeasurementSystemEvaluator.cs) that's used in the response.
  - Add another test method, for example, [a method that evaluates multiple responses](https://github.com/dotnet/ai-samples/blob/main/src/microsoft-extensions-ai-evaluation/api/reporting/ReportingExamples.Example02_SamplingAndEvaluatingMultipleResponses.cs) from the LLM. Since each response can be different, it's good to sample and evaluate at least a few responses to a question. In this case, you specify an iteration name each time you call <xref:Microsoft.Extensions.AI.Evaluation.Reporting.ReportingConfiguration.CreateScenarioRunAsync(System.String,System.String,System.Collections.Generic.IEnumerable{System.String},System.Collections.Generic.IEnumerable{System.String},System.Threading.CancellationToken)>.

---
title: The Microsoft.Extensions.AI.Evaluation libraries
description: Learn about the Microsoft.Extensions.AI.Evaluation libraries, which simplify the process of evaluating the quality and accuracy of responses generated by AI models in .NET intelligent apps.
ms.topic: concept-article
ms.date: 07/24/2025
---
# The Microsoft.Extensions.AI.Evaluation libraries

The Microsoft.Extensions.AI.Evaluation libraries simplify the process of evaluating the quality and safety of responses generated by AI models in .NET intelligent apps. Various quality metrics measure aspects like relevance, truthfulness, coherence, and completeness of the responses. Safety metrics measure aspects like hate and unfairness, violence, and sexual content. Evaluations are crucial in testing, because they help ensure that the AI model performs as expected and provides reliable and accurate results.

The evaluation libraries, which are built on top of the [Microsoft.Extensions.AI abstractions](../microsoft-extensions-ai.md), are composed of the following NuGet packages:

- [📦 Microsoft.Extensions.AI.Evaluation](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation) – Defines the core abstractions and types for supporting evaluation.
- [📦 Microsoft.Extensions.AI.Evaluation.NLP](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.NLP) - Contains [evaluators](#nlp-evaluators) that evaluate the similarity of an LLM's response text to one or more reference responses using natural language processing (NLP) metrics. These evaluators aren't LLM or AI-based; they use traditional NLP techniques such as text tokenization and n-gram analysis to evaluate text similarity.
- [📦 Microsoft.Extensions.AI.Evaluation.Quality](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Quality) – Contains [evaluators](#quality-evaluators) that assess the quality of LLM responses in an app according to metrics such as relevance and completeness. These evaluators use the LLM directly to perform evaluations.
- [📦 Microsoft.Extensions.AI.Evaluation.Safety](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Safety) – Contains [evaluators](#safety-evaluators), such as the `ProtectedMaterialEvaluator` and `ContentHarmEvaluator`, that use the [Microsoft Foundry](/azure/ai-foundry/) Evaluation service to perform evaluations.
- [📦 Microsoft.Extensions.AI.Evaluation.Reporting](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Reporting) – Contains support for caching LLM responses, storing the results of evaluations, and generating reports from that data.
- [📦 Microsoft.Extensions.AI.Evaluation.Reporting.Azure](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Reporting.Azure) - Supports the reporting library with an implementation for caching LLM responses and storing the evaluation results in an [Azure Storage](/azure/storage/common/storage-introduction) container.
- [📦 Microsoft.Extensions.AI.Evaluation.Console](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Console) – A command-line tool for generating reports and managing evaluation data.

## Test integration

The libraries are designed to integrate smoothly with existing .NET apps, allowing you to leverage existing testing infrastructures and familiar syntax to evaluate intelligent apps. You can use any test framework (for example, [MSTest](../../core/testing/index.md#mstest), [xUnit](../../core/testing/index.md#xunitnet), or [NUnit](../../core/testing/index.md#nunit)) and testing workflow (for example, [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer), [dotnet test](../../core/tools/dotnet-test.md), or a CI/CD pipeline). The library also provides easy ways to do online evaluations of your application by publishing evaluation scores to telemetry and monitoring dashboards.

## Comprehensive evaluation metrics

The evaluation libraries were built in collaboration with data science researchers from Microsoft and GitHub, and were tested on popular Microsoft Copilot experiences. The following sections show the built-in [quality](#quality-evaluators), [NLP](#nlp-evaluators), and [safety](#safety-evaluators) evaluators and the metrics they measure.

You can also customize to add your own evaluations by implementing the <xref:Microsoft.Extensions.AI.Evaluation.IEvaluator> interface.

### Quality evaluators

Quality evaluators measure response quality. They use an LLM to perform the evaluation.

| Evaluator type                                                       | Metric      | Description |
|----------------------------------------------------------------------|-------------|-------------|
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.RelevanceEvaluator> | `Relevance` | Evaluates how relevant a response is to a query |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.CompletenessEvaluator> | `Completeness` | Evaluates how comprehensive and accurate a response is |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.RetrievalEvaluator> | `Retrieval` | Evaluates performance in retrieving information for additional context |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.FluencyEvaluator> | `Fluency` | Evaluates grammatical accuracy, vocabulary range, sentence complexity, and overall readability|
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.CoherenceEvaluator> | `Coherence` | Evaluates the logical and orderly presentation of ideas |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.EquivalenceEvaluator> | `Equivalence` | Evaluates the similarity between the generated text and its ground truth with respect to a query |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.GroundednessEvaluator> | `Groundedness` | Evaluates how well a generated response aligns with the given context |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.RelevanceTruthAndCompletenessEvaluator>† | `Relevance (RTC)`, `Truth (RTC)`, and `Completeness (RTC)` | Evaluates how relevant, truthful, and complete a response is |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.IntentResolutionEvaluator> | `Intent Resolution` | Evaluates an AI system's effectiveness at identifying and resolving user intent (agent-focused) |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.TaskAdherenceEvaluator> | `Task Adherence` | Evaluates an AI system's effectiveness at adhering to the task assigned to it (agent-focused) |
| <xref:Microsoft.Extensions.AI.Evaluation.Quality.ToolCallAccuracyEvaluator> | `Tool Call Accuracy` | Evaluates an AI system's effectiveness at using the tools supplied to it (agent-focused) |

† This evaluator is marked [experimental](../../fundamentals/syslib-diagnostics/experimental-overview.md).

### NLP evaluators

NLP evaluators evaluate the quality of an LLM response by comparing it to a reference response using natural language processing (NLP) techniques. These evaluators aren't LLM or AI-based; instead, they use older NLP techniques to perform text comparisons.

| Evaluator type                                                            | Metric             | Description |
|---------------------------------------------------------------------------|--------------------|-------------|
| <xref:Microsoft.Extensions.AI.Evaluation.NLP.BLEUEvaluator>  | `BLEU` | Evaluates a response by comparing it to one or more reference responses using the bilingual evaluation understudy (BLEU) algorithm. This algorithm is commonly used to evaluate the quality of machine-translation or text-generation tasks.  |
| <xref:Microsoft.Extensions.AI.Evaluation.NLP.GLEUEvaluator> | `GLEU` | Measures the similarity between the generated response and one or more reference responses using the Google BLEU (GLEU) algorithm, a variant of the BLEU algorithm that's optimized for sentence-level evaluation. |
| <xref:Microsoft.Extensions.AI.Evaluation.NLP.F1Evaluator> | `F1` | Evaluates a response by comparing it to a reference response using the *F1* scoring algorithm (the ratio of the number of shared words between the generated response and the reference response). |

### Safety evaluators

Safety evaluators check for presence of harmful, inappropriate, or unsafe content in a response. They rely on the Foundry Evaluation service, which uses a model that's fine tuned to perform evaluations.

| Evaluator type                                                            | Metric             | Description |
|---------------------------------------------------------------------------|--------------------|-------------|
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.GroundednessProEvaluator> | `Groundedness Pro` | Uses a fine-tuned model hosted behind the Foundry Evaluation service to evaluate how well a generated response aligns with the given context |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.ProtectedMaterialEvaluator> | `Protected Material` | Evaluates response for the presence of protected material |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.UngroundedAttributesEvaluator> | `Ungrounded Attributes` | Evaluates a response for the presence of content that indicates ungrounded inference of human attributes |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.HateAndUnfairnessEvaluator>† | `Hate And Unfairness` | Evaluates a response for the presence of content that's hateful or unfair |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.SelfHarmEvaluator>† | `Self Harm` | Evaluates a response for the presence of content that indicates self harm |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.ViolenceEvaluator>† | `Violence` | Evaluates a response for the presence of violent content |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.SexualEvaluator>† | `Sexual` | Evaluates a response for the presence of sexual content |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.CodeVulnerabilityEvaluator> | `Code Vulnerability` | Evaluates a response for the presence of vulnerable code |
| <xref:Microsoft.Extensions.AI.Evaluation.Safety.IndirectAttackEvaluator> | `Indirect Attack` | Evaluates a response for the presence of indirect attacks, such as manipulated content, intrusion, and information gathering |

† In addition, the <xref:Microsoft.Extensions.AI.Evaluation.Safety.ContentHarmEvaluator> provides single-shot evaluation for the four metrics supported by `HateAndUnfairnessEvaluator`, `SelfHarmEvaluator`, `ViolenceEvaluator`, and `SexualEvaluator`.

## Cached responses

The library uses *response caching* functionality, which means responses from the AI model are persisted in a cache. In subsequent runs, if the request parameters (prompt and model) are unchanged, responses are then served from the cache to enable faster execution and lower cost.

## Reporting

The library contains support for storing evaluation results and generating reports. The following image shows an example report in an Azure DevOps pipeline:


The `dotnet aieval` tool, which ships as part of the `Microsoft.Extensions.AI.Evaluation.Console` package, includes functionality for generating reports and managing the stored evaluation data and cached responses. For more information, see [Generate a report](evaluate-with-reporting.md#generate-a-report).

## Configuration

The libraries are designed to be flexible. You can pick the components that you need. For example, you can disable response caching or tailor reporting to work best in your environment. You can also customize and configure your evaluations, for example, by adding customized metrics and reporting options.

## Samples

For a more comprehensive tour of the functionality and APIs available in the Microsoft.Extensions.AI.Evaluation libraries, see the [API usage examples (dotnet/ai-samples repo)](https://github.com/dotnet/ai-samples/blob/main/src/microsoft-extensions-ai-evaluation/api/). These examples are structured as a collection of unit tests. Each unit test showcases a specific concept or API and builds on the concepts and APIs showcased in previous unit tests.

## See also

- [Evaluation of generative AI apps (Foundry)](/azure/ai-studio/concepts/evaluation-approach-gen-ai)

---
title: Responsible AI with .NET
description: Learn what responsible AI is and how you can use .NET to evaluate the safety of your AI apps.
ms.date: 09/08/2025
ai-usage: ai-assisted
---

# Responsible AI with .NET

*Responsible AI* refers to the practice of designing, developing, and deploying artificial intelligence systems in a way that is ethical, transparent, and aligned with human values. It emphasizes fairness, accountability, privacy, and safety to ensure that AI technologies benefit individuals and society as a whole. As AI becomes increasingly integrated into applications and decision-making processes, prioritizing responsible AI is of utmost importance.

Microsoft has identified [six principles](https://www.microsoft.com/ai/responsible-ai) for responsible AI:

- Fairness
- Reliability and safety
- Privacy and security
- Inclusiveness
- Transparency
- Accountability

If you're building an AI app with .NET, the [📦 Microsoft.Extensions.AI.Evaluation.Safety](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation.Safety) package provides evaluators to help ensure that the responses your app generates, both text and image, meet the standards for responsible AI. The evaluators can also detect problematic content in user input. These safety evaluators use the [Microsoft Foundry Evaluation service](/azure/ai-foundry/concepts/evaluation-evaluators/risk-safety-evaluators) to perform evaluations. They include metrics for hate and unfairness, groundedness, ungrounded inference of human attributes, and the presence of:

- Protected material
- Self-harm content
- Sexual content
- Violent content
- Vulnerable code (text-based only)
- Indirect attacks (text-based only)

For more information about the safety evaluators, see [Safety evaluators](libraries.md#safety-evaluators). To get started with the Microsoft.Extensions.AI.Evaluation.Safety evaluators, see [Tutorial: Evaluate response safety with caching and reporting](evaluate-safety.md).

## See also

- [Responsible AI at Microsoft](https://www.microsoft.com/ai/responsible-ai)
- [Training: Embrace responsible AI principles and practices](/training/modules/embrace-responsible-ai-principles-practices/)
- [Foundry Evaluation service](/azure/ai-foundry/concepts/evaluation-evaluators/risk-safety-evaluators)
- [Azure AI Content Safety](/azure/ai-services/content-safety/overview)

---
title: Access data in AI functions
description: Learn how to pass data to AIFunction objects and how to access the data within the function delegate.
ms.date: 11/17/2025
---

# Access data in AI functions

When you create AI functions, you might need to access contextual data beyond the parameters provided by the AI model. The `Microsoft.Extensions.AI` library provides several mechanisms to pass data to function delegates.

## `AIFunction` class

The <xref:Microsoft.Extensions.AI.AIFunction> type represents a function that can be described to an AI service and invoked. You can create `AIFunction` objects by calling one of the <xref:Microsoft.Extensions.AI.AIFunctionFactory.Create*?displayProperty=nameWithType> overloads. But <xref:Microsoft.Extensions.AI.AIFunction> is also a base class, and you can derive from it and implement your own AI function type. <xref:Microsoft.Extensions.AI.DelegatingAIFunction> provides an easy way to wrap an existing `AIFunction` and layer in additional functionality, including capturing additional data to be used.

## Pass data

You can associate data with the function at the time it's created, either via closure or via <xref:Microsoft.Extensions.AI.ChatOptions.AdditionalProperties>. If you're creating your own function, you can populate `AdditionalProperties` however you want. If you use <xref:Microsoft.Extensions.AI.AIFunctionFactory> to create the function, you can populate data using <xref:Microsoft.Extensions.AI.AIFunctionFactoryOptions.AdditionalProperties?displayProperty=nameWithType>.

You can also capture any references to data as part of the delegate provided to `AIFunctionFactory`. That is, you can bake in whatever you want to reference as part of the `AIFunction` itself.

## Access data in function delegates

You might call your `AIFunction` directly, or you might call it indirectly by using <xref:Microsoft.Extensions.AI.FunctionInvokingChatClient>. The following sections describe how to access argument data using either approach.

### Manual function invocation

If you manually invoke an <xref:Microsoft.Extensions.AI.AIFunction> by calling <xref:Microsoft.Extensions.AI.AIFunction.InvokeAsync(Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)?displayProperty=nameWithType>, you pass in <xref:Microsoft.Extensions.AI.AIFunctionArguments>. The <xref:Microsoft.Extensions.AI.AIFunctionArguments> type includes:

- A dictionary of named arguments.
- <xref:Microsoft.Extensions.AI.AIFunctionArguments.Context>: An arbitrary `IDictionary<object, object>` for passing additional ambient data into the function.
- <xref:Microsoft.Extensions.AI.AIFunctionArguments.Services>: An <xref:System.IServiceProvider> that lets the `AIFunction` resolve arbitrary state from a [dependency injection (DI)](../../core/extensions/dependency-injection/overview.md) container.

If you want to access either the `AIFunctionArguments` or the `IServiceProvider` from within your <xref:Microsoft.Extensions.AI.AIFunctionFactory.Create*?displayProperty=nameWithType> delegate, create a parameter typed as `IServiceProvider` or `AIFunctionArguments`. That parameter will be bound to the relevant data from the `AIFunctionArguments` passed to `AIFunction.InvokeAsync()`.

The following code shows an example:


<xref:System.Threading.CancellationToken> is also special-cased: if the `AIFunctionFactory.Create` delegate or lambda has a `CancellationToken` parameter, it will be bound to the `CancellationToken` that was passed to `AIFunction.InvokeAsync()`.

### Invocation through `FunctionInvokingChatClient`

<xref:Microsoft.Extensions.AI.FunctionInvokingChatClient> publishes state about the current invocation to <xref:Microsoft.Extensions.AI.FunctionInvokingChatClient.CurrentContext?displayProperty=nameWithType>, including not only the arguments, but all of the input `ChatMessage` objects, the <xref:Microsoft.Extensions.AI.ChatOptions>, and details on which function is being invoked (out of how many). You can add any data you want into <xref:Microsoft.Extensions.AI.ChatOptions.AdditionalProperties?displayProperty=nameWithType> and extract that inside of your `AIFunction` from `FunctionInvokingChatClient.CurrentContext.Options.AdditionalProperties`.

The following code shows an example:


#### Dependency injection

If you use <xref:Microsoft.Extensions.AI.FunctionInvokingChatClient> to invoke functions automatically, that client configures an <xref:Microsoft.Extensions.AI.AIFunctionArguments> object that it passes into the `AIFunction`. Because `AIFunctionArguments` includes the `IServiceProvider` that the `FunctionInvokingChatClient` was itself provided with, if you construct your client using standard DI means, that `IServiceProvider` is passed all the way into your `AIFunction`. At that point, you can query it for anything you want from DI.

## Advanced techniques

If you want more fine-grained control over how parameters are bound, you can use <xref:Microsoft.Extensions.AI.AIFunctionFactoryOptions.ConfigureParameterBinding?displayProperty=nameWithType>, which puts you in control over how each parameter is populated. For example, the [MCP C# SDK uses this technique](https://github.com/modelcontextprotocol/csharp-sdk/blob/d344c651203841ec1c9e828736d234a6e4aebd07/src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs#L83-L107) to automatically bind parameters from DI.

If you use the <xref:Microsoft.Extensions.AI.AIFunctionFactory.Create(System.Reflection.MethodInfo,System.Func{Microsoft.Extensions.AI.AIFunctionArguments,System.Object},Microsoft.Extensions.AI.AIFunctionFactoryOptions)?displayProperty=nameWithType> overload, you can also run your own arbitrary logic when you create the target object that the instance method will be called on, each time. And you can do whatever you want to configure that instance.

---
title: "Authenticate an Azure hosted .NET app to Azure OpenAI using Microsoft Entra ID"
description: "Learn how to authenticate your Azure hosted .NET app to an Azure OpenAI resource using Microsoft Entra ID."
author: alexwolfmsft
ms.author: alexwolf
ms.topic: how-to
ms.date: 03/04/2026
ai-usage: ai-assisted
zone_pivot_groups: azure-interface
#customer intent: As a .NET developer, I want authenticate and authorize my App Service to Azure OpenAI by using Microsoft Entra so that I can securely use AI in my .NET application.
---

# Authenticate to Azure OpenAI from an Azure hosted app using Microsoft Entra ID

This article demonstrates how to use [Microsoft Entra ID managed identities](/azure/app-service/overview-managed-identity) and the [Microsoft.Extensions.AI library](../microsoft-extensions-ai.md) to authenticate an Azure hosted app to an Azure OpenAI resource.

A managed identity from Microsoft Entra ID lets your app access other Microsoft Entra protected resources such as Azure OpenAI. Azure manages the identity and doesn't require you to provision, manage, or rotate any secrets.

## Prerequisites

* An Azure account that has an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
* [.NET SDK](https://dotnet.microsoft.com/download/visual-studio-sdks)
* [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource)
* [Create and deploy a .NET application to App Service](/azure/app-service/quickstart-dotnetcore)

## Add a managed identity to App Service

Managed identities provide an automatically managed identity in Microsoft Entra ID for applications to use when connecting to resources that support Microsoft Entra authentication. Applications can use managed identities to obtain Microsoft Entra tokens without having to manage any credentials. You can assign two types of identities to your application:

* A **system-assigned identity** is tied to your application and is deleted if your app is deleted. An app can have only one system-assigned identity.
* A **user-assigned identity** is a standalone Azure resource that can be assigned to your app. An app can have multiple user-assigned identities.

:::zone target="docs" pivot="azure-portal"

# [System-assigned](#tab/system-assigned)

1. Go to your app's page in the [Azure portal](https://aka.ms/azureportal), and then scroll down to the **Settings** group.
1. Select **Identity**.
1. On the **System assigned** tab, toggle *Status* to **On**, and then select **Save**.


    > [!NOTE]
    > The preceding screenshot demonstrates this process on an Azure App Service, but the steps are similar on other hosts such as Azure Container Apps.

## [User-assigned](#tab/user-assigned)

To add a user-assigned identity to your app, create the identity, and then add its resource identifier to your app config.

1. Create a user-assigned managed identity resource by following [these instructions](/azure/active-directory/managed-identities-azure-resources/how-to-manage-ua-identity-portal#create-a-user-assigned-managed-identity).
1. In the left navigation pane of your app's page, scroll down to the **Settings** group.
1. Select **Identity**.
1. Select **User assigned** > **Add**.
1. Locate the identity that you created earlier, select it, and then select **Add**.

    > [!IMPORTANT]
    > After you select **Add**, the app restarts.


    > [!NOTE]
    > The preceding screenshot demonstrates this process on an Azure App Service, but the steps are similar on other hosts such as Azure Container Apps.

---

:::zone-end

:::zone target="docs" pivot="azure-cli"

## [System-assigned](#tab/system-assigned)

Run the `az webapp identity assign` command to create a system-assigned identity:

```azurecli
az webapp identity assign --name <appName> --resource-group <groupName>
```

## [User-assigned](#tab/user-assigned)

1. Create a user-assigned identity:

    ```azurecli
    az identity create --resource-group <groupName> --name <identityName>
    ```

1. Assign the identity to your app:

    ```azurecli
    az webapp identity assign --resource-group <groupName> --name <appName> --identities <identityId>
    ```

---

:::zone-end

## Add an Azure OpenAI user role to the identity

:::zone target="docs" pivot="azure-portal"

1. In the [Azure portal](https://aka.ms/azureportal), go to the scope that you want to grant **Azure OpenAI** access to. The scope can be a **Management group**, **Subscription**, **Resource group**, or a specific **Azure OpenAI** resource.
1. In the left navigation pane, select **Access control (IAM)**.
1. Select **Add**, then select **Add role assignment**.


1. On the **Role** tab, select the **Cognitive Services OpenAI User** role.
1. On the **Members** tab, select the managed identity.
1. On the **Review + assign** tab, select **Review + assign** to assign the role.

:::zone-end

:::zone target="docs" pivot="azure-cli"

Use the Azure CLI to assign the Cognitive Services OpenAI User role to your managed identity at different scopes.

# [Resource](#tab/resource)

```azurecli
az role assignment create --assignee "<managedIdentityObjectID>" \
--role "Cognitive Services OpenAI User" \
--scope "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/<providerName>/<resourceType>/<resourceSubType>/<resourceName>"
```

# [Resource group](#tab/resource-group)

```azurecli
az role assignment create --assignee "<managedIdentityObjectID>" \
--role "Cognitive Services OpenAI User" \
--scope "/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>"
```

# [Subscription](#tab/subscription)

```azurecli
az role assignment create --assignee "<managedIdentityObjectID>" \
--role "Cognitive Services OpenAI User" \
--scope "/subscriptions/<subscriptionId>"
```

# [Management group](#tab/management-group)

```azurecli
az role assignment create --assignee "<managedIdentityObjectID>" \
--role "Cognitive Services OpenAI User" \
--scope "/providers/Microsoft.Management/managementGroups/<managementGroupName>"
```

---

:::zone-end

## Implement identity authentication in your app code

1. Add the following NuGet packages to your app:

    ```dotnetcli
    dotnet add package Azure.Identity
    dotnet add package Azure.AI.OpenAI
    dotnet add package Microsoft.Extensions.Azure
    dotnet add package Microsoft.Extensions.AI
    dotnet add package Microsoft.Extensions.AI.OpenAI
    ```

    The preceding packages each handle the following concerns for this scenario:

    - **[Azure.Identity](https://www.nuget.org/packages/Azure.Identity)**: Provides core functionality to work with Microsoft Entra ID
    - **[Azure.AI.OpenAI](https://www.nuget.org/packages/Azure.AI.OpenAI)**: Lets your app interface with the Azure OpenAI service
    - **[Microsoft.Extensions.Azure](https://www.nuget.org/packages/Microsoft.Extensions.Azure)**: Provides helper extensions to register services for dependency injection
    - **[Microsoft.Extensions.AI](https://www.nuget.org/packages/Microsoft.Extensions.AI)**: Provides AI abstractions for common AI tasks
    - **[Microsoft.Extensions.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI)**: Lets you use OpenAI service types as AI abstractions provided by **Microsoft.Extensions.AI**

1. In the `Program.cs` file of your app, create a `DefaultAzureCredential` object to discover and configure available credentials:


1. Create an AI service and register it with the service collection:


1. Inject the registered service for use in your endpoints:


    > [!TIP]
    > For more information about ASP.NET Core dependency injection and registering other AI service types, see the Azure SDK for .NET [dependency injection](../../azure/sdk/dependency-injection.md) documentation.

## Related content

* [How to use managed identities for App Service and Azure Functions](/azure/app-service/overview-managed-identity)
* [Role-based access control for Azure OpenAI Service](/azure/ai-services/openai/how-to/role-based-access-control)

---
title: "Manage Azure OpenAI content filtering in a .NET app"
description: "Learn how to manage Azure OpenAI content filtering programmatically in a .NET app using the Azure OpenAI client library."
ms.topic: how-to
ms.date: 03/04/2026
ai-usage: ai-assisted
---

# Work with Azure OpenAI content filtering in a .NET app

This article shows how to handle content filtering in a .NET app. Azure OpenAI Service includes a content filtering system that works alongside core models. It runs both the prompt and completion through an ensemble of classification models to detect and take action on specific categories of potentially harmful content in both input prompts and output completions. Variations in API configurations and application design might affect completions and thus filtering behavior.

For a deeper exploration of content filtering concepts and concerns, see the [Content Filtering](/azure/ai-services/openai/concepts/content-filter) documentation.

## Prerequisites

* An Azure account that has an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
* [.NET SDK](https://dotnet.microsoft.com/download/visual-studio-sdks)
* [Create and deploy an Azure OpenAI Service resource](/azure/ai-services/openai/how-to/create-resource)

## Configure and test the content filter

To use the sample code in this article, you need to create and assign a content filter to your OpenAI model.

1. [Create and assign a content filter](/azure/ai-services/openai/how-to/content-filters) to your provisioned model.

1. Add the [`Azure.AI.OpenAI`](https://www.nuget.org/packages/Azure.AI.OpenAI) NuGet package to your project.

   ```dotnetcli
   dotnet add package Azure.AI.OpenAI
   ```

   Or, in .NET 10+:

   ```dotnetcli
   dotnet package add Azure.AI.OpenAI
   ```

1. Create a simple chat completion flow in your .NET app using the `AzureOpenAiClient`. Replace the `YOUR_MODEL_ENDPOINT` and `YOUR_MODEL_DEPLOYMENT_NAME` values with your own.


1. Replace the `YOUR_PROMPT` placeholder with your own message and run the app to experiment with content filtering results. If you enter a prompt the AI considers unsafe, Azure OpenAI returns a `400 Bad Request` code. The app prints a message in the console similar to the following:

```output
The response was filtered due to the prompt triggering Azure OpenAI's content management policy...
```

## Related content

* [Create and assign a content filter](/azure/ai-services/openai/how-to/content-filters)
* [Content Filtering concepts](/azure/ai-services/openai/concepts/content-filter)
* [Create a chat app](../quickstarts/prompt-model.md)

---
title: Handle invalid function input from AI models
description: Learn strategies to handle invalid function input when AI models provide incorrect or malformed function call parameters.
ms.date: 01/05/2026
ai-usage: ai-assisted
---

# Handle invalid function input from AI models

When AI models call functions in your .NET code, they might sometimes provide invalid input that doesn't match the expected schema. The `Microsoft.Extensions.AI` library provides several strategies to handle these scenarios gracefully.

## Common scenarios for invalid input

AI models can provide invalid function call input in several ways:

- Missing required parameters.
- Incorrect data types (for example, sending a string when an integer is expected).
- Malformed JSON that can't be deserialized.

Without proper error handling, these issues can cause your application to fail or provide poor user experiences.

## Enable detailed error messages

By default, when a function invocation fails, the AI model receives a generic error message. You can enable detailed error reporting using the <xref:Microsoft.Extensions.AI.FunctionInvokingChatClient.IncludeDetailedErrors?displayProperty=nameWithType> property. When this property is set to `true` and an error occurs during function invocation, the full exception message is added to the chat history. This allows the AI model to see what went wrong and potentially self-correct in subsequent attempts.


> [!NOTE]
> Setting `IncludeDetailedErrors` to `true` can expose internal system details to the AI model and potentially to end users. Ensure exception messages don't contain secrets, connection strings, or other sensitive information. To avoid leaking sensitive information, consider disabling detailed errors in production environments.

## Implement custom error handling

For more control over error handling, you can set a custom <xref:Microsoft.Extensions.AI.FunctionInvokingChatClient.FunctionInvoker?displayProperty=nameWithType> delegate. This allows you to intercept function calls, catch exceptions, and return custom error messages to the AI model.

The following example shows how to implement a custom function invoker that catches serialization errors and provides helpful feedback:


By returning descriptive error messages instead of throwing exceptions, you allow the AI model to see what went wrong and try again with corrected input.

### Best practices for error messages

When returning error messages to enable AI self-correction, provide clear, actionable feedback:

- **Be specific**: Explain exactly what was wrong with the input.
- **Provide examples**: Show the expected format or valid values.
- **Use consistent format**: Help the AI model learn from patterns.
- **Log errors**: Track error patterns for debugging and monitoring.

## Use strict JSON schema (OpenAI only)

When using OpenAI models, you can enable strict JSON schema mode to enforce that the model's output strictly adheres to your function's schema. This helps prevent type mismatches and missing required fields.

Enable strict mode using the `Strict` additional property on your function metadata. When enabled, OpenAI models try to ensure their output matches your schema exactly:


For the latest list of models that support strict JSON schema, check the [OpenAI documentation](https://platform.openai.com/docs/guides/structured-outputs).

### Limitations

While strict mode significantly improves schema adherence, keep these limitations in mind:

- Not all JSON Schema features are supported in strict mode.
- Complex schemas might still produce occasional errors.
- Always validate outputs even with strict mode enabled.
- Strict mode is OpenAI-specific and doesn't apply to other AI providers.

## Next steps

- [Access data in AI functions](access-data-in-functions.md)
- [Execute a local .NET function](../quickstarts/use-function-calling.md)
- [Build a chat app](../quickstarts/build-chat-app.md)

---
title: Use Microsoft.ML.Tokenizers for text tokenization
description: Learn how to use the Microsoft.ML.Tokenizers library to tokenize text for AI models, manage token counts, and work with various tokenization algorithms.
ms.topic: how-to
ms.date: 10/29/2025
ai-usage: ai-assisted
---
# Use Microsoft.ML.Tokenizers for text tokenization

The [Microsoft.ML.Tokenizers](https://www.nuget.org/packages/Microsoft.ML.Tokenizers) library provides a comprehensive set of tools for tokenizing text in .NET applications. Tokenization is essential when you work with large language models (LLMs), as it allows you to manage token counts, estimate costs, and preprocess text for AI models.

This article shows you how to use the library's key features and work with different tokenizer models.

## Prerequisites

- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later

> [!NOTE]
> The Microsoft.ML.Tokenizers library also supports .NET Standard 2.0, making it compatible with .NET Framework 4.6.1 and later.

## Install the package

Install the Microsoft.ML.Tokenizers NuGet package:

```dotnetcli
dotnet add package Microsoft.ML.Tokenizers
```

For Tiktoken models (like GPT-4), you also need to install the corresponding data package:

```dotnetcli
dotnet add package Microsoft.ML.Tokenizers.Data.O200kBase
```

## Key features

The Microsoft.ML.Tokenizers library provides:

- **Extensible tokenizer architecture**: Allows specialization of Normalizer, PreTokenizer, Model/Encoder, and Decoder components.
- **Multiple tokenization algorithms**: Supports BPE (byte-pair encoding), Tiktoken, Llama, CodeGen, and more.
- **Token counting and estimation**: Helps manage costs and context limits when working with AI services.
- **Flexible encoding options**: Provides methods to encode text to token IDs, count tokens, and decode tokens back to text.

## Use Tiktoken tokenizer

The Tiktoken tokenizer is commonly used with OpenAI models like GPT-4. The following example shows how to initialize a Tiktoken tokenizer and perform common operations:


For better performance, you should cache and reuse the tokenizer instance throughout your app.

When you work with LLMs, you often need to manage text within token limits. The following example shows how to trim text to a specific token count:


## Use Llama tokenizer

The Llama tokenizer is designed for the Llama family of models. It requires a tokenizer model file, which you can download from model repositories like Hugging Face:


All tokenizers support advanced encoding options, such as controlling normalization and pretokenization:


## Use BPE tokenizer

*Byte-pair encoding* (BPE) is the underlying algorithm used by many tokenizers, including Tiktoken. BPE was initially developed as an algorithm to compress texts, and then used by OpenAI for tokenization when it pretrained the GPT model. The following example demonstrates BPE tokenization:


The library also provides specialized tokenizers like <xref:Microsoft.ML.Tokenizers.BpeTokenizer> and <xref:Microsoft.ML.Tokenizers.EnglishRobertaTokenizer> that you can configure with custom vocabularies for specific models.

For more information about BPE, see [Byte-pair encoding tokenization](https://huggingface.co/learn/llm-course/chapter6/5).

## Common tokenizer operations

All tokenizers in the library implement the <xref:Microsoft.ML.Tokenizers.Tokenizer> base class. The following table shows the available methods.

| Method                                                | Description                          |
|-------------------------------------------------------|--------------------------------------|
| <xref:Microsoft.ML.Tokenizers.Tokenizer.EncodeToIds*> | Converts text to a list of token IDs. |
| <xref:Microsoft.ML.Tokenizers.Tokenizer.Decode*>      | Converts token IDs back to text.      |
| <xref:Microsoft.ML.Tokenizers.Tokenizer.CountTokens*> | Returns the number of tokens in a text string. |
| <xref:Microsoft.ML.Tokenizers.Tokenizer.EncodeToTokens*> | Returns detailed token information including values and IDs. |
| <xref:Microsoft.ML.Tokenizers.Tokenizer.GetIndexByTokenCount*> | Finds the character index for a specific token count from the start. |
| <xref:Microsoft.ML.Tokenizers.Tokenizer.GetIndexByTokenCountFromEnd*> | Finds the character index for a specific token count from the end. |

## Migrate from other libraries

If you're currently using `DeepDev.TokenizerLib` or `SharpToken`, consider migrating to Microsoft.ML.Tokenizers. The library has been enhanced to cover scenarios from those libraries and provides better performance and support. For migration guidance, see the [migration guide](https://github.com/dotnet/machinelearning/blob/main/docs/code/microsoft-ml-tokenizers-migration-guide.md).

## Related content

- [Understanding tokens](../conceptual/understanding-tokens.md)
- [Microsoft.ML.Tokenizers API reference](/dotnet/api/microsoft.ml.tokenizers)
- [Microsoft.ML.Tokenizers NuGet package](https://www.nuget.org/packages/Microsoft.ML.Tokenizers)

---
title: Quickstart - Create a .NET AI app using the AI app template
description: Create a .NET AI app to chat with custom data using the AI app template extensions and the Microsoft.Extensions.AI libraries
ms.date: 03/04/2026
ms.topic: quickstart
zone_pivot_groups: meai-targets
ai-usage: ai-assisted
---

# Create a .NET AI app to chat with custom data using the AI app template extensions

In this quickstart, you learn how to create a .NET AI app to chat with custom data using the .NET AI app template. The template is designed to streamline the getting started experience for building AI apps with .NET by handling common setup tasks and configurations for you.

:::zone target="docs" pivot="github-models"

[!INCLUDE [ai-templates-github-models](includes/ai-templates-github-models.md)]

:::zone-end

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [ai-templates-azure-openai](includes/ai-templates-azure-openai.md)]

:::zone-end

:::zone target="docs" pivot="openai"

[!INCLUDE [ai-templates-openai](includes/ai-templates-openai.md)]

:::zone-end

:::zone target="docs" pivot="ollama"

[!INCLUDE [ai-templates-ollama](includes/ai-templates-ollama.md)]

:::zone-end

## Run and test the app

1. Select the run button at the top of Visual Studio to launch the app. After a moment, you should see the following UI load in the browser:


1. Enter a prompt into the input box such as *"What are some essential tools in the survival kit?"* to ask your AI model a question about the ingested data from the example files.


    The app responds with an answer to the question and provides citations of where it found the data. You can click on one of the citations to be directed to the relevant section of the example files.

## Next steps

- [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

---
title: Quickstart - Build an AI chat app with .NET
description: Create a simple AI powered chat app using Microsoft.Extensions.AI and the OpenAI or Azure OpenAI SDKs
ms.date: 03/04/2026
ms.topic: quickstart
zone_pivot_groups: openai-library
ai-usage: ai-assisted
---

# Build an AI chat app with .NET

In this quickstart, you learn how to create a conversational .NET console chat app using 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.

:::zone target="docs" pivot="openai"

[!INCLUDE [openai-prereqs](includes/prerequisites-openai.md)]

:::zone-end

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]

:::zone-end

## Create the app

Complete the following steps to create a .NET console app to connect to an AI model.

1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:

    ```dotnetcli
    dotnet new console -o ChatAppAI
    ```

1. Change directory into the app folder:

    ```dotnetcli
    cd ChatAppAI
    ```

1. Install the required packages:

    :::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 --prerelease
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    ```

    :::zone-end

    :::zone target="docs" pivot="openai"

    ```bash
    dotnet add package 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 .
    ```

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [create-ai-service](includes/create-ai-service.md)]

:::zone-end

:::zone target="docs" pivot="openai"

## Configure the app

1. Navigate to the root of your .NET project from a terminal or command prompt.

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>
    ```

:::zone-end

## Add the app code

This app uses the [`Microsoft.Extensions.AI`](https://www.nuget.org/packages/Microsoft.Extensions.AI/) package to send and receive requests to the AI model. The app provides users with information about hiking trails.

1. In the `Program.cs` file, add the following code to connect and authenticate to the AI model.

    :::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 Foundry tools with .NET](../azure-ai-services-authentication.md).

    :::zone-end

    :::zone target="docs" pivot="openai"


    :::zone-end

1. Create a system prompt to provide the AI model with initial role context and instructions about hiking recommendations:


1. Create a conversational loop that accepts an input prompt from the user, sends the prompt to the model, and prints the response completion:


1. Use the `dotnet run` command to run the app:

    ```dotnetcli
    dotnet run
    ```

    The app prints out the completion response from the AI model. Send additional follow up prompts and ask other questions to experiment with the AI chat functionality.

:::zone target="docs" pivot="azure-openai"

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and GPT-4 model deployment.

1. In the [Azure portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

:::zone-end

## Next steps

- [Quickstart - Chat with a local AI model](chat-local-model.md)
- [Generate images from text using AI](text-to-image.md)

---
title: Quickstart - Create a minimal MCP client using .NET
description: Learn to create a minimal MCP client and connect it to an MCP server using .NET
ms.date: 03/04/2026
ms.topic: quickstart
author: alexwolfmsft
ai-usage: ai-assisted
---

# Create a minimal MCP client using .NET

In this quickstart, you build a minimal [Model Context Protocol (MCP)](../get-started-mcp.md) client using the [C# SDK for MCP](https://github.com/modelcontextprotocol/csharp-sdk). You also learn how to configure the client to connect to an MCP server, such as the one created in the [Build a minimal MCP server](build-mcp-server.md) quickstart.

## Prerequisites

- [.NET 8.0 SDK or higher](https://dotnet.microsoft.com/download)
- [Visual Studio Code](https://code.visualstudio.com/)

> [!NOTE]
> The MCP client you build in the sections ahead connects to the sample MCP server from the [Build a minimal MCP server](build-mcp-server.md) quickstart. You can also use your own MCP server if you provide your own connection configuration.

## Create the .NET host app

Complete the following steps to create a .NET console app. The app acts as a host for an MCP client that connects to an MCP server.

### Create the project

1. In a terminal window, navigate to the directory where you want to create your app, and create a new console app with the `dotnet new` command:

   ```console
   dotnet new console -n MCPHostApp
   ```

1. Navigate into the newly created project folder:

   ```console
   cd MCPHostApp
   ```

1. Run the following commands to add the necessary NuGet packages:

   ```console
   dotnet add package Azure.AI.OpenAI --prerelease
   dotnet add package Azure.Identity
   dotnet add package Microsoft.Extensions.AI
   dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
   dotnet add package ModelContextProtocol --prerelease
   ```

1. Open the project folder in your editor of choice, such as Visual Studio Code:

    ```console
    code .
    ```

### Add the app code

Replace the contents of `Program.cs` with the following code:


The preceding code accomplishes the following tasks:

- Initializes an `IChatClient` abstraction using the [`Microsoft.Extensions.AI`](../microsoft-extensions-ai.md) libraries.
- Creates an MCP client and configures it to connect to your MCP server.
- Retrieves and displays a list of available tools from the MCP server, which is a standard MCP function.
- Implements a conversational loop that processes user prompts and utilizes the tools for responses.

## Run and test the app

Complete the following steps to test your .NET host app:

1. In a terminal window open to the root of your project, run the following command to start the app:

   ```console
   dotnet run
   ```

1. Once the app is running, enter a prompt to run the **ReverseEcho** tool:

    ```console
    Reverse the following: "Hello, minimal MCP server!"
    ```

1. Verify that the server responds with the echoed message:

    ```output
    !revres PCM laminim ,olleH
    ```

## Related content

[Get started with .NET AI and the Model Context Protocol](../get-started-mcp.md)

---
title: Quickstart - Create a minimal MCP server and publish to NuGet
description: Learn to create and connect to a minimal MCP server using C# and publish it to NuGet.
ms.date: 03/04/2026
ms.topic: quickstart
author: alexwolfmsft
ms.author: alexwolf
zone_pivot_groups: development-environment-one
ai-usage: ai-assisted
---

# Create a minimal MCP server using C# and publish to NuGet

In this quickstart, you create a minimal Model Context Protocol (MCP) server using the [C# SDK for MCP](https://github.com/modelcontextprotocol/csharp-sdk), connect to it using GitHub Copilot, and publish it to NuGet (stdio transport only). MCP servers are services that expose capabilities to clients through the Model Context Protocol (MCP).

> [!NOTE]
> The `Microsoft.McpServer.ProjectTemplates` template package is currently in preview.

## Prerequisites

::: zone pivot="visualstudio"

- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet)
- [Visual Studio 2022 or higher](https://visualstudio.microsoft.com/)
- [GitHub Copilot](https://github.com/features/copilot)
- [NuGet.org account](https://www.nuget.org/users/account/LogOn)

::: zone-end

::: zone pivot="vscode"

- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet)
- [Visual Studio Code](https://code.visualstudio.com/) (optional)
- [C# Dev Kit extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit)
- [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) for Visual Studio Code
- [NuGet.org account](https://www.nuget.org/users/account/LogOn)

::: zone-end

::: zone pivot="cli"

- [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet)
- [Visual Studio Code](https://code.visualstudio.com/) (optional)
- [Visual Studio](https://visualstudio.microsoft.com/) (optional)
- [GitHub Copilot](https://github.com/features/copilot) / [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) for Visual Studio Code
- [NuGet.org account](https://www.nuget.org/users/account/LogOn)

::: zone-end

## Create the project

::: zone pivot="visualstudio"

1. In a terminal window, install the MCP Server template:

   ```dotnetcli
   dotnet new install Microsoft.McpServer.ProjectTemplates
   ```

    > [!NOTE]
    > .NET 10.0 SDK or a later version is required to install `Microsoft.McpServer.ProjectTemplates`.

1. Open Visual Studio, and select **Create a new project** in the start window (or select **File** > **New** > **Project/Solution** from inside Visual Studio).


1. In the **Create a new project** window, select **C#** from the Language list and **AI** from the **All project types** list.  After you apply the language and project type filters, select the **MCP Server App** template, and then select **Next**.


1. In the **Configure your new project** window, enter **MyMcpServer** in the **Project name** field.  Then, select **Next**.


1. In the **Additional information** window, you can configure the following options:

    - **Framework**: Select the target .NET framework.
    - **MCP Server Transport Type**: Choose between creating a **local** (stdio) or a **remote** (http) MCP server.
    - **Enable native AOT (Ahead-Of-Time) publish**: Enable your MCP server to be self-contained and compiled to native code. For more information, see the [Native AOT deployment guide](../../core/deploying/native-aot/index.md).
    - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#self-contained-deployment).

    Choose your preferred options or keep the default ones, and then select **Create**.


    Visual Studio opens your new project.

1. Update the `<PackageId>` in the `.csproj` file to be unique on NuGet.org, for example `<NuGet.org username>.SampleMcpServer`.

::: zone-end

::: zone pivot="vscode"

1. In a terminal window, install the MCP Server template:

   ```bash
   dotnet new install Microsoft.McpServer.ProjectTemplates
   ```

    > [!NOTE]
    > .NET 10.0 SDK or later is required to install `Microsoft.McpServer.ProjectTemplates`.

1. Open Visual Studio Code.

1. Go to the **Explorer** view and select **Create .NET Project**.  Alternatively, you can bring up the Command Palette using <kbd>Ctrl+Shift+P</kbd> (<kbd>Command+Shift+P</kbd> on MacOS) and then type ".NET" to find and select the **.NET: New Project** command.

    This action will bring up a dropdown list of .NET projects.


1. After selecting the command, use the Search bar in the Command Palette or scroll down to locate the **MCP Server App** template.


1. Select the location where you would like the new project to be created.

1. Give your new project a name, **MyMCPServer**. Press **Enter**.

1. Select your solution file format (`.sln` or `.slnx`).

1. Select **Template Options**.  Here, you can configure the following options:

    - **Framework**: Select the target .NET framework.
    - **MCP Server Transport Type**: Choose between creating a **local** (stdio) or a **remote** (http) MCP server.
    - **Enable native AOT (Ahead-Of-Time) publish**: Enable your MCP server to be self-contained and compiled to native code. For more information, see the [Native AOT deployment guide](../../core/deploying/native-aot/index.md).
    - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#self-contained-deployment).


    Choose your preferred options or keep the default ones, and then select **Create Project**.

    VS Code opens your new project.

1. Update the `<PackageId>` in the `.csproj` file to be unique on NuGet.org, for example `<NuGet.org username>.SampleMcpServer`.

::: zone-end

::: zone pivot="cli"

1. Create a new MCP server app with the `dotnet new mcpserver` command:

   ```bash
   dotnet new mcpserver -n SampleMcpServer
   ```

   By default, this command creates a self-contained tool package targeting all of the most common platforms that .NET is supported on. To see more options, use `dotnet new mcpserver --help`.

   Using the `dotnet new mcpserver --help` command gives you several template options you can add when creating a new MCP server:

    - **Framework**: Select the target .NET framework.
    - **MCP Server Transport Type**: Choose between creating a **local** (stdio) or a **remote** (http) MCP server.
    - **Enable native AOT (Ahead-Of-Time) publish**: Enable your MCP server to be self-contained and compiled to native code. For more information, see the [Native AOT deployment guide](../../core/deploying/native-aot/index.md).
    - **Enable self-contained publish**: Enable your MCP server to be published as a self-contained executable. For more information, see the [Self-contained deployment section of the .NET application publishing guide](../../core/deploying/index.md#self-contained-deployment).


1. Navigate to the `SampleMcpServer` directory:

   ```bash
   cd SampleMcpServer
   ```

1. Build the project:

   ```bash
   dotnet build
   ```

1. Update the `<PackageId>` in the `.csproj` file to be unique on NuGet.org, for example `<NuGet.org username>.SampleMcpServer`.

::: zone-end

## Tour the MCP Server Project

Creating your MCP server project via the template gives you the following major files:

* `Program.cs`: A file defining the application as an MCP server and registering MCP services such as transport type and MCP tools.  
  * Choosing the (default) **stdio** transport option in when creating the project, this file will be configured to define the MCP Server as a local one (that is, `.withStdioServerTransport()`).
  * Choosing the **http** transport option will configure this file to include remote transport-specific definitions (that is, `.withHttpServerTransport()`, `MapMcp()`).
* `RandomNumberTools.cs`: A class defining an example MCP server tool that returns a random number between user-specified min/max values.
* **[HTTP Transport Only]** `[MCPServerName].http`: A file defining the default host address for an HTTP MCP server and JSON-RPC communication.
* `server.json`: A file defining how and where your MCP server is published.

::: zone pivot="visualstudio"


::: zone-end

::: zone pivot="cli,vscode"


::: zone-end

## Configure the MCP server

::: zone pivot="visualstudio"

Configure GitHub Copilot for Visual Studio to use your custom MCP server.

1. In Visual Studio, select the GitHub Copilot icon in the top right corner and select **Open Chat Window**.

1. In the GitHub Copilot Chat window, click the **Select Tools** wrench icon followed by the plus icon in the top right corner.


1. In the **Add Custom MCP Server** dialog window, enter the following info:

    * **Destination**: Choose the scope of where your MCP server is configured:
        * **Solution** - The MCP server is available only across the active solution.
        * **Global** - The MCP server is available across all solutions.
    * **Server ID**: The unique name / identifier for your MCP server.
    * **Type**: The transport type of your MCP server (stdio or HTTP).
    * **Command (Stdio transport only)**: The command to run your stdio MCP server (that is, `dotnet run --project [relative path to .csproj file]`)
    * **URL (HTTP transport only)**: The address of your HTTP MCP server
    * **Environment Variables (optional)**


1. Select **Save**.  A `.mcp.json` file will be added to the specified destination.

**Stdio Transport `.mcp.json`**

Add the  relative path to your `.csproj` file under the "args" field.

   ```json
   {
     "inputs": [],
     "servers": {
       "MyMcpServer": {
         "type": "stdio",
         "command": "dotnet",
         "args": [
           "run",
           "--project",
           "<relative-path-to-project-file>"
         ]
       }
     }
   }
   ```

**HTTP Transport `.mcp.json`**

   ```json
   {
    "inputs": [],
     "servers": {
       "MyMCPServer": {
         "url": "http://localhost:6278",
         "type": "http",
         "headers": {}
       }
     }
   }
   ```

::: zone-end

::: zone pivot="vscode,cli"

Configure GitHub Copilot for Visual Studio Code to use your custom MCP server, either via the VS Code Command Palette or manually.

### Command Palette configuration

1. Open the Command Palette using <kbd>Ctrl+Shift+P</kbd> (<kbd>Command+Shift+P</kbd> on macOS). Search "mcp" to locate the `MCP: Add Server` command.

1. Select the type of MCP server to add (typically the transport type you selected at project creation).


1. If adding a **stdio** MCP server, enter a command and optional arguments.  For this example, use `dotnet run --project`.

    If adding an **HTTP** MCP server, enter the localhost or web address.

1. Enter a unique server ID (example: "MyMCPServer").

1. Select a configuration target:

    * **Global**: Make the MCP server available across all workspaces.  The generated `mcp.json` file will appear under your global user configuration.

    * **Workspace**: Make the MCP server available only from within the current workspace.  The generated `mcp.json` file will appear under the `.vscode` folder within your workspace.


1. After you complete the previous steps, an `.mcp.json` file will be created in the location specified by the configuration target.

**Stdio Transport `mcp.json`**

Add the relative path to your `.csproj` file under the "args" field.

   ```json
   {
     "servers": {
       "MyMcpServer": {
         "type": "stdio",
         "command": "dotnet",
         "args": [
           "run",
           "--project",
           "<relative-path-to-project-file>"
         ]
       }
     }
   }
   ```

**HTTP Transport `mcp.json`**

   ```json
   {
     "servers": {
       "MyMCPServer": {
         "url": "http://localhost:6278",
         "type": "http"
       }
     },
     "inputs": []
   }
   ```

### Manual configuration

1. Create a `.vscode` folder at the root of your project.
1. Add an `mcp.json` file in the `.vscode` folder with the following content:

   ```json
   {
     "servers": {
       "SampleMcpServer": {
         "type": "stdio",
         "command": "dotnet",
         "args": [
           "run",
           "--project",
           "<relative-path-to-project-file>"
         ]
       }
     }
   }
   ```

    > [!NOTE]
    > VS Code executes MCP servers from the workspace root. The `<relative-path-to-project-file>` placeholder should point to your .NET project file. For example, the value for this **SampleMcpServer** app would be `SampleMcpServer.csproj`.

1. Save the file.

::: zone-end

## Test the MCP server

::: zone pivot="visualstudio"

The MCP server template includes a tool called `get_random_number` you can use for testing and as a starting point for development.

1. Open GitHub Copilot chat in Visual Studio and switch to **Agent** mode.

1. Select the **Select tools** icon to verify your **MyMCPServer** is available with the sample tool listed.


1. Enter a prompt to run the **get_random_number** tool:

    ```console
    Give me a random number between 1 and 100.
    ```

1. GitHub Copilot requests permission to run the **get_random_number** tool for your prompt. Select **Continue** or use the arrow to select a more specific behavior:

    - **Current session** always runs the operation in the current GitHub Copilot Agent Mode session.
    - **Current solution** always runs the command for the current VS solution.
    - **Always allow** sets the operation to always run for any GitHub Copilot Agent Mode session.

1. Verify that the server responds with a random number:

    ```output
    Your random number is 42.
    ```

::: zone-end

::: zone pivot="vscode,cli"

The MCP server template includes a tool called `get_random_number` you can use for testing and as a starting point for development.

1. Open GitHub Copilot chat in VS Code and switch to **Agent** mode.

1. Select the **Select tools** icon to verify your **MyMCPServer** is available with the sample tool listed.


1. Enter a prompt to run the **get_random_number** tool:

    ```console
    Give me a random number between 1 and 100.
    ```

1. GitHub Copilot requests permission to run the **get_random_number** tool for your prompt. Select **Continue** or use the arrow to select a more specific behavior:

    - **Current session** always runs the operation in the current GitHub Copilot Agent Mode session.
    - **Current workspace** always runs the command for the current VS Code workspace.
    - **Always allow** sets the operation to always run for any GitHub Copilot Agent Mode session.

1. Verify that the server responds with a random number:

    ```output
    Your random number is 42.
    ```

::: zone-end

## Add inputs and configuration options

In this example, you enhance the MCP server to use a configuration value set in an environment variable. This could be configuration needed for the functioning of your MCP server, such as an API key, an endpoint to connect to, or a local directory path.

1. Add another tool method after the `GetRandomNumber` method in `Tools/RandomNumberTools.cs`. Update the tool code to use an environment variable.


1. Update the `.vscode/mcp.json` to set the `WEATHER_CHOICES` environment variable for testing.

   ```json
   {
      "servers": {
        "SampleMcpServer": {
          "type": "stdio",
          "command": "dotnet",
          "args": [
            "run",
            "--project",
            "<relative-path-to-project-file>"
          ],
          "env": {
             "WEATHER_CHOICES": "sunny,humid,freezing"
          }
        }
      }
    }
    ```

1. Try another prompt with Copilot in VS Code, such as:

    ```console
    What is the weather in Redmond, Washington?
    ```

    VS Code should return a random weather description.

1. Update the `.mcp/server.json` to declare your environment variable input. The `server.json` file schema is defined by the [MCP Registry project](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md) and is used by NuGet.org to generate VS Code MCP configuration.

   - Use the `environmentVariables` property to declare environment variables used by your app that will be set by the client using the MCP server (for example, VS Code).

   - Use the `packageArguments` property to define CLI arguments that will be passed to your app. For more examples, see the [MCP Registry project](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md#examples).


   The only information used by NuGet.org in the `server.json` is the first `packages` array item with the `registryType` value matching `nuget`. The other top-level properties aside from the `packages` property are currently unused and are intended for the upcoming central MCP Registry. You can leave the placeholder values until the MCP Registry is live and ready to accept MCP server entries.

You can [test your MCP server again](#test-the-mcp-server) before moving forward.

## Pack and publish to NuGet

1. Pack the project:

    ```bash
    dotnet pack -c Release
    ```

    This command produces one tool package and several platform-specific packages based on the `<RuntimeIdentifiers>` list in `SampleMcpServer.csproj`.

1. Publish the packages to NuGet:

    ```bash
    dotnet nuget push bin/Release/*.nupkg --api-key <your-api-key> --source https://api.nuget.org/v3/index.json
    ```

    Be sure to publish all `.nupkg` files to ensure every supported platform can run the MCP server.

    If you want to test the publishing flow before publishing to NuGet.org, you can register an account on the NuGet Gallery integration environment: [https://int.nugettest.org](https://int.nugettest.org). The `push` command would be modified to:

    ```bash
    dotnet nuget push bin/Release/*.nupkg --api-key <your-api-key> --source https://apiint.nugettest.org/v3/index.json
    ```

For more information, see [Publish a package](/nuget/nuget-org/publish-a-package).

## Discover MCP servers on NuGet.org

1. Search for your MCP server package on [NuGet.org](https://www.nuget.org/packages?packagetype=mcpserver) (or [int.nugettest.org](https://int.nugettest.org/packages?packagetype=mcpserver) if you published to the integration environment) and select it from the list.


1. View the package details and copy the JSON from the "MCP Server" tab.


1. In your `mcp.json` file in the `.vscode` folder, add the copied JSON, which looks like this:

   ```json
   {
     "inputs": [
       {
         "type": "promptString",
         "id": "weather_choices",
         "description": "Comma separated list of weather descriptions to randomly select.",
         "password": false
       }
     ],
     "servers": {
       "Contoso.SampleMcpServer": {
         "type": "stdio",
         "command": "dnx",
         "args": ["Contoso.SampleMcpServer@0.0.1-beta", "--yes"],
         "env": {
           "WEATHER_CHOICES": "${input:weather_choices}"
         }
       }
     }
   }
   ```

   If you published to the NuGet Gallery integration environment, you need to add `"--add-source", "https://apiint.nugettest.org/v3/index.json"` at the end of the `"args"` array.

1. Save the file.

1. In GitHub Copilot, select the **Select tools** icon to verify your **SampleMcpServer** is available with the tools listed.

1. Enter a prompt to run the new **get_city_weather** tool:

    ```console
    What is the weather in Redmond?
    ```

1. If you added inputs to your MCP server (for example, `WEATHER_CHOICES`), you will be prompted to provide values.

1. Verify that the server responds with the random weather:

    ```output
    The weather in Redmond is balmy.
    ```

## Common issues

### The command "dnx" needed to run SampleMcpServer was not found

If VS Code shows this error when starting the MCP server, you need to install a compatible version of the .NET SDK.


The `dnx` command is shipped as part of the .NET SDK, starting with version 10. [Install the .NET 10 SDK](https://dotnet.microsoft.com/download/dotnet) to resolve this issue.

### GitHub Copilot doesn't use your tool (an answer is provided without invoking your tool)

Generally speaking, an AI agent like GitHub Copilot is informed that it has some tools available by the client application, such as VS Code. Some tools, such as the sample random number tool, might not be leveraged by the AI agent because it has similar functionality built in.

If your tool is not being used, check the following:

1. Verify that your tool appears in the list of tools that VS Code has enabled. See the screenshot in [Test the MCP server](#test-the-mcp-server) for how to check this.
1. Explicitly reference the name of the tool in your prompt. In VS Code, you can reference your tool by name. For example, `Using #get_random_weather, what is the weather in Redmond?`.
1. Verify your MCP server is able to start. You can check this by clicking the "Start" button visible above your MCP server configuration in the VS Code user or workspace settings.


## Related content

- [Get started with .NET AI and the Model Context Protocol](../get-started-mcp.md)
- [Model Context Protocol .NET samples](https://github.com/microsoft/mcp-dotnet-samples)
- [Build a minimal MCP client](build-mcp-client.md)
- [Publish a package](/nuget/nuget-org/publish-a-package)
- [Find and evaluate NuGet packages for your project](/nuget/consume-packages/finding-and-choosing-packages)
- [What's new in .NET 10](../../core/whats-new/dotnet-10/overview.md)

---
title: Quickstart - Build a minimal .NET AI RAG app
description: Create an AI powered app to search and integrate with vector stores using embeddings and the Microsoft.Extensions.VectorData package for .NET
ms.date: 03/04/2026
ms.topic: quickstart
zone_pivot_groups: openai-library
ai-usage: ai-assisted
---

# Build a .NET AI vector search app

In this quickstart, you create a .NET console app to perform semantic search on a _vector store_ to find relevant results for the user's query. You learn how to generate embeddings for user prompts and use those embeddings to query the vector data store.

Vector stores, or vector databases, are essential for tasks like semantic search, retrieval augmented generation (RAG), and other scenarios that require grounding generative AI responses. While relational databases and document databases are optimized for structured and semi-structured data, vector databases are built to efficiently store, index, and manage data represented as embedding vectors. As a result, the indexing and search algorithms used by vector databases are optimized to efficiently retrieve data that can be used downstream in your applications.

## About the libraries

The app uses the <xref:Microsoft.Extensions.AI> and <xref:Microsoft.Extensions.VectorData> libraries so you can write code using AI abstractions rather than a specific SDK. AI abstractions help create loosely coupled code that allows you to change the underlying AI model with minimal app changes.

[📦 Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions/) is a .NET library that provides a unified layer of abstractions for interacting with vector stores. The abstractions in `Microsoft.Extensions.VectorData.Abstractions` provide library authors and developers with the following functionality:

- Perform create-read-update-delete (CRUD) operations on vector stores.
- Use vector and text search on vector stores.

<!--Prerequisites section-->

:::zone target="docs" pivot="openai"

[!INCLUDE [openai-prereqs](includes/prerequisites-openai.md)]

:::zone-end

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]

:::zone-end

## Create the app

Complete the following steps to create a .NET console app that can:

- Create and populate a vector store by generating embeddings for a data set.
- Generate an embedding for the user prompt.
- Query the vector store using the user prompt embedding.
- Display the relevant results from the vector search.

1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:

    ```dotnetcli
    dotnet new console -o VectorDataAI
    ```

1. Change directory into the app folder:

    ```dotnetcli
    cd VectorDataAI
    ```

1. Install the required packages:

    :::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 Microsoft.Extensions.VectorData.Abstractions
    dotnet add package Microsoft.SemanticKernel.Connectors.InMemory --prerelease
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    dotnet add package System.Linq.AsyncEnumerable
    ```

    The following list describes each package in the `VectorDataAI` app:

    - [`Azure.Identity`](https://www.nuget.org/packages/Azure.Identity) provides [`Microsoft Entra ID`](/entra/fundamentals/whatis) token authentication support across the Azure SDK using classes such as `DefaultAzureCredential`.
    - [`Azure.AI.OpenAI`](https://www.nuget.org/packages/Azure.AI.OpenAI) is the official package for using OpenAI's .NET library with the Azure OpenAI Service.
    - [`Microsoft.Extensions.VectorData.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions) enables Create-Read-Update-Delete (CRUD) and search operations on vector stores.
    - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
    - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides an implementation of key-value pair&mdash;based configuration.
    - [`Microsoft.Extensions.Configuration.UserSecrets`](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.UserSecrets) is a user secrets configuration provider implementation for `Microsoft.Extensions.Configuration`.

    :::zone-end

    :::zone target="docs" pivot="openai"

    ```bash
    dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
    dotnet add package Microsoft.Extensions.VectorData.Abstractions
    dotnet add package Microsoft.SemanticKernel.Connectors.InMemory --prerelease
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    dotnet add package System.Linq.AsyncEnumerable
    ```

    The following list describes each package in the `VectorDataAI` app:

    - [`Microsoft.Extensions.AI.OpenAI`](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) provides AI abstractions for OpenAI-compatible models or endpoints. This library also includes the official [`OpenAI`](https://www.nuget.org/packages/OpenAI) library for the OpenAI service API as a dependency.
    - [`Microsoft.Extensions.VectorData.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions) enables Create-Read-Update-Delete (CRUD) and search operations on vector stores.
    - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
    - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides an implementation of key-value pair&mdash;based configuration.
    - [`Microsoft.Extensions.Configuration.UserSecrets`](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.UserSecrets) is a user secrets configuration provider implementation for `Microsoft.Extensions.Configuration`.

    :::zone-end

1. Open the app in Visual Studio Code (or your editor of choice).

    ```bash
    code .
    ```

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [create-ai-service](includes/create-ai-service.md)]

:::zone-end

:::zone target="docs" pivot="openai"

## Configure the app

1. Navigate to the root of your .NET project from a terminal or command prompt.

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>
    ```

:::zone-end

> [!NOTE]
> For the model name, you need to specify a text embedding model such as `text-embedding-3-small` or `text-embedding-3-large` to generate embeddings for vector search in the sections that follow. For more information about embedding models, see [Embeddings](/azure/ai-services/openai/concepts/models#embeddings).

## Add the app code

1. Add a new class named `CloudService` to your project with the following properties:


    The <xref:Microsoft.Extensions.VectorData> attributes, such as <xref:Microsoft.Extensions.VectorData.VectorStoreKeyAttribute>, influence how each property is handled when used in a vector store. The `Vector` property stores a generated embedding that represents the semantic meaning of the `Description` value for vector searches.

1. In the `Program.cs` file, add the following code to create a data set that describes a collection of cloud services:


1. Create and configure an `IEmbeddingGenerator` implementation to send requests to an embedding AI model:

    :::zone target="docs" pivot="azure-openai"


    > [!NOTE]
    > <xref:Azure.Identity.DefaultAzureCredential> searches for authentication credentials from your local tooling. 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 Foundry tools with .NET](../azure-ai-services-authentication.md).

    :::zone-end

    :::zone target="docs" pivot="openai"


    :::zone-end

1. Create and populate a vector store with the cloud service data. Use the `IEmbeddingGenerator` implementation to create and assign an embedding vector for each record in the cloud service data:


   The embeddings are numerical representations of the semantic meaning for each data record, which makes them compatible with vector search features.

1. Create an embedding for a search query and use it to perform a vector search on the vector store:


1. Use the `dotnet run` command to run the app:

    ```dotnetcli
    dotnet run
    ```

    The app prints out the top result of the vector search, which is the cloud service that's most relevant to the original query. You can modify the query to try different search scenarios.

:::zone target="docs" pivot="azure-openai"

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and model deployment.

1. In the [Azure portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

:::zone-end

## Next steps

- [Quickstart - Chat with a local AI model](chat-local-model.md)
- [Generate images from text using AI](text-to-image.md)

---
title: Quickstart - Connect to and chat with a local AI using .NET
description: Set up a local AI model and chat with it using a .NET console app and the Microsoft.Extensions.AI libraries
ms.date: 03/04/2026
ms.topic: quickstart
ai-usage: ai-assisted
---

# Chat with a local AI model using .NET

In this quickstart, you learn how to create a conversational .NET console chat app using 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.

## Prerequisites

* [Install .NET 8.0](https://dotnet.microsoft.com/download) or higher
* [Install Ollama](https://ollama.com/) locally on your device
* [Visual Studio Code](https://code.visualstudio.com/) (optional)

## Run the local AI model

Complete the following steps to configure and run a local AI model on your device. Many different AI models are available to run locally and are trained for different tasks, such as generating code, analyzing images, generative chat, or creating embeddings. For this quickstart, you'll use the general purpose `phi3:mini` model, which is a small but capable generative AI created by Microsoft.

1. Open a terminal window and verify that Ollama is available on your device:

    ```bash
    ollama
    ```

    If Ollama is available, it displays a list of available commands.

1. Start Ollama:

    ```bash
    ollama serve
    ```

    If Ollama is running, it displays a list of available commands.

1. Pull the `phi3:mini` model from the Ollama registry and wait for it to download:

    ```bash
    ollama pull phi3:mini
    ```

1. After the download completes, run the model:

    ```bash
    ollama run phi3:mini
    ```

    Ollama starts the `phi3:mini` model and provides a prompt for you to interact with it.

## Create the .NET app

Complete the following steps to create a .NET console app that connects to your local `phi3:mini` AI model.

1. In a terminal window, navigate to an empty directory on your device and create a new app with the `dotnet new` command:

    ```dotnetcli
    dotnet new console -o LocalAI
    ```

1. Change directory into the app folder:

    ```dotnetcli
    cd LocalAI
    ```

1. Add the [OllamaSharp](https://www.nuget.org/packages/OllamaSharp) package to your app:

    ```dotnetcli
    dotnet add package OllamaSharp
    ```

1. Open the new app in your editor of choice, such as Visual Studio Code.

    ```dotnetcli
    code .
    ```

## Connect to and chat with the AI model

In the steps ahead, you'll create a simple app that connects to the local AI and stores conversation history to improve the chat experience.

1. Open the _Program.cs_ file and replace the contents of the file with the following code:


    The preceding code accomplishes the following:

    * Creates an `OllamaChatClient` that implements the `IChatClient` interface.
        * This interface provides a loosely coupled abstraction you can use to chat with AI Models.
        * You can later change the underlying chat client implementation to another model, such as Azure OpenAI, without changing any other code.
    * Creates a `ChatHistory` object to store the messages between the user and the AI model.
    * Retrieves a prompt from the user and stores it in the `ChatHistory`.
    * Sends the chat data to the AI model to generate a response.

    > [!NOTE]
    > Ollama runs on port 11434 by default, which is why the AI model endpoint is set to `http://localhost:11434`.

1. Run the app and enter a prompt into the console to receive a response from the AI, such as the following:

    ```output
    Your prompt:
    Tell me three facts about .NET.

    AI response:
    1. **Cross-Platform Development:** One of the significant strengths of .NET,
    particularly its newer iterations (.NET Core and .NET 5+), is cross-platform support.
    It allows developers to build applications that run on Windows, Linux, macOS,
    and various other operating systems seamlessly, enhancing flexibility and
    reducing barriers for a wider range of users.

    2. **Rich Ecosystem and Library Support:** .NET has a rich ecosystem,
    comprising an extensive collection of libraries (such as those provided by the
    official NuGet Package Manager), tools, and services. This allows developers
    to work on web applications (.NET for desktop apps and ASP.NET Core
    for modern web applications), mobile applications (.NET MAUI),
    IoT solutions, AI/ML projects, and much more with a vast array of prebuilt
    components available at their disposal.

    3. **Type Safety:** .NET operates under the Common Language Infrastructure (CLI)
    model and employs managed code for executing applications. This approach inherently
    offers strong type safety checks which help in preventing many runtime errors that
    are common in languages like C/C++. It also enables features such as garbage collection,
    thus relieving developers from manual memory management. These characteristics enhance
    the reliability of .NET-developed software and improve productivity by catching
    issues early during development.
    ```

1. The response from the AI is accurate, but also verbose. The stored chat history enables the AI to modify its response. Instruct the AI to shorten the list it provided:

    ```output
    Your prompt:
    Shorten the length of each item in the previous response.

    AI Response:
     **Cross-platform Capabilities:** .NET allows building for various operating systems
    through platforms like .NET Core, promoting accessibility (Windows, Linux, macOS).

    **Extensive Ecosystem:** Offers a vast library selection via NuGet and tools for web
    (.NET Framework), mobile development (.NET MAUI), IoT, AI, providing rich
    capabilities to developers.

    **Type Safety & Reliability:** .NET's CLI model enforces strong typing and automatic
    garbage collection, mitigating runtime errors, thus enhancing application stability.
    ```

    The updated response from the AI is much shorter the second time. Due to the available chat history, the AI was able to assess the previous result and provide shorter summaries.

## Next steps

* [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

---
title: Quickstart - Create a minimal AI assistant using .NET
description: Learn to create a minimal AI assistant with tooling capabilities using .NET and the Azure OpenAI SDK libraries
ms.date: 03/04/2026
ms.topic: quickstart
zone_pivot_groups: openai-library
ai-usage: ai-assisted
---

# Create a minimal AI assistant using .NET

In this quickstart, you'll learn how to create a minimal AI assistant using the OpenAI or Azure OpenAI SDK libraries. AI assistants provide agentic functionality to help users complete tasks using AI tools and models. In the sections ahead, you'll learn the following:

- Core components and concepts of AI assistants
- How to create an assistant using the Azure OpenAI SDK
- How to enhance and customize the capabilities of an assistant

## Prerequisites

::: zone pivot="openai"

* [Install .NET 8.0](https://dotnet.microsoft.com/download) or higher
* [Visual Studio Code](https://code.visualstudio.com/) (optional)
* [Visual Studio](https://visualstudio.com/) (optional)
* An access key for an OpenAI model

:::zone-end

::: zone pivot="azure-openai"

* [Install .NET 8.0](https://dotnet.microsoft.com/download) or higher
* [Visual Studio Code](https://code.visualstudio.com/) (optional)
* [Visual Studio](https://visualstudio.com/) (optional)
* Access to an Azure OpenAI instance via Azure Identity or an access key

:::zone-end

## Core components of AI assistants

AI assistants are based around conversational threads with a user. The user sends prompts to the assistant on a conversation thread, which direct the assistant to complete tasks using the tools it has available. Assistants can process and analyze data, make decisions, and interact with users or other systems to achieve specific goals. Most assistants include the following components:

| **Component** | **Description** |
|---------------|-----------------|
| **Assistant** | The core AI client and logic that uses Azure OpenAI models, manages conversation threads, and utilizes configured tools. |
| **Thread**    | A conversation session between an assistant and a user. Threads store messages and automatically handle truncation to fit content into a model's context. |
| **Message**   | A message created by an assistant or a user. Messages can include text, images, and other files. Messages are stored as a list on the thread. |
| **Run**       | Activation of an assistant to begin running based on the contents of the thread. The assistant uses its configuration and the thread's messages to perform tasks by calling models and tools. As part of a run, the assistant appends messages to the thread. |
| **Run steps** | A detailed list of steps the assistant took as part of a run. An assistant can call tools or create messages during its run. Examining run steps allows you to understand how the assistant is getting to its final results. |

Assistants can also be configured to use multiple tools in parallel to complete tasks, including the following:

- **Code interpreter tool**: Writes and runs code in a sandboxed execution environment.
- **Function calling**: Runs local custom functions you define in your code.
- **File search capabilities**: Augments the assistant with knowledge from outside its model.

By understanding these core components and how they interact, you can build and customize powerful AI assistants to meet your specific needs.

## Create the .NET app

Complete the following steps to create a .NET console app and add the package needed to work with assistants:

::: zone pivot="openai"

1. In a terminal window, navigate to an empty directory on your device and create a new app with the `dotnet new` command:

    ```dotnetcli
    dotnet new console -o AIAssistant
    ```

1. Add the [OpenAI](https://www.nuget.org/packages/OpenAI) package to your app:

    ```dotnetcli
    dotnet add package OpenAI
    ```

1. Open the new app in your editor of choice, such as Visual Studio Code.

    ```dotnetcli
    code .
    ```

::: zone-end

::: zone pivot="azure-openai"

1. In a terminal window, navigate to an empty directory on your device and create a new app with the `dotnet new` command:

    ```dotnetcli
    dotnet new console -o AIAssistant
    ```

1. Add the [Azure.AI.OpenAI](https://www.nuget.org/packages/Azure.AI.OpenAI) package to your app:

    ```dotnetcli
    dotnet add package Azure.AI.OpenAI
    ```

1. Open the new app in your editor of choice, such as Visual Studio Code.

    ```dotnetcli
    code .
    ```

::: zone-end

## Create the AI assistant client

1. Open the `Program.cs` file and replace the contents of the file with the following code to create the required clients:


1. Create an in-memory sample document and upload it to the `OpenAIFileClient`:


1. Enable file search and code interpreter tooling capabilities via the `AssistantCreationOptions`:


1. Create the `Assistant` and a thread to manage interactions between the user and the assistant:


1. Print the messages and save the generated image from the conversation with the assistant:


    Locate and open the saved image in the app `bin` directory, which should resemble the following:


## Next steps

- [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

---
title: Quickstart - Generate images using OpenAI.Images.ImageClient
description: Create a simple app using to generate images using OpenAI.Images.ImageClient in .NET.
ms.date: 03/04/2026
ms.topic: quickstart
zone_pivot_groups: openai-library
ai-usage: ai-assisted
---

# Generate images using OpenAI.Images.ImageClient

In this quickstart, you create a .NET console app that uses `OpenAI.Images.ImageClient` to generate images using an OpenAI or Azure OpenAI DALL-E AI model. These models generate images from text prompts.

:::zone target="docs" pivot="openai"

[!INCLUDE [openai-prereqs](includes/prerequisites-openai.md)]

:::zone-end

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]

:::zone-end

## Create the app

Complete the following steps to create a .NET console app to connect to an AI model.

1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:

    ```dotnetcli
    dotnet new console -o ImagesAI
    ```

1. Change directory into the app folder:

    ```dotnetcli
    cd ImagesAI
    ```

1. Install the required packages:

    :::zone target="docs" pivot="azure-openai"

    ```bash
    dotnet add package Azure.AI.OpenAI
    dotnet add package Azure.Identity
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    ```

    :::zone-end

    :::zone target="docs" pivot="openai"

    ```bash
    dotnet add package OpenAI
    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 .
    ```

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [create-ai-service](includes/create-ai-service.md)]

:::zone-end

:::zone target="docs" pivot="openai"

## Configure the app

1. Navigate to the root of your .NET project from a terminal or command prompt.

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>
    ```

:::zone-end

## Add the app code

1. In the `Program.cs` file, add the following code to connect and authenticate to the AI model.

    :::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 Foundry tools with .NET](../azure-ai-services-authentication.md).

    :::zone-end

    :::zone target="docs" pivot="openai"


    :::zone-end

    The preceding code:

    - 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. Run the app:

    ```dotnetcli
    dotnet run
    ```

    Navigate to the image URL in the console output to view the generated image. Customize the text content of the prompt to create new images or modify the original.

:::zone target="docs" pivot="azure-openai"

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and GPT-4 model deployment.

1. In the [Azure portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

:::zone-end

## Next steps

- [Quickstart - Build an AI chat app with .NET](build-chat-app.md)
- [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

---
title: Quickstart - Process custom data for AI
description: Create a data ingestion pipeline to process and prepare custom data for AI applications using Microsoft.Extensions.DataIngestion.
ms.date: 12/11/2025
ms.topic: quickstart
ai-usage: ai-assisted
---

# Process custom data for AI applications

In this quickstart, you learn how to create a data ingestion pipeline to process and prepare custom data for AI applications. The app uses the <xref:Microsoft.Extensions.DataIngestion> library to read documents, enrich content with AI, chunk text semantically, and store embeddings in a vector database for semantic search.

Data ingestion is essential for retrieval-augmented generation (RAG) scenarios where you need to process large amounts of unstructured data and make it searchable for AI applications.

[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]

## Create the app

Complete the following steps to create a .NET console app.

1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:

    ```dotnetcli
    dotnet new console -o ProcessDataAI
    ```

1. Change directory into the app folder:

    ```dotnetcli
    cd ProcessDataAI
    ```

1. Install the required packages:

    ```bash
    dotnet add package Azure.AI.OpenAI
    dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    dotnet add package Microsoft.Extensions.DataIngestion --prerelease
    dotnet add package Microsoft.Extensions.DataIngestion.Markdig --prerelease
    dotnet add package Microsoft.Extensions.Logging.Console
    dotnet add package Microsoft.ML.Tokenizers.Data.O200kBase
    dotnet add package Microsoft.SemanticKernel.Connectors.SqliteVec --prerelease
    ```

## Create the AI service

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. For this quickstart, you need to provision two models: `gpt-5` and `text-embedding-3-small`.

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 API key for the sample app:

    ```bash
    dotnet user-secrets init
    dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
    dotnet user-secrets set AZURE_OPENAI_API_KEY <your-Azure-OpenAI-API-key>
    ```

## Open the app in an editor

Open the app in Visual Studio Code (or your editor of choice).

```bash
code .
```

## Create the sample data

1. Copy the [sample.md](https://raw.githubusercontent.com/dotnet/docs/refs/heads/main/docs/ai/quickstarts/snippets/process-data/data/sample.md) file to a folder named `data` in your project directory.
1. 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**.

## Add the app code

The data ingestion pipeline consists of several components that work together to process documents:

- **Document reader**: Reads Markdown files from a directory.
- **Document processor**: Enriches images with AI-generated alternative text.
- **Chunker**: Splits documents into semantic chunks using embeddings.
- **Chunk processor**: Generates AI summaries for each chunk.
- **Vector store writer**: Stores chunks with embeddings in a SQLite database.

1. In the `Program.cs` file, delete any existing code and add the following code to configure the document reader:


   The <xref:Microsoft.Extensions.DataIngestion.MarkdownReader> class reads Markdown documents and converts them into a unified format that works well with large language models.

1. Add code to configure logging for the pipeline:


1. Add code to configure the AI client for enrichment and chat:


1. Add code to configure the document processor that enriches images with AI-generated descriptions:


   The <xref:Microsoft.Extensions.DataIngestion.ImageAlternativeTextEnricher> uses large language models to generate descriptive alternative text for images within documents. That text makes them more accessible and improves their semantic meaning.

1. Add code to configure the embedding generator for creating vector representations:


   [Embeddings](../conceptual/embeddings.md) are numerical representations of the semantic meaning of text, which enables vector similarity search.

1. Add code to configure the chunker that splits documents into semantic chunks:


   The <xref:Microsoft.Extensions.DataIngestion.Chunkers.SemanticSimilarityChunker> intelligently splits documents by analyzing the semantic similarity between sentences, ensuring that related content stays together. This process produces chunks that preserve meaning and context better than simple character or token-based chunking.

1. Add code to configure the chunk processor that generates summaries:


   The <xref:Microsoft.Extensions.DataIngestion.SummaryEnricher> automatically generates concise summaries for each chunk, which can improve retrieval accuracy by providing a high-level overview of the content.

1. Add code to configure the SQLite vector store for storing embeddings:


   The vector store stores chunks along with their embeddings, enabling fast semantic search capabilities.

1. Add code to compose all the components into a complete pipeline:


   The <xref:Microsoft.Extensions.DataIngestion.IngestionPipeline`1> combines all the components into a cohesive workflow that processes documents from start to finish.

1. Add code to process documents from a directory:


   The pipeline processes all Markdown files in the `./data` directory and reports the status of each document.

1. Add code to enable interactive search of the processed documents:


   The search functionality converts user queries into embeddings and finds the most semantically similar chunks in the vector store.

## Run the app

1. Use the `dotnet run` command to run the app:

   ```dotnetcli
   dotnet run
   ```

   The app processes all Markdown files in the `./data` directory and displays the processing status for each document. Once processing is complete, you can enter natural language questions to search the processed content.

1. Enter a question at the prompt to search the data:

   ```output
   Enter your question (or 'exit' to quit): What is data ingestion?
   ```

   The app returns the most relevant chunks from your documents along with their similarity scores.

1. Type `exit` to quit the application.

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and model deployment.

1. In the [Azure Portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

## Next steps

- [Data ingestion concepts](../conceptual/data-ingestion.md)
- [Implement RAG using vector search](../tutorials/tutorial-ai-vector-search.md)
- [Build a .NET AI vector search app](build-vector-search-app.md)

---
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: 03/04/2026
ms.topic: quickstart
zone_pivot_groups: openai-library
ai-usage: ai-assisted
---

# 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.

:::zone target="docs" pivot="openai"

[!INCLUDE [openai-prereqs](includes/prerequisites-openai.md)]

:::zone-end

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]

:::zone-end

## Create the app

Complete the following steps to create a .NET console app to connect to an AI model.

1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:

    ```dotnetcli
    dotnet new console -o ExtensionsAI
    ```

1. Change directory into the app folder:

    ```dotnetcli
    cd ExtensionsAI
    ```

1. Install the required packages:

    :::zone target="docs" pivot="azure-openai"

    ```bash
    dotnet add package Azure.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
    ```

    :::zone-end

    :::zone target="docs" pivot="openai"

    ```bash
    dotnet add package 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.

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [create-ai-service](includes/create-ai-service.md)]

:::zone-end

:::zone target="docs" pivot="openai"

## Configure the app

1. Navigate to the root of your .NET project from a terminal or command prompt.

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>
   ```

:::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. 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**.

1. In the `Program.cs` file, add the following code to connect and authenticate to the AI model.

   :::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 Foundry tools with .NET](../azure-ai-services-authentication.md).

   :::zone-end

   :::zone target="docs" pivot="openai"


   :::zone-end

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 `GetResponseAsync` method to send the prompt to the model to generate a response.


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.

:::zone target="docs" pivot="azure-openai"

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and GPT-4 model deployment.

1. In the [Azure portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

:::zone-end

## Next steps

- [Quickstart - Build an AI chat app with .NET](build-chat-app.md)
- [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

---
title: Quickstart - Publish a .NET MCP server to the MCP Registry
description: Learn how to publish your NuGet-based MCP server to the Official MCP Registry, including creating a server.json manifest, updating your package README, and using the MCP Publisher tool.
ms.date: 03/04/2026
ms.topic: quickstart
author: joelverhagen
zone_pivot_groups: operating-systems-set-one
ai-usage: ai-assisted
---

# Publish an MCP server on NuGet.org to the Official MCP Registry

In this quickstart, you publish your NuGet-based local MCP server to the [Official MCP Registry](https://github.com/modelcontextprotocol/registry/blob/main/docs/design/ecosystem-vision.md).

The Official MCP Registry is an *upstream data source* for the MCP ecosystem. Other MCP registries, such as the [GitHub MCP Registry](https://github.com/mcp), will soon use the Official MCP Registry as a source of MCP server listings.

> [!NOTE]
> This guide focuses on publishing **local MCP servers** packaged with NuGet. The Official MCP Registry also supports **remote MCP servers**. While the `server.json` publishing process is similar for remote servers, their configuration requires a URL instead of a package manager reference. Remote servers can be implemented in any language. For an example, see [an Azure Functions code sample for a .NET remote MCP server](/samples/azure-samples/remote-mcp-functions-dotnet/remote-mcp-functions-dotnet/).

## Prerequisites

- A [GitHub account](https://github.com/join)
- [Visual Studio Code](https://code.visualstudio.com/)
- Your MCP server is packaged with NuGet and published to NuGet.org ([quickstart](./build-mcp-server.md)).

## Create a server.json manifest file

*If you used the NuGet MCP server quickstart and `mcpserver` project template, you can skip this step.*

1. Navigate to your MCP server's source directory and create a new `server.json` file.
   ::: zone pivot="os-windows"

   ```powershell
   cd path\my\project

   # create and open the server.json file
   code .mcp\server.json
   ```

   ::: zone-end
   ::: zone pivot="os-linux"

   ```bash
   cd path/my/project

   # create and open the server.json file
   code .mcp/server.json
   ```

   ::: zone-end
   ::: zone pivot="os-macos"

   ```bash
   cd path/my/project

   # create and open the server.json file
   code .mcp/server.json
   ```

   ::: zone-end
2. Use this content to start with and fill in the placeholders.
3. Save the file.

Use this reference to understand more about the fields:

| Property                | Example                                | Purpose                                                                                                     |
| ----------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `name`                  | `io.github.contoso/data-mcp`           | Unique identifier for the MCP server, namespaced using reverse DNS names, **case sensitive**                |
| `version`               | `0.1.0-beta`                           | Version of the MCP server listing<br>Consider using the same version as the MCP server package on NuGet.org |
| `description`           | `Access Contoso data in your AI agent` | Description of your MCP server, up to 100 characters                                                        |
| `title`                 | `Contoso Data`                         | Optional: short human-readable title, up to 100 characters                                                  |
| `websiteUrl`            | `https://contoso.com/docs/mcp`         | Optional: URL to the server's homepage, documentation, or project website                                   |
| `packages` `identifier` | `Contoso.Data.Mcp`                     | The ID of your MCP server package on NuGet.org                                                              |
| `packages` `version`    | `0.1.0-beta`                           | The version of your MCP server package on NuGet.org                                                         |
| `repository` `url`      | `https://github.com/contoso/data-mcp`  | Optional: GitHub repository URL                                                                             |

The `name` field has two parts, separated by a forward slash `/`. The first part is a namespace based off of a reverse DNS name. The authentication method you use in later steps will give you access to a specific namespace. For example, using GitHub-based authentication will give you access to `io.github.<your GitHub username>/*`.  The second part, after the forward slash, is a custom identifier for your server within the namespace. Think of this much like a NuGet package ID. It should be unchanging and descriptive of your MCP server. Using your GitHub repository name is a reasonable option if you only have one MCP server published from that repository.

## Update your package README

The Official MCP Registry verifies that your MCP server package references the `name` specified in your `server.json` file.

1. If you haven't already, add a README.md to your MCP server NuGet package. See [how to do this in your project file](/nuget/reference/msbuild-targets#packagereadmefile).
2. Open the README.md used by your NuGet package.
   ::: zone pivot="os-windows"

   ```powershell
   code path\to\README.md
   ```

   ::: zone-end
   ::: zone pivot="os-linux"

   ```bash
   code path/to/README.md
   ```

   ::: zone-end
   ::: zone pivot="os-macos"

   ```bash
   code path/to/README.md
   ```

   ::: zone-end
3. Add the following line to your README.md. Since it is enclosed in an HTML comment, it can be anywhere and won't be rendered.

   ```markdown
   <!-- mcp-name: [name property from the server.json] -->
   ```

   Example:

   ```markdown
   <!-- mcp-name: io.github.contoso/data-mcp -->
   ```

4. Save the README.md file.

## Publish your MCP server package to NuGet.org

Because your README.md now has an `mcp-name` declared in it, publish the latest package to NuGet.org.

1. If needed, update your package version and the respective version strings in your `server.json`.
2. Pack your project so the latest README.md version is contained.

   ```bash
   dotnet pack
   ```

3. Push it to NuGet.org either [via the website](https://www.nuget.org/packages/manage/upload) or using the CLI:
   ::: zone pivot="os-windows"

   ```powershell
   dotnet push bin\Release\*.nupkg -k <API key here> -s https://api.nuget.org/v3/index.json
   ```

   ::: zone-end
   ::: zone pivot="os-linux"

   ```bash
   dotnet push bin/Release/*.nupkg -k <API key here> -s https://api.nuget.org/v3/index.json
   ```

   ::: zone-end
   ::: zone pivot="os-macos"

   ```bash
   dotnet push bin/Release/*.nupkg -k <API key here> -s https://api.nuget.org/v3/index.json
   ```

   ::: zone-end

## Wait for your package to become available

NuGet.org performs validations against your package before making it available so you must wait to publish your MCP server to the Official MCP Registry since it verifies that the package is accessible.

To wait for your package to become available, either continue to periodically refresh the package details page on NuGet.org until the validating message disappears, or use the following PowerShell script to poll for availability.

```powershell
$id = "<your NuGet package ID here>".ToLowerInvariant()
$version = "<your NuGet package version here>".ToLowerInvariant()
$url = "https://api.nuget.org/v3-flatcontainer/$id/$version/readme"
$elapsed = 0; $interval = 10; $timeout = 300
Write-Host "Checking for package README of $id $version."
while ($true) {
    if ($elapsed -gt $timeout) {
        Write-Error "Package README is not available after $elapsed seconds. URL: $url"
        exit 1
    }
    try {
        Invoke-WebRequest -Uri $url -ErrorAction Stop | Out-Null
        Write-Host "Package README is now available."
        break
    } catch {
        Write-Host "Package README is not yet available. Elapsed time: $elapsed seconds."
        Start-Sleep -Seconds $interval; $elapsed += $interval
        continue
    }
}
```

This script can be leveraged in a CI/CD pipeline to ensure the next step (publishing to the Official MCP Registry) does not happen before the NuGet package is available.

## Download the MCP Publisher tool

1. Download the `mcp-publisher-*.tar.gz` file from the Official MCP Registry GitHub repository that matches your CPU architecture.
   ::: zone pivot="os-windows"
   - Windows x64: [mcp-publisher_windows_amd64.tar.gz](https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_amd64.tar.gz)
   - Windows Arm64: [mcp-publisher_windows_arm64.tar.gz](https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_arm64.tar.gz)
   ::: zone-end
   ::: zone pivot="os-linux"
   - Linux x64: [mcp-publisher_linux_amd64.tar.gz](https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz)
   - Linux Arm64: [mcp-publisher_linux_arm64.tar.gz](https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_arm64.tar.gz)
   ::: zone-end
   ::: zone pivot="os-macos"
   - macOS x64: [mcp-publisher_darwin_amd64.tar.gz](https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_darwin_amd64.tar.gz)
   - macOS Arm64: [mcp-publisher_darwin_arm64.tar.gz](https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_darwin_arm64.tar.gz)
   ::: zone-end
   See the full list of assets in the [latest release](https://github.com/modelcontextprotocol/registry/releases/latest).
2. Extract the downloaded .tar.gz to the current directory.
   ::: zone pivot="os-windows"

   ```powershell
   # For Windows x64
   tar xf 'mcp-publisher_windows_amd64.tar.gz'

   # For Windows ARM64
   tar xf 'mcp-publisher_windows_arm64.tar.gz'
   ```

   ::: zone-end
   ::: zone pivot="os-linux"

   ```bash
   # For Linux x64
   tar xf 'mcp-publisher_linux_amd64.tar.gz'

   # For Linux ARM64
   tar xf 'mcp-publisher_linux_arm64.tar.gz'
   ```

   ::: zone-end
   ::: zone pivot="os-macos"

   ```bash
   # For macOS x64
   tar xf 'mcp-publisher_darwin_amd64.tar.gz'

   # For macOS ARM64
   tar xf 'mcp-publisher_darwin_arm64.tar.gz'
   ```

   ::: zone-end

## Publish to the Official MCP Registry

The Official MCP Registry has different authentication mechanisms based on the namespace MCP server's `name`. In this guide, we are using a namespace based on GitHub (`io.github.<your GitHub username>/*`) so GitHub authentication must be used. See the [registry documentation for information on other authentication modes](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx), which unlock other namespaces.

1. Log in using GitHub interactive authentication.
   ::: zone pivot="os-windows"

   ```powershell
   .\mcp-publisher.exe login github
   ```

   ::: zone-end
   ::: zone pivot="os-linux"

   ```bash
   ./mcp-publisher login github
   ```

   ::: zone-end
   ::: zone pivot="os-macos"

   ```bash
   ./mcp-publisher login github
   ```

   ::: zone-end
   Follow the instructions provided by the tool. You will provide a code to GitHub in your web browser to complete the flow.

   Once the flow is complete, you will be able to publish `server.json` files to the `io.github.<your GitHub username>/*` namespace.

2. Publish your `server.json` file to the Official MCP Registry.
   ::: zone pivot="os-windows"

   ```powershell
   .\mcp-publisher.exe publish path\to\.mcp\server.json
   ```

   ::: zone-end
   ::: zone pivot="os-linux"

   ```bash
   ./mcp-publisher publish path/to/.mcp/server.json
   ```

   ::: zone-end
   ::: zone pivot="os-macos"

   ```bash
   ./mcp-publisher publish path/to/.mcp/server.json
   ```

   ::: zone-end
3. When the command succeeds, you can verify that your MCP server is published by going to the [registry home page](https://registry.modelcontextprotocol.io/) and searching for your server name.

## Related content

- [Build and publish an MCP server to NuGet.org](./build-mcp-server.md)
- [Publish a NuGet package](/nuget/nuget-org/publish-a-package)
- [Conceptual: MCP servers in NuGet Packages](/nuget/concepts/nuget-mcp)
- [Get started with .NET AI and the Model Context Protocol](../get-started-mcp.md)

---
title: Quickstart - Request a response with structured output
description: Learn how to create a chat app that responds with structured output, that is, output that conforms to a type that you specify.
ms.date: 03/04/2026
ms.topic: quickstart
ai-usage: ai-assisted
---

# Request a response with structured output

In this quickstart, you create a chat app that requests a response with *structured output*. A structured output response is a chat response that's of a type you specify instead of just plain text. The chat app you create in this quickstart analyzes sentiment of various product reviews, categorizing each review according to the values of a custom enumeration.

## Prerequisites

- [.NET 8 or a later version](https://dotnet.microsoft.com/download)
- [Visual Studio Code](https://code.visualstudio.com/) (optional)

## Configure the AI service

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. In the "Deploy a model" step, select the `gpt-5` model.

## Create the chat app

Complete the following steps to create a console app that connects to the `gpt-5` AI model.

1. In a terminal window, navigate to the directory where you want to create your app, and create a new console app with the `dotnet new` command:

    ```dotnetcli
    dotnet new console -o SOChat
    ```

1. Navigate to the `SOChat` directory, and add the necessary packages to your app:

    ```dotnetcli
    dotnet add package Azure.AI.OpenAI
    dotnet add package Azure.Identity
    dotnet add package Microsoft.Extensions.AI
    dotnet add package Microsoft.Extensions.AI.OpenAI
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    ```

1. Run the following commands to add [app secrets](/aspnet/core/security/app-secrets) for your Azure OpenAI endpoint and tenant ID:

    ```bash
    dotnet user-secrets init
    dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
    dotnet user-secrets set AZURE_TENANT_ID <your-tenant-ID>
    ```

   > [!NOTE]
   > Depending on your environment, the tenant ID might not be needed. In that case, remove it from the code that instantiates the <xref:Azure.Identity.DefaultAzureCredential>.

1. Open the new app in your editor of choice.

## Add the code

1. Define the enumeration that describes the different sentiments.


1. Create the <xref:Microsoft.Extensions.AI.IChatClient> that will communicate with the model.


   > [!NOTE]
   > <xref:Azure.Identity.DefaultAzureCredential> searches for authentication credentials from your environment or local tooling. 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 Foundry tools with .NET](../azure-ai-services-authentication.md).

1. Send a request to the model with a single product review, and then print the analyzed sentiment to the console. You declare the requested structured output type by passing it as the type argument to the <xref:Microsoft.Extensions.AI.ChatClientStructuredOutputExtensions.GetResponseAsync``1(Microsoft.Extensions.AI.IChatClient,System.String,Microsoft.Extensions.AI.ChatOptions,System.Nullable{System.Boolean},System.Threading.CancellationToken)?displayProperty=nameWithType> extension method.


   This code produces output similar to:

   ```output
   Sentiment: Positive
   ```

1. Instead of just analyzing a single review, you can analyze a collection of reviews.


   This code produces output similar to:

   ```output
   Review: Best purchase ever! | Sentiment: Positive
   Review: Returned it immediately. | Sentiment: Negative
   Review: Hello | Sentiment: Neutral
   Review: It works as advertised. | Sentiment: Neutral
   Review: The packaging was damaged but otherwise okay. | Sentiment: Neutral
   ```

1. And instead of requesting just the analyzed enumeration value, you can request the text response along with the analyzed value.

   Define a [record type](../../csharp/language-reference/builtin-types/record.md) to contain the text response and analyzed sentiment:


   (This record type is defined using [primary constructor](../../csharp/programming-guide/classes-and-structs/instance-constructors.md#primary-constructors) syntax. Primary constructors combine the type definition with the parameters necessary to instantiate any instance of the class. The C# compiler generates public properties for the primary constructor parameters.)

   Send the request using the record type as the type argument to `GetResponseAsync<T>`:


   This code produces output similar to:

   ```output
   Response text: Certainly, I have analyzed the sentiment of the review you provided.
   Sentiment: Neutral
   ```

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and model deployment.

1. In the [Azure portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

## See also

- [Structured outputs (Azure OpenAI Service)](/azure/ai-services/openai/how-to/structured-outputs)
- [Using JSON schema for structured output in .NET for OpenAI models](https://devblogs.microsoft.com/semantic-kernel/using-json-schema-for-structured-output-in-net-for-openai-models)
- [Introducing Structured Outputs in the API (OpenAI)](https://openai.com/index/introducing-structured-outputs-in-the-api/)

---
title: Quickstart - Generate images from text using AI
description: Learn how to use Microsoft.Extensions.AI to generate images from text prompts using AI models in a .NET application.
ms.date: 03/04/2026
ms.topic: quickstart
ai-usage: ai-assisted
---

# Generate images from text using AI

In this quickstart, you use the <xref:Microsoft.Extensions.AI> (MEAI) library to generate images from text prompts using an AI model. The MEAI text-to-image capabilities let you generate images from natural language prompts or existing images using a consistent and extensible API surface.

The <xref:Microsoft.Extensions.AI.IImageGenerator> interface provides a unified, extensible API for working with various image generation services, making it easy to integrate text-to-image capabilities into your .NET apps. The interface supports:

- Text-to-image generation.
- Pipeline composition with middleware (logging, telemetry, caching).
- Flexible configuration options.
- Support for multiple AI providers.

> [!NOTE]
> The `IImageGenerator` interface is currently marked as experimental with the `MEAI001` diagnostic ID. You might need to suppress this warning in your project file or code.

<!--Prereqs-->
[!INCLUDE [azure-openai-prereqs](../quickstarts/includes/prerequisites-azure-openai.md)]

## Configure the AI service

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. In the "Deploy a model" step, select the `gpt-image-1` model.

> [!NOTE]
> `gpt-image-1` is a newer model that offers several improvements over DALL-E 3. It's available from OpenAI on a limited basis; apply for access with [this form](https://aka.ms/oai/gptimage1access).

## Create the application

Complete the following steps to create a .NET console application that generates images from text prompts.

1. Create a new console application:

    ```dotnetcli
    dotnet new console -o TextToImageAI
    ```

1. Navigate to the `TextToImageAI` directory, and add the necessary packages to your app:

    ```dotnetcli
    dotnet add package Azure.AI.OpenAI
    dotnet add package Microsoft.Extensions.AI.OpenAI
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    ```

1. Run the following commands to add [app secrets](/aspnet/core/security/app-secrets) for your Azure OpenAI endpoint and API key:

    ```bash
    dotnet user-secrets init
    dotnet user-secrets set AZURE_OPENAI_ENDPOINT <your-Azure-OpenAI-endpoint>
    dotnet user-secrets set AZURE_OPENAI_API_KEY <your-azure-openai-api-key>
    ```

1. Open the new app in your editor of choice (for example, Visual Studio).

## Implement basic image generation

1. Update the `Program.cs` file with the following code to get the configuration data and create the <xref:Azure.AI.OpenAI.AzureOpenAIClient>:


   The preceding code:

   - Loads configuration from user secrets.
   - Creates an `ImageClient` from the OpenAI SDK.
   - Converts the `ImageClient` to an `IImageGenerator` using the <xref:Microsoft.Extensions.AI.OpenAIClientExtensions.AsIImageGenerator(OpenAI.Images.ImageClient)> extension method.

1. Add the following code to implement basic text-to-image generation:


   The preceding code:

   - Sets the requested image file type by setting <xref:Microsoft.Extensions.AI.ImageGenerationOptions.MediaType?displayProperty=nameWithType>.
   - Generates an image using the <xref:Microsoft.Extensions.AI.ImageGeneratorExtensions.GenerateImagesAsync(Microsoft.Extensions.AI.IImageGenerator,System.String,Microsoft.Extensions.AI.ImageGenerationOptions,System.Threading.CancellationToken)> method with a text prompt.
   - Saves the generated image to a file in the local user directory.

1. Run the application, either through the IDE or using `dotnet run`.

   The application generates an image and outputs the file path to the image. Open the file to view the generated image. The following image shows one example of a generated image.


## Configure image generation options

You can customize image generation by providing other options such as size, response format, and number of images to generate. The <xref:Microsoft.Extensions.AI.ImageGenerationOptions> class allows you to specify:

- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.AdditionalProperties>: Provider-specific options.
- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.Count>: The number of images to generate.
- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.ImageSize>: The dimensions of the generated image as a <xref:System.Drawing.Size?displayProperty=fullName>. For supported sizes, see the [OpenAI API reference](https://platform.openai.com/docs/api-reference/images/create).
- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.MediaType>: The media type (MIME type) of the generated image.
- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.ModelId>: The model ID.
- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.RawRepresentationFactory>: The callback that creates the raw representation of the image generation options from an underlying implementation.
- <xref:Microsoft.Extensions.AI.ImageGenerationOptions.ResponseFormat>: Options are <xref:Microsoft.Extensions.AI.ImageGenerationResponseFormat.Uri>, <xref:Microsoft.Extensions.AI.ImageGenerationResponseFormat.Data>, and <xref:Microsoft.Extensions.AI.ImageGenerationResponseFormat.Hosted>.

## Use hosting integration

When you build web apps or hosted services, you can integrate image generation using dependency injection and hosting patterns. This approach provides better lifecycle management, configuration integration, and testability.

### Configure hosting services

The `Aspire.Azure.AI.OpenAI` package provides extension methods to register Azure OpenAI services with your application's dependency injection container:

1. Add the necessary packages to your web application:

   ```dotnetcli
   dotnet add package Aspire.Azure.AI.OpenAI --prerelease
   dotnet add package Azure.AI.OpenAI
   dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
   ```

1. Configure the Azure OpenAI client and image generator in your `Program.cs` file:


   The <xref:Microsoft.Extensions.Hosting.AspireAzureOpenAIExtensions.AddAzureOpenAIClient(Microsoft.Extensions.Hosting.IHostApplicationBuilder,System.String,System.Action{Aspire.Azure.AI.OpenAI.AzureOpenAISettings},System.Action{Azure.Core.Extensions.IAzureClientBuilder{Azure.AI.OpenAI.AzureOpenAIClient,Azure.AI.OpenAI.AzureOpenAIClientOptions}})> method registers the Azure OpenAI client with dependency injection. The connection string (named `"openai"`) is retrieved from configuration, typically from `appsettings.json` or environment variables:

   ```json
   {
     "ConnectionStrings": {
       "openai": "Endpoint=https://your-resource-name.openai.azure.com/;Key=your-api-key"
     }
   }
   ```

1. Register the <xref:Microsoft.Extensions.AI.IImageGenerator> service with dependency injection:


   The <xref:Microsoft.Extensions.DependencyInjection.ImageGeneratorBuilderServiceCollectionExtensions.AddImageGenerator*> method registers the image generator as a singleton service that can be injected into controllers, services, or minimal API endpoints.

1. Add options and logging::


   The preceding code:

   - Configures options by calling the <xref:Microsoft.Extensions.AI.ConfigureOptionsImageGeneratorBuilderExtensions.ConfigureOptions(Microsoft.Extensions.AI.ImageGeneratorBuilder,System.Action{Microsoft.Extensions.AI.ImageGenerationOptions})> extension method on the <xref:Microsoft.Extensions.AI.ImageGeneratorBuilder>. This method configures the <xref:Microsoft.Extensions.AI.ImageGenerationOptions> to be passed to the next generator in the pipeline.
   - Adds logging to the image generator pipeline by calling the <xref:Microsoft.Extensions.AI.LoggingImageGeneratorBuilderExtensions.UseLogging(Microsoft.Extensions.AI.ImageGeneratorBuilder,Microsoft.Extensions.Logging.ILoggerFactory,System.Action{Microsoft.Extensions.AI.LoggingImageGenerator})> extension method.

### Use the image generator in endpoints

Once registered, you can inject `IImageGenerator` into your endpoints or services:


This hosting approach provides several benefits:

- **Configuration management**: Connection strings and settings are managed through the .NET configuration system.
- **Dependency injection**: The image generator is available throughout your application via DI.
- **Lifecycle management**: Services are properly initialized and disposed of by the hosting infrastructure.
- **Testability**: Mock implementations can be easily substituted for testing.
- **Integration with .NET Aspire**: When using .NET Aspire, the `AddAzureOpenAIClient` method integrates with service discovery and telemetry.

## Best practices

When implementing text-to-image generation in your applications, consider these best practices:

- **Prompt engineering**: Write clear, detailed prompts that describe the desired image. Include specific details about style, composition, colors, and elements.
- **Cost management**: Image generation can be expensive. Cache results when possible and implement rate limiting to control costs.
- **Content safety**: Always review generated images for appropriate content, especially in production applications. Consider implementing content filtering and moderation.
- **User experience**: Image generation can take several seconds. Provide progress indicators and handle timeouts gracefully.
- **Legal considerations**: Be aware of licensing and usage rights for generated images. Review the terms of service for your AI provider.

## Clean up resources

When you no longer need the Azure OpenAI resource, delete it to avoid incurring charges:

1. In the [Azure portal](https://portal.azure.com), navigate to your Azure OpenAI resource.
1. Select the resource and then select **Delete**.

## Next steps

You've successfully generated some different images using the <xref:Microsoft.Extensions.AI.IImageGenerator> interface in <xref:Microsoft.Extensions.AI>. Next, you can explore some of the additional functionality, including:

- Refining the generated image iteratively.
- Editing an existing image.
- Personalizing an image, diagram, or theme.

## See also

- [Explore text-to-image capabilities in .NET (blog post)](https://devblogs.microsoft.com/dotnet/explore-text-to-image-dotnet/)
- [Microsoft.Extensions.AI library overview](../microsoft-extensions-ai.md)
- [Quickstart: Build an AI chat app with .NET](../quickstarts/build-chat-app.md)

---
title: Quickstart - Extend OpenAI using functions and execute a local function with .NET
description: Create a simple chat app using OpenAI and extend the model to execute a local function.
ms.date: 03/04/2026
ms.topic: quickstart
ai-usage: ai-assisted
zone_pivot_groups: openai-library
---

# Invoke .NET functions using an AI model

In this quickstart, you create a .NET console AI chat app that connects to an AI model with local function-calling enabled. 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.

:::zone target="docs" pivot="openai"

[!INCLUDE [openai-prereqs](includes/prerequisites-openai.md)]

:::zone-end

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [azure-openai-prereqs](includes/prerequisites-azure-openai.md)]

:::zone-end

## Create the app

Complete the following steps to create a .NET console app to connect to an AI model.

1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:

    ```dotnetcli
    dotnet new console -o FunctionCallingAI
    ```

1. Change directory into the app folder:

    ```dotnetcli
    cd FunctionCallingAI
    ```

1. Install the required packages:

    :::zone target="docs" pivot="azure-openai"

    ```bash
    dotnet add package Azure.Identity
    dotnet add package Azure.AI.OpenAI
    dotnet add package Microsoft.Extensions.AI
    dotnet add package Microsoft.Extensions.AI.OpenAI
    dotnet add package Microsoft.Extensions.Configuration
    dotnet add package Microsoft.Extensions.Configuration.UserSecrets
    ```

    :::zone-end

    :::zone target="docs" pivot="openai"

    ```bash
    dotnet add package Microsoft.Extensions.AI
    dotnet add package Microsoft.Extensions.AI.OpenAI
    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 .
    ```

:::zone target="docs" pivot="azure-openai"

[!INCLUDE [create-ai-service](includes/create-ai-service.md)]

:::zone-end

:::zone target="docs" pivot="openai"

## Configure the app

1. Navigate to the root of your .NET project from a terminal or command prompt.

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>
    ```

:::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. The `ChatClient` is also configured to use function invocation, which allows the AI model to call .NET functions in your code.

    :::zone target="docs" pivot="azure-openai"


    :::zone-end

    :::zone target="docs" pivot="openai"


    :::zone-end

1. Create a new `ChatOptions` object that contains an inline function the AI model can call to get the current weather. The function declaration includes a delegate to run logic, and name and description parameters to describe the purpose of the function to the AI model.


1. Add a system prompt to the `chatHistory` to provide context and instructions to the model. Send a user prompt with a question that requires the AI model to call the registered function to properly answer the question.


1. Use the `dotnet run` command to run the app:

    ```dotnetcli
    dotnet run
    ```

    The app prints the completion response from the AI model, which includes data provided by the .NET function. The AI model understood that the registered function was available and called it automatically to generate a proper response.

:::zone target="docs" pivot="azure-openai"

## Clean up resources

If you no longer need them, delete the Azure OpenAI resource and GPT-4 model deployment.

1. In the [Azure portal](https://aka.ms/azureportal), navigate to the Azure OpenAI resource.
1. Select the Azure OpenAI resource, and then select **Delete**.

:::zone-end

## Next steps

- [Handle invalid tool input from AI models](../how-to/handle-invalid-tool-input.md)
- [Access data in AI functions](../how-to/access-data-in-functions.md)
- [Quickstart - Build an AI chat app with .NET](build-chat-app.md)
- [Generate text and conversations with .NET and Azure OpenAI Completions](/training/modules/open-ai-dotnet-text-completions/)

---
title: Azure AI learning resources
description: This article provides a list of resources about Azure AI scenarios for .NET developers, including documentation and code samples.
ms.date: 09/04/2025
ms.topic: reference
---

# Azure AI learning resources

This article contains an organized list of the best learning resources for .NET developers who are building AI apps using Azure services. Resources include popular quickstart articles, reference samples, documentation, and training courses.

[!INCLUDE [include-file-from-azure-dev-docs-pr](~/azure-dev-docs-pr/articles/ai/includes/azure-ai-for-developers-dotnet.md)]

---
title: Learning resources to get started with AI in .NET
description: This article provides a list of resources for .NET developers who are starting to build AI apps with .NET.
ms.date: 09/04/2025
ms.topic: reference
---

# Learning resources to get started with AI in .NET

This article contains an organized list of the best learning resources for .NET developers who are starting to build AI apps with .NET. Resources include samples, documentation, videos, and workshops.

## Tutorials

- [Generative AI for beginners](https://github.com/microsoft/Generative-AI-for-beginners-dotnet)

## Workshops

- [AI workshop](https://github.com/dotnet-presentations/ai-workshop)
- [Steve Sanderson's AI workshop](https://github.com/SteveSandersonMS/dotnet-ai-workshop)

## Sample apps

- [AI samples for .NET](https://github.com/dotnet/ai-samples)

---
title: MCP server learning resources
description: This article provides a list of resources for .NET developers who are building MCP servers.
ms.date: 09/04/2025
ms.topic: reference
---

# MCP server learning resources

This article contains an organized list of the best learning resources for .NET developers who are building Model Context Protocol (MCP) servers. Resources include samples, documentation, videos, and workshops.

## Getting started

| Link | Description |
|------|-------------|
|[Anthropic - Getting Started with MCP](https://modelcontextprotocol.io/docs/getting-started/intro)|Anthropic's official guide to the Model Context Protocol (MCP) and overview on how to get started writing or using an MCP server.|
|[Create a minimal MCP server using C# and publish to NuGet](../quickstarts/build-mcp-server.md)|A quick guide to writing an MCP server in VS Code and publishing it to NuGet.|
|[MCP for Beginners GitHub repo](https://github.com/microsoft/mcp-for-beginners)|A Microsoft-official GitHub repository with a full, hands-on curriculum for developing MCP servers in .NET, Java, TypeScript, JavaScript, Rust, and Python.|
|[Build agents using MCP on Azure](/azure/developer/ai/build-openai-mcp-server-dotnet)| A walkthrough on how to connect an MCP client using Azure OpenAI and MCP server to Azure Container Apps. |

## Libraries

| Link                                                             | Description |
|------------------------------------------------------------------|-------------|
| [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) | Microsoft and Anthropic's official C# SDK for MCP servers and clients. |

## Samples

| Link | Description |
|------|-------------|
|[MCP Workshop GitHub repo](https://github.com/Azure-Samples/mcp-workshop-dotnet)|A sample MCP server and client with corresponding, step-by-step walkthroughs on how to implement them and how MCP works.|

## Documentation

| Link | Description |
|------|-------------|
|[MCP C# SDK Documentation](https://modelcontextprotocol.github.io/csharp-sdk/index.html)|Anthropic's official guide to the Model Context Protocol (MCP) and overview on how to get started writing or using an MCP server.|
|[VS Code MCP Developer Guide](https://code.visualstudio.com/api/extension-guides/ai/mcp)| Official documentation for building, debugging, and registering an MCP server in VS Code.|

## Additional resources

| Link | Description |
|------|-------------|
|[MCP Inspector Tool](https://github.com/modelcontextprotocol/inspector)|The Anthropic-official GitHub repo for the MCP Inspector tool, a visual testing and debugging tool for MCP servers.|
|[MCP servers for VS Code](https://code.visualstudio.com/mcp)|A hub for quickly installing first-party and third-party MCP servers in VS Code.|
|[Third party MCP servers](https://github.com/modelcontextprotocol/servers?tab=readme-ov-file#-third-party-servers)|A GitHub repo containing a comprehensive list of publicly available MCP servers.|

## Videos

| Link | Description |
|------|-------------|
|[MCP Dev Days (Microsoft Reactor)](https://developer.microsoft.com/reactor/series/S-1563/)|A 2-day virtual event and video series showing how to use and write MCP servers.|
|[ASP.NET Community Standup - Build MCP servers with ASP.NET Core](https://www.youtube.com/live/x_6iUhdHnhc?si=J8QQuirYWk0JXC_V)|A roundtable discussion and demo on building an MCP server with ASP.NET Core and the MCP C# SDK.|

## Communities

| Link | Description |
|------|-------------|
|[Anthropic MCP Discussions](https://github.com/orgs/modelcontextprotocol/discussions)|An open forum for discussing MCP in Anthropic's official MCP GitHub repo.|
|[Microsoft Foundry Discord](https://discord.com/invite/ByRwuEEgH4)|A Discord discussion space for developers looking to build with Microsoft AI tooling.|

---
title: Tutorial - Integrate OpenAI with the RAG pattern and vector search using Azure Cosmos DB for MongoDB
description: Create a simple recipe app using the RAG pattern and vector search using Azure Cosmos DB for MongoDB.
ms.date: 03/04/2026
ai-usage: ai-assisted
ms.topic: tutorial
author: alexwolfmsft
ms.author: alexwolf
---

# Implement Azure OpenAI with RAG using vector search in a .NET app

This tutorial explores integration of the RAG pattern using OpenAI models and vector search capabilities in a .NET app. The sample application performs vector searches on custom data stored in Azure Cosmos DB for MongoDB and further refines the responses using generative AI models, such as gpt-5. In the sections that follow, you set up a sample application and explore key code examples that demonstrate these concepts.

## Prerequisites

- [.NET 8.0](https://dotnet.microsoft.com/)
- An [Azure Account](https://azure.microsoft.com/free)
- An [Azure Cosmos DB for MongoDB vCore](/azure/cosmos-db/mongodb/vcore/introduction) service
- An [Azure Open AI](/azure/ai-services/openai/overview) service
  - Deploy `text-embedding-ada-002` model for embeddings
  - Deploy `gpt-35-turbo` model for chat completions

## App overview

The Cosmos Recipe Guide app lets you perform vector and AI-driven searches against a set of recipe data. Search directly for available recipes or prompt the app with ingredient names to find related recipes. The app and the sections ahead guide you through the following workflow to demonstrate this type of functionality:

1. Upload sample data to an Azure Cosmos DB for MongoDB database.
1. Create embeddings and a vector index for the uploaded sample data using the Azure OpenAI `text-embedding-3-small` model.
1. Perform vector similarity search based on the user prompts.
1. Use the Azure OpenAI `gpt-35-turbo` completions model to compose more meaningful answers based on the search results data.


## Get started

1. Clone the following GitHub repository:

    ```bash
    git clone https://github.com/microsoft/AzureDataRetrievalAugmentedGenerationSamples.git
    ```

1. In the _C#/CosmosDB-MongoDBvCore_ folder, open the **CosmosRecipeGuide.sln** file.

1. In the _appsettings.json_ file, replace the following config values with your Azure OpenAI and Azure Cosmos DB for MongoDB values:

    ```json
    "OpenAIEndpoint": "https://<your-service-name>.openai.azure.com/",
    "OpenAIKey": "<your-API-key>",
    "OpenAIEmbeddingDeployment": "<your-ADA-deployment-name>",
    "OpenAIcompletionsDeployment": "<your-GPT-deployment-name>",
    "MongoVcoreConnection": "<your-Mongo-connection-string>"
    ```

1. Launch the app by pressing the **Start** button at the top of Visual Studio.

## Explore the app

When you run the app for the first time, it connects to Azure Cosmos DB and reports that there are no recipes available yet. Follow the steps displayed by the app to begin the core workflow.

1. Select **Upload recipe(s) to Cosmos DB** and press <kbd>Enter</kbd>. This command reads sample JSON files from the local project and uploads them to the Cosmos DB account.

    The code from the _Utility.cs_ class parses the local JSON files.

    ``` C#
    public static List<Recipe> ParseDocuments(string Folderpath)
    {
        List<Recipe> recipes = new List<Recipe>();

        Directory.GetFiles(Folderpath)
            .ToList()
            .ForEach(f =>
            {
                var jsonString= System.IO.File.ReadAllText(f);
                Recipe recipe = JsonConvert.DeserializeObject<Recipe>(jsonString);
                recipe.id = recipe.name.ToLower().Replace(" ", "");
                recipes.Add(recipe);
            }
        );

        return recipes;
    }
    ```

    The `UpsertVectorAsync` method in the _VCoreMongoService.cs_ file uploads the documents to Azure Cosmos DB for MongoDB.

    ```C#
    public async Task UpsertVectorAsync(Recipe recipe)
        {
            BsonDocument document = recipe.ToBsonDocument();

            if (!document.Contains("_id"))
            {
                Console.WriteLine("UpsertVectorAsync: Document does not contain _id.");
                throw new ArgumentException("UpsertVectorAsync: Document does not contain _id.");
            }

            string? _idValue = document["_id"].ToString();

            try
            {
                var filter = Builders<BsonDocument>.Filter.Eq("_id", _idValue);
                var options = new ReplaceOptions { IsUpsert = true };
                await _recipeCollection.ReplaceOneAsync(filter, document, options);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Exception: UpsertVectorAsync(): {ex.Message}");
                throw;
            }
        }
    ```

1. Select **Vectorize the recipe(s) and store them in Cosmos DB**.

    The JSON items uploaded to Cosmos DB don't contain embeddings and therefore are not optimized for RAG via vector search. An embedding is an information-dense, numerical representation of the semantic meaning of a piece of text. Vector searches can find items with contextually similar embeddings.

    The `GetEmbeddingsAsync` method in the _OpenAIService.cs_ file creates an embedding for each item in the database.

    ```C#
    public async Task<float[]?> GetEmbeddingsAsync(dynamic data)
    {
        try
        {
            EmbeddingsOptions options = new EmbeddingsOptions(data)
            {
                Input = data
            };

            var response = await _openAIClient.GetEmbeddingsAsync(openAIEmbeddingDeployment, options);

            Embeddings embeddings = response.Value;
            float[] embedding = embeddings.Data[0].Embedding.ToArray();

            return embedding;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"GetEmbeddingsAsync Exception: {ex.Message}");
            return null;
        }
    }
    ```

    The `CreateVectorIndexIfNotExists` in the _VCoreMongoService.cs_ file creates a vector index, which lets you perform vector similarity searches.

    ```C#
    public void CreateVectorIndexIfNotExists(string vectorIndexName)
    {
        try
        {
            //Find if vector index exists in vectors collection
            using (IAsyncCursor<BsonDocument> indexCursor = _recipeCollection.Indexes.List())
            {
                bool vectorIndexExists = indexCursor.ToList().Any(x => x["name"] == vectorIndexName);
                if (!vectorIndexExists)
                {
                    BsonDocumentCommand<BsonDocument> command = new BsonDocumentCommand<BsonDocument>(
                        BsonDocument.Parse(@"
                            { createIndexes: 'Recipe',
                                indexes: [{
                                name: 'vectorSearchIndex',
                                key: { embedding: 'cosmosSearch' },
                                cosmosSearchOptions: {
                                    kind: 'vector-ivf',
                                    numLists: 5,
                                    similarity: 'COS',
                                    dimensions: 1536 }
                                }]
                            }"));

                    BsonDocument result = _database.RunCommand(command);
                    if (result["ok"] != 1)
                    {
                        Console.WriteLine("CreateIndex failed with response: " + result.ToJson());
                    }
                }
            }
        }
        catch (MongoException ex)
        {
            Console.WriteLine("MongoDbService InitializeVectorIndex: " + ex.Message);
            throw;
        }
    }
    ```

1. Select the **Ask AI Assistant (search for a recipe by name or description, or ask a question)** option in the app to run a user query.

   The app converts the user query to an embedding using the OpenAI service and the embedding model, then sends the embedding to Azure Cosmos DB for MongoDB to perform a vector search. The `VectorSearchAsync` method in the _VCoreMongoService.cs_ file performs a vector search to find vectors that are close to the supplied vector and returns a list of documents from Azure Cosmos DB for MongoDB vCore.

    ```C#
    public async Task<List<Recipe>> VectorSearchAsync(float[] queryVector)
        {
            List<string> retDocs = new List<string>();
            string resultDocuments = string.Empty;

            try
            {
                //Search Azure Cosmos DB for MongoDB vCore collection for similar embeddings
                //Project the fields that are needed
                BsonDocument[] pipeline = new BsonDocument[]
                {
                    BsonDocument.Parse(
                        @$"{{$search: {{
                                cosmosSearch:
                                    {{ vector: [{string.Join(',', queryVector)}],
                                       path: 'embedding',
                                       k: {_maxVectorSearchResults}}},
                                       returnStoredSource:true
                                    }}
                                }}"),
                    BsonDocument.Parse($"{{$project: {{embedding: 0}}}}"),
                };

                var bsonDocuments = await _recipeCollection
                    .Aggregate<BsonDocument>(pipeline).ToListAsync();

                var recipes = bsonDocuments
                    .ToList()
                    .ConvertAll(bsonDocument =>
                        BsonSerializer.Deserialize<Recipe>(bsonDocument));
                return recipes;
            }
            catch (MongoException ex)
            {
                Console.WriteLine($"Exception: VectorSearchAsync(): {ex.Message}");
                throw;
            }
        }
    ```

   The `GetChatCompletionAsync` method generates an improved chat completion response based on the user prompt and the related vector search results.

    ``` C#
    public async Task<(string response, int promptTokens, int responseTokens)> GetChatCompletionAsync(string userPrompt, string documents)
    {
        try
        {
            ChatMessage systemMessage = new ChatMessage(
                ChatRole.System, _systemPromptRecipeAssistant + documents);
            ChatMessage userMessage = new ChatMessage(
                ChatRole.User, userPrompt);

            ChatCompletionsOptions options = new()
            {
                Messages =
                {
                    systemMessage,
                    userMessage
                },
                MaxTokens = openAIMaxTokens,
                Temperature = 0.5f, //0.3f,
                NucleusSamplingFactor = 0.95f,
                FrequencyPenalty = 0,
                PresencePenalty = 0
            };

            Azure.Response<ChatCompletions> completionsResponse =
                await openAIClient.GetChatCompletionsAsync(openAICompletionDeployment, options);
            ChatCompletions completions = completionsResponse.Value;

            return (
                response: completions.Choices[0].Message.Content,
                promptTokens: completions.Usage.PromptTokens,
                responseTokens: completions.Usage.CompletionTokens
            );

        }
        catch (Exception ex)
        {
            string message = $"OpenAIService.GetChatCompletionAsync(): {ex.Message}";
            Console.WriteLine(message);
            throw;
        }
    }
    ```

   The app also uses prompt engineering to ensure OpenAI service limits and formats the response for supplied recipes.

    ```C#
    //System prompts to send with user prompts to instruct the model for chat session
    private readonly string _systemPromptRecipeAssistant = @"
        You are an intelligent assistant for Contoso Recipes.
        You are designed to provide helpful answers to user questions about
        recipes, cooking instructions provided in JSON format below.

        Instructions:
        - Only answer questions related to the recipe provided below.
        - Don't reference any recipe not provided below.
        - If you're unsure of an answer, say ""I don't know"" and recommend users search themselves.
        - Your response  should be complete.
        - List the Name of the Recipe at the start of your response followed by step by step cooking instructions.
        - Assume the user is not an expert in cooking.
        - Format the content so that it can be printed to the Command Line console.
        - In case there is more than one recipe you find, let the user pick the most appropriate recipe.";
     ```