將原始 SQL 專案轉換為 SDK 樣式專案

發行項
03/21/2025

適用於：SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Microsoft Fabric 中的 SQL 資料庫

建立新的 SDK 樣式 SQL 專案是一項快速工作。不過，如果您有現有的 SQL 專案，可以將這些專案轉換成 SDK 樣式的 SQL 專案，以利用新功能。

轉換專案之後，您可以使用 SDK 樣式專案的新功能，例如：

跨平台建置支援
簡化的專案檔格式
套件參考

若要仔細完成轉換，我們將：

建立原始專案檔的備份。
從原始專案建置 .dacpac 檔案，以進行比較。
將專案檔修改為 SDK 樣式專案。
從修改的專案建置 .dacpac 檔案，以進行比較。
驗證 .dacpac 檔案是否相同。

Visual Studio 中的 SQL Server Data Tools （SSDT）不支援 SDK 樣式專案。轉換之後，您必須使用下列中的一項來建置或編輯專案：

命令列
Visual Studio Code 中的 SQL 資料庫專案延伸模組
Azure Data Studio 中的 SQL 資料庫專案延伸模組
Visual Studio 2022 中的 SQL Server Data Tools， SDK 樣式（預覽）

必要條件

.NET 8 SDK

步驟 1：建立原始專案檔的備份

轉換專案之前，請先建立原始專案檔的備份。這樣一來，您可以在需要時恢復到原始專案。

在檔案總管中，為您要轉換的專案建立 .sqlproj 檔案的複本，並在檔案延伸模組末尾附加 .original。例如，MyProject.sqlproj 會成為 MyProject.sqlproj.original。

步驟 2：從原始專案建置 `.dacpac` 檔案，以進行比較

在 Visual Studio 2022 中開啟專案。 .sqlproj 檔案仍為原始格式，因此您會在原始 SQL Server Data Tools 中開啟。

以滑鼠右鍵按一下 [方案總管] 中的資料庫節點，然後選取 [建置]，在 Visual Studio 中建置專案。

若要從原始專案建置 .dacpac 檔案，您必須在 Visual Studio 中使用原始的 SQL Server Data Tools (SSDT) 。在已安裝原始 SQL Server Data Tools 的 Visual Studio 2022 中開啟專案檔。

以滑鼠右鍵按一下 [方案總管] 中的資料庫節點，然後選取 [建置]，在 Visual Studio 中建置專案。

在 VS Code 或 Azure Data Studio 中開啟專案資料夾。在 VS Code 或 Azure Data Studio 的 [資料庫專案] 檢視中，以滑鼠右鍵按一下專案節點，然後選取 [建置]。

您可以使用 dotnet build 命令，從命令列建置 SQL 資料庫專案。

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 ...> 開頭的行。如果在您的 .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）預設已包含，因此必須移除這些檔案的 <Build Include="...." /> 條目，以避免影響建置效能。

應該從項目檔中移除的行，例如：

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

您不應該移除 <PreDeploy Include="..." /> 或 <PostDeploy Include="..." /> 項目，因為這些節點會指定這些檔案的特定行為。您也不應對於不在 SQL 專案的資料夾樹中的檔案移除 <Build Include="..." /> 項目。

可選：移除 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：從修改的專案建置 `.dacpac` 檔案，以進行比較

SQL 專案不再與 Visual Studio 2022 相容。若要建置或編輯專案，必須使用下列其中一項：

命令列
Visual Studio Code 中的 SQL 資料庫專案延伸模組
Azure Data Studio 中的 SQL 資料庫專案延伸模組
Visual Studio 2022 中的 SQL Server Data Tools， SDK 樣式（預覽）

項目檔現在的格式為 SDK 樣式，但若要在 Visual Studio 2022 中開啟項目檔，您必須安裝 SQL Server Data Tools、SDK 樣式（預覽）。在具有已安裝 SQL Server Data Tools SDK 樣式（預覽版）的 Visual Studio 2022 中開啟專案。

