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

Amazon QLDB-Treiber für.NET — Schnellstart-Tutorial

In diesem Tutorial erfahren Sie, wie Sie eine einfache Anwendung mit dem Amazon-QLDB-T Dieses Handbuch enthält Schritte zum Installieren des Treibers und kurze Codebeispiele für grundlegende CRUD-Vorgänge (Create, Read, Update und Delete).

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:

Führen Sie die Voraussetzungen für den .NET-Treiber aus, sofern Sie dies noch nicht getan haben. Dazu gehören die RegistrierungAWS, die Gewährung von programmatischem Zugriff für die Entwicklung und die Installation des.NET Core SDK.
Ledger mit dem Namen quick-start erstellen.

Informationen zum Erstellen eines Ledgers finden Sie unterGrundfunktionen für Amazon QLDB-Ledgers oderSchritt 1: Erstellen eines neuen Ledgers unter Erste Schritte mit der Konsole.

Schritt 1: Einrichten des Projekts

Richten Sie zuerst Ihr .NET-Projekt ein.

Um eine Vorlagenanwendung zu erstellen und auszuführen, geben Sie die folgendendotnet Befehle auf einem Terminal ein PowerShell, z. B. bash 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.NET zu installieren. Wir empfehlen, Visual Studio oder eine IDE Ihrer Wahl zu verwenden, um Ihrem Projekt Abhängigkeiten hinzuzufügen. Der Name des Treiberpakets ist Amazon.QLDB.Driver.
- Ö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. Oder Sie können das step-by-step Tutorial überspringen und stattdessen die komplette Anwendung ausführen.

Anmerkung

Wahl zwischen synchronen und asynchronen APIs — Der Treiber stellt synchrone und asynchrone APIs bereit. Für stark beanspruchte Anwendungen, die mehrere Anfragen verarbeiten, ohne sie zu blockieren, empfehlen wir die Verwendung der asynchronen APIs, um die Leistung zu verbessern. Der Treiber bietet synchrone APIs als zusätzlichen Komfort für bestehende Codebasen, die synchron geschrieben wurden.

Dieses Tutorial enthält sowohl synchrone als auch asynchrone Codebeispiele. Weitere Informationen zu den APIs finden Sie in den IQldbDriver - und AsyncQldbDriverI-Schnittstellen 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-Objektmapper. QLDB führte den Ion Object Mapper in Version 1.3.0 des .NET-Treibers ein. 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-Funktion.

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, wieCREATE INDEX AND-Anweisungen ausgeführtCREATE TABLE werden. Es erstellt eine benannte TabellePerson und einen Index für dasfirstName Feld in dieser Tabelle. Indizes sind erforderlich, um die Abfrageleistung zu optimieren und dabei zu helfen, Konfliktausnahmen für Optimist Concurrency Control (OCC) zu begrenzen.

Schritt 4: Einfügen eines Dokuments

Im folgenden Codebeispiel wird veranschaulicht, wie eine INSERT-Anweisung ausgeführt wird. QLDB unterstützt die PartiQL-Abfragesprache (SQL-kompatibel) und das Amazon Ion-Datenformat (Superset von JSON).

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

Tipp

Um mehrere Dokumente mithilfe einer einzigenINSERT Anweisung einzufügen, können Sie wie folgt einen Ion-Listtypparameter an die Anweisung übergeben.


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

Sie schließen den variablen Platzhalter (?) nicht in doppelte eckige Klammern (<<...>>) ein, wenn Sie eine Ion-Liste übergeben. In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Bag 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 derPerson Tabelle aktualisiert, indemage 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 derPerson Tabelle aktualisiert, indemage 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 derProgram.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 für den Ledger namens quick-start.

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

.NET-Treiber

Kochbuchreferenz