Aspire.Hosting.SqlServer 17.0.0

Prefix Reserved
dotnet add package Aspire.Hosting.SqlServer --version 17.0.0
                    
NuGet\Install-Package Aspire.Hosting.SqlServer -Version 17.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Aspire.Hosting.SqlServer" Version="17.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Aspire.Hosting.SqlServer" Version="17.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Aspire.Hosting.SqlServer" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Aspire.Hosting.SqlServer --version 17.0.0
                    
#r "nuget: Aspire.Hosting.SqlServer, 17.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Aspire.Hosting.SqlServer@17.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Aspire.Hosting.SqlServer&version=17.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Aspire.Hosting.SqlServer&version=17.0.0
                    
Install as a Cake Tool

SQL Server hosting integration

Use this integration to model, configure, and orchestrate a SQL Server database resource in an Aspire solution.

Getting started

Add the integration

From your AppHost directory, add the Aspire.Hosting.SqlServer integration with the Aspire CLI:

aspire add Aspire.Hosting.SqlServer
aspire add Aspire.Hosting.Dotnet

Usage example

In the AppHost, add a SQL Server resource and reference it from another resource with either C# or TypeScript:

C#

var db = builder.AddSqlServer("sql").AddDatabase("db");

var myService = builder.AddDotnetProject("myservice", "../MyService/MyService.csproj")
   .WithReference(db);

TypeScript

const db = await builder.addSqlServer("sql").addDatabase("db");

const myService = await builder.addNodeApp("myService", "../my-service", "server.js")
   .withReference(db);

SQL REPL

Call WithRepl() to opt into a REPL command on the SQL Server resource in the dashboard:

builder.AddSqlServer("sqlserver").WithRepl();
await builder.addSqlServer("sqlserver").withRepl();

REPL access is disabled by default and is available only in run mode. Enable it only for trusted dashboard users: the shell runs as sa and can execute server-side operating system commands when enabled. Sharing the dashboard through a tunnel, Codespaces, or VS Code remote development also exposes this capability to users who can execute resource commands.

Use QUIT before closing the terminal tab to end the session cleanly. Closing the tab alone can leave sqlcmd running inside the container. Stopping the container also ends any remaining REPL processes.

While the container is running, the command opens sqlcmd in the terminal dock. It connects inside the container as sa to the master database, using the configured password without putting it in command-line arguments. No local SQL client installation is required.

Enter SQL statements followed by GO on its own line to execute a batch:

SELECT DB_NAME();
GO

Use USE [db]; followed by GO to switch databases, and QUIT to exit. The command trusts the local server's self-signed certificate, matching the integration's local connection string.

Select the client executable

The REPL invokes /opt/mssql-tools18/bin/sqlcmd directly by default, matching the tools version included in the integration's default 2022-latest image. It does not probe for another client or invoke a shell. No override is needed when using the default image.

When pinning an older image that includes /opt/mssql-tools/bin/sqlcmd, select the version 17 command. Replace <your-pinned-image-tag> with the tag of that image:

C#

builder.AddSqlServer("sqlserver")
    .WithImageTag("<your-pinned-image-tag>")
    .WithRepl(options => options.Command = SqlServerReplCommand.Version17);

TypeScript

import { SqlServerReplCommand } from "./.aspire/modules/aspire.mjs";

await builder.addSqlServer("sqlserver")
    .withImageTag("<your-pinned-image-tag>")
    .withRepl({
        configure: async options => {
            await options.command.set(SqlServerReplCommand.Version17);
        }
    });

SqlServerReplCommand.Version17 and SqlServerReplCommand.Version18 are string constants for the well-known executable paths. Choose based on the client tools installed in the image, not the SQL Server version. Changing Command does not install tools or change the image. This command is available only in run mode and uses the configured Docker or Podman runtime.

For an image that installs sqlcmd elsewhere, configure the resource with that executable path instead:

sqlServer.WithRepl(options => options.Command = "/usr/local/bin/sqlcmd");
await sqlServer.withRepl({
    configure: async options => {
        await options.command.set("/usr/local/bin/sqlcmd");
    }
});

Run a wrapper script

Set Command to an executable script inside the container to run work before and after the interactive SQL session. For example, place these two files in a sql directory under the AppHost directory.

sql/Dockerfile

FROM mcr.microsoft.com/mssql/server:2022-latest
COPY --chmod=755 sqlcmd-wrapper.sh /usr/local/bin/sqlcmd-wrapper

sql\sqlcmd-wrapper.sh

#!/bin/sh

echo "Running pre-session work"

/opt/mssql-tools18/bin/sqlcmd "$@"
status=$?

echo "Running post-session work"

exit "$status"

Replace the echoed messages with the work you want to run, then configure Aspire to build the image and launch the wrapper:

C#

builder.AddSqlServer("sqlserver")
    .WithDockerfile("sql")
    .WithRepl(options => options.Command = "/usr/local/bin/sqlcmd-wrapper");

TypeScript

await builder.addSqlServer("sqlserver")
    .withDockerfile("sql")
    .withRepl({
        configure: async options => {
            await options.command.set("/usr/local/bin/sqlcmd-wrapper");
        }
    });

The wrapper receives Aspire's usual sqlcmd arguments and the SQLCMDPASSWORD environment variable. Forward "$@" to preserve argument boundaries; do not put the password in arguments or log it. The example preserves sqlcmd's exit code.

Save the script with LF line endings and make it executable; the Dockerfile's COPY --chmod=755 sets the permissions. Its #!/bin/sh line selects the interpreter when the script is executed. Do not use exec to invoke sqlcmd if you need work to run afterward, because it replaces the wrapper process. Post-session work runs when sqlcmd returns; forcibly stopping the container can prevent it.

