Azure SQL Hosting integration reference

To get started with the Aspire Azure SQL integrations, follow the Get started with Azure SQL integrations guide.

This article includes full details about the Aspire Azure SQL Hosting integration, which models Azure SQL server and database resources as the AzureSqlServerResource and AzureSqlDatabaseResource types. To access these types and APIs, you need to install the Azure SQL Hosting integration in your AppHost project.

Installation

The Aspire Azure SQL Database hosting integration models the SQL Server as the AzureSqlServerResource type and SQL databases as the AzureSqlDatabaseResource type. To access these types and APIs for expressing them within your AppHost project, install the 📦 Aspire.Hosting.Azure.Sql NuGet package:

Install the NuGet package

dotnet add package Aspire.Hosting.Azure.Sql

Add Azure SQL server resource and database resource

In your AppHost project, call AddAzureSqlServer to add and return an Azure SQL server resource builder. Chain a call to the returned resource builder to AddDatabase, to add an Azure SQL database resource:

var builder = DistributedApplication.CreateBuilder(args);
  
var azureSql = builder.AddAzureSqlServer("azuresql")
    .AddDatabase("database");
  
var myService = builder.AddProject<Projects.MyService>()
    .WithReference(azureSql);

The preceding call to AddAzureSqlServer configures the Azure SQL server resource to be deployed as an Azure SQL Database server.

Caution

When you call AddAzureSqlServer, it implicitly calls AddAzureProvisioning—which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration.

Note

When you call WithReference in the AppHost to pass Azure SQL resources to a consuming project, Aspire makes several properties available to that project, such as connection strings, URIs, and port numbers. For a complete list of these properties, see Properties of the Azure SQL resources.

Connect to an existing Azure SQL server

You might have an existing Azure SQL Database service that you want to connect to. You can chain a call to annotate that your AzureSqlServerResource is an existing resource:

var builder = DistributedApplication.CreateBuilder(args);
  
var existingSqlServerName = builder.AddParameter("existingSqlServerName");
var existingSqlServerResourceGroup = builder.AddParameter("existingSqlServerResourceGroup");
  
var sqlserver = builder.AddAzureSqlServer("sqlserver")
    .AsExisting(existingSqlServerName, existingSqlServerResourceGroup)
    .AddDatabase("database");
  
builder.AddProject<Projects.ExampleProject>()
    .WithReference(sqlserver);
  
// After adding all resources, run the app...

For more information on treating Azure SQL resources as existing resources, see Use existing Azure resources.

Run Azure SQL server resource as a container

The Azure SQL Server hosting integration supports running the Azure SQL server as a local container. This is beneficial for situations where you want to run the Azure SQL server locally for development and testing purposes, avoiding the need to provision an Azure resource or connect to an existing Azure SQL server.

To run the Azure SQL server as a container, call the RunAsContainer method:

var builder = DistributedApplication.CreateBuilder(args);
  
var azureSql = builder.AddAzureSqlServer("azuresql")
    .RunAsContainer();
  
var azureSqlData = azureSql.AddDatabase("database");
  
var exampleProject = builder.AddProject<Projects.ExampleProject>()
    .WithReference(azureSqlData);

The preceding code configures an Azure SQL Database resource to run locally in a container.

Tip

The RunAsContainer method is useful for local development and testing. The API exposes an optional delegate that enables you to customize the underlying SqlServerServerResource configuration. For example, you can add a data volume or data bind mount. For more information, see the Aspire SQL Server hosting integration section.

Admin deployment script

When you deploy an Azure SQL Server resource, Aspire runs a deployment script that grants your application's managed identity access to the SQL database. For more information, including private endpoint considerations and how to customize the deployment script behavior, see Admin deployment script.