技术老小子
LiteDB 在 C# 中的基本使用教程
编辑
2025-02-03
C# 应用
00
请注意，本文编写于 92 天前，最后修改于 92 天前，其中某些信息可能已经过时。

目录

1. 准备工作
2. 定义实体模型
3. 数据库连接与基本操作
3.1 创建数据库连接
3.2 插入文档
调用
3.3 查询文档
调用
3.4 更新文档
实例更新
3.5 删除文档
4. 高级特性
4.1 事务支持
4.2 索引管理
5. 注意事项
7. 异常处理
结语

在当今快速发展的软件开发领域，开发者常常需要一个轻量、高效、易用的数据存储解决方案。LiteDB 应运而生，为 .NET 开发者提供了一个简单而强大的嵌入式 NoSQL 数据库选择。

本教程将带你全面深入地探索 LiteDB 的使用，从基础的数据库连接和实体模型设计，到复杂的文档增删改查操作，再到事务处理、性能优化和异常处理，通过系统性的学习，你将全面掌握 LiteDB 在实际项目中的应用技巧和最佳实践。

1. 准备工作

首先，确保通过 NuGet 安装 LiteDB 包：

Bash
Install-Package LiteDB

2. 定义实体模型

C#
// 用户实体类
public class User
{
    // LiteDB 要求每个文档都有一个 Id 属性
    public int Id { get; set; }
    
    // 用户基本信息
    public string Username { get; set; }
    public string Email { get; set; }
    public int Age { get; set; }
    
    // 用户角色信息
    public string[] Roles { get; set; }
    
    // 用户详细信息
    public UserProfile Profile { get; set; }
}



C#
// 用户详细信息类
public class UserProfile
{
    public string Address { get; set; }
    public string PhoneNumber { get; set; }
}

3. 数据库连接与基本操作

3.1 创建数据库连接

C#
using LiteDB;

public class UserRepository
{
    // 数据库连接字符串
    private const string DATABASE_PATH = @"MyDatabase.db";

    // 创建数据库连接
    private LiteDatabase CreateDatabaseConnection()
    {
        // 创建 LiteDB 数据库实例
        return new LiteDatabase(DATABASE_PATH);
    }
}

3.2 插入文档

C#
public void InsertUser(User user)
{
    // 使用 using 确保资源正确释放
    using (var db = CreateDatabaseConnection())
    {
        // 获取 Users 集合
        var users = db.GetCollection<User>("users");
        
        // 插入单个文档
        users.Insert(user);
        
        // 插入多个文档
        var multiUsers = new List<User> 
        {
            new User { Username = "张三", Email = "zhangsan@example.com", Age = 25 },
            new User { Username = "李四", Email = "lisi@example.com", Age = 30 }
        };
        users.InsertBulk(multiUsers);
    }
}

调用

C#
internal class Program
{
    static void Main(string[] args)
    {
        UserRepository userRepository = new UserRepository();
        userRepository.InsertUser(new User
        {
            Id = 1,
            Username = "John",
            Age = 25,
            Email = "john@example.com",
            Roles = new string[] { "admin", "user" },
            Profile = new UserProfile { Address = "123 Main St", PhoneNumber = "555-555-5555" }
        });
    }
}

image.png

3.3 查询文档

C#
// 根据 Id 查询单个用户
public User GetUserById(int userId)
{
    using (var db = CreateDatabaseConnection())
    {
        var users = db.GetCollection<User>("users");
        return users.FindById(userId);
    }
}

// 复杂条件查询
public List<User> QueryUsers(int minAge, string role)
{
    using (var db = CreateDatabaseConnection())
    {
        var users = db.GetCollection<User>("users");

        // 使用 LiteDB 支持的查询方式  
        return users.Query()
                    .Where(u =>
                        u.Age >= minAge &&
                        u.Roles != null &&
                        u.Roles.Contains(role)
                    )
                    .OrderBy(u => u.Username)
                    .Limit(100)
                    .ToList();
    }
}

// 模糊查询
public List<User> SearchUsersByName(string keyword)
{
    using (var db = CreateDatabaseConnection())
    {
        var users = db.GetCollection<User>("users");
        return users.Query()
            .Where(u => u.Username.Contains(keyword))
            .ToList();
    }
}

调用

C#
internal class Program
{
    static void Main(string[] args)
    {
        UserRepository userRepository = new UserRepository();
        var user = userRepository.GetUserById(1);
        //Console输入出user的信息
        Console.WriteLine(user.Username);
        Console.WriteLine(user.Age);
        Console.WriteLine(user.Email);
        foreach (var role in user.Roles)
        {
            Console.WriteLine(role);
        }
        Console.WriteLine(user.Profile.Address);
        Console.WriteLine(user.Profile.PhoneNumber);    
    }
}

image.png

注意：在Roles为空时的判断

3.4 更新文档

实例更新

C#
public bool UpdateUser(User user)
{
    using (var db = CreateDatabaseConnection())
    {
        var users = db.GetCollection<User>("users");

        // 根据 Id 更新整个文档
        var result = users.Update(user);

        return result;
    }
}

3.5 删除文档

C#
public class UserRepository
{
    // 按 Id 删除
    public void DeleteUserById(int userId)
    {
        using (var db = CreateDatabaseConnection())
        {
            var users = db.GetCollection<User>("users");
            users.Delete(userId);
        }
    }

    // 按条件删除
    public void DeleteUsersByCondition()
    {
        using (var db = CreateDatabaseConnection())
        {
            var users = db.GetCollection<User>("users");

            // 删除 30 岁以下的用户
            users.DeleteMany(u => u.Age < 30);
        }
    }
}

