Prasyarat Langkah 1: Siapkan proyek Anda Langkah 2: Inisialisasi driver Langkah 3: Buat tabel dan indeks Langkah 4: Masukkan dokumen Langkah 5: Kueri dokumen Langkah 6: Perbarui dokumen Menjalankan aplikasi lengkap

Driver Amazon QLDB untuk.NET - Tutorial mulai cepat

penting

Pemberitahuan akhir dukungan: Pelanggan yang ada akan dapat menggunakan Amazon QLDB hingga akhir dukungan pada 07/31/2025. Untuk detail selengkapnya, lihat Memigrasi Buku Besar QLDB Amazon ke Amazon Aurora PostgreSQL.

Dalam tutorial ini, Anda belajar cara mengatur aplikasi sederhana menggunakan driver Amazon QLDB untuk.NET. Panduan ini mencakup langkah-langkah untuk menginstal driver dan contoh kode pendek dari operasi dasar membuat, membaca, memperbarui, dan menghapus (CRUD).

Prasyarat

Sebelum memulai, pastikan Anda melakukan hal berikut:

Lengkapi Prasyarat untuk driver.NET, jika Anda belum melakukannya. Ini termasuk mendaftar AWS, memberikan akses terprogram untuk pengembangan, dan menginstal .NET Core SDK.
Buat buku besar bernamaquick-start.

Untuk mempelajari cara membuat buku besar, lihat Operasi dasar untuk buku besar QLDB Amazon atau Langkah 1: Buat buku besar baru di Memulai dengan konsol.

Langkah 1: Siapkan proyek Anda

Pertama, siapkan proyek.NET Anda.

Untuk membuat dan menjalankan aplikasi template, masukkan dotnet perintah berikut pada terminal seperti bash, PowerShell, atau Command Prompt.
```
$ dotnet new console --output Amazon.QLDB.QuickStartGuide
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```
Template ini membuat folder bernamaAmazon.QLDB.QuickStartGuide. Dalam folder itu, ia membuat proyek dengan nama yang sama dan file bernamaProgram.cs. Program ini berisi kode yang menampilkan outputHello World!.
Gunakan manajer NuGet paket untuk menginstal driver QLDB untuk.NET. Sebaiknya gunakan Visual Studio atau IDE pilihan Anda untuk menambahkan dependensi ke proyek Anda. Nama paket driver adalah Amazon.QLDB.Driver.
- Misalnya di Visual Studio, buka NuGet Package Manager Console pada menu Tools. Kemudian, masukkan perintah berikut pada PM> prompt.
```
PM> Install-Package Amazon.QLDB.Driver
```
- Atau, Anda dapat memasukkan perintah berikut di terminal Anda.
```
$ cd Amazon.QLDB.QuickStartGuide
$ dotnet add package Amazon.QLDB.Driver
```
Menginstal driver juga menginstal dependensinya, termasuk perpustakaan Amazon Ion dan AWS SDK for .NET Amazon.

Instal perpustakaan serialisasi driver.


PM> Install-Package Amazon.QLDB.Driver.Serialization

Buka file Program.cs.

Kemudian, secara bertahap tambahkan contoh kode dalam langkah-langkah berikut untuk mencoba beberapa operasi CRUD dasar. Atau, Anda dapat melewati step-by-step tutorial dan menjalankan aplikasi lengkap.

catatan

Memilih antara sinkron dan asinkron APIs — Driver menyediakan sinkron dan asinkron. APIs Untuk aplikasi permintaan tinggi yang menangani beberapa permintaan tanpa memblokir, sebaiknya gunakan asinkron APIs untuk meningkatkan kinerja. Pengemudi menawarkan sinkron APIs sebagai kenyamanan tambahan untuk basis kode yang ada yang ditulis secara sinkron.

