Vorherige

Nächste

Übung: Erstellen neuer Elemente

Abgeschlossen

Erinnern Sie sich daran, dass Sie Elemente in Ihrem Container mithilfe des Azure Cosmos DB SDK für .NET erstellen können. Für dieses Projekt enthält der products-Container sowohl die einzelnen product-Elemente als auch spezielle category-Elemente für jede Kategorie. Es gibt zwei Fälle, die Sie in dieser Anwendung behandeln müssen:

• Wenn eine Kategorie leer ist, ist es in Ordnung, das Element dieser Kategorie einfach einzeln zu erstellen. Es gibt keine verwandten product-Elemente, die erstellt werden müssen.
• Wenn eine Kategorie jedoch verwandte Produkte enthält, möchten Sie das category-Element und die zugehörigen product-Elemente gleichzeitig erstellen.

Im Moment unterliegen Sie zwei wesentlichen Anforderungen:

1. Einzelnes Erstellen eines Elements in einem Einzelvorgang.
2. Verwenden eines Transaktionsbatches zum Erstellen mehrerer verwandter Elemente.

Nachdem Sie diese Übung abgeschlossen haben, verfügt Ihr Projekt über die Logik zum Erstellen von Elementen in Ihrem Container, entweder einzeln oder als Batch.

Hinzufügen eines einzelnen Elements zu einem Container

In Azure Cosmos DB können Sie Elemente in einem Container erstellen, ersetzen oder ein Upsert ausführen. Das Erstellen eines Elements erfordert, dass das Element über einen eindeutigen Bezeichner verfügt. Das Ersetzen eines Elements erfordert, dass das Element bereits vorhanden ist. Ein Upsert vereint das Beste aus beiden Welten, indem es den eindeutigen Bezeichner überprüft, dann das Element ersetzt oder erstellt. Für dieses Projekt müssen Sie die App mehrmals ohne Fehler ausführen können, was Upsert zur ersten Wahl macht. Für das erste Element erstellen Sie eine Kategorie, die keine zugehörigen Produkte enthält. Hier implementieren Sie einen einzelnen Upsert-Vorgang mit einer manuell erstellten Kategorie.

1. Öffnen Sie die Datei Program.cs erneut.

2. Erstellen Sie eine neue Category-Instanz namens goggles mit den folgenden Werten:

   Eigenschaft	Wert
   id	ef7fa0f1-0e9d-4435-aaaf-a778179a94ad
   categoryId	gear-snow-goggles

   Category goggles = new(
       Id: "ef7fa0f1-0e9d-4435-aaaf-a778179a94ad",
       CategoryId: "gear-snow-goggles"
   );
   

3. Erstellen Sie eine neue PartitionKey-Instanz mit demselben Wert wie dem der Eigenschaft categoryId für die von Ihnen zuvor erstellte Category-Instanz.

   PartitionKey gogglesKey = new("gear-snow-goggles");
   

4. Verwenden Sie die UpsertItemAsync-Methode, um das Element zu erstellen oder zu ersetzen, wobei Sie ein Objekt für das zu erstellende Element übergeben sowie einen Partitionsschlüsselwert.

   Category result = await container.UpsertItemAsync(goggles, gogglesKey);
   

5. Geben Sie verschiedene Eigenschaften von result in die Konsole aus, einschließlich des eindeutigen Bezeichners des Elements und des Typs des Elements.

   Console.WriteLine($"[New item created]:\t{result.Id}\t(Type: {result.Type})");
   

6. Erstellen Sie eine neue Category-Instanz namens helmets mit den folgenden Werten:

   Eigenschaft	Wert
   id	91f79374-8611-4505-9c28-3bbbf1aa7df7
   categoryId	gear-climb-helmets

   Category helmets = new(
       Id: "91f79374-8611-4505-9c28-3bbbf1aa7df7",
       CategoryId: "gear-climb-helmets"
   );
   

7. Erstellen Sie eine neue PartitionKey-Instanz mit demselben Wert wie dem der Eigenschaft categoryId für die von Ihnen zuvor erstellte Category-Instanz.

   PartitionKey helmetsKey = new("gear-climb-helmets");
   