4. 高级特性

4.1 事务支持

C#
public void PerformTransactionalOperation()
{
    using (var db = CreateDatabaseConnection())
    {
        var transaction = db.BeginTrans();
        {
            try
            {
                var users = db.GetCollection<User>("users");

                // 执行多个操作  
                users.Insert(new User { Username = "新用户" });
                users.Delete(100);  // 删除特定用户  

                // 如果没有异常，提交事务  
                db.Commit();
            }
            catch (Exception ex)
            {
                // 发生异常时自动回滚  
                db.Rollback();
                throw;
            }
        }
    }
}

image.png

4.2 索引管理

C#
public void ManageIndexes()
{
    using (var db = CreateDatabaseConnection())
    {
        var users = db.GetCollection<User>("users");

        // 为 Username 创建唯一索引
        users.EnsureIndex(u => u.Username, unique: true);

        // 为 Email 创建文本索引
        users.EnsureIndex(u => u.Email);
    }
}

5. 注意事项

  1. LiteDB 是嵌入式数据库，适合小型应用
  2. 每个文档必须有唯一 Id
  3. 支持索引以提高查询性能
  4. 线程安全，但大量并发需谨慎
  5. 对常用查询字段创建索引

7. 异常处理

文件和数据库相关错误：

C#
FILE_NOT_FOUND = 101,               // 文件未找到
DATABASE_SHUTDOWN = 102,             // 数据库已关闭
INVALID_DATABASE = 103,              // 无效的数据库
FILE_SIZE_EXCEEDED = 105,            // 文件大小超限
ALREADY_OPEN_DATAFILE = 124,         // 数据文件已打开
INVALID_DATAFILE_STATE = 999,        // 数据文件状态无效

集合和索引相关错误：

C#
COLLECTION_LIMIT_EXCEEDED = 106,     // 集合数量超限
INDEX_DROP_ID = 108,                 // 不能删除ID索引
INDEX_DUPLICATE_KEY = 110,           // 索引键重复
INVALID_INDEX_KEY = 111,             // 无效的索引键
INDEX_NOT_FOUND = 112,               // 索引未找到
INDEX_NAME_LIMIT_EXCEEDED = 128,     // 索引名称长度超限
INVALID_INDEX_NAME = 129,            // 无效的索引名称
COLLECTION_NOT_FOUND = 133,          // 集合未找到
COLLECTION_ALREADY_EXIST = 134,      // 集合已存在
INDEX_ALREADY_EXIST = 135,           // 索引已存在

命名和操作相关错误：

C#
INVALID_COLLECTION_NAME = 130,       // 无效的集合名称
ALREADY_EXISTS_COLLECTION_NAME = 122,// 集合名称已存在
INVALID_COMMAND = 121,               // 无效的命令
INVALID_UPDATE_FIELD = 136,          // 无效的更新字段

事务和引擎相关错误：

C#
INVALID_TRANSACTION_STATE = 126,     // 事务状态无效
TEMP_ENGINE_ALREADY_DEFINED = 131,   // 临时引擎已定义
ENGINE_DISPOSED = 137,                // 引擎已释放
LOCK_TIMEOUT = 120,                   // 锁定超时

数据和类型相关错误：

C#
INVALID_FORMAT = 200,                // 无效的格式
DOCUMENT_MAX_DEPTH = 201,            // 文档最大深度超限
INVALID_CTOR = 202,                  // 无效的构造函数
UNEXPECTED_TOKEN = 203,              // 意外的标记
INVALID_DATA_TYPE = 204,             // 无效的数据类型
PROPERTY_NOT_MAPPED = 206,           // 属性未映射
INVALID_TYPED_NAME = 207,            // 无效的类型名称
PROPERTY_READ_WRITE = 209,           // 属性读写错误
DATA_TYPE_NOT_ASSIGNABLE = 214,      // 数据类型不可分配

加密和安全相关错误：

C#
INITIALSIZE_CRYPTO_NOT_SUPPORTED = 210,  // 初始大小加密不支持
INVALID_INITIALSIZE = 211,            // 无效的初始大小
INVALID_NULL_CHAR_STRING = 212,       // 无效的空字符串
NOT_ENCRYPTED = 216,                  // 未加密
INVALID_PASSWORD = 217,               // 无效的密码
ILLEGAL_DESERIALIZATION_TYPE = 218,   // 非法反序列化类型

其他特殊错误：

C#
INVALID_EXPRESSION_TYPE = 132,        // 无效的表达式类型
INVALID_FREE_SPACE_PAGE = 213,        // 无效的空闲空间页
AVOID_USE_OF_PROCESS = 215,           // 避免使用进程

使用示例：

C#
try 
{
    // 数据库操作
}
catch (LiteException ex)
{
    switch (ex.ErrorCode)
    {
        case LiteErrorCode.COLLECTION_NOT_FOUND:
            Console.WriteLine("集合未找到，请检查集合名称");
            break;
        case LiteErrorCode.INDEX_DUPLICATE_KEY:
            Console.WriteLine("索引键重复，无法插入");
            break;
        // 其他错误处理
    }
}

结语

LiteDB 是一个轻量、简单、功能强大的嵌入式 NoSQL 数据库，非常适合中小型 .NET 应用。它提供了直观的 API，支持复杂查询，并且易于使用和集成。无论是桌面应用、移动应用还是小型 Web 服务，LiteDB 都是一个值得考虑的数据存储解决方案。

本文作者:rick

本文链接:

版权声明:本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！