通过

.NET AspireAzure SQL 集成

包含：托管集成已包含 - Client 集成已包含Client 集成

Azure SQL 是一系列在云中 Azure 运行的关系数据库管理系统。 数据库系统是平台即服务（PaaS）产品，使数据库管理员能够在不维护复杂的基础结构本身的情况下实现高度可缩放和可用的数据库。 托管.NET AspireAzureSQL Server集成提供在应用主机项目中通过代码Azure创建新的.NET Aspire数据库服务器和数据库的方法。 在使用项目中，可以像使用任何其他的.NET Aspire 实例一样使用SQL ServerSQL Server 客户端集成。

托管集成

SQL Azure 托管集成将 Azure SQL Server 建模为 AzureSqlServerResource 类型，并将数据库建模为 AzureSqlDatabaseResource 类型。 若要访问这些类型和 API，请在📦项目中添加 AspireAzure.Hosting..Sql NuGet 包。

dotnet add package Aspire.Hosting.Azure.Sql

有关详细信息，请参阅 dotnet 添加包 或 管理 .NET 应用程序中的包依赖性。

Azure SQL 托管集成依赖于 📦Aspire.Hosting.SqlServer NuGet 包，将其扩展为支持Azure。 你可以使用 .NET AspireSQL Server 集成 和 .NET AspireSQL ServerEntity Framework Core 集成 所能做的所有事情，也可以在此集成中完成。

添加 Azure SQL Server 资源和数据库资源

在应用主机项目中，调用 AddAzureSqlServer 添加并返回 Azure SQL Server 资源生成器。 将返回的资源生成器的调用链接到 AddDatabase，以添加一个 Azure SQL 数据库资源。

var azureSql = builder.AddAzureSqlServer("azuresql")
                      .AddDatabase("database");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(azureSql);

上一次调用将 AddAzureSqlServer SQL Server 资源配置为将被部署为 Azure。

重要

默认情况下， AddAzureSqlServer 配置 Microsoft Entra ID 身份验证。 这需要更改需要连接到这些资源的应用程序。 有关详细信息，请参阅 Client 整合。

小窍门

调用 AddAzureSqlServer时，它会隐式调用 AddAzureProvisioning ， 这增加了在应用启动期间动态生成 Azure 资源的支持。 应用程序必须配置相应的订阅和位置。 有关详细信息，请参阅 本地预配：配置。

连接到现有 Azure SQL Server

你可能想要连接一个现有的 Azure SQL 数据库服务。 可以链式调用以标注 AzureSqlServerResource 是现有资源。

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...

有关将 Azure SQL 数据库资源视为现有资源的详细信息，请参阅 “使用现有 Azure 资源”。

注释

可以选择不表示 Azure SQL 数据库资源，而是在应用主机中添加连接字符串。 此方法属于弱类型，不适用于角色分配或基础结构自定义。 有关详细信息，请参阅 添加包含连接字符串的现有 Azure 资源。

将 SQL Server 资源作为容器运行Azure

托管 AzureSQL Server 集成支持将 Azure SQL Server 作为本地容器运行。 这适用于想要在本地运行 Azure SQL Server 以进行开发和测试的情况，避免需要预配 Azure 资源或连接到现有 Azure SQL Server。

若要将 Azure SQL Server 作为容器运行，请调用 RunAsContainer 以下方法：

var builder = DistributedApplication.CreateBuilder(args);

var azureSql = builder.AddAzureSqlServer("azuresql")
                      .RunAsContainer();

var azureSqlData = azureSql.AddDatabase("database");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(azureSqlData);

前面的代码将 Azure SQL 数据库资源配置为在容器中本地运行。

小窍门

RunAsContainer 方法可用于本地开发和测试。 API 提供一个可选委托，允许您自定义底层的 SqlServerServerResource 配置。 例如，可以添加数据卷或数据绑定装载。 有关详细信息，请参阅 .NET AspireSQL Server 托管集成 部分。

Client 集成

若要开始 .NET AspireSQL Server 客户端集成，请在使用 📦 客户端的应用程序项目中安装 Aspire NuGet 包。 SQL Server 客户端集成会注册一个 SqlConnection 实例，该实例可用于与 SQL Server交互。

dotnet add package Aspire.Microsoft.Data.SqlClient

添加 SQL Server 客户端

在您的客户端消费项目中的 Program.cs 文件中，对任何 AddSqlServerClient 调用 IHostApplicationBuilder 扩展方法，以注册 SqlConnection，以便通过依赖注入容器进行使用。 该方法采用连接名称参数。

builder.AddSqlServerClient(connectionName: "database");

小窍门

