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。
