将原始 SQL 项目转换为 SDK 样式项目

适用于：SQL ServerAzure SQL 数据库Azure SQL 托管实例Microsoft Fabric 中的 SQL 数据库

创建新的 SDK 样式 SQL 项目是一项快速任务。 不过，如果你已有现有的SQL项目，可以将其转换为SDK风格的SQL项目，以利用新功能。

转换项目后，你可以使用SDK风格项目的新功能，例如：

• 跨平台构建支持
• 简化项目文件格式
• 软件包引用

要仔细完成转换，请按照以下步骤操作：

1. 创建原始项目文件的备份。
2. 从原始项目生成 .dacpac 文件以进行比较。
3. 将项目文件修改为 SDK 样式的项目。
4. 从修改的项目生成 .dacpac 文件以进行比较。
5. 验证 .dacpac 文件是否相同。

Visual Studio中的SQL Server Data Tools（SSDT）不支持SDK风格的项目。 转换项目后，使用以下工具之一来构建或编辑项目：

• Visual Studio Code中的SQL数据库项目扩展
• SQL Server Management Studio （SSMS） 中的数据库 DevOps
• 命令行
• Visual Studio 2022 中的 SQL Server Data Tools（SDK 样式，预览版）

Prerequisites

步骤 1：创建原始项目文件的备份

在转换项目之前，请创建原始项目文件的备份。 这样，可以根据需要还原到原始项目。

在文件资源管理器中，为要转换的项目创建一个 .sqlproj 文件的副本，并在文件扩展名后附加 .original。 例如，MyProject.sqlproj 将变为 MyProject.sqlproj.original。

步骤 2：从原始项目生成 .dacpac 文件以进行比较

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

默认情况下，生成过程会在项目的 .dacpac 文件夹中创建一个 bin\Debug 文件。 使用文件资源管理器，找到由构建过程创建的 .dacpac，并将其复制到项目目录外的新文件夹中，命名为 original_project.dacpac。 用这个 .dacpac 文件做对比，以后验证你的转换。

步骤 3：将项目文件修改为 SDK 样式的项目

修改项目文件是一个手动过程，最好是在文本编辑器中执行。 在文本编辑器中打开 .sqlproj 文件并进行以下更改：

必需：添加 SDK 引用

在项目元素内，添加一个Sdk项以引用 Microsoft.Build.Sql，并引用来自 https://www.nuget.org/packages/Microsoft.build.sql 的最新版本，#.#.# 包含在下面的代码片段中。

<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" ToolsVersion="4.0">
  <Sdk Name="Microsoft.Build.Sql" Version="#.#.#" />
...

必需：删除不必要的生成目标导入

原始 SQL 项目引用 Import 语句中的多个生成目标和属性。 除了显式添加的 <Import/> 项目（这是唯一且经过深思熟虑的更改）外，删除以 <Import ...> 开头的行。 如果在 .sqlproj 中出现，请删除以下示例：

...
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
<Import Condition="..." Project="...\Microsoft.Data.Tools.Schema.SqlTasks.targets"/>
<Import Condition="'$(SQLDBExtensionsRefPath)' != ''" Project="$(SQLDBExtensionsRefPath)\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
<Import Condition="'$(SQLDBExtensionsRefPath)' == ''" Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets" />
...

必需：删除“属性”文件夹

原始 SQL 项目在解决方案资源管理器中有一个 Properties 文件夹的记录，该文件夹代表访问项目属性的通道。 将此项从项目文件中移除。

要删除的示例（如果出现在 .sqlproj 中）：

<ItemGroup>
  <Folder Include="Properties" />
</ItemGroup>

必需：删除默认包含的生成项

