Realm .NET 使用教程

1. 项目介绍

Realm .NET 是一个移动数据库，专为在手机、平板电脑和可穿戴设备上直接运行而设计。它是 SQLite 和 ORM（对象关系映射）的替代品，提供了更简单、更现代且更快速的解决方案。Realm .NET 支持多种平台，包括 iOS、Android、UWP、macOS、Linux 和 Windows。

主要特点

• 移动优先：专为移动设备设计，性能优越。
• 简单易用：数据直接暴露为对象，支持 LINQ 查询，无需复杂的 ORM。
• 现代：支持关系、泛型、向量化和现代 C# 特性。
• 快速：在常见操作上比 SQLite 更快，同时提供丰富的功能。
• MongoDB Atlas Device Sync：支持实时数据同步，简化跨用户、设备和后端的数据同步。

2. 项目快速启动

安装

首先，通过 NuGet 安装 Realm .NET：

dotnet add package Realm

创建数据库和对象

创建一个简单的 Realm 对象类：

public class Dog : RealmObject
{
    [PrimaryKey]
    public string Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}

初始化 Realm 数据库

在应用程序启动时初始化 Realm：

var config = new RealmConfiguration("my.realm");
var realm = Realm.GetInstance(config);

添加数据

向 Realm 数据库中添加数据：

realm.Write(() =>
{
    realm.Add(new Dog { Id = Guid.NewGuid().ToString(), Name = "Rex", Age = 5 });
});

查询数据

使用 LINQ 查询数据：

var dogs = realm.All<Dog>().Where(d => d.Age > 3);
foreach (var dog in dogs)
{
    Console.WriteLine(dog.Name);
}

3. 应用案例和最佳实践

案例1：快速日志应用

使用 Realm 创建一个简单的日志应用，记录用户的日常活动。

public class JournalEntry : RealmObject
{
    [PrimaryKey]
    public string Id { get; set; }
    public DateTimeOffset Date { get; set; }
    public string Content { get; set; }
}

// 添加日志条目
realm.Write(() =>
{
    realm.Add(new JournalEntry { Id = Guid.NewGuid().ToString(), Date = DateTimeOffset.Now, Content = "今天天气很好" });
});

// 查询日志条目
var entries = realm.All<JournalEntry>().OrderByDescending(e => e.Date);
foreach (var entry in entries)
{
    Console.WriteLine($"{entry.Date}: {entry.Content}");
}

案例2：实时同步任务列表

使用 MongoDB Atlas Device Sync 实现任务列表的实时同步。

public class Task : RealmObject
{
    [PrimaryKey]
    public string Id { get; set; }
    public string Title { get; set; }
    public bool IsCompleted { get; set; }
}

// 初始化同步配置
var syncConfig = new SyncConfiguration("your-partition-value", user, new Uri("your-realm-url"));
var syncedRealm = Realm.GetInstance(syncConfig);

// 添加任务
syncedRealm.Write(() =>
{
    syncedRealm.Add(new Task { Id = Guid.NewGuid().ToString(), Title = "完成报告", IsCompleted = false });
});

// 查询任务
var tasks = syncedRealm.All<Task>().Where(t => !t.IsCompleted);
foreach (var task in tasks)
{
    Console.WriteLine(task.Title);
}

4. 典型生态项目

Realm .NET 示例项目

• QuickJournalSync：一个 MAUI 应用示例，展示了如何集成 Realm 和 Atlas Device Sync，重点关注错误处理、连接状态变化和离线 Realm。
• AnalyticsTelemetry：一个 MAUI 应用示例，展示了如何使用 Realm 进行分析或遥测应用，结合 Atlas Device Sync 和数据摄取，并使用 MongoDB Charts 可视化数据。
• AtlasSearch：一个 MAUI 应用示例，展示了如何使用 Realm 和 Atlas Search 实现全文搜索功能。

相关资源

• 官方文档：Realm .NET 文档
• API 参考：Realm .NET API 参考
• 示例代码库：Realm .NET 示例代码库

通过这些资源，您可以深入了解 Realm .NET 的使用和最佳实践，快速上手并构建高性能的移动应用。