Ferdinando Papale

.NET Engineer on the Realm team

The latest releases of Realm .NET have included some interesting updates that we would love to share — in particular, source generated classes and support for nullability annotation. 

## Source generated classes

[Realm 10.18.0](https://github.com/realm/realm-dotnet/releases/tag/10.18.0) introduced `Realm.SourceGenerator`, a source generator that can generate Realm model classes. This is part of our ongoing effort to modernize the Realm library, and will allow us to introduce certain language level features more easily in the future.

The migration to the new source generated classes is quite straightforward. All you need to do is:

* Declare the Realm classes as `partial`, including all the eventual containing classes.
* Swap out the base Realm classes (`RealmObject`, `EmbeddedObject`, `AsymmetricObject`) for the equivalent interfaces (`IRealmObject`, `IEmbeddedObject`, `IAsymmetricObject`).
* Declare `OnManaged` and `OnPropertyChanged` methods as `partial` instead of overriding them, if they are used.

The property definition remains the same, and the source generator will take care of adding the full implementation of the interfaces. 

To give an example, if your model definition looks like this:

```csharp
public class Person: RealmObject
{
    public string Name { get; set; }  

    public PhoneNumber Phone { get; set; }

    protected override void OnManaged()
    {
        //...
    }

    protected override void OnPropertyChanged(string propertyName)
    {
        //...
    } 
}

public class PhoneNumber: EmbeddedObject
{
    public string Number { get; set; }

    public string Prefix { get; set; }  
}
```
This is how it should look like after you migrated it: 

```csharp
public partial class Person: IRealmObject
{
    public string Name { get; set; }  

    public PhoneNumber Phone { get; set; }

    partial void OnManaged()
    {
        //...
    }

    partial void OnPropertyChanged(string propertyName)
    {
        //...
    } 
}

public partial class PhoneNumber: IEmbeddedObject
{
    public string Number { get; set; }

    public string Prefix { get; set; }  
}
```
The classic Realm model definition is still supported, but it will not receive some of the new updates, such as the support for nullability annotations, and will be phased out in the future. 

## Nullability annotations

[Realm 10.20.0](https://github.com/realm/realm-dotnet/releases/tag/10.20.0) introduced full support for nullability annotations in the model definition for source generated classes. This allows you to use Realm models as usual when nullable context is active, and removes the need to use the `Required` attribute to indicate required properties, as this information will be inferred directly from the nullability status.

To sum up the expected nullability annotations:
* Value type properties, such as `int`, can be declared as before, either nullable or not.
* `string` and `byte[]` properties now cannot be decorated anymore with the `Required` attribute, as this information will be inferred from the nullability. If the property is not nullable, then it is considered equivalent as declaring it with the `Required` attribute.
* Collections (list, sets, dictionaries, and backlinks) cannot be declared nullable, but their parameters may be.
* Properties that link to a single Realm object are inherently nullable, and thus the type must be defined as nullable.
* Lists, sets, and backlinks of objects cannot contain null values, and thus the type parameter must be non-nullable.
* Dictionaries of object values can contain null, and thus the type parameter must be nullable.

Defining the properties with a different nullability annotation than what has been outlined will raise a diagnostic error. For instance:
  ```cs
public partial class Person: IRealmObject
{
    //string (same for byte[])
    public string Name { get; set; } //Correct, required property

    public string? Name { get; set; } //Correct, non-required property

    //Collections
    public IList<int> IntList { get; } //Correct

    public IList<int?> IntList { get; } //Correct

    public IList<int>? IntList { get; } //Error

    //Object 
    public Dog? MyDog { get; set; } //Correct

    public Dog MyDog { get; set; } //Error

    //List of objects
    public IList<Dog> MyDogs { get; } //Correct

    public IList<Dog?> MyDogs { get; } //Error

    //Set of objects
    public ISet<Dog> MyDogs { get; } //Correct

    public ISet<Dog?> MyDogs { get; } //Error

    //Dictionary of objects
    public IDictionary<string, Dog?> MyDogs { get; } //Correct

    public IDictionary<string, Dog> MyDogs { get; } //Error

    //Backlink
    [Realms.Backlink("...")]
    public IQueryable<Dog> MyDogs { get; } //Correct

    [Realms.Backlink("...")]
    public IQueryable<Dog?> MyDogs { get; } //Error
}
  ```

We realize that some developers would prefer to have more freedom in the nullability annotation of object properties, and it is possible to do so by setting `realm.ignore_objects_nullability = true` in a global configuration file (more information about this can be found in the [.NET documentation](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-files)). If this option is enabled, all the object properties (including collections) will be considered valid, and the nullability annotations will be ignored.

Finally, please note that this will only work with source generated classes, and not with the classic Realm model definition. If you want more information, you can take a look at the [Realm .NET repository](https://github.com/realm/realm-dotnet) and at our [documentation](https://www.mongodb.com/docs/realm/sdk/dotnet/).

Want to continue the conversation? Head over to our [community forums](https://www.mongodb.com/community/forums/)!

The latest release of Realm .NET includes interesting updates we'd love to share — particularly source generated classes and support for nullability annotation.

Source Generated Classes and Nullability in Realm .NET

Full-text search is an important feature in modern mobile applications, as it allows you to quickly and efficiently access information within large text datasets. This is fundamental for certain app categories that deal with large amounts of text documents, like news and magazines apps and chat and email applications. 

We are happy to introduce full-text search (FTS) support for Realm — a feature long requested by our developers. While traditional search with string matching returns exact occurrences, FTS returns results that contain the words from the query, but respecting word boundaries. For example, looking for the word “cat” with FTS will return only text containing exactly that word, while a traditional search will return also text containing words like “catalog” and “advocating”. Additionally, it’s also possible to specify words that should *not* be present in the result texts. Another important addition with the Realm-provided FTS is speed: As the index is created beforehand, searches on it are very fast compared to pure string matching.

In this tutorial, we are giving examples using FTS with the [.NET](https://github.com/realm/realm-dotnet) SDK, but FTS is also available in the Realm SDK for [Kotlin](https://github.com/realm/realm-kotlin), [Dart](https://github.com/realm/realm-dart), and [JS](https://github.com/realm/realm-js), and will soon be available for [Swift and Obj-C](https://github.com/realm/realm-swift). 

Later, we will show a practical example, but for now, let us take a look at what you need in order to use the new FTS search with the .NET Realm SDK:

1. Add the `[Indexed(IndexType.FullText)]` attribute on the string property to create an index for searching.
2. Running queries
    1. To run Language-Integrated Query (LINQ) queries, use `QueryMethods.FullTextSearch`. For example: `realm.All<Book>().Where(b => QueryMethods.FullTextSearch(b.Summary, "fantasy novel")`
    2. To run `Filter` queries, use the `TEXT` operator. For example: `realm.All<Book>().Filter("Summary TEXT $0", "fantasy novel");`

Additionally, words in the search phrase can be prepended with a “-” to indicate that certain words should not occur. For example: `realm.All<Book>().Where(b => QueryMethods.FullTextSearch(b.Summary, "fantasy novel -rings")`

## Search example

In this example, we will be creating a realm with book summaries indexed and searchable by the full-text search. First, we’ll create the object schema for the books and index on the summary property:

```csharp
public partial class Book : IRealmObject
{
    [PrimaryKey]
    public string Name { get; set; } = null!;

    [Indexed(IndexType.FullText)]
    public string Summary { get; set; } = null!;
}
```

Next, we’ll define a few books with summaries and add those to the realm:

```csharp
// ..
var animalFarm = new Book
{
    Name = "Animal Farm",
    Summary = "Animal Farm is a novel that tells the story of a group of farm animals who rebel against their human farmer, hoping to create a society where the animals can be equal, free, and happy. Ultimately, the rebellion is betrayed, and the farm ends up in a state as bad as it was before."
};

var lordOfTheRings = new Book
{
    Name = "Lord of the Rings",
    Summary = "The Lord of the Rings is an epic high-fantasy novel by English author and scholar J. R. R. Tolkien. Set in Middle-earth, the story began as a sequel to Tolkien's 1937 children's book The Hobbit, but eventually developed into a much larger work."
};

var lordOfTheFlies = new Book
{
    Name = "Lord of the Flies",
    Summary = "Lord of the Flies is a novel that revolves around a group of British boys who are stranded on an uninhabited island and their disastrous attempts to govern themselves."
};

var realm = Realm.GetInstance();

realm.Write(() =>
{
    realm.Add(animalFarm);
    realm.Add(lordOfTheFlies);
    realm.Add(lordOfTheRings);
});
```

And finally, we are ready for searching the summaries as follows:

```csharp
var books = realm.All<Book>();

// Returns all books with summaries containing both "novel" and "lord"
var result = books.Where(b => QueryMethods.FullTextSearch(b.Summary, "novel lord"));

// Equivalent query using `Filter`
result = books.Filter("Summary TEXT $0", "novel lord");

// Returns all books with summaries containing both "novel" and "lord", but not "rings"
result = books.Where(b => QueryMethods.FullTextSearch(b.Summary, "novel -rings"));
```

## Additional information 

A few important things to keep in mind when using full-text search:

- Only string properties are valid for an FTS index, also on embedded objects. A collection of strings cannot be indexed. 
- Indexes spanning multiple properties are not supported. For example, if you have a `Book` object, with `Name` and `Summary` properties, you cannot declare a single index that covers both, but you can have one index per property. 
- Doing an FTS lookup for a phrase across multiple properties must be done using a combination of two expressions (i.e., trying to find `red ferrari` where `red` appears in property A and `ferrari` in property B must be done with `(A TEXT 'red') AND (B TEXT 'ferrari'))`.
- FTS only supports languages that use ASCII and Latin-1 character sets (most western languages). Only sequences of (alphanumeric) characters from these sets will be tokenized and indexed. All others will be considered white space.
- Searching is case- and diacritics-insensitive, so “Garcon” matches “garçon”.

We understand there are additional features to FTS we could work to add. Please give us feedback and head over to our [community forums](https://www.mongodb.com/community/forums/)!

Learn how to add Full-Text Search (FTS) to your mobile applications using C# with Realm and MongoDB.

How to Do Full-Text Search in a Mobile App with MongoDB Realm

Shane McAllister

Lead Developer Advocacy (Global)

Nikola Irinchev

Lead Realm .Net Engineering Team

Missed Realm .NET for Xamarin (best practices and roadmap) meetup event? Don't worry, you can catch up here.

Realm .NET for Xamarin (Best Practices and Roadmap) Meetup

This article shows how to effectively use Realm in a Xamarin.Forms app using recommended patterns. 

Ferdinando Papale

Content by Ferdinando Papale

Source Generated Classes and Nullability in Realm .NET

How to Do Full-Text Search in a Mobile App with MongoDB Realm

Realm .NET for Xamarin (Best Practices and Roadmap) Meetup

How to Use Realm Effectively in a Xamarin.Forms App