Voraussetzungen Schritt 1: Einrichten des Projekts Schritt 2: Initialisieren des Treibers Schritt 3: Erstellen einer Tabelle und eines Index Schritt 4: Einfügen eines Dokuments Schritt 5: Abfragen des Dokuments Schritt 6: Aktualisieren des Dokuments Ausführen der vollständigen Anwendung

QLDBAmazon-Treiber für. NET— Schnellstart-Tutorial

Wichtig

Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter Migrieren eines Amazon QLDB Ledgers zu Amazon Aurora SQL Postgre.

In diesem Tutorial erfahren Sie, wie Sie eine einfache Anwendung mit dem QLDB Amazon-Treiber für einrichten. NET. Dieses Handbuch enthält Schritte zur Installation des Treibers und kurze Codebeispiele für grundlegende Erstellungs-, Lese-, Aktualisierungs- und Löschvorgänge (CRUD).

Themen

Voraussetzungen
Schritt 1: Einrichten des Projekts
Schritt 2: Initialisieren des Treibers
Schritt 3: Erstellen einer Tabelle und eines Index
Schritt 4: Einfügen eines Dokuments
Schritt 5: Abfragen des Dokuments
Schritt 6: Aktualisieren des Dokuments
Ausführen der vollständigen Anwendung

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass die folgende Voraussetzung erfüllt ist:

Vervollständigen Sie das Voraussetzungen für. NETFahrer, falls Sie dies noch nicht getan haben. Dazu gehören die Registrierung für AWS, die Gewährung des programmatischen Zugriffs für die Entwicklung und die Installation von. NETKernSDK.
Ledger mit dem Namen quick-start erstellen.

Informationen zum Erstellen eines Ledgers finden Sie unter Grundlegende Operationen für QLDB Amazon-Ledger oder Schritt 1: Erstellen Sie ein neues Hauptbuch in Erste Schritte mit der Konsole.

Schritt 1: Einrichten des Projekts

Richten Sie zunächst Ihre ein. NETProjekt.

Um eine Vorlagenanwendung zu erstellen und auszuführen, geben Sie die folgenden dotnet Befehle auf einem Terminal ein, z. B. bash PowerShell, oder Command Prompt.
```
$ dotnet new console --output Amazon.QLDB.QuickStartGuide
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```
Diese Vorlage erstellt einen Ordner mit dem Namen Amazon.QLDB.QuickStartGuide. In diesem Ordner wird ein Projekt mit dem gleichen Namen und einer Datei mit dem Namen Program.cs erstellt. Das Programm enthält Code, der die Ausgabe Hello World! anzeigt.
Verwenden Sie den NuGet Paketmanager, um den QLDB Treiber für zu installieren. NET. Wir empfehlen, Visual Studio oder ein Programm IDE Ihrer Wahl zu verwenden, um Ihrem Projekt Abhängigkeiten hinzuzufügen. Der Name des Treiberpakets ist Amazon. QLDB.Treiber.
- Öffnen Sie beispielsweise in Visual Studio die NuGet Package Manager Console im Menü Tools. Geben Sie anschließend den folgenden Befehl an der PM>-Eingabeaufforderung ein:
```
PM> Install-Package Amazon.QLDB.Driver
```
- Oder Sie können die folgenden Befehle auf Ihrem Terminal eingeben.
```
$ cd Amazon.QLDB.QuickStartGuide
$ dotnet add package Amazon.QLDB.Driver
```
Beim Installieren des Treibers werden auch die Abhängigkeiten installiert, einschließlich der AWS SDK for .NET- und der Amazon Ion-Bibliotheken.
Installieren Sie die Serialisierungsbibliothek des Treibers.
```
PM> Install-Package Amazon.QLDB.Driver.Serialization
```
Öffnen Sie die Program.cs Datei.

Fügen Sie dann schrittweise die Codebeispiele in den folgenden Schritten hinzu, um einige grundlegende CRUD Operationen auszuprobieren. Sie können das step-by-step Tutorial auch überspringen und stattdessen die gesamte Anwendung ausführen.

Anmerkung

Wahl zwischen synchron und asynchron APIs — Der Treiber bietet synchron und asynchron. APIs Für stark beanspruchte Anwendungen, die mehrere Anfragen verarbeiten, ohne sie zu blockieren, empfehlen wir die asynchrone Variante, um die Leistung zu verbessern. APIs Der Treiber bietet Synchron APIs als zusätzlichen Komfort für bestehende Codebasen, die synchron geschrieben werden.