8. Verwenden Sie die UpsertItemAsync-Methode, um das Element zu erstellen oder zu ersetzen. Übergeben Sie ein Objekt für das zu erstellende Element sowie einen Partitionsschlüsselwert. Geben Sie ein Objekt des Typs ItemResponse<T> zurück.

   ItemResponse<Category> response = await container.UpsertItemAsync(helmets, helmetsKey);
   

9. Geben Sie verschiedene Eigenschaften von response in die Konsole aus, einschließlich des eindeutigen Bezeichners des zugrunde liegenden Elements, des Typs des zugrunde liegenden Elements sowie der Anforderungsbelastung in RUs.

   Console.WriteLine($"[New item created]:\t{response.Resource.Id}\t(Type: {response.Resource.Type})\t(RUs: {response.RequestCharge})");
   

10. Speichern Sie die Datei Program.cs.

Implementieren mehrerer Vorgänge als Transaktionsbatch

Betrachten Sie nun ein Szenario, in dem Sie mehrere Produkte zusammen mit einer Kategorie erstellen möchten. Wenn die Produkte erstellt werden, die Kategorie aber nicht vorhanden ist, sind diese Produkte auch nicht annähernd so nützlich. Das Erstellen mehrerer Elemente ist eine Situation, in der Sie eine Transaktion verwenden können, um mehrere „Punkt“-Vorgänge gemeinsam zu gruppieren, damit sie alle als einzelne zusammenhängende Einheit erfolgreich sind oder fehlschlagen. Zurück zu unserem Szenario, müssen wir eine Kategorie für Outdoor-Zelte mit ein paar Zeltprodukten erstellen. Wir haben bereits ein einzelnes Kategorieelement ohne Produktelemente. Folgendes sollte am Ende unser Ergebnis sein:

Diagramm verschiedener Elemente in Azure Cosmos DB, die nach ihrem spezifischen Partitionsschlüssel organisiert sind. Das Diagramm veranschaulicht, wie fünf Elemente zum Partitionsschlüsselwert „tents“ (Zelte) gehören, und nur ein Element gehört zu „helmets“ (Helme).

In diesem Abschnitt erstellen Sie einen Transaktionsbatch, um die Kategorie tents (Zelte) und verwandte Produkte zusammen zu erstellen.

1. Erstellen Sie in Program.cs eine neue Category-Instanz namens tents mit den folgenden Werten:

   Eigenschaft	Wert
   id	5df21ec5-813c-423e-9ee9-1a2aaead0be4
   categoryId	gear-camp-tents

   Category tents = new(
       Id: "5df21ec5-813c-423e-9ee9-1a2aaead0be4",
       CategoryId: "gear-camp-tents"
   );
   

2. Erstellen Sie vier Instanzen des Typs Product mithilfe dieser Werte.

   Eigenschaft	cirroa	kuloar	mammatin	nimbolo
   Id	e8dddee4-9f43-4d15-9b08-0d7f36adcac8	e6f87b8d-8cd7-4ade-a005-14d3e2fbd1aa	f7653468-c4b8-47c9-97ff-451ee55f4fd5	6e3b7275-57d4-4418-914d-14d1baca0979
   CategoryId	gear-camp-tents	gear-camp-tents	gear-camp-tents	gear-camp-tents
   Name	Cirroa Tent	Kuloar Tent	Mammatin Tent	Nimbolo Tent
   Preis	490.00	530.00	0.00	330.00
   Archived	false	false	true	false
   Menge	15	8	0	35

   Product cirroa = new(
       Id: "e8dddee4-9f43-4d15-9b08-0d7f36adcac8",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Cirroa Tent",
       Price = 490.00m,
       Archived = false,
       Quantity = 15
   };
   

   Product kuloar = new(
       Id: "e6f87b8d-8cd7-4ade-a005-14d3e2fbd1aa",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Kuloar Tent",
       Price = 530.00m,
       Archived = false,
       Quantity = 8
   };
   

   Product mammatin = new(
       Id: "f7653468-c4b8-47c9-97ff-451ee55f4fd5",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Mammatin Tent",
       Price = 0.00m,
       Archived = true,
       Quantity = 0
   };
   

   Product nimbolo = new(
       Id: "6e3b7275-57d4-4418-914d-14d1baca0979",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Nimbolo Tent",
       Price = 330.00m,
       Archived = false,
       Quantity = 35
   };
   