connectionName 参数必须与在应用主机项目中添加 SQL Server 数据库资源时使用的名称匹配。 换句话说，当你调用 AddDatabase 并提供 database 的名称时，应该在调用 AddSqlServerClient时使用相同的名称。 有关详细信息，请参阅 添加 SQL Server 资源和数据库资源。

然后，可以使用依赖项注入检索 SqlConnection 实例。 例如，若要从示例服务检索连接，

public class ExampleService(SqlConnection connection)
{
    // Use connection...
}

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加已加密的SQL Server客户端

在某些情况下，可能需要使用不同的连接名称注册多个 SqlConnection 实例。 若要注册密钥 SQL Server 客户端，请调用 AddKeyedSqlServerClient 方法：

builder.AddKeyedSqlServerClient(name: "mainDb");
builder.AddKeyedSqlServerClient(name: "loggingDb");

重要

当使用密钥服务时，预计您的 SQL Server 资源配置了两个命名数据库，一个用于 mainDb，一个用于 loggingDb。

然后，可以使用依赖项注入检索 SqlConnection 实例。 例如，若要从示例服务检索连接，

public class ExampleService(
    [FromKeyedServices("mainDb")] SqlConnection mainDbConnection,
    [FromKeyedServices("loggingDb")] SqlConnection loggingDbConnection)
{
    // Use connections...
}

有关密钥服务的详细信息，请参阅 .NET 依赖关系注入：密钥服务。

配置

.NET AspireSQL Server 集成提供了多个选项，用于根据项目的要求和约定配置连接。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 AddSqlServerClient 方法时提供连接字符串的名称：

builder.AddSqlServerClient(connectionName: "sql");

然后，从 ConnectionStrings 配置部分检索连接字符串：

{
  "ConnectionStrings": {
    "database": "Data Source=myserver;Initial Catalog=master"
  }
}

有关如何设置此连接字符串格式的详细信息，请参阅 ConnectionString。

使用配置提供器

.NET AspireSQL Server 集成支持 Microsoft.Extensions.Configuration。 它使用 MicrosoftDataSqlClientSettings 键来从配置中加载 Aspire:Microsoft:Data:SqlClient。 以下代码片段是一个 appsettings.json 文件的示例，该文件配置了一些选项：

{
  "Aspire": {
    "Microsoft": {
      "Data": {
        "SqlClient": {
          "ConnectionString": "YOUR_CONNECTIONSTRING",
          "DisableHealthChecks": false,
          "DisableMetrics": true
        }
      }
    }
  }
}

有关完整的 SQL Server 客户端集成 JSON 架构，请参阅 Aspire。Microsoft.Data.SqlClient/ConfigurationSchema.json。

使用内联委托功能

还可以传递 Action<MicrosoftDataSqlClientSettings> configureSettings 代理来内联设置一些或全部选项，例如从代码中禁用健康状态检查：

builder.AddSqlServerClient(
    "database",
    static settings => settings.DisableHealthChecks = true);

Client 集成健康检查

默认情况下，.NET.NET Aspire 集成会为所有服务启用 健康检查。 有关详细信息，请参阅 .NET.NET Aspire 集成概述。

.NET AspireSQL Server 的集成：

  • 在MicrosoftDataSqlClientSettings.DisableHealthChecks为false时添加健康检查，以尝试连接到SQL Server。
  • 与 /health HTTP 终结点集成，该终结点要求所有已注册的健康检查都必须通过，应用才能被视为准备好接受流量。

可观测性和遥测

.NET.NET Aspire 集成会自动设置日志记录、跟踪和指标等配置，这些配置有时称为 可观测性的基础支柱。 有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。 根据支持服务，某些集成可能仅支持其中一些功能。 例如，某些集成支持日志记录和跟踪，但不支持指标。 还可以使用 “配置” 部分中介绍的技术禁用遥测功能。

伐木业

由于 .NET Aspire的限制，SQL ServerMicrosoft.Data.SqlClient 集成目前默认不启用日志记录。

追踪

.NET AspireSQL Server 集成使用 OpenTelemetry输出以下跟踪活动：

  • OpenTelemetry.Instrumentation.SqlClient

指标

.NET AspireSQL Server 集成将通过 OpenTelemetry发出以下指标：

  • Microsoft.Data.SqlClient.EventSource
    • active-hard-connections
    • hard-connects
    • hard-disconnects
    • active-soft-connects
    • soft-connects
    • soft-disconnects
    • number-of-non-pooled-connections
    • number-of-pooled-connections
    • number-of-active-connection-pool-groups
    • number-of-inactive-connection-pool-groups
    • number-of-active-connection-pools
    • number-of-inactive-connection-pools
    • number-of-active-connections
    • number-of-free-connections
    • number-of-stasis-connections
    • number-of-reclaimed-connections

另请参阅