Dieses Tutorial enthält sowohl synchrone als auch asynchrone Codebeispiele. Weitere Informationen zu den finden Sie APIs unter den IAsyncQldbDriverSchnittstellen IQldbDriverund in der API Dokumentation.
Verarbeitung von Amazon Ion-Daten — Dieses Tutorial enthält Codebeispiele für die standardmäßige Verarbeitung von Amazon Ion-Daten mit dem Ion-Object-Mapper. QLDBführte den Ion Object Mapper in Version 1.3.0 von ein. NETTreiber. Gegebenenfalls enthält dieses Tutorial auch Codebeispiele, bei denen die Standard-Ion-Bibliothek als Alternative verwendet wird. Weitere Informationen hierzu finden Sie unter Arbeiten mit Amazon Ion.

Schritt 2: Initialisieren des Treibers

Initialisieren Sie eine Instance des Treibers, der eine Verbindung mit dem Ledger quick-start herstellt. Fügen Sie nun folgenden Code in die Datei Program.cs ein:

Schritt 3: Erstellen einer Tabelle und eines Index

Für den Rest dieses Tutorials bis Schritt 6 müssen Sie die folgenden Codebeispiele an das vorherige Codebeispiel anhängen.

In diesem Schritt zeigt der folgende Code, wie CREATE INDEX Anweisungen ausgeführt werdenCREATE TABLE. Es erstellt eine Tabelle mit dem Namen Person und einen Index für das firstName Feld in dieser Tabelle. Indizes sind erforderlich, um die Abfrageleistung zu optimieren und zur Begrenzung von Konfliktausnahmen bei optimistischer Parallelitätssteuerung (OCC) beizutragen.

Schritt 4: Einfügen eines Dokuments

Im folgenden Codebeispiel wird veranschaulicht, wie eine INSERT-Anweisung ausgeführt wird. QLDBunterstützt die PartiQL-Abfragesprache (SQLkompatibel) und das Amazon Ion-Datenformat (Superset vonJSON).

Fügen Sie den folgenden Code hinzu, der ein Dokument in die Tabelle Person einfügt.

Tipp

Um mehrere Dokumente mithilfe einer einzigen INSERT Anweisung einzufügen, können Sie der Anweisung wie folgt einen Parameter vom Typ Ion-Liste übergeben.


// people is an Ion list
txn.Execute("INSERT INTO Person ?", people);

Wenn Sie eine Ion-Liste übergeben, schließen Sie den Platzhalter für die Variable (?) nicht in doppelte spitze Klammern (<<...>>) ein. In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Tasche bezeichnet wird.

Schritt 5: Abfragen des Dokuments

Im folgenden Codebeispiel wird veranschaulicht, wie eine SELECT-Anweisung ausgeführt wird.

Fügen Sie den folgenden Code hinzu, der ein Dokument aus der Tabelle Person abfragt.

In diesem Beispiel wird ein Fragezeichen (?) als Variablenplatzhalter verwendet, um die Dokumentinformationen an die Anweisung zu übergeben. Wenn Sie Platzhalter verwenden, müssen Sie einen Wert vom Typ IonValue übergeben.

Schritt 6: Aktualisieren des Dokuments

Im folgenden Codebeispiel wird veranschaulicht, wie eine UPDATE-Anweisung ausgeführt wird.

Fügen Sie den folgenden Code hinzu, der ein Dokument in der Person Tabelle aktualisiert, indem age es auf 42 aktualisiert wird.

Fragen Sie das Dokument erneut ab, um den aktualisierten Wert zu sehen.

Um die Anwendung auszuführen, geben Sie den folgenden Befehl aus dem übergeordneten Verzeichnis Ihres Amazon.QLDB.QuickStartGuide-Projektverzeichnisses ein.
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

Fügen Sie den folgenden Code hinzu, der ein Dokument in der Person Tabelle aktualisiert, indem age es auf 42 aktualisiert wird.

Fragen Sie das Dokument erneut ab, um den aktualisierten Wert zu sehen.

Um die Anwendung auszuführen, geben Sie den folgenden Befehl aus dem übergeordneten Verzeichnis Ihres Amazon.QLDB.QuickStartGuide-Projektverzeichnisses ein.
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

Ausführen der vollständigen Anwendung

Das folgende Codebeispiel ist die vollständige Version der Program.cs Anwendung. Anstatt die vorherigen Schritte einzeln auszuführen, können Sie dieses Codebeispiel auch kopieren und von Anfang bis Ende ausführen. Diese Anwendung demonstriert einige grundlegende CRUD Operationen auf dem genannten quick-start Hauptbuch.

