data migration desktop tool
2.1.6
若要存取工具的存檔版本，請導覽至存檔分支。
Azure Cosmos DB 桌面資料移轉工具是一個開源項目，其中包含為 Azure Cosmos DB 提供匯入和匯出功能的命令列應用程式。
要使用該工具，請從發行版下載適用於您的平台（win-x64、mac-x64 或 linux-x64）的最新 zip 文件，並將所有文件解壓縮到所需的安裝位置。若要開始資料傳輸操作，請先使用資料來源和接收器的適當設定填入migrationsettings.json檔案（請參閱下方的詳細說明或檢視範例），然後從命令列執行應用程式：Windows 上的dmt.exe或dmt在其他平台上。
該存儲庫中提供了多個擴充功能。使用提供的連結尋找有關每個功能的使用和配置的文件：
Azure 宇宙資料庫
Azure 表 API
JSON
MongoDB
SQL伺服器
實木複合地板
CSV
文件儲存
Azure Blob 儲存
AWS S3
Azure 認知搜尋
Azure Cosmos DB 桌面資料遷移工具是利用託管擴展性框架 (MEF) 的輕量級可執行檔。 MEF 支援核心專案及其擴展的解耦實作。核心應用程式是一個命令列可執行文件，負責在運行時透過從應用程式的 Extensions 資料夾自動載入所需的擴充功能來組合它們。擴展是一個類別庫，其中包括作為來源和（可選）用於資料傳輸的接收器的系統的實作。核心應用程式項目不包含任何擴充實作的直接引用。相反，這些項目共享一個公共介面。
Cosmos DB 資料遷移工具核心專案是 C# 命令列執行檔。核心應用程式可作為所需來源和接收器擴充功能的組合容器。因此，應用程式使用者在執行應用程式之前只需將所需的Extension類別庫組件放入Extensions資料夾中即可。此外，核心專案有一個單元測試專案來測試應用程式的行為，而擴充專案則包含依賴外部系統的特定整合測試。
該專案採用了微軟開源行為準則。有關詳細信息，請參閱行為準則常見問題解答或聯繫 [email protected] 提出任何其他問題或意見。
git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git使用 Visual Studio 2022 開啟CosmosDbDataMigrationTool.sln 。
使用鍵盤快速鍵Ctrl + Shift + B （在 Mac 上為Cmd + Shift + B ）建置專案。這將建立所有當前的擴展項目以及命令列核心應用程式。擴充專案建構程式集被寫入核心應用程式建構的擴充資料夾中。這樣，應用程式運行時所有擴充選項都可用。
本教學概述如何使用 Azure Cosmos DB 桌面資料移轉工具將 JSON 資料移至 Azure Cosmos DB。本教學使用 Azure Cosmos DB 模擬器。
啟動 Azure Cosmos DB 模擬器應用程式並在瀏覽器中開啟 https://localhost:8081/_explorer/index.html。
從左側選單中選擇資源管理器選項。然後選擇「常見任務」標題下的「新資料庫」連結。
在「新資料庫」側邊欄標籤上，在「資料庫 ID」欄位中輸入datamigration ，然後選擇「確定」 。
如果資料遷移資料庫未出現在資料庫清單中，請選擇「刷新」圖示。
展開資料遷移資料庫旁的省略號選單，然後選擇New Container 。
在「新容器」側邊欄標籤上，在「容器 id」欄位中輸入btcdata ，在「分區鍵」欄位中輸入/id 。選擇確定按鈕。
注意：使用 Cosmos DB 資料遷移工具時，容器不必預先存在，它將使用接收器配置中指定的分區鍵自動建立。
每個擴充功能都包含一個自述文件，概述了資料遷移的配置。在本例中，找到 JSON（來源）和 Cosmos DB（接收器）的配置。
在 Visual Studio 解決方案資源管理器中，展開Microsoft.Data.Transfer.Core項目，然後開啟migrationsettings.json 。此文件提供了設定文件結構的範例概要。使用上面連結的文檔，配置SourceSettings和SinkSettings部分。確保FilePath設定是提取範例資料的位置。 ConnectionString 設定可以在 Cosmos DB Emulator Quickstart畫面上作為Primary Connection String找到。儲存文件。
注意：在設定檔和命令列參數中，可以使用替代術語Target和Destination來取代Sink 。例如，
"Target"和"TargetSettings"在下面的範例中也有效。
{
"Source" : " JSON " ,
"Sink" : " Cosmos-nosql " ,
"SourceSettings" : {
"FilePath" : " C: \ btcdata \ simple_json.json "
},
"SinkSettings" : {
"ConnectionString" : " AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDj... " ,
"Database" : " datamigration " ,
"Container" : " btcdata " ,
"PartitionKeyPath" : " /id " ,
"RecreateContainer" : false ,
"IncludeMetadataFields" : false
}
}
確保Cosmos.DataTransfer.Core項目設定為啟動項目，然後按F5運行應用程式。
然後應用程式執行資料遷移。片刻之後，該過程將指示資料傳輸完成。或資料傳輸失敗。
注意：
Source和Sink屬性應與擴充程式碼中設定的DisplayName相符。
下載最新版本，或確保專案已建置。
Extensions資料夾包含可在遷移中使用的插件。每個擴充功能都位於具有資料來源名稱的資料夾中。例如，Cosmos DB 擴充位於資料夾Cosmos 。在運行應用程式之前，您可以打開擴充功能資料夾並刪除遷移不需要的擴充功能的任何資料夾。
在建置資料夾的根目錄中，找到migrationsettings.json並更新擴充文件中記錄的設定。範例文件（類似上面的教學）：
{
"Source" : " JSON " ,
"Sink" : " Cosmos-nosql " ,
"SourceSettings" : {
"FilePath" : " C: \ btcdata \ simple_json.json "
},
"SinkSettings" : {
"ConnectionString" : " AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDj... " ,
"Database" : " datamigration " ,
"Container" : " btcdata " ,
"PartitionKeyPath" : " /id " ,
"RecreateContainer" : false ,
"IncludeMetadataFields" : false
}
}注意： migrationsettings.json也可以設定為使用單一執行指令執行多個資料傳輸操作。為此，請包含一個由物件陣列組成的
Operations屬性，其中包含SourceSettings和SinkSettings屬性，其格式與上面針對單一操作顯示的格式相同。其他詳細資訊和範例可以在此部落格文章中找到。
使用以下命令執行程式：
使用Windows
dmt.exe注意：使用
--settings選項和檔案路徑來指定不同的設定檔（覆蓋預設的migrationsettings.json檔案）。這有助於在程式設計循環中自動執行不同的遷移作業。
使用 macOS
./dmt注意：在 macOS 上運行該工具之前，您需要按照 Apple 關於如何打開來自身份不明的開發人員的 Mac 應用程式的說明進行操作。
決定您要建立什麼類型的擴充功能。有 3 種不同類型的擴展，每種擴展都可以實現讀取資料、寫入資料或兩者兼而有之。
在擴充資料夾中新增一個資料夾，並命名為您的擴充功能。
建立擴充項目和隨附的測試項目。
Cosmos.DataTransfer.<Name>Extension 。二進位檔案儲存擴充功能僅與其他擴充功能結合使用，因此應放置在 .NET 6類別庫中，而無需下面所需的額外偵錯配置。
將新專案新增至CosmosDbDataMigrationTool解決方案。
為了方便本機偵錯，需要將擴充建置輸出以及任何相依性複製到CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions資料夾中。若要將項目設定為自動複製，請新增以下變更。
LocalDebugFolder資料夾，目標位置為......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions< Target Name = " PublishDebug " AfterTargets = " Build " Condition = " '$(Configuration)' == 'Debug' " >
< Exec Command = " dotnet publish --no-build -p:PublishProfile=LocalDebugFolder " />
</ Target >新增對System.ComponentModel.Composition NuGet 套件和Cosmos.DataTransfer.Interfaces專案的參考。
擴充可以實作IDataSourceExtension來讀取數據，也可以實作IDataSinkExtension來寫入資料。實作這些介面的類別應包含類別層級System.ComponentModel.Composition.ExportAttribute ，並將實作的介面類型作為參數。這將允許主應用程式拾取該插件。
IComposableDataSource或IComposableDataSink介面。若要與不同的檔案格式一起使用，包含格式化程式的項目應引用擴充功能的項目，並新增引用儲存和格式化程式擴充的新CompositeSourceExtension或CompositeSinkExtension 。IFormattedDataReader或IFormattedDataWriter介面。為了可用，每個擴充功能也應該宣告一個或多個CompositeSourceExtension或CompositeSinkExtension來定義該格式的可用儲存位置。這將需要添加對儲存擴充項目的引用，並為每個檔案格式/儲存組合添加聲明。例子： [ Export ( typeof ( IDataSinkExtension ) ) ]
public class JsonAzureBlobSink : CompositeSinkExtension < AzureBlobDataSink , JsonFormatWriter >
{
public override string DisplayName => " JSON-AzureBlob " ;
}ReadAsync和WriteAsync方法的IConfiguration實例，可以從主應用程式中的任何標準 .NET 設定來源檢索擴充所需的設定。將包含SourceSettings / SinkSettings下的設定以及SourceSettingsPath / SinkSettingsPath指定的 JSON 檔案中包含的任何設定。使用通用IDataItem介面實現擴充功能以進行讀取和/或寫入，該介面將物件屬性公開為列表鍵值對。根據所實現的資料儲存類型的特定結構，您可以選擇支援嵌套物件和陣列或僅支援平面頂級屬性。
二進位檔案儲存擴充功能僅涉及通用存儲，因此僅適用於表示整個檔案的
Stream實例，而不是單一IDataItem。