原始 SQL 项目将项目文件中显式表示数据库对象的所有 .sql 文件作为 <Build Include="..." /> 项列出。 在 SDK 风格的 SQL 项目中，项目文件夹树（.sql）中的任何**/*.sql文件默认包含。 为避免构建性能问题，请从这些文件的 .sql 项中移除 <Build Include="...." /> 指定的文件。

从项目文件中移除以下几行：

  <Build Include="SalesLT/Products.sql" />
  <Build Include="SalesLT/SalesLT.sql" />
  <Build Include="SalesLT/Categories.sql" />
  <Build Include="SalesLT/CategoriesProductCount.sql" />

不要移除：

• <Build Include="..." />为不在 SQL 项目文件夹树中的文件添加的项.sql
• <PreDeploy Include="..." /> 或 <PostDeploy Include="..." /> 项，因为这些节点决定了这些文件的特定行为
• 非.sql文件的项，例如<None Include="..." />项中的.publish.xml文件、<RefactorLog Include="..." />项中的.refactorlog.xml文件，或<Build Include="..." />项中的.xsd文件

可选：删除 SSDT 引用

原始 SQL Server Data Tools (SSDT) 需要项目文件中的额外内容来检测 Visual Studio 安装程序。 这些行在 SDK 样式的 SQL 项目中是不必要的，可以删除：

  <PropertyGroup>
    <VisualStudioVersion Condition="'$(VisualStudioVersion)' == ''">11.0</VisualStudioVersion>
    <!-- Default to the v11.0 targets path if the targets file for the current VS version is not found -->
    <SSDTExists Condition="Exists('$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\SSDT\Microsoft.Data.Tools.Schema.SqlTasks.targets')">True</SSDTExists>
    <VisualStudioVersion Condition="'$(SSDTExists)' == ''">11.0</VisualStudioVersion>
  </PropertyGroup>

可选：删除默认的生成设置

原始 SQL 项目包含两个大块用于发布和调试构建设置，而在 SDK 风格的 SQL 项目中，SDK 已知这些选项的默认设置。 如果没有对生成设置进行自定义，请考虑删除以下块：

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <OutputPath>bin\Release\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>False</TreatWarningsAsErrors>
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <DefineDebug>false</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <OutputPath>bin\Debug\</OutputPath>
    <BuildScriptName>$(MSBuildProjectName).sql</BuildScriptName>
    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <DefineDebug>true</DefineDebug>
    <DefineTrace>true</DefineTrace>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
  </PropertyGroup>

项目属性引用列出了可用属性及其默认值。

步骤 4：解决方案文件

你的项目文件可能在解决方案文件中引用（.sln）。 如果你有解决方案文件，更新它以引用新的 SDK 风格项目文件。 如果没有解决方案文件，可以跳过本部分，然后继续执行步骤 5。

选项 1：创建新的解决方案文件

如果解决方案文件只包含 SQL 项目，删除解决方案文件并用 SDK 风格项目创建新解决方案文件会更简单。

dotnet new sln --name MySolution
dotnet sln MySolution.sln add MyDatabaseProject\MyDatabaseProject.sqlproj

选项 2：编辑解决方案文件

如果解决方案文件包含多个项目，请更新解决方案文件以引用新的 SDK 风格项目文件。 可以在文本编辑器中编辑解决方案文件，并更改对新 SDK 样式项目文件的项目引用。 解决方案文件中的项目引用应如下所示：

Project("{PROJECT_TYPE_GUID}") = "MyDatabaseProject", "MyDatabaseProject\MyDatabaseProject.sqlproj", "{PROJECT_GUID}"
EndProject

Microsoft.Build.Sql 项目的 PROJECT_TYPE_GUID 值为 42EA0DBD-9CF1-443E-919E-BE9C484E4577。 PROJECT_GUID 是项目的唯一标识符，可在项目文件的 <ProjectGuid> 元素中找到。 如果你的项目里有解决方案文件，就不需要更改 PROJECT_GUID 数值。 将 PROJECT_TYPE_GUID 值更改为 Microsoft.Build.Sql 项目类型 GUID。

步骤 5：从修改的项目生成 .dacpac 文件进行比较

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

默认情况下，生成过程会在项目的 .dacpac 文件夹中创建一个 bin\Debug 文件。 使用文件资源管理器，找到 .dacpac “由构建进程创建”，并将其复制到项目目录外的新文件夹中。 用这个 .dacpac 文件做对比，以后验证你的转换。

步骤 6：验证 .dacpac 文件是否相同

若要验证转换是否成功，请比较从原始项目和修改的项目创建的 .dacpac 文件。 利用SQL项目的 模式比较 功能，可视化这两个 .dacpac 文件之间数据库模型的差异。 或者，可以使用 DacpacVerify 命令行工具比较这两个 .dacpac 文件，包括它们的部署前后脚本和项目设置。

你可以把DacpacVerify作为 dotnet工具安装。 若要安装该工具，请运行以下命令：

dotnet tool install --global Microsoft.DacpacVerify --prerelease

DacpacVerify 的语法是将两个文件的文件路径分别指定为.dacpac和dacpacverify <source DACPAC path> <target DACPAC path>。 若要比较这两 .dacpac 个文件，请运行以下命令：

DacpacVerify original_project.dacpac modified_project.dacpac

可以使用架构比较工具比较文件中的对象 .dacpac 。

运行架构比较时，不应显示任何结果。 缺少差异表示原始项目和修改的项目是等效的，在 .dacpac 文件中生成相同的数据库模型。

相关内容

• 什么是 SQL 数据库项目？
• SQL 数据库项目入门
• SQL 项目包引用