在 Visual Studio Code 中開發倉庫專案

適用於：✅ Microsoft Fabric 中的倉庫

學習如何在 Visual Studio Code 中為 Fabric 的 Data Warehouse 建立資料庫專案。 你建立一個新專案，定義結構物件，建置並驗證專案，然後發佈到你的倉庫。

這很重要

這項功能目前處於預覽階段。

先決條件

開始之前，請確定您：

  • 具有參與者或更高權限的使用者，可以存取 Fabric 工作區內的現有倉儲項目。
  • 在你的工作站上安裝 Visual Studio Code。
  • 安裝 .NET SDK 以建立並發佈資料庫專案。
  • 安裝兩個Visual Studio Code擴充功能：SQL Database Projects 以及 SQL Server （mssql）。
    • 你可以直接在 Visual Studio Code 市集內搜尋「SQL Database Projects」或「SQL Server （mssql）」來安裝所需的擴充功能。

建立新的資料庫專案

你可以從零開始建立資料庫專案，也可以從現有倉庫中建立。

選項一：從 Visual Studio Code 的指令面板建立一個新的資料庫專案

  1. 開啟Visual Studio Code。

  2. 開啟「指令面板Ctrl+Shift+P」（或Cmd+Shift+P在 Mac 上）。

  3. 搜尋 新的資料庫專案。

  4. 選擇 資料庫專案類型作為 SQL Server 資料庫。

  5. 選擇專案名稱，然後選取本機資料夾位置。

  6. 選擇Synapse Data Warehouse 在 Microsoft Fabric作為目標平台。

  7. 出現提示時，針對 SDK 樣式專案選取 [ 是 （建議） ]。

    這很重要

    僅支援 SDK 風格 專案，Fabric Data Warehouse 支援。

  8. 選取 [ 是 ] 以回答問題 您要 將 SQL 專案組建設定為此資料夾的預設組建組態嗎？

  9. 選取 [ 是 ] 以信任此資料夾中檔案的作者。

選項 2：從資料庫專案延伸模組建立新的資料庫專案

  1. 在Visual Studio Code中，從 Activity Bar 選擇 Database Projects 擴充功能圖示。

  2. 在 [資料庫專案 ] 窗格中，選取 [ 新建]。

    Visual Studio Code截圖，顯示資料庫專案的擴充功能窗格和建立新建按鈕。

  3. 選擇 資料庫專案類型作為 SQL Server 資料庫。

  4. 選擇專案名稱，然後選取本機資料夾位置。

  5. 選擇Synapse Data Warehouse 在 Microsoft Fabric作為目標平台。

  6. 出現提示時，針對 SDK 樣式專案選取 [ 是 （建議） ]。 僅支援 SDK 風格 專案，Fabric Data Warehouse 支援。

  7. 選取 [ 是 ] 以回答問題 您要 將 SQL 專案組建設定為此資料夾的預設組建組態嗎？

  8. 選取 [ 是 ] 以信任此資料夾中檔案的作者。

選項 3：從現有倉庫建立資料庫專案

  1. 首先，在 Visual Studio Code 中為你的倉庫建立一個新的連線設定檔。

    1. 請從活動列中選擇Visual Studio Code中的SQL Server擴充功能。
    2. 提供 設定檔名稱。 選擇 Parameters （參數）。
    3. 輸入 伺服器名稱。 在 Fabric 入口網站中，於您倉庫的 設定 中選取 SQL 連線字串，然後複製提供的連線字串。 這個字串是你倉庫的伺服器名稱，與 SQL 分析端點不同。 看起來像 <server unique ID>.datawarehouse.fabric.microsoft.com。
    4. 對於 認證類型，請使用 Microsoft Entra ID - Universal 支援多因子驗證。 用你的 Microsoft Entra ID 驗證。
    5. 請依預設或偏好提供其他資訊，並選擇 「連接」。

  2. 在Visual Studio Code中，從活動欄選擇 Database Projects 擴充功能圖示。

  3. 從 ...] 窗格中選取選項按鈕，然後選擇 [從資料庫建立專案] 選項。

    Visual Studio Code截圖顯示「從資料庫建立專案」選項。

  4. 從現有的連線設定檔中選擇您的倉庫。

  5. 輸入專案名稱，並在工作站上選擇專案資料夾。

  6. 針對資料夾結構，選取 結構描述/物件型別 （建議）。

  7. 針對 [在專案中包含許可權]，選取 [否 （預設）]。

  8. 針對 SDK 樣式專案，選取 [是 （建議）]。

  9. 選取 [ 是 ] 以回答問題 您要 將 SQL 專案組建設定為此資料夾的預設組建組態嗎？

  10. Visual Studio Code 會從倉庫專案中擷取專案檔案。

    Visual Studio Code截圖顯示解壓專案檔案的進度通知。

  11. 成功解壓後，你會看到以下通知：「解壓專案檔案：成功。 已完成“。

  12. 選取 [ 是 ] 以信任此資料夾中檔案的作者。

