SQL Server EF Core integrations overview

SQL Server is a relational database management system developed by Microsoft. The Aspire SQL Server Entity Framework Core (EF Core) integration lets you model a SQL Server instance and its databases as first-class resources in your AppHost, then connect to them from C# consuming apps using EF Core’s familiar DbContext API.

Why use SQL Server with Aspire

Adding SQL Server through Aspire — rather than wiring up containers and connection strings by hand — gives you:

• Zero-config local development. Aspire runs SQL Server from the mcr.microsoft.com/mssql/server container image with credentials generated automatically for you.
• Consistent connection info. Once you reference the database from a consuming app, Aspire injects connection properties as environment variables in a predictable format.
• Built-in health checks. The hosting integration automatically registers a health check so the dashboard and your orchestrator can tell when the server is ready.
• Dashboard observability. The database resource shows up in the Aspire dashboard with logs, status, and telemetry alongside your other services.
• A first-class C# EF Core integration. C# apps can use the Aspire.Microsoft.EntityFrameworkCore.SqlServer package for automatic DbContext registration, health checks, and OpenTelemetry.

How the pieces fit together

The SQL Server EF Core integration has two sides: a hosting integration that you use in your AppHost to model the database resource, and a C# EF Core client integration for consuming apps.

architecture-beta

  group apphost(server)[AppHost]
  group consumer(server)[Consuming app]

  service hosting(server)[Hosting integration] in apphost
  service sqlserver(database)[SQL Server] in apphost
  service db(database)[sqldb] in apphost

  service client(iconoir:server-connection)[EF Core client integration] in consumer
  service app(server)[App] in consumer

  hosting:R --> L:sqlserver
  sqlserver:R --> L:db
  db:R --> L:client
  client:R --> L:app

The hosting integration lives in your AppHost project and models the SQL Server instance and databases as resources. The EF Core client integration lives in each C# consuming app and registers a DbContext wired to the SQL Server database Aspire injects.

Getting there is a two-step process: model the SQL Server resources in your AppHost, then connect to the database from each app that needs it.

1. Model SQL Server in your AppHost

   Add the SQL Server hosting integration to your AppHost, then declare a SQL Server instance, one or more databases, and reference them from the apps that need to talk to the database. The SQL Server Hosting integration article walks through every capability — adding databases, data volumes, and more.

   Set up SQL Server in the AppHost

2. Connect from your consuming C# app

   When you reference a SQL Server database from a C# consuming app, Aspire injects its connection information automatically. See Connect to SQL Server (EF Core) for the C# EF Core client integration walkthrough, including DbContext registration, enrichment, configuration, health checks, and telemetry.

   Connect to SQL Server