{"slug":"dotnet-microsoft-extensions-ai","title":"dotnet-microsoft-extensions-ai","summary":"Build provider-agnostic .NET AI integrations with `Microsoft.Extensions.AI`, `IChatClient`, embeddings, middleware, structured output, vector search, and evaluation.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-27T21:00:36.244251Z","repo":{"url":"https://github.com/Postpartum-genushyacinthus29/dotnet-skills","stars":12,"forks":1,"license":"MIT","updatedAt":"2026-09-27T19:34:14Z"},"bodyHtml":"<hr>\n<h2>name: dotnet-microsoft-extensions-ai\nversion: \"1.3.0\"\ncategory: \"AI\"\ndescription: \"Build provider-agnostic .NET AI integrations with <code>Microsoft.Extensions.AI</code>, <code>IChatClient</code>, embeddings, middleware, structured output, vector search, and evaluation.\"\ncompatibility: \"Requires <code>Microsoft.Extensions.AI</code> or a .NET AI application that needs model, embedding, tool-calling, or evaluation composition without full agent orchestration.\"</h2>\n<h1>Microsoft.Extensions.AI</h1>\n<h2>Trigger On</h2>\n<ul>\n<li>building or reviewing <code>.NET</code> code that uses <code>Microsoft.Extensions.AI</code>, <code>Microsoft.Extensions.AI.Abstractions</code>, <code>IChatClient</code>, <code>IEmbeddingGenerator</code>, <code>ChatOptions</code>, or <code>AIFunction</code></li>\n<li>adding <code>IImageGenerator</code>, local-model chat via Ollama, AI app templates, or the <code>.NET AI</code> quickstarts for assistants and MCP</li>\n<li>choosing between low-level AI abstractions, provider SDKs, vector-search composition, evaluation libraries, and a fuller agent framework</li>\n<li>adding streaming chat, structured output, embeddings, tool calling, telemetry, caching, or DI-based AI middleware</li>\n<li>wiring <code>Microsoft.Extensions.VectorData</code>, <code>Microsoft.Extensions.DataIngestion</code>, MCP tooling, or evaluation packages around a provider-agnostic AI app</li>\n</ul>\n<h2>Workflow</h2>\n<ol>\n<li>Classify the request first: plain model access, tool calling, embeddings/vector search, evaluation, image generation, local-model prototyping, MCP bootstrap, or true agent orchestration.</li>\n<li>Default to <code>Microsoft.Extensions.AI</code> for application and service code that needs provider-agnostic chat, embeddings, middleware, structured output, and testability.</li>\n<li>Reference <code>Microsoft.Extensions.AI.Abstractions</code> directly only when authoring provider libraries or lower-level reusable integration packages.</li>\n<li>Model <code>IChatClient</code> and <code>IEmbeddingGenerator</code> composition explicitly in DI. Keep options, caching, telemetry, logging, and tool invocation inspectable in the pipeline.</li>\n<li>Treat chat state deliberately. For stateless providers, resend history. For stateful providers, propagate <code>ConversationId</code> rather than assuming all providers behave the same way.</li>\n<li>Use <code>Microsoft.Extensions.VectorData</code> and <code>Microsoft.Extensions.DataIngestion</code> as adjacent building blocks for RAG instead of hand-rolling store abstractions prematurely. Model ingestion as an explicit reader -&gt; processor -&gt; chunker -&gt; writer pipeline when the document-preparation path matters.</li>\n<li>Treat the <code>.NET AI</code> quickstarts as bootstrap paths, not finished architecture. They now cover minimal assistants, MCP client/server flows, local models, app templates, and image generation. Start there for a vertical slice, then harden the DI, telemetry, and evaluation story here.</li>\n<li>Escalate to <code>dotnet-microsoft-agent-framework</code> when the requirement becomes agent threads, multi-agent orchestration, higher-order workflows, durable execution, or remote agent hosting.</li>\n<li>Validate with real providers, realistic prompts, and evaluation gates so the abstraction layer actually buys portability and reliability.</li>\n</ol>\n<h2>Architecture</h2>\n<pre>flowchart LR\n  A[\"Task\"] --&gt; B{\"Need agent threads, multi-agent orchestration, or remote agent hosting?\"}\n  B --&gt;|Yes| C[\"Use Microsoft Agent Framework on top of `Microsoft.Extensions.AI.Abstractions`\"]\n  B --&gt;|No| D{\"Need provider-agnostic chat, embeddings, tools, typed output, or evaluation?\"}\n  D --&gt;|Yes| E[\"Use `Microsoft.Extensions.AI`\"]\n  E --&gt; F[\"Compose `IChatClient` / `IEmbeddingGenerator` in DI\"]\n  F --&gt; G[\"Add caching, telemetry, tools, vector data, and evaluation deliberately\"]\n  D --&gt;|No| H[\"Use plain provider SDKs or deterministic .NET code\"]\n</pre>\n<h2>Core Knowledge</h2>\n<ul>\n<li><code>Microsoft.Extensions.AI.Abstractions</code> contains the core exchange contracts such as <code>IChatClient</code>, <code>IEmbeddingGenerator&lt;TInput, TEmbedding&gt;</code>, message/content types, and tool abstractions.</li>\n<li><code>Microsoft.Extensions.AI</code> adds the higher-level application surface: middleware builders, automatic function invocation, caching, logging, and OpenTelemetry integration.</li>\n<li>Most apps and services should reference <code>Microsoft.Extensions.AI</code>; provider and connector libraries usually reference only the abstractions package.</li>\n<li><code>IChatClient</code> centers on <code>GetResponseAsync</code> and <code>GetStreamingResponseAsync</code>. The returned <code>ChatResponse</code> or <code>ChatResponseUpdate</code> objects carry messages, tool-related content, metadata, and optional conversation identifiers.</li>\n<li>Local-model quickstarts still route through the same <code>IChatClient</code> abstraction. Ollama-backed clients are useful for low-cost prototyping, offline dev loops, and portability testing, but you still own chat history replay, latency, and model-quality tradeoffs.</li>\n<li><code>ChatOptions</code> is the normal control plane for model ID, temperature, tools, <code>AdditionalProperties</code>, and provider-specific raw options.</li>\n<li>Tool calling is modeled with <code>AIFunction</code>, <code>AIFunctionFactory</code>, and <code>FunctionInvokingChatClient</code>. Ambient data can flow through closures, <code>AdditionalProperties</code>, <code>AIFunctionArguments.Context</code>, or DI.</li>\n<li>Tool calling can target local .NET methods, external APIs, or MCP-backed tools. The model requests calls; your app still owns execution, validation, and side-effect boundaries.</li>\n<li>Tool definitions consume request tokens. Keep tool descriptions short and register only the tools relevant for the current conversation or workflow.</li>\n<li><code>FunctionInvokingChatClient</code> can handle the tool-invocation loop and parallel tool-call responses automatically when the provider/model supports that shape.</li>\n<li><code>IEmbeddingGenerator</code> is the standard abstraction for semantic search, vector indexing, similarity, and cache-key generation. Pair it with <code>Microsoft.Extensions.VectorData.Abstractions</code> for vector store operations.</li>\n<li><code>IImageGenerator</code> is the experimental MEAI image surface. Treat <code>MEAI001</code> as an intentional opt-in, keep image generation separate from chat concerns, and compose logging/caching/hosting middleware around it the same way you would for <code>IChatClient</code>.</li>\n<li><code>Microsoft.Extensions.DataIngestion</code> gives you the document-side RAG pipeline: <code>IngestionDocument</code>, document readers like MarkItDown/Markdig, document processors such as <code>ImageAlternativeTextEnricher</code>, chunkers, chunk processors, <code>VectorStoreWriter&lt;T&gt;</code>, and <code>IngestionPipeline&lt;T&gt;</code> for end-to-end composition.</li>\n<li><code>IngestionPipeline&lt;T&gt;.ProcessAsync</code> is partial-success oriented. Handle <code>IAsyncEnumerable&lt;IngestionResult&gt;</code> deliberately instead of assuming one failed document should automatically crash the whole ingestion run.</li>\n<li><code>Microsoft.Extensions.AI.Evaluation.*</code> gives you quality, NLP, safety, caching, and reporting layers for regression checks and CI gates.</li>\n<li>The official <code>.NET AI</code> docs now make MCP, assistants, local models, templates, and text-to-image part of the same app-level story. Use <code>dotnet-mcp</code> when the protocol itself becomes the design problem; stay here when you still mostly need app composition around <code>IChatClient</code> and friends.</li>\n<li><code>Microsoft Agent Framework</code> builds on these abstractions. Use it when you need autonomous orchestration, threads, workflows, hosting, or multi-agent collaboration instead of just model composition.</li>\n</ul>\n<h2>Decision Cheatsheet</h2>\n<table>\n<thead>\n<tr>\n<th>If you need</th>\n<th>Default choice</th>\n<th>Why</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>App-level provider abstraction with middleware</td>\n<td><code>Microsoft.Extensions.AI</code></td>\n<td>Highest leverage for apps and services</td>\n</tr>\n<tr>\n<td>A reusable provider or connector library</td>\n<td><code>Microsoft.Extensions.AI.Abstractions</code></td>\n<td>Keeps your package at the contract layer</td>\n</tr>\n<tr>\n<td>Typed chat or UI streaming</td>\n<td><code>IChatClient</code> with <code>GetResponseAsync</code> / <code>GetStreamingResponseAsync</code></td>\n<td>Common request/response shape across providers</td>\n</tr>\n<tr>\n<td>Tool calling from .NET methods</td>\n<td><code>AIFunction</code> + <code>FunctionInvokingChatClient</code></td>\n<td>Native function metadata and invocation pipeline</td>\n</tr>\n<tr>\n<td>Typed structured output</td>\n<td><code>IChatClient.GetResponseAsync&lt;T&gt;</code> extensions</td>\n<td>Keeps schema intent in code instead of prompt parsing</td>\n</tr>\n<tr>\n<td>Vector search or RAG</td>\n<td><code>IEmbeddingGenerator</code> + <code>Microsoft.Extensions.VectorData.Abstractions</code></td>\n<td>Standardizes embeddings and store access</td>\n</tr>\n<tr>\n<td>Local model prototyping</td>\n<td><code>IChatClient</code> with an Ollama-backed implementation</td>\n<td>Keeps the app on the MEAI abstractions while you validate prompts or UX locally</td>\n</tr>\n<tr>\n<td>Text-to-image or image-generation middleware</td>\n<td><code>IImageGenerator</code></td>\n<td>Use the dedicated image abstraction instead of overloading chat APIs</td>\n</tr>\n<tr>\n<td>Evaluation and regression gates</td>\n<td><code>Microsoft.Extensions.AI.Evaluation.*</code></td>\n<td>Relevance, safety, task adherence, caching, reports</td>\n</tr>\n<tr>\n<td>Agent threads or multi-step autonomous orchestration</td>\n<td><code>dotnet-microsoft-agent-framework</code></td>\n<td>This is beyond plain provider abstraction</td>\n</tr>\n</tbody>\n</table>\n<h2>Common Failure Modes</h2>\n<ul>\n<li>Referencing only <code>Microsoft.Extensions.AI.Abstractions</code> in an app and then rebuilding middleware, telemetry, or function invocation by hand.</li>\n<li>Treating <code>IChatClient</code> as if it already gives you durable agent threads, orchestration, or hosted-agent semantics.</li>\n<li>Mixing provider-specific assistants APIs with <code>IChatClient</code> as if they were the same runtime contract.</li>\n<li>Forgetting to distinguish stateless history replay from stateful <code>ConversationId</code> flows.</li>\n<li>Hiding important chat behavior in singleton service fields instead of explicit message history, options, or persistent storage.</li>\n<li>Adding tool calling without validating parameter binding, invalid input behavior, side effects, or DI-scoped dependencies.</li>\n<li>Building RAG without stable chunking, embedding-model/version tracking, or vector dimension discipline.</li>\n<li>Shipping AI features without evaluation baselines, safety checks, or telemetry for prompt/model drift.</li>\n</ul>\n<h2>Deliver</h2>\n<ul>\n<li>a justified package and abstraction choice: <code>Abstractions</code> only vs full <code>Microsoft.Extensions.AI</code></li>\n<li>a concrete <code>IChatClient</code> / <code>IEmbeddingGenerator</code> composition strategy</li>\n<li>explicit tool-calling, options, state, caching, logging, and telemetry decisions</li>\n<li>vector-search, evaluation, or MCP integration guidance when the scenario needs it</li>\n<li>a clear escalation path to Agent Framework when the problem exceeds provider abstraction</li>\n</ul>\n<h2>Validate</h2>\n<ul>\n<li>the abstraction layer solves a real portability, testability, or composition problem</li>\n<li>provider registration and middleware order stay explicit in DI</li>\n<li>chat state management matches whether the provider is stateless or stateful</li>\n<li>structured output, tool invocation, and embedding flows are typed and observable</li>\n<li>vector store, embedding model, and chunking strategy are consistent</li>\n<li>evaluation or safety gates exist for important prompts and agent-like behaviors</li>\n<li>agentic requirements are not being under-modeled as a simple <code>IChatClient</code> integration</li>\n</ul>\n<p>When exact wording, edge-case API behavior, or less-common examples matter, check the local official docs snapshot before relying on summaries.</p>\n<h2>References</h2>\n<ul>\n<li><a href=\"references/official-docs-index.md\">official-docs-index.md</a> - Slim local snapshot map with direct links to every mirrored <code>.NET AI</code> docs page plus API-reference pointers</li>\n<li><a href=\"references/patterns.md\">patterns.md</a> - Package choice, <code>IChatClient</code>, embeddings, DI pipelines, tool-calling, and Agent Framework escalation guidance</li>\n<li><a href=\"references/examples.md\">examples.md</a> - Quickstart-to-task map covering chat, structured output, function calling, vector search, local models, MCP, and assistants</li>\n<li><a href=\"references/evaluation.md\">evaluation.md</a> - Quality, NLP, safety, caching, reporting, and CI-oriented evaluation guidance</li>\n</ul>\n","files":[{"path":"references/evaluation.md","sizeBytes":3837,"isText":true},{"path":"references/examples.md","sizeBytes":4683,"isText":true},{"path":"references/official-docs/azure-ai-services-authentication.md","sizeBytes":9115,"isText":true},{"path":"references/official-docs/conceptual/agents.md","sizeBytes":3127,"isText":true},{"path":"references/official-docs/conceptual/ai-tools.md","sizeBytes":5599,"isText":true},{"path":"references/official-docs/conceptual/chain-of-thought-prompting.md","sizeBytes":2721,"isText":true},{"path":"references/official-docs/conceptual/data-ingestion.md","sizeBytes":13011,"isText":true},{"path":"references/official-docs/conceptual/embeddings.md","sizeBytes":5260,"isText":true},{"path":"references/official-docs/conceptual/how-genai-and-llms-work.md","sizeBytes":8402,"isText":true},{"path":"references/official-docs/conceptual/prompt-engineering-dotnet.md","sizeBytes":4805,"isText":true},{"path":"references/official-docs/conceptual/rag.md","sizeBytes":2648,"isText":true},{"path":"references/official-docs/conceptual/understanding-tokens.md","sizeBytes":6817,"isText":true},{"path":"references/official-docs/conceptual/vector-databases.md","sizeBytes":3593,"isText":true},{"path":"references/official-docs/conceptual/zero-shot-learning.md","sizeBytes":4870,"isText":true},{"path":"references/official-docs/dotnet-ai-ecosystem.md","sizeBytes":9815,"isText":true},{"path":"references/official-docs/evaluation/evaluate-ai-response.md","sizeBytes":6663,"isText":true},{"path":"references/official-docs/evaluation/evaluate-safety.md","sizeBytes":12796,"isText":true},{"path":"references/official-docs/evaluation/evaluate-with-reporting.md","sizeBytes":14504,"isText":true},{"path":"references/official-docs/evaluation/libraries.md","sizeBytes":12162,"isText":true},{"path":"references/official-docs/evaluation/responsible-ai.md","sizeBytes":2376,"isText":true},{"path":"references/official-docs/get-started-app-chat-scaling-with-azure-container-apps.md","sizeBytes":2440,"isText":true},{"path":"references/official-docs/get-started-app-chat-template.md","sizeBytes":17419,"isText":true},{"path":"references/official-docs/get-started-mcp.md","sizeBytes":7146,"isText":true},{"path":"references/official-docs/how-to/access-data-in-functions.md","sizeBytes":5851,"isText":true},{"path":"references/official-docs/how-to/app-service-aoai-auth.md","sizeBytes":8078,"isText":true},{"path":"references/official-docs/how-to/content-filtering.md","sizeBytes":2675,"isText":true},{"path":"references/official-docs/how-to/handle-invalid-tool-input.md","sizeBytes":3950,"isText":true},{"path":"references/official-docs/how-to/use-tokenizers.md","sizeBytes":5036,"isText":true},{"path":"references/official-docs/ichatclient.md","sizeBytes":16895,"isText":true},{"path":"references/official-docs/iembeddinggenerator.md","sizeBytes":4304,"isText":true},{"path":"references/official-docs-index.md","sizeBytes":8487,"isText":true},{"path":"references/official-docs/microsoft-extensions-ai.md","sizeBytes":6559,"isText":true},{"path":"references/official-docs/overview.md","sizeBytes":4033,"isText":true},{"path":"references/official-docs/quickstarts/ai-templates.md","sizeBytes":1877,"isText":true},{"path":"references/official-docs/quickstarts/build-chat-app.md","sizeBytes":4483,"isText":true},{"path":"references/official-docs/quickstarts/build-mcp-client.md","sizeBytes":3110,"isText":true},{"path":"references/official-docs/quickstarts/build-mcp-server.md","sizeBytes":21794,"isText":true},{"path":"references/official-docs/quickstarts/build-vector-search-app.md","sizeBytes":9755,"isText":true},{"path":"references/official-docs/quickstarts/chat-local-model.md","sizeBytes":6417,"isText":true},{"path":"references/official-docs/quickstarts/create-assistant.md","sizeBytes":5279,"isText":true},{"path":"references/official-docs/quickstarts/generate-images.md","sizeBytes":4112,"isText":true},{"path":"references/official-docs/quickstarts/process-data.md","sizeBytes":7231,"isText":true},{"path":"references/official-docs/quickstarts/prompt-model.md","sizeBytes":4862,"isText":true},{"path":"references/official-docs/quickstarts/publish-mcp-registry.md","sizeBytes":12449,"isText":true},{"path":"references/official-docs/quickstarts/structured-output.md","sizeBytes":5616,"isText":true},{"path":"references/official-docs/quickstarts/text-to-image.md","sizeBytes":10707,"isText":true},{"path":"references/official-docs/quickstarts/use-function-calling.md","sizeBytes":4719,"isText":true},{"path":"references/official-docs/resources/azure-ai.md","sizeBytes":625,"isText":true},{"path":"references/official-docs/resources/get-started.md","sizeBytes":845,"isText":true},{"path":"references/official-docs/resources/mcp-servers.md","sizeBytes":3839,"isText":true},{"path":"references/official-docs/tutorials/tutorial-ai-vector-search.md","sizeBytes":12673,"isText":true},{"path":"references/patterns.md","sizeBytes":5310,"isText":true},{"path":"SKILL.md","sizeBytes":11239,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-27T21:02:49.479333Z","sha256":"5E62EE92B16C9764585FA570503233F66B699EA5D3E569AC5A11F8822CEDDA16","sizeBytes":136657},"review":null,"source":{"repositoryUrl":"https://github.com/Postpartum-genushyacinthus29/dotnet-skills","path":"skills/dotnet-microsoft-extensions-ai","license":"MIT","commit":"bfa4ebd86f6bd674800f209ebf72ca770c2f026b","subtreeSha":"12738E55C25B97EEE3FD14E223368D61D3EEC215E09611123F6D087AEC09D7E5","lastSyncedAt":"2026-09-27T21:00:28.368219Z"},"reviewedAt":"2026-09-27T21:12:26.881972Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/Postpartum-genushyacinthus29/dotnet-skills/tree/main/skills/dotnet-microsoft-extensions-ai"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install postpartum-genushyacinthus29-dotnet-skills@llmmart"},{"target":"git","command":"git clone https://github.com/Postpartum-genushyacinthus29/dotnet-skills.git"}]}