Anmerkung

Bevor Sie diesen Code ausführen, stellen Sie sicher, dass Sie noch keine aktive Tabelle mit dem Namen Person im quick-start-Ledger besitzen.

Async


using Amazon.QLDB.Driver;
using Amazon.QLDB.Driver.Generic;
using Amazon.QLDB.Driver.Serialization;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        public class Person
        {
            public string FirstName { get; set; }

            public string LastName { get; set; }

            public int Age { get; set; }

            public override string ToString()
            {
                return FirstName + ", " + LastName + ", " + Age.ToString();
            }
        }

        static async Task Main(string[] args)
        {
            Console.WriteLine("Create the async QLDB driver");
            IAsyncQldbDriver driver = AsyncQldbDriver.Builder()
                .WithLedger("quick-start")
                .WithSerializer(new ObjectSerializer())
                .Build();

            Console.WriteLine("Creating the table and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            await driver.Execute(async txn =>
            {
                await txn.Execute("CREATE TABLE Person");
                await txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            Person myPerson = new Person {
                FirstName = "John",
                LastName = "Doe",
                Age = 32
            };

            await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("INSERT INTO Person ?", myPerson);
                await txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IAsyncResult<Person> selectResult = await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return await txn.Execute(myQuery);
            });

            await foreach (Person person in selectResult)
            {
                Console.WriteLine(person);
                // John, Doe, 32
            }

            Console.WriteLine("Updating the document");

            await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("UPDATE Person SET Age = ? WHERE FirstName = ?", 42, "John");
                await txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table for the updated document");

            IAsyncResult<Person> updateResult = await driver.Execute(async txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return await txn.Execute(myQuery);
            });

            await foreach (Person person in updateResult)
            {
                Console.WriteLine(person);
                // John, Doe, 42
            }
        }
    }
}

Sync


using Amazon.QLDB.Driver;
using Amazon.QLDB.Driver.Generic;
using Amazon.QLDB.Driver.Serialization;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        public class Person
        {
            public string FirstName { get; set; }

            public string LastName { get; set; }

            public int Age { get; set; }

            public override string ToString()
            {
                return FirstName + ", " + LastName + ", " + Age.ToString();
            }
        }

        static void Main(string[] args)
        {
            Console.WriteLine("Create the sync QLDB driver");
            IQldbDriver driver = QldbDriver.Builder()
                .WithLedger("quick-start")
                .WithSerializer(new ObjectSerializer())
                .Build();

            Console.WriteLine("Creating the table and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            driver.Execute(txn =>
            {
                txn.Execute("CREATE TABLE Person");
                txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            Person myPerson = new Person {
                FirstName = "John",
                LastName = "Doe",
                Age = 32
            };

            driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("INSERT INTO Person ?", myPerson);
                txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IResult<Person> selectResult = driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return txn.Execute(myQuery);
            });

            foreach (Person person in selectResult)
            {
                Console.WriteLine(person);
                // John, Doe, 32
            }

            Console.WriteLine("Updating the document");

            driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("UPDATE Person SET Age = ? WHERE FirstName = ?", 42, "John");
                txn.Execute(myQuery);
            });

            Console.WriteLine("Querying the table for the updated document");

            IResult<Person> updateResult = driver.Execute(txn =>
            {
                IQuery<Person> myQuery = txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "John");
                return txn.Execute(myQuery);
            });

            foreach (Person person in updateResult)
            {
                Console.WriteLine(person);
                // John, Doe, 42
            }

        }
    }
}

Async


