data migration desktop tool
2.1.6
Um auf die archivierte Version des Tools zuzugreifen, navigieren Sie zum Zweig „Archiv“ .
Das Azure Cosmos DB Desktop Data Migration Tool ist ein Open-Source-Projekt mit einer Befehlszeilenanwendung, die Import- und Exportfunktionen für Azure Cosmos DB bereitstellt.
Um das Tool zu verwenden, laden Sie die neueste ZIP-Datei für Ihre Plattform (Win-x64, Mac-x64 oder Linux-x64) von Releases herunter und extrahieren Sie alle Dateien an den gewünschten Installationsort. Um einen Datenübertragungsvorgang zu starten, füllen Sie zunächst die Datei migrationsettings.json mit den entsprechenden Einstellungen für Ihre Datenquelle und -senke (siehe detaillierte Anweisungen unten oder sehen Sie sich Beispiele an) und führen Sie dann die Anwendung über eine Befehlszeile aus: dmt.exe unter Windows oder dmt auf anderen Plattformen.
In diesem Repository werden mehrere Erweiterungen bereitgestellt. Über die bereitgestellten Links finden Sie die Dokumentation zur Verwendung und Konfiguration der einzelnen Elemente:
Azure Cosmos DB
Azure-Tabellen-API
JSON
MongoDB
SQL-Server
Parkett
CSV
Dateispeicherung
Azure Blob Storage
AWS S3
Azure Cognitive Search
Das Azure Cosmos DB Desktop Data Migration Tool ist eine einfache ausführbare Datei, die das Managed Extensibility Framework (MEF) nutzt. MEF ermöglicht eine entkoppelte Umsetzung des Kernprojekts und seiner Erweiterungen. Die Kernanwendung ist eine ausführbare Befehlszeilendatei, die für die Erstellung der erforderlichen Erweiterungen zur Laufzeit verantwortlich ist, indem sie diese automatisch aus dem Ordner „Extensions“ der Anwendung lädt. Eine Erweiterung ist eine Klassenbibliothek, die die Implementierung eines Systems als Quelle und (optional) Senke für die Datenübertragung umfasst. Das Kernanwendungsprojekt enthält keine direkten Verweise auf eine Erweiterungsimplementierung. Stattdessen teilen sich diese Projekte eine gemeinsame Schnittstelle.
Das Kernprojekt des Cosmos DB Data Migration Tool ist eine ausführbare C#-Befehlszeilendatei. Die Kernanwendung dient als Kompositionscontainer für die erforderlichen Source- und Sink-Erweiterungen. Daher muss der Anwendungsbenutzer vor dem Ausführen der Anwendung nur die gewünschte Extension-Klassenbibliotheksassembly im Ordner „Extensions“ ablegen. Darüber hinaus verfügt das Kernprojekt über ein Unit-Test-Projekt, um das Verhalten der Anwendung zu testen, während Erweiterungsprojekte konkrete Integrationstests enthalten, die auf externen Systemen basieren.
Dieses Projekt hat den Microsoft Open Source Verhaltenskodex übernommen. Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex oder wenden Sie sich bei weiteren Fragen oder Kommentaren an [email protected].
git clone https://github.com/AzureCosmosDB/data-migration-desktop-tool.git Öffnen Sie mit Visual Studio 2022 CosmosDbDataMigrationTool.sln .
Erstellen Sie das Projekt mit der Tastenkombination Strg + Umschalt + B ( Befehl + Umschalt + B auf einem Mac). Dadurch werden alle aktuellen Erweiterungsprojekte sowie die Befehlszeilen- Core- Anwendung erstellt. Die Build-Assemblys der Erweiterungsprojekte werden in den Ordner „Extensions“ des Core- Anwendungs-Builds geschrieben. Auf diese Weise stehen alle Erweiterungsoptionen zur Verfügung, wenn die Anwendung ausgeführt wird.
In diesem Tutorial wird beschrieben, wie Sie mit dem Azure Cosmos DB-Desktop-Datenmigrationstool JSON-Daten nach Azure Cosmos DB verschieben. In diesem Tutorial wird der Azure Cosmos DB-Emulator verwendet.
Starten Sie die Azure Cosmos DB-Emulatoranwendung und öffnen Sie https://localhost:8081/_explorer/index.html in einem Browser.
Wählen Sie im linken Menü die Option „Explorer“ . Wählen Sie dann den Link „Neue Datenbank“ unter der Überschrift „Allgemeine Aufgaben“ .
Geben Sie auf dem Blatt „Neue Datenbank“ datamigration in das Feld „Datenbank-ID“ ein und wählen Sie dann „OK“ aus.
Wenn die Datenmigrationsdatenbank nicht in der Liste der Datenbanken angezeigt wird, wählen Sie das Symbol „Aktualisieren“ aus.
Erweitern Sie das Auslassungspunkte-Menü neben der Datenmigrationsdatenbank und wählen Sie Neuer Container aus.
Geben Sie auf dem Blatt „Neuer Container“ btcdata in das Feld „Container-ID“ und /id in das Feld „Partitionsschlüssel“ ein. Wählen Sie die Schaltfläche OK .
Hinweis : Bei Verwendung des Cosmos DB-Datenmigrationstools muss der Container nicht zuvor vorhanden sein, er wird automatisch mit dem in der Senkenkonfiguration angegebenen Partitionsschlüssel erstellt.
Jede Erweiterung enthält ein README-Dokument, das die Konfiguration für die Datenmigration beschreibt. Suchen Sie in diesem Fall die Konfiguration für JSON (Quelle) und Cosmos DB (Senke).
Erweitern Sie im Projektmappen-Explorer von Visual Studio das Projekt Microsoft.Data.Transfer.Core und öffnen Sie migrationsettings.json . Diese Datei enthält einen Beispielüberblick über die Struktur der Einstellungsdatei. Konfigurieren Sie mithilfe der oben verlinkten Dokumentation die Abschnitte SourceSettings und SinkSettings . Stellen Sie sicher, dass die Einstellung „FilePath“ der Speicherort ist, an dem die Beispieldaten extrahiert werden. Die ConnectionString-Einstellung finden Sie auf dem Schnellstartbildschirm des Cosmos DB-Emulators als primäre Verbindungszeichenfolge . Speichern Sie die Datei.
Hinweis : In Konfigurationsdateien und Befehlszeilenparametern können anstelle von Sink die alternativen Begriffe Target und Destination verwendet werden. Beispielsweise wären
"Target"und"TargetSettings"auch im folgenden Beispiel gültig.
{
"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
}
}
Stellen Sie sicher, dass das Projekt Cosmos.DataTransfer.Core als Startprojekt festgelegt ist, und drücken Sie dann F5, um die Anwendung auszuführen.
Anschließend führt die Anwendung die Datenmigration durch. Nach einigen Augenblicken zeigt der Vorgang an , dass die Datenübertragung abgeschlossen ist. oder Datenübertragung fehlgeschlagen .
Hinweis : Die Eigenschaften
SourceundSinksollten mit dem im Code für die Erweiterungen festgelegten DisplayName übereinstimmen.
Laden Sie die neueste Version herunter oder stellen Sie sicher, dass das Projekt erstellt wird.
Der Ordner „Erweiterungen“ enthält die Plug-Ins, die für die Verwendung bei der Migration verfügbar sind. Jede Erweiterung befindet sich in einem Ordner mit dem Namen der Datenquelle. Die Cosmos DB-Erweiterung befindet sich beispielsweise im Ordner Cosmos . Bevor Sie die Anwendung ausführen, können Sie den Ordner „Erweiterungen“ öffnen und alle Ordner für die Erweiterungen entfernen, die für die Migration nicht erforderlich sind.
Suchen Sie im Stammverzeichnis des Build-Ordners nach migrationsettings.json und aktualisieren Sie die Einstellungen, wie in der Erweiterungsdokumentation dokumentiert. Beispieldatei (ähnlich wie oben im Tutorial):
{
"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
}
}Hinweis : migrationsettings.json kann auch so konfiguriert werden, dass mehrere Datenübertragungsvorgänge mit einem einzigen Ausführungsbefehl ausgeführt werden. Fügen Sie dazu eine
OperationsEigenschaft ein, die aus einem Array von Objekten besteht, dieSourceSettingsundSinkSettingsEigenschaften enthalten, und verwenden Sie dabei dasselbe Format wie oben für einzelne Vorgänge gezeigt. Weitere Details und Beispiele finden Sie in diesem Blogbeitrag.
Führen Sie das Programm mit dem folgenden Befehl aus:
Verwendung von Windows
dmt.exeHinweis : Verwenden Sie die Option
--settingsmit einem Dateipfad, um eine andere Einstellungsdatei anzugeben (wodurch die Standarddatei migrationsettings.json überschrieben wird). Dies erleichtert die Automatisierung der Ausführung verschiedener Migrationsjobs in einer Programmschleife.
Mit macOS
./dmtHinweis : Bevor Sie das Tool unter macOS ausführen, müssen Sie den Anweisungen von Apple zum Öffnen einer Mac-App von einem nicht identifizierten Entwickler folgen.
Entscheiden Sie, welche Art von Erweiterung Sie erstellen möchten. Es gibt drei verschiedene Arten von Erweiterungen, und jede davon kann zum Lesen von Daten, Schreiben von Daten oder beidem implementiert werden.
Fügen Sie im Ordner „Erweiterungen“ einen neuen Ordner mit dem Namen Ihrer Erweiterung hinzu.
Erstellen Sie das Erweiterungsprojekt und ein begleitendes Testprojekt.
Cosmos.DataTransfer.<Name>Extension .Binary File Storage-Erweiterungen werden nur in Kombination mit anderen Erweiterungen verwendet und sollten daher ohne die unten erforderliche zusätzliche Debugging-Konfiguration in einer .NET 6 -Klassenbibliothek platziert werden.
Fügen Sie die neuen Projekte zur CosmosDbDataMigrationTool -Lösung hinzu.
Um das lokale Debuggen zu erleichtern, muss die Ausgabe des Erweiterungsbuilds zusammen mit etwaigen Abhängigkeiten in den Ordner CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions kopiert werden. Um das Projekt so einzurichten, dass es automatisch kopiert wird, fügen Sie die folgenden Änderungen hinzu.
LocalDebugFolder ein Veröffentlichungsprofil mit dem Zielspeicherort ......CoreCosmos.DataTransfer.CorebinDebugnet6.0Extensions< Target Name = " PublishDebug " AfterTargets = " Build " Condition = " '$(Configuration)' == 'Debug' " >
< Exec Command = " dotnet publish --no-build -p:PublishProfile=LocalDebugFolder " />
</ Target > Fügen Sie Verweise auf das NuGet-Paket System.ComponentModel.Composition und das Projekt Cosmos.DataTransfer.Interfaces hinzu.
Erweiterungen können entweder IDataSourceExtension zum Lesen von Daten oder IDataSinkExtension zum Schreiben von Daten implementieren. Klassen, die diese Schnittstellen implementieren, sollten ein System.ComponentModel.Composition.ExportAttribute auf Klassenebene mit dem implementierten Schnittstellentyp als Parameter enthalten. Dadurch kann das Plugin von der Hauptanwendung übernommen werden.
IComposableDataSource oder IComposableDataSink . Um mit verschiedenen Dateiformaten verwendet zu werden, sollten die Projekte, die die Formatierer enthalten, auf das Projekt der Erweiterung verweisen und eine neue CompositeSourceExtension oder CompositeSinkExtension hinzufügen, die auf die Speicher- und Formatierererweiterungen verweist.IFormattedDataReader oder IFormattedDataWriter . Um verwendbar zu sein, sollte jeder auch eine oder mehrere CompositeSourceExtension oder CompositeSinkExtension deklarieren, um verfügbare Speicherorte für das Format zu definieren. Dazu müssen Verweise auf Speichererweiterungsprojekte und eine Deklaration für jede Dateiformat-/Speicherkombination hinzugefügt werden. Beispiel: [ Export ( typeof ( IDataSinkExtension ) ) ]
public class JsonAzureBlobSink : CompositeSinkExtension < AzureBlobDataSink , JsonFormatWriter >
{
public override string DisplayName => " JSON-AzureBlob " ;
}IConfiguration Instanz verwendet wird, die an die Methoden ReadAsync und WriteAsync übergeben wird. Einstellungen unter SourceSettings / SinkSettings werden ebenso einbezogen wie alle Einstellungen, die in JSON-Dateien enthalten sind, die durch SourceSettingsPath / SinkSettingsPath angegeben werden. Implementieren Sie Ihre Erweiterung zum Lesen und/oder Schreiben mithilfe der generischen IDataItem Schnittstelle, die Objekteigenschaften als Liste von Schlüssel-Wert-Paaren verfügbar macht. Abhängig von der spezifischen Struktur des zu implementierenden Datenspeichertyps können Sie wählen, ob verschachtelte Objekte und Arrays oder nur flache Eigenschaften der obersten Ebene unterstützt werden sollen.
Binäre Dateispeichererweiterungen befassen sich nur mit generischem Speicher und funktionieren daher nur mit
Stream-Instanzen, die ganze Dateien darstellen, und nicht mit einzelnenIDataItem.
