将 SDK 样式的 SQL 项目与 SQL 数据库项目扩展（预览版）结合使用

项目
08/16/2024

本文介绍 Azure Data Studio 或 Visual Studio Code 的 SQL 数据库项目扩展中适用于 SDK 样式的 SQL 项目的 Microsoft.Build.Sql。 SDK 样式的 SQL 项目对于通过管道传送或是在跨平台环境中构建的应用程序尤其有利。 TechCommunity 中提供了初始公告。

注意

Microsoft.Build.Sql 目前为预览版。

创建 SDK 样式的数据库项目

可以从空白项目或现有数据库创建 SDK 样式的数据库项目。

空白项目

在“数据库项目”视图中，选择“新建项目”按钮，然后在显示的文本输入中输入项目名称。在出现的“选择文件夹”对话框中，选择项目文件夹的目录、 文件和要包含的其他内容.sqlproj。

默认情况下，“SDK 样式项目(预览版)”选项处于选中状态。该对话框完成后，空项目会在“数据库项目”视图中打开并可见，可供编辑。

从现有数据库进行还原

在“项目”视图中，选择“从数据库创建项目”按钮并连接到 SQL Server。建立连接后，从可用数据库列表选择数据库，然后设置项目的名称。选择提取的目标结构。

默认情况下，“SDK 样式项目(预览版)”选项处于选中状态。该对话框完成后，将打开新项目，其中包含所选数据库内容的 SQL 脚本。

生成并发布

在 Azure Data Studio 和 Visual Studio Code 界面中，生成并发布 SDK 样式的 SQL 项目的完成方式与以前的 SQL 项目格式相同。有关此过程的详细信息，请参阅生成并发布项目。

若要在 Windows、macOS 或 Linux 上通过命令行生成 SDK 样式的 SQL 项目，请使用以下命令：

dotnet build

生成 SDK 样式的 SQL 项目所产生的 .dacpac 文件与数据层应用程序框架的关联工具兼容（.dacpac、.bacpac），包括 SqlPackage 和 GitHub sql-action。

项目功能

在 SQL 项目中，可以在 .sqlproj 文件中指定一些功能，这些功能在项目生成或部署时会影响数据库模型。以下部分介绍其中一些可用于 Microsoft.Build.Sql 项目的功能。

目标平台

目标平台属性包含在 <PropertyGroup> 项下的 .sqlproj 文件的 DSP 标记中。目标平台在项目生成期间用于验证对项目中包含的功能的支持，并作为属性添加到 .dacpac 文件中。默认情况下，在部署期间，针对目标数据库检查目标平台，以确保兼容性。如果目标数据库不支持目标平台，除非指定替代发布选项，否则部署将失败。

<Project DefaultTargets="Build">
  <Sdk Name="Microsoft.Build.Sql" Version="0.1.12-preview" />
  <PropertyGroup>
    <Name>AdventureWorks</Name>
    <DSP>Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider</DSP>
  </PropertyGroup>

目标平台的有效设置包括：

Microsoft.Data.Tools.Schema.Sql.Sql120DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql130DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql140DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql150DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlAzureV12DatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlDwDatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlServerlessDatabaseSchemaProvider
Microsoft.Data.Tools.Schema.Sql.SqlDwUnifiedDatabaseSchemaProvider

数据库引用

生成时的数据库模型验证可以通过数据库引用扩展到 SQL 项目的内容之外。 .sqlproj 文件中指定的数据库引用可以引用另一个 SQL 项目或 .dacpac 文件，表示另一个数据库或同一数据库的更多组件。

以下属性可用于表示另一个数据库的数据库引用：

DatabaseSqlCmdVariable：该值是用于引用数据库的变量的名称
- 引用设置：<DatabaseSqlCmdVariable>SomeOtherDatabase</DatabaseSqlCmdVariable>
- 用例：SELECT * FROM [$(SomeOtherDatabase)].dbo.Table1
ServerSqlCmdVariable：值是用于引用数据库所在服务器的变量的名称。当数据库位于另一个服务器中时，与 DatabaseSqlCmdVariable 一起使用。
- 引用设置：<ServerSqlCmdVariable>SomeOtherServer</ServerSqlCmdVariable>
- 用例：SELECT * FROM [$(SomeOtherServer)].[$(SomeOtherDatabase)].dbo.Table1
DatabaseVariableLiteralValue：该值是 SQL 项目中使用的数据库的文本名称，类似于 DatabaseSqlCmdVariable，但对其他数据库的引用是文本值
- 引用设置：<DatabaseVariableLiteralValue>SomeOtherDatabase</DatabaseVariableLiteralValue>
- 用例：SELECT * FROM [SomeOtherDatabase].dbo.Table1

在 SQL 项目文件中，数据库引用被指定为 ArtifactReference 项，且 Include 属性设置为 .dacpac 文件的路径。

  <ItemGroup>
    <ArtifactReference Include="SampleA.dacpac">
      <DatabaseSqlCmdVariable>DatabaseA</DatabaseSqlCmdVariable>
    </ArtifactReference>
  </ItemGroup>
</Project>

包引用

包引用用于引用包含 .dacpac 文件的 NuGet 包，并用于在生成时扩展数据库模型，类似于数据库引用。

以下示例来自一个 SQL 项目文件，其中引用了 master 数据库的 Microsoft.SqlServer.Dacpacs 包。

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0" />
  </ItemGroup>
</Project>

除了可用于数据库引用的属性外，还可以指定以下 DacpacName 属性，以从包含多个 .dacpac 文件的包中选择 .dacpac。

  <ItemGroup>
    <PackageReference Include="Microsoft.SqlServer.Dacpacs" Version="160.0.0">
      <DacpacName>msdb</DacpacName>
    </PackageReference>
  </ItemGroup>
</Project>

SqlCmd 变量

SqlCmd 变量可以在 .sqlproj 文件中定义，用于在 .dacpac 部署期间替换 SQL 对象和脚本中的令牌。 SQL 项目文件中的以下示例定义了一个名为 EnvironmentName 的变量，该变量可用于项目的对象和脚本。

  <ItemGroup>
    <SqlCmdVariable Include="EnvironmentName">
      <DefaultValue>testing</DefaultValue>
      <Value>$(SqlCmdVar__1)</Value>
    </SqlCmdVariable>
  </ItemGroup>
</Project>

IF '$(EnvironmentName)' = 'testing'
BEGIN
    -- do something
END

部署已编译的 SQL 项目 (.dacpac) 后，变量的值将替换为部署命令中指定的值。例如，以下命令部署 AdventureWorks.dacpac，并将 EnvironmentName 变量的值设置为 production。

SqlPackage /Action:Publish /SourceFile:AdventureWorks.dacpac /TargetConnectionString:{connection_string_here} /v:EnvironmentName=production

预先/后期部署脚本

预先和后期部署脚本是包含在要在部署期间执行的项目中的 SQL 脚本。预先/后期部署脚本包含在 .dacpac 中，但它们不会编译到数据库对象模型中或使用数据库对象模型进行验证。在应用数据库模型之前执行预先部署脚本，在应用数据库模型之后执行后期部署脚本。 SQL 项目文件中的以下示例将 populate-app-settings.sql 文件添加为后期部署脚本。

  <ItemGroup>
    <PostDeploy Include="populate-app-settings.sql" />
  </ItemGroup>
</Project>

通过