3. Erstellen Sie jetzt eine neue PartitionKey-Instanz mithilfe des gear-camp-tents-Werts.

   PartitionKey tentsKey = new("gear-camp-tents");
   

4. Erstellen Sie einen neuen Transaktionsbatch für den Bereich des gear-camp-tents-Partitionsschlüsselwerts mithilfe der CreateTransactionalBatch(PartitionKey)-Methode. Fügen Sie mithilfe der Fluent-Syntax fünf Upsert-Vorgänge hinzu, um die Elemente zu erstellen, die wir in unserem Container für die Kategorie benötigen, sowie alle zugehörigen Produkte.

   TransactionalBatch batch = container.CreateTransactionalBatch(tentsKey)
       .UpsertItem<Category>(tents)
       .UpsertItem<Product>(cirroa)
       .UpsertItem<Product>(kuloar)
       .UpsertItem<Product>(mammatin)
       .UpsertItem<Product>(nimbolo);
   

5. Geben Sie eine Nachricht in die Konsole aus, die angibt, dass wir einen Batchvorgang starten.

   Console.WriteLine("[Batch started]");
   

6. Verwenden Sie die TransactionalBatch.ExecuteAsync-Methode, um den Batch auszuführen und einen speziellen Antworttyp zurückzugeben.

   using TransactionalBatchResponse batchResponse = await batch.ExecuteAsync();
   

7. Durchlaufen Sie mithilfe einer for-Schleife alle Elemente in der Antwort. Konvertieren Sie zunächst jedes Element in den Typ TransactionalBatchOperationResult, indem Sie Ihre Basisklasse Item als generische Klasse verwenden. Geben Sie dann den eindeutigen Bezeichner und den Typ des Antwortobjekts aus.

   for (int i = 0; i < batchResponse.Count; i++)
   {
       TransactionalBatchOperationResult<Item> batchResult = batchResponse.GetOperationResultAtIndex<Item>(i);
       Console.WriteLine($"[New item created]:\t{batchResult.Resource.Id}\t(Type: {batchResult.Resource.Type})");
   }
   

8. Geben Sie eine weitere Nachricht in die Konsole aus, die angibt, dass der Batch abgeschlossen ist. Schließen Sie die Anforderungsbelastung für den gesamten Batch in diese Nachricht ein.

   Console.WriteLine($"[Batch completed]:\t(RUs: {batchResponse.RequestCharge})");
   

9. Speichern Sie die Datei Program.cs.

Arbeit überprüfen

Ihre App erstellt jetzt mehrere Elemente und ist so konzipiert, dass sie resilient genug ist, um mehrmals ausgeführt zu werden, ohne eine Ausnahme zu verursachen. Hier führen Sie die Anwendung aus und überprüfen die Ausgabe auf die eindeutigen Bezeichner jedes der sechs neu erstellten Elemente.

Ausführen der Anwendung

1. Ausführen der .NET-Anwendung im Terminal:

   dotnet run
   

2. Beobachten Sie die Ausgabe der Ausführung der Anwendung. Die Ausgabe sollte dem folgenden Beispiel entsprechen:

   ...
   [New item created]:     ef7fa0f1-0e9d-4435-aaaf-a778179a94ad    (Type: Category)
   [New item created]:     91f79374-8611-4505-9c28-3bbbf1aa7df7    (Type: Category)        (RUs: 10.29)
   [Batch started]
   [New item created]:     5df21ec5-813c-423e-9ee9-1a2aaead0be4    (Type: Category)
   [New item created]:     e8dddee4-9f43-4d15-9b08-0d7f36adcac8    (Type: Product)
   [New item created]:     e6f87b8d-8cd7-4ade-a005-14d3e2fbd1aa    (Type: Product)
   [New item created]:     f7653468-c4b8-47c9-97ff-451ee55f4fd5    (Type: Product)
   [New item created]:     6e3b7275-57d4-4418-914d-14d1baca0979    (Type: Product)
   [Batch completed]:      (RUs: 36.76)
   

   Tipp

   Die in dieser Beispielausgabe gezeigten RUs können von Ihrer Ausgabe abweichen.