using System;
using System.Threading.Tasks;
using Amazon.IonDotnet.Tree;
using Amazon.IonDotnet.Tree.Impl;
using Amazon.QLDB.Driver;
using IAsyncResult = Amazon.QLDB.Driver.IAsyncResult;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        static IValueFactory valueFactory = new ValueFactory();

        static async Task Main(string[] args)
        {
            Console.WriteLine("Create the async QLDB driver");
            IAsyncQldbDriver driver = AsyncQldbDriver.Builder()
                .WithLedger("quick-start")
                .Build();

            Console.WriteLine("Creating the table and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            await driver.Execute(async txn =>
            {
                await txn.Execute("CREATE TABLE Person");
                await txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            // This is one way of creating Ion values. We can also use an IonLoader.
            // For more details, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-cookbook-dotnet.html#cookbook-dotnet.ion
            IIonValue ionPerson = valueFactory.NewEmptyStruct();
            ionPerson.SetField("firstName", valueFactory.NewString("John"));
            ionPerson.SetField("lastName", valueFactory.NewString("Doe"));
            ionPerson.SetField("age", valueFactory.NewInt(32));

            await driver.Execute(async txn =>
            {
                await txn.Execute("INSERT INTO Person ?", ionPerson);
            });

            Console.WriteLine("Querying the table");

            IIonValue ionFirstName = valueFactory.NewString("John");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IAsyncResult selectResult = await driver.Execute(async txn =>
            {
                return await txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName);
            });

            await foreach (IIonValue row in selectResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }

            Console.WriteLine("Updating the document");

            IIonValue ionIntAge = valueFactory.NewInt(42);
            IIonValue ionFirstName2 = valueFactory.NewString("John");

            await driver.Execute(async txn =>
            {
                await txn.Execute("UPDATE Person SET age = ? WHERE firstName = ?", ionIntAge, ionFirstName2);
            });

            Console.WriteLine("Querying the table for the updated document");

            IIonValue ionFirstName3 = valueFactory.NewString("John");

            IAsyncResult updateResult = await driver.Execute(async txn =>
            {
                return await txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName3);
            });

            await foreach (IIonValue row in updateResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }
        }
    }
}

Sync


using System;
using Amazon.IonDotnet.Tree;
using Amazon.IonDotnet.Tree.Impl;
using Amazon.QLDB.Driver;

namespace Amazon.QLDB.QuickStartGuide
{
    class Program
    {
        static IValueFactory valueFactory = new ValueFactory();

        static void Main(string[] args)
        {
            Console.WriteLine("Create the sync QLDB Driver");
            IQldbDriver driver = QldbDriver.Builder()
                .WithLedger("quick-start")
                .Build();

            Console.WriteLine("Creating the tables and index");

            // Creates the table and the index in the same transaction.
            // Note: Any code within the lambda can potentially execute multiple times due to retries.
            // For more information, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-retry-policy
            driver.Execute(txn =>
            {
                txn.Execute("CREATE TABLE Person");
                txn.Execute("CREATE INDEX ON Person(firstName)");
            });

            Console.WriteLine("Inserting a document");

            // This is one way of creating Ion values. We can also use an IonLoader.
            // For more details, see: https://docs.aws.amazon.com/qldb/latest/developerguide/driver-cookbook-dotnet.html#cookbook-dotnet.ion
            IIonValue ionPerson = valueFactory.NewEmptyStruct();
            ionPerson.SetField("firstName", valueFactory.NewString("John"));
            ionPerson.SetField("lastName", valueFactory.NewString("Doe"));
            ionPerson.SetField("age", valueFactory.NewInt(32));

            driver.Execute(txn =>
            {
                txn.Execute("INSERT INTO Person ?", ionPerson);
            });

            Console.WriteLine("Querying the table");

            IIonValue ionFirstName = valueFactory.NewString("John");

            // The result from driver.Execute() is buffered into memory because once the
            // transaction is committed, streaming the result is no longer possible.
            IResult selectResult = driver.Execute(txn =>
            {
                return txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName);
            });

            foreach (IIonValue row in selectResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }

            Console.WriteLine("Updating a document");

            IIonValue ionIntAge = valueFactory.NewInt(42);
            IIonValue ionFirstName2 = valueFactory.NewString("John");

            driver.Execute(txn =>
            {
                txn.Execute("UPDATE Person SET age = ? WHERE firstName = ?", ionIntAge, ionFirstName2);
            });

            Console.WriteLine("Querying the table for the updated document");

            IIonValue ionFirstName3 = valueFactory.NewString("John");

            IResult updateResult = driver.Execute(txn =>
            {
                return txn.Execute("SELECT * FROM Person WHERE firstName = ?", ionFirstName3);
            });

            foreach (IIonValue row in updateResult)
            {
                Console.WriteLine(row.GetField("firstName").StringValue);
                Console.WriteLine(row.GetField("lastName").StringValue);
                Console.WriteLine(row.GetField("age").IntValue);
            }
        }
    }
}

Um die vollständige Anwendung auszuführen, geben Sie den folgenden Befehl aus dem übergeordneten Verzeichnis Ihres Amazon.QLDB.QuickStartGuide-Projektverzeichnisses ein.


$ dotnet run --project Amazon.QLDB.QuickStartGuide

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

. NETFahrer

Referenz zum Kochbuch