Includes: Hosting integration only — Client integration not included

In this article, you learn how to use the Aspire SQL Database Projects hosting integration to publish your database schema to your SQL Server database.

Prerequisites

This integration requires a SQL Database Project based on eitherMSBuild.Sdk.SqlProj orMicrosoft.Build.Sql.

Hosting integration

To get started with the Aspire SQL Database Projects hosting integration, install the📦 CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects NuGet package in the AppHost project.

dotnet add package CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects

<PackageReference Include="CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects"                  Version="*" />

For more information, seedotnet add package orManage package dependencies in .NET applications.

Example usage

Add a reference to the📦 MSBuild.Sdk.SqlProj or📦 Microsoft.Build.Sql project you want to publish in your Aspire AppHost project:

dotnet add reference ../MySqlProj/MySqlProj.csproj

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);

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

NuGet Package support

Starting with version 9.2.0, you can deploy databases from referenced NuGet packages, such as those produced by📦 MSBuild.Sdk.SqlProj or📦 Microsoft.Build.Sql. To deploy, add the NuGet package to your Aspire AppHost project, for example:

dotnet add package ErikEJ.Dacpac.Chinook

Next, edit your project file to set theIsAspirePackageResource flag toTrue for the correspondingPackageReference, as shown in the following example:

<PackageReference Include="ErikEJ.Dacpac.Chinook" Version="1.0.0"                  IsAspirePackageResource="True" />

Finally, add the package as a resource to your app model:

var builder = DistributedApplication.CreateBuilder(args);var sql = builder.AddSqlServer("sql")                 .AddDatabase("test");builder.AddSqlPackage<Packages.ErikEJ_Dacpac_Chinook>("chinook")       .WithReference(sql);

Local .dacpac file support

If you are sourcing your.dacpac file from somewhere other than a project reference, you can also specify the path to the.dacpac file directly:

var builder = DistributedApplication.CreateBuilder(args);var sql = builder.AddSqlServer("sql")                 .AddDatabase("test");builder.AddSqlProject("mysqlproj")       .WithDacpac("path/to/mysqlproj.dacpac")       .WithReference(sql);

Support for existing SQL Server instances

Starting with version 9.2.0, you can publish the SQL Database project to an existing SQL Server instance by using a connection string:

var builder = DistributedApplication.CreateBuilder(args);// Get an existing SQL Server connection string from the configurationvar connection = builder.AddConnectionString("Aspire");builder.AddSqlProject<Projects.SdkProject>("mysqlproj")       .WithReference(connection);builder.Build().Run();

Deployment options support

To define options that affect the behavior of package deployment, call theWithConfigureDacDeployOptions API:

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();

The preceding code:

• Adds a SQL server resource namedsql and adds atest database resource to it.
• Adds a SQL project resource namedmysqlproj and then configures theDacDeployOptions.
• The SQL project resource depends on the database resource.

Redeploy support

If you make changes to your SQL Database project while the AppHost is running, you can use theRedeploy custom action on the Aspire dashboard to redeploy your updates without having to restart the AppHost.

See also

• MSBuild.Sdk.SqlProj GitHub repository
• Microsoft.Build.Sql GitHub repository
• Get started with SQL database projects
• Aspire Community Toolkit GitHub repo