Tutorial ini mencakup contoh kode sinkron dan asinkron. Untuk informasi selengkapnya tentang APIs, lihat IQldbDriver dan IAsyncQldbDriverantarmuka dalam dokumentasi API.
Memproses data Amazon Ion - Tutorial ini memberikan contoh kode pemrosesan data Amazon Ion menggunakan pemetaan objek Ion secara default. QLDB memperkenalkan pemetaan objek Ion di driver .NET versi 1.3.0. Jika berlaku, tutorial ini juga menyediakan contoh kode menggunakan pustaka Ion standar sebagai alternatif. Untuk mempelajari selengkapnya, lihat Bekerja dengan Amazon Ion.

Langkah 2: Inisialisasi driver

Inisialisasi instance driver yang terhubung ke buku besar bernama. quick-start Tambahkan kode berikut ke Program.cs file Anda.

Langkah 3: Buat tabel dan indeks

Untuk sisa tutorial ini melalui Langkah 6, Anda perlu menambahkan contoh kode berikut ke contoh kode sebelumnya.

Pada langkah ini, kode berikut menunjukkan cara menjalankan CREATE TABLE dan CREATE INDEX pernyataan. Ini menciptakan tabel bernama Person dan indeks untuk firstName bidang pada tabel itu. Indeks diperlukan untuk mengoptimalkan kinerja kueri dan membantu membatasi pengecualian konflik kontrol konkurensi optimis (OCC).

Langkah 4: Masukkan dokumen

Contoh kode berikut menunjukkan bagaimana menjalankan INSERT pernyataan. QLDB mendukung bahasa kueri PartiQL (kompatibel dengan SQL) dan format data Amazon Ion (superset JSON).

Tambahkan kode berikut yang menyisipkan dokumen ke dalam Person tabel.

Tip

Untuk menyisipkan beberapa dokumen dengan menggunakan INSERT pernyataan tunggal, Anda dapat meneruskan parameter tipe daftar Ion ke pernyataan sebagai berikut.


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

Anda tidak melampirkan variabel placeholder (?) dalam tanda kurung sudut ganda (<<...>>) saat melewati daftar Ion. Dalam pernyataan PartiQL manual, tanda kurung sudut ganda menunjukkan koleksi tidak berurutan yang dikenal sebagai tas.

Langkah 5: Kueri dokumen

Contoh kode berikut menunjukkan bagaimana menjalankan SELECT pernyataan.

Tambahkan kode berikut yang menanyakan dokumen dari Person tabel.

Contoh ini menggunakan tanda tanya (?) sebagai placeholder variabel untuk meneruskan informasi dokumen ke pernyataan. Saat Anda menggunakan placeholder, Anda harus melewati nilai tipe. IonValue

Langkah 6: Perbarui dokumen

Contoh kode berikut menunjukkan bagaimana menjalankan UPDATE pernyataan.

Tambahkan kode berikut yang memperbarui dokumen dalam Person tabel dengan memperbarui age ke 42.

Kueri dokumen lagi untuk melihat nilai yang diperbarui.

Untuk menjalankan aplikasi, masukkan perintah berikut dari direktori induk direktori Amazon.QLDB.QuickStartGuide proyek Anda.
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

Tambahkan kode berikut yang memperbarui dokumen dalam Person tabel dengan memperbarui age ke 42.

Kueri dokumen lagi untuk melihat nilai yang diperbarui.

Untuk menjalankan aplikasi, masukkan perintah berikut dari direktori induk direktori Amazon.QLDB.QuickStartGuide proyek Anda.
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

Menjalankan aplikasi lengkap

Contoh kode berikut adalah versi lengkap Program.cs aplikasi. Alih-alih melakukan langkah-langkah sebelumnya satu per satu, Anda juga dapat menyalin dan menjalankan contoh kode ini dari awal hingga akhir. Aplikasi ini menunjukkan beberapa operasi CRUD dasar pada buku besar bernama. quick-start

catatan

Sebelum Anda menjalankan kode ini, pastikan bahwa Anda belum memiliki tabel aktif bernama Person dalam quick-start buku besar.

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);
            }
        }
    }
}

Untuk menjalankan aplikasi lengkap, masukkan perintah berikut dari direktori induk direktori Amazon.QLDB.QuickStartGuide proyek Anda.


$ dotnet run --project Amazon.QLDB.QuickStartGuide

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Pengemudi .NET

Referensi buku masak