How to Fix .NET AI App Errors: Microsoft.Extensions.AI Setup

Let's be methodical here. Open your .csproj file directly, not the NuGet Package Manager UI, which can lag behind, and look at what's actually referenced.

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.AI" Version="9.*" />
  <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.*" />
  <PackageReference Include="Azure.AI.OpenAI" Version="2.*" />
</ItemGroup>

The version numbers matter. Microsoft.Extensions.AI tracks with the .NET Extensions versioning scheme. The provider-specific packages (Microsoft.Extensions.AI.OpenAI, Microsoft.Extensions.AI.Ollama) must be compatible with your base Microsoft.Extensions.AI version. Mismatched minor versions across these packages is a frequent source of assembly binding failures that show up as MissingMethodException or TypeLoadException at runtime, not at build time, which makes them especially frustrating to diagnose.

Run dotnet nuget locals all --list to see your local package cache locations. If you've been working with pre-release builds, stale cached packages can override your intended versions. Clear the cache with:

dotnet nuget locals all --clear

Then restore fresh:

dotnet restore --no-cache

One more thing: if you're in a corporate environment with a private NuGet feed, make sure nuget.config includes https://api.nuget.org/v3/index.json as a source. Some enterprise feeds are configured as exclusive sources that block public packages entirely, and the error message ("package not found") looks identical to a typo in the package name.

When this step works, dotnet build completes without CS0246 ("type or namespace not found") errors on any Microsoft.Extensions.AI types.

The second most common failure point when you build AI apps with .NET is credentials, either hardcoded in the wrong place, missing from environment variables at runtime, or structured for one provider when you're actually targeting another.

Never put API keys in appsettings.json committed to source control. Use appsettings.Development.json (which should be in .gitignore) for local development, or better yet, the .NET Secret Manager:

dotnet user-secrets init
dotnet user-secrets set "OpenAI:ApiKey" "sk-your-key-here"
dotnet user-secrets set "AzureOpenAI:Endpoint" "https://your-resource.openai.azure.com/"
dotnet user-secrets set "AzureOpenAI:ApiKey" "your-azure-key"

For Azure OpenAI, you also need the deployment name, this is not the model name like "gpt-4o", it's the name you gave your deployment inside the Azure AI Foundry portal. These are often different and the error when they don't match is a 404 that looks like a connectivity problem:

dotnet user-secrets set "AzureOpenAI:DeploymentName" "my-gpt4o-deployment"

In your Program.cs, read configuration cleanly before registering services:

var builder = WebApplication.CreateBuilder(args);

var endpoint = builder.Configuration["AzureOpenAI:Endpoint"]
    ?? throw new InvalidOperationException("AzureOpenAI:Endpoint is not set");
var deploymentName = builder.Configuration["AzureOpenAI:DeploymentName"]
    ?? throw new InvalidOperationException("AzureOpenAI:DeploymentName is not set");

The explicit null-check with a descriptive exception message means you get a meaningful startup error instead of a cryptic NullReferenceException buried in a stack frame that points at the .NET AI internals.

For GitHub Models, which lets you access a range of models through GitHub's AI model marketplace, the configuration is the same structure as OpenAI direct, but the endpoint points to https://models.inference.ai.azure.com and you use a GitHub Personal Access Token instead of an OpenAI key. That mismatch in mental model catches people regularly.

You'll know this step is done correctly when builder.Build() succeeds without a configuration exception and your app starts cleanly.

This is where the Microsoft.Extensions.AI abstractions layer really earns its place. The IChatClient interface is your application's single point of contact with any AI model, swap the provider by changing one registration line, and nothing else in your application needs to change. That's the architecture goal, and it works when the DI registration is correct.

Here's the minimal correct registration for Azure OpenAI:

using Azure.AI.OpenAI;
using Microsoft.Extensions.AI;

// Inside builder.Services setup:
var azureClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new Azure.AzureKeyCredential(apiKey));

builder.Services.AddSingleton<IChatClient>(
    azureClient.AsChatClient(deploymentName));

For Ollama running locally on its default port:

builder.Services.AddSingleton<IChatClient>(
    new OllamaChatClient(new Uri("http://localhost:11434"), "phi3"));

The "phi3" here is the model name as Ollama knows it, run ollama list in a terminal to see exactly what's available on your machine. If you reference a model that hasn't been pulled, you'll get a connection-refused-style error because Ollama returns a non-2xx response, and the .NET AI client surfaces this as a generic HttpRequestException.