倉庫的新資料庫專案

倉儲的新資料庫專案會顯示在 [SQL 資料庫專案] 功能表中。

Visual Studio Code中的截圖，顯示AdventureWorksDW2022的新資料庫專案。

您的專案結構如下所示：

 | Project Name
 ├── Database References
 ├── SQLCMD Variables
 ├── .vscode/
 └── schema/
     ├── Functions
     ├── Tables
     └── Views

設定資料庫專案

  1. 以滑鼠右鍵按一下專案，然後選取 [編輯 .sqlproj 檔案]。

    截圖來自Visual Studio Code及資料庫專案的右鍵選單。編輯 sqlproj 檔案選項被標示出來了。

  2. 確認檔案中包含最新版本的 Microsoft。Build.SQL SDK。 例如，在 .sqlproj 檔案中，將 Microsoft.Build.Sql 的版本變更為 2.3.0。

       <Sdk Name="Microsoft.Build.Sql" Version="2.3.0" />

  3. 請確認最新版本的 Microsoft.SqlServer.Dacpacs.FabricDw，並在 XML 節點Project/ItemGroup中新增參考。 例如：

       <PackageReference Include="Microsoft.SqlServer.Dacpacs.FabricDw" Version="170.0.4">
       <DatabaseVariableLiteralValue>master</DatabaseVariableLiteralValue>
       <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
   </PackageReference>

    這很重要

    如果你在未加入 DatabaseVariableLiteralValue 中繼資料的情況下新增套件參考，專案仍可成功建置，但 sqlpackage 和 Script 動作可能會在你的程式碼一旦參考 sys 結構描述中的物件（例如 sys.views）時失敗。 在這種情況下，你會看到以下錯誤：

    Error SQL72033: This deployment may encounter errors during execution because [<schema>].[<procedure>] depends on [sys].[views].[schema_id] and [sys].[views].[schema_id] does not exist in the target database.

    這是更新後倉庫的資料庫專案的外觀。

     <?xml version="1.0" encoding="utf-8"?>
 <Project DefaultTargets="Build">
   <Sdk Name="Microsoft.Build.Sql" Version="2.3.0" />
   <PropertyGroup>
     <Name>DatabaseProject715wh</Name>
     <ProjectGuid>{2E278BCC-F118-4DDB-9255-94697F2930B4}</ProjectGuid>
     <DSP>Microsoft.Data.Tools.Schema.Sql.SqlDwUnifiedDatabaseSchemaProvider</DSP>
     <ModelCollation>1033, CI</ModelCollation>
   </PropertyGroup>
   <ItemGroup>
     <None Include=".vscode\tasks.json" />
     <PackageReference Include="Microsoft.SqlServer.Dacpacs.FabricDw" Version="170.0.4">
       <DatabaseVariableLiteralValue>master</DatabaseVariableLiteralValue>
       <SuppressMissingDependenciesErrors>False</SuppressMissingDependenciesErrors>
     </PackageReference>
   </ItemGroup>
   <Target Name="BeforeBuild">
     <Delete Files="$(BaseIntermediateOutputPath)\project.assets.json" />
   </Target>
 </Project>

  4. 儲存您的 .sqlproj 檔案。 在重新載入資料庫專案的提示上，選取 [ 是]。

這很重要

Fabric Data Warehouse 團隊經常釋出新版本的 NuGet 套件。 由於 .sqlproj 檔案中的預設版本值會隨時間變動，請在本機專案中更新這些值，以與 NuGet 上 Microsoft.SqlServer.Dacpacs.FabricDw 提供的最新版本保持一致。

新增或更新資料庫物件

您可以在倉儲專案中定義或修改資料庫物件，例如表格、視圖、預存程序及函數。

例如 dbo，在結構描述的資料夾下，新增或刪除或變更倉儲中物件的 T-SQL 定義。 若要修改現有物件，請開啟其對應 .sql 的檔案，並視需要更新定義。

當您建置專案時，所有新的和更新的物件都會經過驗證，並包含在檔案中 {project folder location}/bin/debug/{project name}.dacpac 產生的 dacpac 檔案中。

在這裡所做的變更僅限於資料庫專案，必須在你建置和發佈專案後才會反映在 Microsoft Fabric 中。

