快速入门 — .NET SDK
在此页面上
本快速入门演示了如何将Realm与Realm .NET SDK结合使用。 然后演示如何使用Atlas App Services将Device Sync添加到您的应用中。 开始之前，请确保您已安装.NET SDK。
安装 Realm
按照以下步骤将 .NET SDK 添加到您的项目中。
重要
为所有项目安装 SDK
如果您有多平台解决方案，请务必为所有平台项目安装 SDK，即使给定项目不包含任何 SDK 特定代码。
将 Realm Weaver 添加到 FodyWeavers.xml
注意
如果您 尚未 使用 Fody ，则可以跳过此步骤 在您的项目中。文件您FodyWeavers.xml .
如果您的项目已在使用 Fody ，您必须手动将 Realm 编织器添加到FodyWeavers.xml 文件中。完成后，您的FodyWeavers.xml文件应如下所示：
<Weavers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FodyWeavers.xsd"> <Realm /> </Weavers>
导入 Realm
将以下行添加到源文件顶部以使用 Realm：
using Realms;
定义对象模型
应用程序的对象模型定义了您可以在Realm中存储以及与Atlas App Services之间同步的数据。
重要
继承
所有 Realm 对象均会继承IRealmObject 、 IEmbeddedObject或IAsymmetricObject接口，并且必须声明为partial类。
在早于10.18.0的 .NET SDK 版本中， 派生自RealmObject 、 EmbeddedObject或AsymmetricObject基类的对象。 这种 Realm 模型定义方法仍然受支持，但不包括可空性注解等新功能。 在未来的 SDK 版本中，基类将被弃用。 您编写的任何新类都应使用接口，并应考虑迁移现有类。
以下代码展示了如何为Item对象定义对象模型。 在此示例中，我们已将Id字段标记为主键，并将Status属性标记为可选。 我们还选择使用MapTo属性；属性将以小写形式存储在服务器上，但在使用 Device Sync 时，可以对属性名称使用 .NET 友好的大小写。
public partial class Item : IRealmObject { [] [] public ObjectId Id { get; set; } = ObjectId.GenerateNewId(); [] public string Assignee { get; set; } [] public string? Name { get; set; } [] public string? Status { get; set; } }
打开本地 Realm
在仅限本地的 Realm 中，您可以使用Realm.GetInstance()或Realm.GetInstanceAsync()方法打开一个 Realm。 使用哪种方法完全取决于您是否以及如何使用 异步模式 在您的应用中。以下代码展示了如何使用GetInstance() ：
var realm = Realm.GetInstance();
有关更多信息，请参阅：打开 Realm。
创建、读取、更新和删除对象
创建或更新文档时，所有写入都必须在事务中进行。
以下代码展示了创建新 Realm 对象的两种方法。 在第一个示例中，我们首先创建对象，然后使用WriteAsync()方法将其添加到 Realm。 在第二个示例中，我们在WriteAsync区块中创建文档，该区块会返回一个可供我们进一步使用的 Realm 对象。
var testItem = new Item { Name = "Do this thing", Status = ItemStatus.Open.ToString(), Assignee = "Aimee" }; await realm.WriteAsync(() => { realm.Add(testItem); }); // Or var testItem2 = await realm.WriteAsync(() => { return realm.Add<Item>(new Item { Name = "Do this thing, too", Status = ItemStatus.InProgress.ToString(), Assignee = "Satya" }); } );
更新或插入文档与创建新文档相同，只是您将可选的update参数设置为true 。 在此示例中，我们创建一个具有唯一Id的新Item对象。 然后，我们插入一个具有相同ID但 Name 值不同的项目。 由于我们已将update参数设置为true ，因此现有记录将更新为新名称。
var id = ObjectId.GenerateNewId(); var item1 = new Item { Id = id, Name = "Defibrillate the Master Oscillator", Assignee = "Aimee" }; // Add a new person to the realm. Since nobody with the existing Id // has been added yet, this person is added. await realm.WriteAsync(() => { realm.Add(item1, update: true); }); var item2 = new Item { Id = id, Name = "Fluxify the Turbo Encabulator", Assignee = "Aimee" }; // Based on the unique Id field, we have an existing person, // but with a different name. When `update` is true, you overwrite // the original entry. await realm.WriteAsync(() => { realm.Add(item2, update: true); }); // item1 now has a Name of "Fluxify the Turbo Encabulator" // and item2 was not added as a new Item in the collection.
您还可以在WriteAsync()方法中删除项目。 以下代码演示如何从集合中删除单个Item以及如何删除整个集合：
realm.Write(() => { realm.Remove(myItem); }); realm.Write(() => { realm.RemoveAll<Item>(); });
以下页面更详细地介绍了这些主题：
查找、筛选和排序文档
Atlas SearchRealm您可以使用 LINQ 或 RQL (RQL ) 通过 查询引擎 文档。以下示例查找类型为“Item”的所有对象：
var allItems = realm.All<Item>();
您可以使用 LINQ 或 RQL 筛选结果。 此示例使用 LINQ 查找所有状态为“打开”的项目：
var openItems = realm.All<Item>() .Where(i => i.Status == "Open");
您还可以使用 LINQ 或 RQL 对结果进行排序：
var sortedItems = realm.All<Item>() .OrderBy(i => i.Status);
有关查询、筛选和排序文档的详细信息，请参阅筛选和排序数据 - .NET SDK。
注意更改
随着文档集合的变化，更新客户端应用上的数据通常很重要。 您可以使用 SubscribeForNotifications() 方法 观察域、集合或对象的更改 。
以下示例展示了如何在整个 Realm 集合上添加通知处理程序：
// Observe realm notifications. realm.RealmChanged += (sender, eventArgs) => { // The "sender" object is the realm that has changed. // "eventArgs" is reserved for future use. // ... update UI ... };
您还可以在集合和单个对象上添加通知处理程序。 有关更多信息，请参阅React变更。
添加 Device Sync（可选）
如果要跨设备同步 Realm 数据，可以配置 Atlas App Services 并启用Device Sync 。 完成此操作后，将同步添加到客户端代码中。
先决条件
同步 Realm 数据之前，您必须：
在以下代码中，我们启用了匿名身份验证，并使用ownerId作为Flexible Sync配置中的唯一字段。
初始化 App Services
要使用身份验证和同步等 App Services 功能，请使用您的App ID 访问 App Services 应用。您可在 App Services 用户界面中找到您的 App ID。
然后初始化您的应用：
app = App.Create(myRealmAppId);
将对象模型与同步结合使用
使用 Sync 时，只有在 用户界面中启用了 Sync with Development Mode Atlas App Services（与开发模式同步），才能直接在代码中定义对象模型。
注意
禁用开发模式时从用户界面获取模式
如果您已启用同步但关闭了开发模式，则可以从Atlas App Services用户界面的 SDKs 标签页复制并粘贴Atlas App Services为您生成的对象模型定义。 如果要从客户端代码更改对象模型定义，则必须重新启用开发模式。
有关更多信息，请参阅创建数据模型。
验证用户身份
在本快速入门中，我们使用匿名身份验证来登录用户，而不要求他们提供任何身份信息。 验证用户身份后，您可以为该用户打开 Realm。
var user = await app.LogInAsync(Credentials.Anonymous());
您还应该为用户提供注销方法。 以下代码演示了如何通过调用LogOutAsync()来执行此操作：
await user.LogOutAsync();
Realm .NET SDK 提供了许多其他方法来对用户进行身份验证、注册和链接。 有关其他身份验证提供程序，请参阅：对用户进行身份验证 - .NET SDK
打开同步 Realm
启用 Device Sync并对用户进行身份验证后，您可以打开 Synced Realm 。 使用 FlexibleSyncConfiguration 对象控制应用程序如何与Atlas App Services同步数据的细节。 然后，您可以添加Flexible Sync订阅，该订阅决定用户可以查询哪些数据。
var config = new FlexibleSyncConfiguration(app.CurrentUser) { PopulateInitialSubscriptions = (realm) => { var myItems = realm.All<Item>().Where(n => n.OwnerId == myUserId); realm.Subscriptions.Add(myItems); } }; // The process will complete when all the user's items have been downloaded. var realm = await Realm.GetInstanceAsync(config);
在同步 Realm 上读取、写入和监视通知的语法与上述针对非同步 Realm 的语法相同。 当您使用本地数据时，后台线程可以高效地集成、上传和下载变更集。
有关创建支持 Sync 的App Services App的信息，请参阅.NET教程。
有关在客户端代码中实现 Sync 的信息，请参阅将 Device Sync 添加到应用程序。