先決條件步驟 1：設定您的專案步驟 2：初始化驅動程式步驟 3：建立資料表和索引步驟 4：插入文件步驟 5：查詢文件步驟 6：更新文件執行完整的應用程式

適用於 .NET 的 Amazon QLDB 驅動程式 – 快速入門教學課程

重要

支援終止通知：現有客戶將可以使用 Amazon QLDB，直到 07/31/2025 的支援結束為止。如需詳細資訊，請參閱將 Amazon QLDB Ledger 遷移至 Amazon Aurora PostgreSQL。

在本教學課程中，您將了解如何使用適用於 .NET 的 Amazon QLDB 驅動程式設定簡單的應用程式。本指南包含安裝驅動程式的步驟，以及基本建立、讀取、更新和刪除 (CRUD) 操作的簡短程式碼範例。

先決條件

開始之前，請務必執行下列動作：

如果您尚未執行此操作，請完成 .NET 驅動程式先決條件的。這包括註冊 AWS、授予開發的程式設計存取權，以及安裝 .NET Core SDK。
建立名為的分類帳quick-start。

若要了解如何建立分類帳，請參閱主控台入門步驟 1：建立新的分類帳中的 Amazon QLDB 分類帳的基本操作或。

步驟 1：設定您的專案

首先，設定您的 .NET 專案。

若要建立和執行範本應用程式，請在 bash、PowerShell 或 Command Prompt 等終端機上輸入下列dotnet命令。
```
$ dotnet new console --output Amazon.QLDB.QuickStartGuide
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```
此範本會建立名為的資料夾Amazon.QLDB.QuickStartGuide。在該資料夾中，它會建立具有相同名稱和名為的檔案的專案Program.cs。程式包含顯示輸出的程式碼Hello World!。
使用 NuGet 套件管理員安裝適用於 .NET 的 QLDB 驅動程式。我們建議您使用 Visual Studio 或您選擇的 IDE，將相依性新增至您的專案。驅動程式套件名稱為 Amazon.QLDB.Driver。
- 例如，在 Visual Studio 中，開啟工具功能表上的 NuGet 套件管理員主控台。然後，在PM>提示中輸入下列命令。
```
PM> Install-Package Amazon.QLDB.Driver
```
- 或者，您可以在終端機上輸入下列命令。
```
$ cd Amazon.QLDB.QuickStartGuide
$ dotnet add package Amazon.QLDB.Driver
```
安裝驅動程式也會安裝其相依性，包括 AWS SDK for .NET和 Amazon Ion 程式庫。

安裝驅動程式的序列化程式庫。


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

開啟 Program.cs 檔案。

然後，在下列步驟中逐步新增程式碼範例，以嘗試一些基本的 CRUD 操作。或者，您可以略過step-by-step教學課程，改為執行完整的應用程式。

注意

選擇同步和非同步 APIs – 驅動程式提供同步和非同步 APIs。對於在不封鎖的情況下處理多個請求的高需求應用程式，我們建議您使用非同步 APIs以提高效能。驅動程式提供同步 APIs，為同步寫入的現有程式碼基礎增加便利性。

本教學課程包含同步和非同步程式碼範例。如需 APIs的詳細資訊，請參閱 API 文件中的 IQldbDriver 和 IAsyncQldbDriver 介面。
處理 Amazon Ion 資料 – 此教學課程提供程式碼範例，以預設使用 Ion 物件映射器處理 Amazon Ion 資料。QLDB 在 .NET 驅動程式的 1.3.0 版中推出 Ion 物件映射器。如適用，本教學課程也提供使用標準 Ion 程式庫做為替代程式碼範例。如需進一步了解，請參閱使用 Amazon Ion。

步驟 2：初始化驅動程式

初始化連接至名為之分類帳的驅動程式執行個體quick-start。將下列程式碼新增至您的 Program.cs 檔案。

步驟 3：建立資料表和索引

對於本教學課程的其餘部分，您需要將下列程式碼範例附加至先前的程式碼範例。

在此步驟中，下列程式碼會示範如何執行 CREATE TABLE和 CREATE INDEX陳述式。它會為該資料表上的 firstName 欄位建立名為的資料表Person和索引。需要索引才能最佳化查詢效能，並協助限制樂觀並行控制 (OCC) 衝突例外狀況。

步驟 4：插入文件

下列程式碼範例示範如何執行 INSERT陳述式。QLDB 支援 PartiQL 查詢語言（與 SQL 相容）和 Amazon Ion 資料格式 (JSON 的超集）。

新增下列程式碼，將文件插入Person資料表。

提示

若要使用單一INSERT陳述式插入多個文件，您可以將 Ion 清單類型參數傳遞至陳述式，如下所示。


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

傳遞 Ion 清單時，您不會將變數預留位置 (?) 括在雙角度括號 ( ) <<...>> 中。在手動 PartiQL 陳述式中，雙角括號表示稱為包的未排序集合。

步驟 5：查詢文件

下列程式碼範例示範如何執行 SELECT陳述式。

新增下列程式碼，以查詢Person資料表中的文件。

此範例使用問號 (?) 做為變數預留位置，將文件資訊傳遞至陳述式。使用預留位置時，您必須傳遞類型的值IonValue。

步驟 6：更新文件

下列程式碼範例示範如何執行 UPDATE陳述式。

新增下列程式碼，透過更新age至 42 來更新Person資料表中的文件。

再次查詢文件以查看更新的值。

若要執行應用程式，請從Amazon.QLDB.QuickStartGuide專案目錄的父目錄輸入下列命令。
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

新增下列程式碼，透過更新age至 42 來更新Person資料表中的文件。

再次查詢文件以查看更新的值。

若要執行應用程式，請從Amazon.QLDB.QuickStartGuide專案目錄的父目錄輸入下列命令。
```
$ dotnet run --project Amazon.QLDB.QuickStartGuide
```

執行完整的應用程式

下列程式碼範例是Program.cs應用程式的完整版本。您也可以從頭到尾複製並執行此程式碼範例，而不是個別執行上述步驟。此應用程式會在名為的分類帳上示範一些基本 CRUD 操作quick-start。

注意

在您執行此程式碼之前，請確定您尚未在分類帳Person中擁有名為 quick-start 的作用中資料表。

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

若要執行完整應用程式，請從Amazon.QLDB.QuickStartGuide專案目錄的父目錄中輸入下列命令。


$ dotnet run --project Amazon.QLDB.QuickStartGuide

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

.NET 驅動程式

技術指南參考