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

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

准备工作

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

Bash
Install-Package LiteDB

定义实体模型

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

数据库连接与基本操作

创建数据库连接

C#
using LiteDB;

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

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

插入文档

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

查询文档

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

注意：在Roles为空时的判断

更新文档

实例更新

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

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

        return result;
    }
}

删除文档

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

高级特性

事务支持

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

索引管理

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

注意事项

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

异常处理

文件和数据库相关错误：

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 都是一个值得考虑的数据存储解决方案。

目录