共用方式為

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

  • 發行項

適用於：SQL Server Azure SQL 資料庫 Azure 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 資料庫專案延伸模組
  • Azure Data Studio 中的 SQL 資料庫專案延伸模組

必要條件

步驟 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

建置程序預設會在專案的 bin\Debug 資料夾中建立 .dacpac 檔案。 使用檔案總管，找出建置程序所建立的 .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="0.2.0-preview" />
...

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

原始 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>

可選：移除 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 資料庫專案延伸模組

專案檔現在為 SDK 樣式格式，但若要在 Visual Studio 2022 中開啟，您必須安裝 SDK 樣式 SQL Server Data Tools (預覽版)，且專案必須具有副檔名 .sqlprojx。 在已安裝 SDK 樣式 SQL Server Data Tools (預覽版) 的 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

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

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

若要驗證轉換成功，請比較從原始和修改的專案建立的 .dacpac 檔案。 SQL 專案的結構描述比較功能能讓我們視覺化資料庫模型的差異。

您可以使用 Visual Studio、Visual Studio Code 或 Azure Data Studio 中的結構描述比較工具來比較 .dacpac 檔案。 您也可以使用以 DacFx .NET 程式庫為基礎的社群工具。

在未載入專案的情況下啟動 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 檔案比較不會驗證預先部署/部署後指令碼、重構或其他專案設定。 而是只會驗證資料庫模型。 將 .dacpac 轉換成 .zip 封存，並且手動比較內容可以提供更詳細的比較。

相關內容