在 VS Code 或 Azure Data Studio 中開啟專案資料夾。在 VS Code 或 Azure Data Studio 的 [資料庫專案] 檢視中，以滑鼠右鍵按一下專案節點，然後選取 [建置]。

您可以使用 dotnet build 命令，從命令列建置 SQL 資料庫專案。

dotnet build

# optionally specify the project file
dotnet build MyDatabaseProject.sqlproj

建置程序預設會在專案的 .dacpac 資料夾中建立 bin\Debug 檔案。使用檔案總管，找出建置程序所建立的 .dacpac，並將其複製到專案目錄外部的新資料夾。我們使用此 .dacpac 檔案進行比較，以便稍後驗證轉換。

步驟 5：驗證 `.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

您可以使用 Visual Studio 或 Azure Data Studio 中的架構比較工具來比較 .dacpac 檔案中的物件。

在未載入專案的情況下啟動 Visual Studio。前往工具>SQL Server>新增架構比較。選取原始 .dacpac 檔案作為來源，並將修改的 .dacpac 檔案選取為目標。如需在 Visual Studio 中使用結構描述比較的詳細資訊，請參閱使用結構描述比較來比較不同的資料庫定義。

Visual Studio 中，SDK 樣式 SQL 專案 (預覽版) 中尚不提供圖形架構比較。使用 Azure Data Studio 來比較結構描述。

Visual Studio Code 中無法使用模式比較功能。使用 Azure Data Studio 或 Visual Studio 來比較結構描述。

在 Azure Data Studio 中，如果尚未安裝 SQL Server 結構描述比較延伸模組，請加以安裝。使用 Ctrl/Cmd+Shift+P 開啟命令選擇區並輸入 Schema Compare，以啟動命令選擇區的新結構描述比較。

選取原始 .dacpac 檔案作為來源，並將修改的 .dacpac 檔案選取為目標。

在 Visual Studio 和 Azure Data Studio 中提供圖形結構描述比較。

執行結構描述比較時，不應顯示任何結果。缺乏差異表示原始和修改的專案相等，在 .dacpac 檔案中產生相同的資料庫模型。

注意

透過結構描述比較的 .dacpac 檔案比較不會驗證預部署/部署後的腳本、重構日誌或其他專案設定。而是只會驗證資料庫模型。建議使用 DacpacVerify 命令行公用程式來驗證這兩個 .dacpac 檔案是否相等。

共用方式為

將原始 SQL 專案轉換為 SDK 樣式專案

必要條件

步驟 1：建立原始專案檔的備份

步驟 2：從原始專案建置 `.dacpac` 檔案，以進行比較

步驟 3：將專案檔修改為 SDK 樣式專案

必須：新增 SDK 參考

必須：移除不必要的建置目標匯入

必需：移除 [屬性] 資料夾

必要：移除預設包含的建置項目

可選：移除 SSDT 參考

可選：移除預設建置設定

步驟 4：從修改的專案建置 `.dacpac` 檔案，以進行比較

步驟 5：驗證 `.dacpac` 檔案是否相同

意見反應

其他資源

共用方式為

將原始 SQL 專案轉換為 SDK 樣式專案

必要條件

步驟 1：建立原始專案檔的備份

步驟 2：從原始專案建置 .dacpac 檔案，以進行比較

步驟 3：將專案檔修改為 SDK 樣式專案

必須：新增 SDK 參考

必須：移除不必要的建置目標匯入

必需：移除 [屬性] 資料夾

必要：移除預設包含的建置項目

可選：移除 SSDT 參考

可選：移除預設建置設定

步驟 4：從修改的專案建置 .dacpac 檔案，以進行比較

步驟 5：驗證 .dacpac 檔案是否相同

相關內容

意見反應

其他資源

步驟 2：從原始專案建置 `.dacpac` 檔案，以進行比較

步驟 4：從修改的專案建置 `.dacpac` 檔案，以進行比較

步驟 5：驗證 `.dacpac` 檔案是否相同