先决条件步骤 1：设置您的项目第 2 步：初始化驱动程序第 3 步：创建表和索引第 4 步：插入文档第 5 步：查询文档第 6 步：更新文档运行完整的应用程序

适用于.NET 的 Amazon QLDB 驱动程序 — 快速入门教程

重要

终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL。

在本教程中，您将学习如何使用适用于.NET 的 Amazon QLDB 驱动程序来设置简单应用程序。本指南包括安装驱动程序的步骤以及创建、读取、更新和删除（CRUD）的基本操作的简短代码示例。

先决条件

在开始之前，请务必执行以下操作：

请为 .NET 驱动程序完成（先决条件如果尚未执行此操作）。这包括注册 AWS、授予开发所需的编程访问权限以及安装.NET Core SDK。
创建一个名为 quick-start 分类账。

要了解如何创建分类账，请参阅控制台入门中的 Amazon QLDB 分类账的基本操作或第 1 步：创建新分类账。

步骤 1：设置您的项目

首先，您需要设置您的 .NET 项目。

要创建和运行模板应用程序，请在终端上输入以下dotnet命令，例如 bash PowerShell、或命令提示符。
```
$ 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 中，在 “工具” 菜单上打开 Pack NuGet age Manager 控制台。然后在 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 文档中的IQldb驱动程序和IAsyncQldbDriver接口。
处理 Amazon Ion 数据 – 本教程提供了默认使用 Ion 对象映射器处理 Amazon Ion 数据的代码示例。QLDB 在.NET 驱动程序的 1.3.0 版本中引入 Ion 对象映射器。在适用的情况下，本教程还提供使用标准 Ion 库作为替代方案的代码示例。要了解更多信息，请参阅使用 Amazon Ion。

第 2 步：初始化驱动程序

初始化连接到名为 quick-start 的分类账的驱动程序实例。将以下代码添加到您的 Program.cs文件。

第 3 步：创建表和索引

在本教程至步骤 6 的其余部分中，您需要将以下代码示例附加到前面的代码示例中。

在此步骤中，以下代码显示了如何运行 CREATE TABLE 和 CREATE INDEX 语句。它会创建一个名为 Person 的表，并为该表上的 firstName 字段创建索引。索引是优化查询性能和帮助限制乐观并发控制（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 语句中，双尖括号表示名为bag的无序集合。

第 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 应用程序的完整版本。您还可以从头到尾复制并运行此代码示例，而不必单独执行前面的步骤。此应用程序演示了对名为 quick-start 的分类账的一些基本的 CRUD 操作。

注意

在运行此代码之前，请确保 quick-start 分类账中还没有名为 Person 的活动表。

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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

.NET 驱动程序

说明书参考