【入门教程】使用C#开发SequoiaDB的应用

Myth丶恋晨 2022-06-06 07:12 233阅读 0赞

#     #

本文为SequoiaDB社区用户贡献的文档教程，帮助大家快速入门SequoiaDB适配C\#，并进行简单的开发。

## 安装Microsoft Visual Studio 2017 ##

通过以下网址： [https://www.visualstudio.com/zh-hans/free-developer-offers/][https_www.visualstudio.com_zh-hans_free-developer-offers]  下载最新版本的Microsoft Visual Studio 2017版本。

使用以下命令创建一个离线安装版本：

vs_community.exe --layout c:\vs2017offline --lang en-US zh-CN

![Center][]

下载时间比较长，完全下载之后，在目录下执行vs\_setup.exe

![Center 1][]

在开始菜单中找到Visual Studio的启动程序。

![Center 2][]

## 调试SequoiaDB自带的Sample Code ##

方法一： 利用安装包自带的sequoiadb.dll

从sdb的安装路径下，找到自带的sequoiadb.dll文件。这个dll动态链接库支持.NETFramework v4.0版本。

![Center 3][]

方法二：利用sdb开源的代码编译自己的sequoiadb.dll。可以通过工程中设置依赖的.NETFrameWork的版本，这个方法应对特殊的应用需求。

从github上下载 sdb driver for C\#，如下图：

![Center 4][]

用Visual Studio 打开工程项目：

![Center 5][]

在Visual Studio工程界面内，右键选择driver工程，重新编译生成。

![Center 6][]

在输出的目录下找到生成的动态编译库：

![Center 7][]

下载SequoiaDB自带的sample代码：

![Center 8][]

打开Visual Studio的开发者命令行：

![Center 9][]

切换到sdb示例代码的目录下，执行自带的编译程序：

![Center 10][]

已经将示例中的cs源代码文件，编译成.exe的执行文件。

可以试着执行这些.exe执行文件：

![Center 11][]

按照 Insert.exe  BulkInsert.exe  Find.exe  Aggregate.exe的顺序执行看看。

## 了解SequoiaDB的C\#接口 ##

通过前两步搭建了一个可以使用SequoiaDB的C\#的学习环境。下面我们来看看SequoiaDB都提供了哪些C\#的API，我们在C\#开发过程中，可以通过API可以对SequoiaDB进行哪些操作呢。

获得SequoiaDB的C\#的参考文档，可以通过以下三种方式获得。

第一种： 通过官网的在线文档，可以获得最新，最全面的帮助文档。网址如下:

[http://doc.sequoiadb.com/cn/SequoiaDB][http_doc.sequoiadb.com_cn_SequoiaDB]

图中示例为SDB的2.8版本，请根据使用的响应版本进行切换。

![Center 12][]

第二种： 在安装目录下，找到doc目录下的SequoiaDB\_usermanuals\_v2.8.chm的文档，可以离线查看SequoiaDB的所有帮助文档。

第三种：在Visual Studio中，利用对象浏览器，查看引用的Sequoiadb.dll中的接口参数。使用这个方法，需要参考第四部分，创建Windows桌面应用的介绍，把sequoiadb.dll引入到项目工程中。

![Center 13][]

然我们来看看C\#的API结构。

SequoiaDB ： SDB的基本操作。这是SDB的系统配置主要关心的各种API集合。

SequoiaDB.Bson：SDB中BSON的数据类型操作 。对SDB中的数据进行操作，这个命名空间中的API接口，是最常用到的。

SequoiaDB.Bson.IO：SDB中BSON引擎进行文档读写操作

SequoiaDB.Bson.Serialization.\*：数据的序列化。

针对SequoiaDB命名空间，看看又细分为哪些API定义类。

BaseException：异常的根类，在项目应用中，可以使用这个类捕获系统的异常事件。

CollectionSpace：集合空间。这是SDB集合空间对象的创建删除操作。

ConfigOptions：SDB系统配置参数对象，主要是变量参数。

DataCenter：

DBCollection：集合对象的操作。类似于数据库的表操作，这是开发中最经常用到的对象了。

DBCursor：数据指针。集合中记录的指针操作。

DBLob：SDB独特的特点，针对非结构化数据的块操作。

DBQuery：SDB查询语句，需要构建特定查询条件。

Domain：SDB域操作

Logger：可以引用的日志方法。

Node：针对特定节点的连接操作API接口

ReplicaGroup：复制分区组对象的操作接口。

SDBConst：SDB数据库的一些静态常量。可以通过这些变量获得SDB的一些内置变量值。

SDBConst.NodeStatus：SDB状态常量。主要用来显示SDB活动状态。

Sequoiadb：SDB数据库对象操作接口，在进行数据库配置的时候比较常用到的类。

ServerAddress：SDB是分布式数据库，利用这个对象来设定连接节点的地址信息。

以下的示例代码，最基本的SDB的连接和集合操作。

<table> 
 <tbody> 
  <tr> 
   <td> <p></p> <pre><code>/******************************************************************************
 *
 * Name: DEMO.cs
 * Description: This program demostrates how to use the C#.Net Driver
 *              This program will also populate some testing data and create
 *              indexes
 * Notice:
 *              Please add reference of 'sequoiadb.dll' in your project.
 *
 * ****************************************************************************/
 
// Please import namespace SequoiaDB and SequoiaDB.Bson
using SequoiaDB;
using SequoiaDB.Bson;
using System;
 
 
namespace Sample
{
    class DEMO
    {
 
//连接到一个数据库
        public static void Connect(Sequoiadb sdb)
        {
            try
            {
                // connect to database
                sdb.Connect();
            }
            catch (Exception e)
            {
                Console.WriteLine("Failed to connect to database at {0}:{1}", sdb.ServerAddr.Host, sdb.ServerAddr.Port);
                Console.WriteLine(e.Message);
                Environment.Exit(0);
            }
        }
 
        // 断开数据库的连接。
        public static void Disconnect(Sequoiadb sdb)
        {
            sdb.Disconnect();
        }
 
        // 获得一个集合空间，如果这个集合空间不存在，创建一个。
        public static CollectionSpace GetCollecitonSpace(Sequoiadb sdb, string csName)
        {
            CollectionSpace cs = null;
            try
            {
                cs = sdb.GetCollecitonSpace(csName);    //用到了SequoiaDB的SequoiaDB对象的根据集合空间名称获得集合空间对象。
            }
            catch (BaseException e)
            {
                // verify whether the collection space exists
                if ("SDB_DMS_CS_NOTEXIST" == e.ErrorType)
                {
                    // 创建集合空间。
                    cs = CreateCollecitonSpace(sdb, csName);
                }
                else
                {
                    Console.WriteLine("Failed to get collection space {0},ErrorType = {1}", csName, e.ErrorType);
                    Environment.Exit(0);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Environment.Exit(0);
            }
 
            return cs;
        }
 
        // 获得集合。集合不存在的时候，创建一个新的集合。
        public static DBCollection GetColleciton(CollectionSpace cs, string cName)
        {
            DBCollection dbc = null;
            try
            {
                dbc = cs.GetCollection(cName);
            }
            catch (BaseException e)
            {
                // verify whether the collection space exists
                if ("SDB_DMS_CS_NOTEXIST" == e.ErrorType)
                {
                    cs = CreateCollecitonSpace(cs.SequoiaDB, cs.Name);
                    dbc = GetColleciton(cs, cName);
                }
                // verify whether the collection exists
                else if ("SDB_DMS_NOTEXIST" == e.ErrorType)
                {
                    // if the collection does not exist, we are going to create one
                    dbc = CreateColleciton(cs, cName);
                }
                else
                {
                    Console.WriteLine("Failed to get collection {0},ErrorType = {1}", cName, e.ErrorType);
                    Environment.Exit(0);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Environment.Exit(0);
            }
 
            return dbc;
        }
 
//创建集合空间
        public static CollectionSpace CreateCollecitonSpace(Sequoiadb sdb, string csName)
        {
            CollectionSpace cs = null;
int pageSize = SDBConst.SDB_PAGESIZE_DEFAULT;   //这里利用SDB的接口中一个常量。
            try
            {
                cs = sdb.CreateCollectionSpace(csName, pageSize);
            }
            catch (BaseException e)
            {
                // verify whether the collection space exists
                if ("SDB_DMS_CS_EXIST" == e.ErrorType)
                    cs = GetCollecitonSpace(sdb, csName);
                // invalid page size argument
                else if ("SDB_INVALIDARG" == e.ErrorType)
                {
                    Console.WriteLine("Failed to create collection space {0}, invalid page size {1}", csName, pageSize);
                    Environment.Exit(0);
                }
                else
                {
                    Console.WriteLine("Failed to create collection space {0},ErrorType = {1}", csName, e.ErrorType);
                    Environment.Exit(0);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Environment.Exit(0);
            }
 
            return cs;
        }
 
        // 创建并返回一个集合对象
        public static DBCollection CreateColleciton(CollectionSpace cs, string cName)
        {
            DBCollection dbc = null;
            try
            {
                dbc = cs.CreateCollection(cName);
            }
            catch (BaseException e)
            {
                // verify whether the collection space exists
                if ("SDB_DMS_CS_NOTEXIST" == e.ErrorType)
                {
                    cs = CreateCollecitonSpace(cs.SequoiaDB, cs.Name);
                    dbc = CreateColleciton(cs, cName);
                }
                // verify whether the collection space exists
                else if ("SDB_DMS_EXIST" == e.ErrorType)
                    dbc = GetColleciton(cs, cName);
                else
                {
                    Console.WriteLine("Failed to create collection {0},ErrorType = {1}", cName, e.ErrorType);
                    Environment.Exit(0);
                }
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Environment.Exit(0);
            }
 
            return dbc;
        }
 
//创建一条JSON记录
        static BsonDocument CreateChineseRecord()
        {
            BsonDocument obj = new BsonDocument();
            try
            {
                obj.Add("姓名", "杰克");
                obj.Add("年龄", 70);
                obj.Add("id", 2001);
 
                // an embedded bson object
                BsonDocument phone = new BsonDocument
                {
                    {"0", "1808835242"},
                    {"1", "1835923246"}
                };
 
                obj.Add("电话", phone);
            }
            catch (Exception e)
            {
                Console.WriteLine("Failed to create record.");
                Console.WriteLine(e.Message);
                Environment.Exit(0);
            }
 
            return obj;
        }
        
//主函数
        public static void Main(string[] args)
        {
            if (args.Length != 1)
            {
                Console.WriteLine("Please give the database server address &lt;IP:Port&gt;");
                Environment.Exit(0);
            }
 
            // The database server address
            string sdbIP = args[0];
            // The collection space name
            string csName = "SAMPLE";
            // The collection name
            string cName = "employee";
 
            BsonDocument insertor = CreateChineseRecord();
 
            Sequoiadb sdb = new Sequoiadb(sdbIP);   //构造SequoiaDB对象
 
            Connect(sdb);
            CollectionSpace cs = GetCollecitonSpace(sdb, csName);
            DBCollection dbc = GetColleciton(cs, cName);
 
            try
            {
                BsonValue id = dbc.Insert(insertor);    //集合对象的插入记录的API接口，插入集合中一条记录，然后返回这个记录的oid.
                Console.WriteLine("Successfully inserted chinese records, object ID = {0}", id.ToString());
            }
            catch (BaseException e)
            {
                Console.WriteLine("Failed to insert chinese record, ErrorType = {0}", e.ErrorType);
                Environment.Exit(0);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Environment.Exit(0);
            }
 
            Disconnect(sdb);  //在开发中，如果不需要对数据库进行操作，一定要断开和数据库的连接来较少资源消耗。
        }
    }
}</code></pre><br> <p></p> </td> 
  </tr> 
 </tbody> 
</table>

## 创建桌面应用示例 ##

在Visual Studio中，创建一个新的项目应用：

![Center 14][]

在项目中，新建一个带表单(Form)的窗口，如下图：

![Center 15][]

项目中引入Sequoiadb.dll的两种方式，

第一种，把sequoiadb.dll放入工程文件的目录，如下图

![Center 16][]

第二种，在项目工程中，添加引用squoiadb.dll的路径。

![Center 17][]

生成的应用可以如下：

![Center 18][]

![Center 19][]

示例代码下载链接：

[https://github.com/haides/SequoiaDB-Csharp-Sample][https_github.com_haides_SequoiaDB-Csharp-Sample]

[产品特性][Link 1]  
[解决方案与案例 ][Link 2]  
[数据库下载 ][Link 3]  
[技术文档 ][Link 4]

微信客服：  
sequoiadb111

![Center 20][]

[https_www.visualstudio.com_zh-hans_free-developer-offers]: https://www.visualstudio.com/zh-hans/free-developer-offers/
[Center]: /images/20220606/e13322f582a24ab1a6f4d3782c322367.png
[Center 1]: /images/20220606/9fd8f2bab8804b6dbdd5c582d43d1ffb.png
[Center 2]: /images/20220606/cadaf141ea3149fda7f98361819a4234.png
[Center 3]: /images/20220606/499ccab3f8394ebc8ef2da06fef3f9fd.png
[Center 4]: /images/20220606/14b547c8d5f447a6a6ba9ea292aafb22.png
[Center 5]: /images/20220606/45ac4346e4364f8da5e03a414af49c67.png
[Center 6]: /images/20220606/6d1e6cf9b4ba41e1a684987ec6e54049.png
[Center 7]: /images/20220606/9986dd282c044707b8cb549eaff6529e.png
[Center 8]: /images/20220606/08fe1e16d07549b2937580c50cbad201.png
[Center 9]: /images/20220606/be19768ffa6448ad8552ef29400b19d2.png
[Center 10]: /images/20220606/24f910eda43841449ae1a096bb15c536.png
[Center 11]: /images/20220606/d54240dfad024ff89017b50e4e08adb8.png
[http_doc.sequoiadb.com_cn_SequoiaDB]: http://doc.sequoiadb.com/cn/SequoiaDB
[Center 12]: /images/20220606/bc92ce8ebfc5451e8d8007b7c8d5d7f6.png
[Center 13]: /images/20220606/b6a0831da12e485caa9b75329f39688b.png
[Center 14]: /images/20220606/8414c79bd02649c980edb23fa0888ff1.png
[Center 15]: /images/20220606/e662a6cc31d34a218c822ba54b900493.png
[Center 16]: /images/20220606/68a354bd0d9c480a8a61849d6dc1a556.png
[Center 17]: /images/20220606/6ba266dd1bfe4e148920a8e63ddfdc40.png
[Center 18]: /images/20220606/a4532916f5aa4b8290eb6f88fda6e2d5.png
[Center 19]: /images/20220606/8c5c653474eb423e97bf348e43737e29.png
[https_github.com_haides_SequoiaDB-Csharp-Sample]: https://github.com/haides/SequoiaDB-Csharp-Sample
[Link 1]: http://product.sequoiadb.com/
[Link 2]: http://solution.sequoiadb.com/
[Link 3]: http://download.sequoiadb.com/
[Link 4]: http://doc.sequoiadb.com/
[Center 20]: /images/20220606/6f053d7148154174bb788bd2ed937e19.png