Connection Properties

When you reference a SQL Server resource using WithReference, the following connection properties are made available to the consuming project:

SQL Server server

The SQL Server server resource exposes the following connection properties:

Property Name Description
Host The hostname or IP address of the SQL Server
Port The port number the SQL Server is listening on
Username The username for authentication
Password The password for authentication
Uri The connection URI in mssql:// format, with the format mssql://{Username}:{Password}@{Host}:{Port}
JdbcConnectionString JDBC-format connection string, with the format jdbc:sqlserver://{Host}:{Port};trustServerCertificate=true. User and password credentials are provided as separate Username and Password properties.

SQL Server database

The SQL Server database resource inherits all properties from its parent SqlServerServerResource and adds:

Property Name Description
Uri The connection URI in mssql:// format, with the format mssql://{Username}:{Password}@{Host}:{Port}/{DatabaseName}
JdbcConnectionString JDBC connection string with database name, with the format jdbc:sqlserver://{Host}:{Port};trustServerCertificate=true;databaseName={DatabaseName}. User and password credentials are provided as separate Username and Password properties.
DatabaseName The name of the database

Aspire exposes each property as an environment variable named [RESOURCE]_[PROPERTY]. For instance, the Uri property of a resource called db1 becomes DB1_URI.

Additional documentation

https://aspire.dev/integrations/gallery/ https://aspire.dev/integrations/databases/sql-server/sql-server-host/

Feedback & contributing

https://github.com/microsoft/aspire

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (28)

Showing the top 5 NuGet packages that depend on Aspire.Hosting.SqlServer:

Package Downloads
Aspire.Hosting.Azure.ServiceBus

Azure Service Bus resource types for Aspire.

Aspire.Hosting.Azure.Sql

Azure SQL Database resource types for Aspire.

CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects

An Aspire hosting integration capable of deploying SQL Server Database Projects as part of your AppHost.

CommunityToolkit.Aspire.Hosting.SqlServer.Extensions

An Aspire hosting integration for extending SQL Server resources with additional management tooling.

FonsecaFramework.Aspire

Collection of classes and extensions for .NET Aspire

GitHub repositories (26)

Showing the top 20 popular GitHub repositories that depend on Aspire.Hosting.SqlServer:

Repository Stars
ardalis/CleanArchitecture
Clean Architecture Solution Template: A proven Clean Architecture Template for ASP.NET Core 10
jbogard/ContosoUniversityDotNetCore-Pages
With Razor Pages
collinbarrett/FilterLists
:shield: The independent, comprehensive directory of filter and host lists for advertisements, trackers, malware, and annoyances.
DuendeSoftware/products
The most flexible and standards-compliant OpenID Connect and OAuth 2.x framework for ASP.NET Core
Azure/data-api-builder
Data API builder provides modern REST, GraphQL endpoints and MCP tools to your Azure Databases and on-prem stores.
bitfoundation/bitplatform
Build all of your apps using what you already know and love ❤️
microsoft/aspire-samples
Browse the sample apps demonstrating Aspire integration across C#, JavaScript, TypeScript, Python, Go, containers, databases, cloud, AI, and observability scenarios.
CommunityToolkit/Aspire
A community project with additional components and extensions for Aspire
mehmetozkaya/Design-Microservices-Architecture-with-Patterns-Principles
Design Microservices Architecture with Patterns & Principles. Design Microservices Architecture with Design Patterns, Principles and the Best Practices. How to handle millions of request with designing system for high availability, high scalability, low latency, and resilience to network failures on distributed microservices.
SSWConsulting/SSW.VerticalSliceArchitecture
An enterprise ready solution template for Vertical Slice Architecture. This template is just one way to apply the Vertical Slice Architecture.
dotnet/systemweb-adapters
rstropek/Samples
ProfessionalCSharp/ProfessionalCSharp2021
Source code for Professional C# and .NET 2021 Edition (with updates for C# 11 and .NET 7)
alex289/CleanArchitecture
Sample .NET 10 API project including Clean Architecture principles, Onion Architecture, MediatR, and Entity Framework with unit and integration tests using xUnit
formcms/formcms
AI Agent: Open-source headless CMS built with ASP.NET Core (C#) and React, featuring REST APIs, GraphQL, and a GrapesJS page designer.
amasen02/freshcart-backend
FreshCart — .NET 10 + Aspire microservices reference e-commerce platform with an Angular 20 SPA
Azure-Samples/eShopLite
eShopLite is a set of reference .NET applications implementing an eCommerce site with features like Semantic Search, MCP, Reasoning models and more.
aws/integrations-on-dotnet-aspire-for-aws
This repository contains integrations with Aspire for AWS.
Keboo/DotnetTemplates
A repository for my dotnet templates
ardalis/RiverBooks
Modular Monolith sample for Dometrain
Version Downloads Last Updated
17.0.0 0 11/18/2026
13.6.5 239,430 11/10/2026
13.6.4 261,306 10/24/2026
13.6.3 52,052 10/21/2026
13.6.2 34,723 10/20/2026
13.6.1 462,550 10/7/2026
13.6.0 174,073 9/29/2026
13.5.4 268,142 9/15/2026
13.5.3 525,739 8/25/2026
13.5.2 105,223 8/21/2026
13.5.1 26,287 8/20/2026
13.5.0 91,899 8/18/2026
13.4.6 1,547,262 6/19/2026
13.4.5 119,953 6/17/2026
13.4.4 94,341 6/15/2026
13.4.3 148,903 6/8/2026
13.4.2 99,146 6/3/2026
13.4.1 3,995 6/3/2026
13.4.0 132,014 6/1/2026
13.3.5 388,783 5/21/2026
Loading failed