A common mistake is registering IChatClient as Transient when the underlying provider client is heavyweight and expensive to initialize. Singleton is correct for most scenarios. If you need per-request isolation (rare, but legitimate), use Scoped and understand that each request creates a new instance.

In a controller or Razor Page, inject it normally:

public class ChatController(IChatClient chatClient) : Controller
{
    public async Task<IActionResult> Ask(string prompt)
    {
        var response = await chatClient.CompleteAsync(prompt);
        return Ok(response.Message.Text);
    }
}

When this step is working, your application starts without InvalidOperationException: No service for type 'Microsoft.Extensions.AI.IChatClient' has been registered. That's the exact error text you're looking to eliminate.

Authentication is where .NET AI app setup gets genuinely tricky in real enterprise environments. The official documentation covers authenticating App Service to Azure OpenAI, and this is the path you should be on for any production workload, API keys in config files are a security liability at scale.

The production-correct approach uses a managed identity. In the Azure portal, navigate to your App Service → Settings → Identity → System assigned, and flip the toggle to On. Copy the Object (principal) ID that appears.

Now go to your Azure OpenAI resource → Access control (IAM) → Add role assignment. Select the Cognitive Services OpenAI User role (not Contributor, least privilege matters here). In the Members tab, choose Managed identity, then select your App Service.

In your .NET code, swap the key credential for a DefaultAzureCredential:

using Azure.Identity;
using Azure.AI.OpenAI;

var azureClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential());

DefaultAzureCredential is smart, in local development it tries your Azure CLI login, Visual Studio login, and environment variables in sequence. In production on App Service, it automatically picks up the managed identity. One code path, both environments.

If you get a 403 even with the role assigned, wait five minutes. Azure RBAC role assignments can take up to five minutes to propagate, and hitting the endpoint immediately after assignment is a classic "it's broken" moment that resolves on its own.

If you see error code AuthorizationFailed in the response body (not just a 403 HTTP status), the issue is at the resource level, the managed identity exists but wasn't granted the OpenAI User role on the correct resource scope. Double-check that you assigned the role on the Azure OpenAI resource specifically, not on the resource group or subscription (though those work too, they're broader than necessary).

For local development, run az login in your terminal before starting the app. If you have multiple subscriptions, run az account set --subscription "your-subscription-id" to make sure the right one is active.

If you've gotten through steps 1–4 and your basic IChatClient works, but now you're building something more complex, multiple AI agents working together, tool calling, RAG pipelines, or any kind of orchestration, you need Microsoft Agent Framework. Using bare IChatClient for these scenarios is like writing a web app without a framework: possible, but you'll reinvent a lot of wheels badly.

Agent Framework is the production-ready open-source framework that brings together the best of Semantic Kernel and Microsoft Research's AutoGen work. It's built on top of Microsoft.Extensions.AI.Abstractions, so your provider knowledge from the previous steps transfers directly.

Add the Agent Framework packages:

dotnet add package Microsoft.AI.Agents
dotnet add package Microsoft.AI.Agents.OpenAI

Agent Framework gives you five orchestration patterns out of the box: sequential (agents run one after another), concurrent (agents run in parallel and results are merged), group chat (agents discuss and iterate), handoff (one agent transfers control to another based on conditions), and magentic (a lead agent directs other agents dynamically). Most real-world agentic applications need magentic or handoff patterns, and building those by hand with raw IChatClient calls is a significant engineering investment.

A minimal two-agent setup where a research agent hands off to a summary agent looks like this:

var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(deploymentName, endpoint, apiKey)
    .Build();

var researchAgent = new ChatCompletionAgent
{
    Name = "Researcher",
    Instructions = "You find relevant facts and data about the given topic.",
    Kernel = kernel
};

var summaryAgent = new ChatCompletionAgent
{
    Name = "Summarizer",
    Instructions = "You take research notes and write a concise summary.",
    Kernel = kernel
};

Agent Framework also has built-in OpenTelemetry support, add your telemetry exporter and you immediately get traces for every agent invocation, tool call, and model response. In an enterprise environment, this observability is not optional. Without it, diagnosing why an agent workflow produces wrong outputs is guesswork.

When this step is working, you can see agent turn-by-turn traces in your telemetry backend and responses flowing through the orchestration chain correctly.