CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects 17.0.0

Prefix Reserved
dotnet add package CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects --version 17.0.0
                    
NuGet\Install-Package CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects -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="CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects" Version="17.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects" Version="17.0.0" />
                    
Directory.Packages.props
<PackageReference Include="CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects" />
                    
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 CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects --version 17.0.0
                    
#r "nuget: CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects, 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 CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects@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=CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects&version=17.0.0
                    
Install as a Cake Addin
#tool nuget:?package=CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects&version=17.0.0
                    
Install as a Cake Tool

CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects library

This package provides Aspire integration for SQL Server Database Projects. It allows you to publish SQL Database Projects as part of your Aspire AppHost projects. It currently works with both MSBuild.Sdk.SqlProj and Microsoft.Build.Sql based projects.

Usage

To use this package, install it into your Aspire AppHost project:

dotnet add package CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects

SQL schemas can be supplied as a project path, a NuGet package ID and version, generated metadata from an AppHost reference, or a DACPAC file. Choose the form that fits how your application obtains its database artifacts.

SQL projects by path

Specify a local SQL project path without adding a SQL ProjectReference to the AppHost:

var builder = DistributedApplication.CreateBuilder(args);
var database = builder.AddSqlServer("sql").AddDatabase("database");

builder.AddSqlProject("schema", "../Database/Database.sqlproj", configuration: "Release")
       .WithReference(database);

builder.Build().Run();

Relative project paths are resolved against the AppHost directory. Relative DACPAC output paths (SqlTargetPath, falling back to TargetPath) are resolved against the SQL project directory. The configuration defaults to Debug and is used for both dotnet build and output evaluation. Each deployment request builds the project, including its restore, before resolving the DACPAC. Both Microsoft.Build.Sql and MSBuild.Sdk.SqlProj are supported; SSDT projects requiring other toolchains are not supported by this path-based workflow. The required .NET SDK must already be installed.

NuGet packages by ID and version

Specify an exact package version without adding a SQL PackageReference to the AppHost:

builder.AddSqlPackage("package-schema", "Company.Database", "1.2.3-preview.1")
       .WithReference(database);

builder.AddSqlPackage("custom-schema", "Company.OtherDatabase", "2.0.0")
       .WithDacpac("schema/custom.dacpac")
       .WithReference(database);

The version must be exact; version ranges and floating versions are not accepted. The default DACPAC location inside the package is tools/<PackageId>.dacpac. For this overload only, WithDacpac specifies a path relative to the package root; absolute paths and paths outside that root are not supported. The original package-relative input is preserved across repeated deployments.

The integration runs dotnet restore with an isolated temporary PackageDownload project under the AppHost's obj directory. The project targets the AppHost's .NET version and uses its SDK selection and NuGet configuration hierarchy, the configured package cache (including NUGET_PACKAGES), and credential providers available in the environment. It does not add SQL package references to the AppHost or copy credentials into generated files. Package dependencies are not restored automatically: the downloaded package must contain the files needed to deploy its DACPAC.

For project paths and package IDs, build and restore run only when deployment is requested, not during resource registration. Failures or cancellation prevent deployment. WithExplicitStart() defers preparation and deployment until the dashboard's Deploy command is invoked. WithSkipWhenDeployed() still prepares the artifact before checking its checksum. SQL project and package resources are excluded from published manifests. Cloud deployment and file watching are not supported.

Referenced SQL projects

An AppHost project reference makes generated project metadata available to AddSqlProject<TProject>. Add a reference to the SQL project:

dotnet add reference ../MySqlProj/MySqlProj.csproj

Note: Depending on the project reference metadata, a SQL project reference may produce warning ASPIRE004. The path-based API above does not require that reference.

Finally add the project as a resource to your Aspire AppHost:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddSqlProject<Projects.MySqlProj>("mysqlproj")
       .WithReference(sql);

builder.Build().Run();

Now when you run your Aspire AppHost project you will see the SQL Database Project being published to the specified SQL Server.

Referenced NuGet packages

A package reference marked with IsAspirePackageResource provides generated metadata for AddSqlPackage<TPackage>:

<PackageReference Include="Company.Database" Version="1.2.3" IsAspirePackageResource="true" />
builder.AddSqlPackage<Packages.Company_Database>("package-schema")
       .WithReference(database);

With this form, the AppHost's NuGet restore acquires the package. WithDacpac can specify a package-relative DACPAC path instead of the default tools/<PackageId>.dacpac.

Local .dacpac file support

To deploy an available DACPAC file, specify its path directly. File preparation is managed outside this resource:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddSqlProject("mysqlproj")
       .WithDacpac("path/to/mysqlproj.dacpac")
       .WithReference(sql);

builder.Build().Run();

Support for existing SQL Server

Instead of using the AddSqlServer method to use a SQL Server container, you can specify a connection string to an existing server:

var builder = DistributedApplication.CreateBuilder(args);

// Get an existing connection string from the configuration
var connection = builder.AddConnectionString("Aspire");

builder.AddSqlProject<Projects.SdkProject>("mysqlproj")
       .WithReference(connection);

builder.Build().Run();

The referenced connection string should include the target database name using either the Database or Initial Catalog setting so the deployment target can be inferred.

Deployment options support

Define options that affect the behavior of package deployment.

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddSqlProject("mysqlproj")
       .WithConfigureDacDeployOptions(options => options.IncludeCompositeObjects = true)
       .WithReference(sql);

builder.Build().Run();

Ability to skip deployment

You can use the WithSkipWhenDeployed method to avoid re-deploying your SQL Database Project if no changes have been made. This is useful in scenarios where the SQL container database is persisted to permanent disk and will significantly improve the Aspire AppHost project startup time.

var builder = DistributedApplication.CreateBuilder(args);

var server = builder.AddSqlServer("sql")
    .WithDataVolume("testdata")
    .WithLifetime(ContainerLifetime.Persistent);

var database = server.AddDatabase("test");

var sdkProject = builder.AddSqlProject<Projects.SdkProject>("mysqlproj")
    .WithSkipWhenDeployed()
    .WithReference(database);

builder.Build().Run();
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.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
17.0.0 0 11/20/2026
17.0.0-beta.1090 0 11/20/2026
17.0.0-beta.1088 0 11/20/2026
17.0.0-beta.1080 0 11/20/2026
17.0.0-beta.1078 61 11/19/2026
17.0.0-beta.1077 49 11/19/2026
17.0.0-beta.1076 45 11/19/2026
17.0.0-beta.1075 41 11/19/2026
17.0.0-beta.1052 102 11/16/2026
17.0.0-beta.1051 63 11/12/2026
17.0.0-beta.1033 59 11/10/2026
17.0.0-beta.1022 57 11/8/2026
17.0.0-beta.1018 61 11/6/2026
17.0.0-beta.1009 61 11/5/2026
17.0.0-beta.994 69 11/4/2026
17.0.0-beta.993 64 11/4/2026
13.6.2-beta.959 81 10/27/2026
13.6.1 17,617 10/26/2026
13.6.1-beta.950 67 10/26/2026
13.6.1-beta.938 75 10/24/2026
Loading failed