Überprüfen des Codes

1. Überprüfen Sie die Codedatei Program.cs, um sicherzustellen, dass Ihr Code diesem Beispiel entspricht.

   using Microsoft.Azure.Cosmos;
   using Microsoft.Azure.Cosmos.Fluent;
   using Microsoft.Azure.Cosmos.Linq;
   
   // Code to create client omitted for brevity
   
   // Code to create resources omitted for brevity
   
   Category goggles = new(
       Id: "ef7fa0f1-0e9d-4435-aaaf-a778179a94ad",
       CategoryId: "gear-snow-goggles"
   );
   
   PartitionKey gogglesKey = new("gear-snow-goggles");
   
   Category result = await container.UpsertItemAsync(goggles, gogglesKey);
   
   Console.WriteLine($"[New item created]:\t{result.Id}\t(Type: {result.Type})");
   
   Category helmets = new(
       Id: "91f79374-8611-4505-9c28-3bbbf1aa7df7",
       CategoryId: "gear-climb-helmets"
   );
   
   PartitionKey helmetsKey = new("gear-climb-helmets");
   
   ItemResponse<Category> response = await container.UpsertItemAsync(helmets, helmetsKey);
   
   Console.WriteLine($"[New item created]:\t{response.Resource.Id}\t(Type: {response.Resource.Type})\t(RUs: {response.RequestCharge})");
   
   Category tents = new(
       Id: "5df21ec5-813c-423e-9ee9-1a2aaead0be4",
       CategoryId: "gear-camp-tents"
   );
   
   Product cirroa = new(
       Id: "e8dddee4-9f43-4d15-9b08-0d7f36adcac8",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Cirroa Tent",
       Price = 490.00m,
       Archived = false,
       Quantity = 15
   };
   
   Product kuloar = new(
       Id: "e6f87b8d-8cd7-4ade-a005-14d3e2fbd1aa",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Kuloar Tent",
       Price = 530.00m,
       Archived = false,
       Quantity = 8
   };
   
   Product mammatin = new(
       Id: "f7653468-c4b8-47c9-97ff-451ee55f4fd5",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Mammatin Tent",
       Price = 0.00m,
       Archived = true,
       Quantity = 0
   };
   
   Product nimbolo = new(
       Id: "6e3b7275-57d4-4418-914d-14d1baca0979",
       CategoryId: "gear-camp-tents"
   ){
       Name = "Nimbolo Tent",
       Price = 330.00m,
       Archived = false,
       Quantity = 35
   };
   
   PartitionKey tentsKey = new("gear-camp-tents");
   
   TransactionalBatch batch = container.CreateTransactionalBatch(tentsKey)
       .UpsertItem<Category>(tents)
       .UpsertItem<Product>(cirroa)
       .UpsertItem<Product>(kuloar)
       .UpsertItem<Product>(mammatin)
       .UpsertItem<Product>(nimbolo);
   
   Console.WriteLine("[Batch started]");
   
   using TransactionalBatchResponse batchResponse = await batch.ExecuteAsync();
   for (int i = 0; i < batchResponse.Count; i++)
   {
       TransactionalBatchOperationResult<Item> batchResult = batchResponse.GetOperationResultAtIndex<Item>(i);
       Console.WriteLine($"[New item created]:\t{batchResult.Resource.Id}\t(Type: {batchResult.Resource.Type})");
   }
   
   Console.WriteLine($"[Batch completed]:\t(RUs: {batchResponse.RequestCharge})");
   

Weiter