建置和驗證專案

  1. 如果資料庫專案還沒開啟，請打開它。

  2. 右鍵點擊專案，選擇 建置 以建立資料庫專案。

    Visual Studio Code截圖顯示建置資料庫專案的選項。

  3. 組建應該會成功。 根據建置事件輸出中提供的訊息修正任何錯誤。

備註

目前，若要讓 Database Projects 擴充功能中的建置程序成功，你的 Visual Studio Code 預設終端機必須是 PowerShell。 在 指令面板中，選擇 終端機：選擇預設設定檔，然後選擇 PowerShell。

發佈至 Fabric Data Warehouse

建置專案後，將其發佈到目標倉庫。 發佈會建立指令碼來解決資料庫專案與實際倉庫之間的差異，並執行指令碼以使倉庫與專案相符。 你可以將倉庫結構的已編譯模型以 .dacpac 檔案部署到目標倉庫。

  1. 以滑鼠右鍵按一下專案，然後選取 [發佈]。

  2. 選擇 [發佈至現有的 SQL Server]。

  3. 針對選取要載入的發佈設定檔，第一次發佈時，選擇不使用設定檔。

    • 儲存發佈倉庫的選項到 發佈設定檔。 Visual Studio Code 通知會讓你選擇將先前使用的發佈選項儲存到發佈設定檔。
    • 未來將專案發佈到您的倉庫時，請再次使用此發佈設定檔。 對於不同的倉儲，或開發/測試/驗收/正式作業開發環境中的不同環境，您可能有不同的設定檔選項。

  4. 從列表中選擇 Fabric Data Warehouse 連線設定檔。

  5. 選擇目標倉庫的名稱。

  6. 在 選擇動作 選項中，您可以 產生指令碼以 在發佈之前檢閱指令碼，或將專案發佈至倉儲。 - 第一次想要部署變更時，請仔細 產生腳本 並檢視產生的 T-SQL 以套用到目標倉庫。 產生腳本不會改變目標倉庫。

    • 如果你選擇 發佈，流程會寫入你的目標倉庫變更。

    Visual Studio Code 截圖顯示部署 dacpac 的通知：正在進行中。

  7. 在通知 [是否要將設定儲存在設定檔中 （.publish.xml）？]上，選擇 [是 ]，然後儲存您的發佈設定檔選項，以備下次需要發佈時使用。

倉儲專案的重要部署設定

當你部署資料庫專案到Fabric Data Warehouse時，有幾個設定會控制結構變更，並可能影響資料安全。 請小心使用。

  • BlockOnPossibleDataLoss

    • 它的用途： 若存在資料遺失風險（例如遺失包含資料的欄位或資料表），則可防止部署。
    • 推薦： 在生產環境中總是設定為 ， True 以保護關鍵資料。
    • 小心： 設定為 False 允許部署，儘管資料可能會遺失。 只在受控環境（例如開發/測試）中使用。

  • DropObjectsNotInSource

    • 它的用途： 將專案來源 中不存在 的物件丟棄目標資料庫。
    • 推薦： 在開發或測試環境中用來清理剩餘的物件。
    • 小心： 在生產環境中使用 DropObjectsNotInSource 可能會 刪除重要的物件和資料。 啟用前請再三確認。

  • PreDeploy 關於 部署前腳本

    • 作用
      • 在架構部署 前 執行自訂 SQL 腳本。
    • 常見用途
      • 在丟棄資料表前先封存或備份資料
      • 暫時停用限制或觸發器
      • 清理遺留物件
    • 警告
      • 確保指令碼具有冪等性，且不會引入與部署衝突的綱要變更。

Tip

當部署流程或查詢是 冪元時，你可以多次執行該指令而不會導致邏輯問題或失敗。 冪等指令的撰寫方式也使其能部署到多個資料庫，無需預先判定其狀態。

  • PostDeploy 用於 部署後的腳本

    • 它的用途： 架構部署 後 執行自訂 SQL 腳本。
    • 常見用途：
      • 種子查詢或參考資料
      • 重新啟用約束或觸發條件
      • 記錄部署歷史
    • 注意： 避免在正式環境中對大型資料表執行高負載操作。 確保腳本在需要時能安全執行多次。

這很重要

發佈前務必檢視部署腳本和設定。 建議先在開發或測試環境中測試，以防止意外的資料遺失。 欲了解更多資訊與範例，請參閱部署前與部署後腳本Fabric Data Warehouse。

驗證發佈

連接到您的倉庫，並為已變更的物件產生指令碼，或透過執行系統目錄物件進行驗證。

相關內容

  • Last updated on