Dominic Frei

Who said creating a website has to be hard?

Writing the code, persisting news, hosting the website. A decade ago, this might have been a lot of work. These days, thanks to [Microsoft Blazor](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor), [Microsoft Azure App Service](https://azure.microsoft.com/en-us/products/app-service/#overview), and [MongoDB Atlas](https://www.mongodb.com/atlas/database), you can get started in minutes. And finish it equally fast!

In this tutorial, I will walk you through:

* Setting up a new Blazor project.
* Creating a new page with a simple UI.
* Creating data in MongoDB Atlas.
* Showing those news on the website.
* Making the website available by using Azure App Service to host it.

All you need is this tutorial and the following pre-requisites, but if you prefer to just read along for now, check out the [GitHub repository for this tutorial](https://github.com/mongodb-developer/crypto-news-website) where you can find the code and the tutorial.

## Pre-requisites for this tutorial

Before we get started, here is a list of everything you need while working through the tutorial. I recommend getting everything set up first so that you can seamlessly follow along.

* [Download and install the .NET framework](https://dotnet.microsoft.com/en-us/download).
  For this tutorial, I am using .NET 7.0.102 for Windows, but any .NET 6.0 or higher should do.
* [Download and install Visual Studio](https://visualstudio.microsoft.com/downloads/).
  I am using the 2022 Community edition, version 17.4.4, but any 2019 or 2022 edition will be okay. Make sure to install the `Azure development` workload as we will be deploying with this later. If you already have an installed version of Visual Studio, go into the Installer and click `modify` to find it.
* [Sign up for a free Microsoft Azure account](https://azure.microsoft.com/en-us/free/).
* [Sign up for a free MongoDB Atlas account](https://account.mongodb.com/account/register).

## Creating a new Microsoft Blazor project that will contain our crypto news website

Now that the pre-requisites are out of the way, let's start by creating a new project.

![Visual Studio Get started screen](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/01_get_started_88f36b9147.jpg)

I have recently discovered [Microsoft Blazor](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor) and I absolutely love it. Such an easy way to create websites quickly and easily. And you don't even have to write any JavaScript or PHP! Let's use it for this tutorial, as well. Search for `Blazor Server App` and click `Next`.

![Project template list in Visual Studio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/02_create_a_new_project_53da789c4c.jpg)

Choose a `Project name` and `Location` of you liking. I like to have the solution and project in the same directory but you don't have to.

![Project Configuration screen in Visual Studio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/03_configure_your_new_project_baec3276cd.jpg)

Choose your currently installed .NET framework (as described in `Pre-requisites`) and leave the rest on default.

Hit `Create` and you are good to go!

![Additional information for the project](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/04_additional_information_47949f55f7.jpg)

## Adding the MongoDB driver to the project to connect to the database

Before we start getting into the code, we need to add one NuGet package to the project: the [MongoDB driver](https://www.mongodb.com/docs/drivers/). The driver is a library that lets you easily access your [MongoDB Atlas cluster](https://www.mongodb.com/basics/clusters) and work with your database. Click on `Project` -> `Manage NuGet Packages...` and search for `MongoDB.Driver`.

![File Menu in Visual Studio](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/07_manage_nuget_packages_664b480003.jpg)

During that process, you might have to install additional components, like the ones shown in the following screenshot. Confirm this installation as we will need some of those, as well.

![Preview of the packages that are about to be installed.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/08_install_additional_components_d8a428df2c.jpg)

Another message you come across might be the following license agreements, which you need to accept to be able to work with those libraries.

![Licenses for the libraries that are about to be installed.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/09_accept_licenses_21361afe2d.jpg)

## Creating a new MongoDB Atlas cluster and database to host our crypto news

Now that we've installed the driver, let's go ahead and create a cluster and database to connect to.

When you register a new account, you will be presented with the selection of a cloud database to deploy. Open the `Advanced Configuration Options`.
For this tutorial, we only need the forever-free shared tier. Since the website will later be deployed to Azure, we also want the Atlas cluster deployed in Azure. And we also want both to reside in the same region. This way, we decrease the chance of having an additional latency as much as possible.

Here, you can choose any region. Just make sure to chose the same one later on when deploying the website to Azure. The remaining options can be left on their defaults.

![Cluster chooser for MongoDB Atlas](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/12_deploy_a_cloud_database_b499ce0e74.jpg)
![Advanced options for creating a MongoDB Atlas cluster](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/13_create_a_shared_cluster_8cdc5c9896.jpg)

The final step of creating a new cluster is to think about security measures by going through the `Security Quickstart`.

![Security Quickstart for the MongoDB Atlas cluster creation](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/30_security_quick_start_d92b651359.jpg)

Choose a `Username` and `Password` for the database user that will access this cluster during the tutorial. For the `Access List`, we need add `0.0.0.0/0` since we do not know the IP address of our Azure deployment yet. This is okay for development purposes and testing, but in production, you should restrict the access to the specific IPs accessing Atlas.

Atlas also supports the use of [network peering and private connections](https://www.mongodb.com/docs/atlas/setup-cluster-security/#optional-security-features) using the major cloud providers. This includes [Azure Private Link](https://learn.microsoft.com/azure/private-link/private-link-overview) or [Azure Virtual Private Connection](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-networks-overview) (VPC), if you are using an M10 or above cluster.

Now hit `Finish and Close`.

Creating a new shared cluster happens very, very fast and you should be able to start within minutes. As soon as the cluster is created, you'll see it in your list of `Database Deployments`.

Let's add some sample data for our website! Click on `Browse Collections` now.

![Atlas Data Services Overview](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/14_your_new_cluster_021c528d9d.jpg)

If you've never worked with Atlas before, here are some vocabularies to get your started:

- A cluster consists of multiple nodes (for redundancy).
- A cluster can contain multiple databases (which are replicated onto all nodes).
- Each database can contain many collections, which are similar to tables in a relational database.
- Each collection can then contain many documents. Think rows, just better!
- [Documents](https://www.mongodb.com/document-databases) are super-flexible because each document can have its own set of properties. They are easy to read and super flexible to work with JSON-like structures that contain our data.

## Creating some test data in Atlas

Since there is no data yet, you will see an empty list of databases and collections. Click on `Add My Own Data` to add the first entry.

![Collections overview for your Atlas cluster](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/15_collections_601bf59508.jpg)

The database name and collection name can be anything, but to be in line with the code we'll see later, call them `crypto-news-website` and `news` respectively, and hit `Create`.

![Create Database pop-up](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/16_create_database_afa2bb61d2.jpg)

This should lead to a new entry that looks like this:

![Newly created database and collection.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/17_your_new_collection_25096bc341.jpg)

Next, click on `INSERT DOCUMENT`.

There are a couple things going on here. The `_id` has already been created automatically. Each document contains one of those and they are of type `ObjectId`. It uniquely identifies the document.

By hovering over the line count on the left, you'll get a pop-op to add more fields. Add one called `title` and set its value to whatever you like. The screenshot shows an example you can use. Choose `String` as the type on the right. Next, add a `date` and choose `Date` as the type on the right.

![Inserting a new document into the collection.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/18_insert_document_c7ce90362e.jpg)

Repeat the above process a couple times to get as much example data in there as you like. You may also just continue with one entry, though, if you like, and fill up your news when you are done.

## Creating a connection string to access your MongoDB Atlas cluster

The final step within MongoDB Atlas is to actually create access to this database so that the MongoDB driver we installed into the project can connect to it. This is done by using a [connection string](https://www.mongodb.com/docs/manual/reference/connection-string/).
A connection string is a URI that contains username, password, and the host address of the database you want to connect to.

Click on `Databases` on the left to get back to the cluster overview.

This time, hit the `Connect` button and then `Connect Your Application`.
If you haven't done so already, choose a username and password for the database user accessing this cluster during the tutorial. Also, add `0.0.0.0/0` as the IP address so that the Azure deployment can access the cluster later on.

Copy the [connection string](https://www.mongodb.com/docs/manual/reference/connection-string/) that is shown in the pop-up.

![Retrieving the connection string for the cluster.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/19_connection_string_cb44991831.jpg)

## Creating a new Blazor page

If you have never used Blazor before, just hit the `Run` button and have a look at the template that has been generated. It's a great start, and we will be reusing some parts of it later on.

Let's add our own page first, though. In your Solution Explorer, you'll see a `Pages` folder. Right-click it and add a `Razor Component`. Those are files that combine the HTML of your page with C# code.

![Context menu for creating a new Razor Component](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/05_add_a_new_component_6476440c47.jpg)
![Choosing a type and name for the new component.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/06_name_the_new_component_8ecc33dea7.jpg)

Now, replace the content of the file with the following code. Explanations can be read inline in the code comments.

```csharp
@* The `page` attribute defines how this page can be opened. *@
@page "/news"

@* The `MongoDB` driver will be used to connect to your Atlas cluster. *@
@using MongoDB.Driver
@* `BSON` is a file format similar to JSON. MongoDB Atlas documents are BSON documents. *@
@using MongoDB.Bson
@* You need to add the `Data` folder as well. This is where the `News` class resides. *@
@using CryptoNewsApp.Data
@using Microsoft.AspNetCore.Builder

@* The page title is what your browser tab will be called.  *@
<PageTitle>News</PageTitle>

@* Let's add a header to the page. *@
<h1>News</h1>

@* And then some data. *@
@* This is just a simple table contains news and their date. *@
@if (_news != null)
{
    <table class="table">
        <thead>
        <tr>
            <th>News</th>
            <th>Date</th>
        </tr>
        </thead>
        <tbody>
        @* Blazor takes this data from the `_news` field that we will fill later on. *@
        @foreach (var newsEntry in _news)
        {
            <tr>
                <td>@newsEntry.Title</td>
                <td>@newsEntry.Date</td>
            </tr>
        }
        </tbody>
    </table>
}

@* This part defines the code that will be run when the page is loaded. It's basically  *@
@* what would usually be PHP in a non-Blazor environment. *@
@code {
    
    // The `_news` field will hold all our news. We will have a look at the `News`
    // class in just a moment.
    private List<News>? _news;

    // `OnInitializedAsync()` gets called when the website is loaded. Our data
    // retrieval logic has to be placed here.
    protected override async Task OnInitializedAsync()
    {
        // First, we need to create a `MongoClient` which is what we use to
        // connect to our cluster.
        // The only argument we need to pass on is the connection string you
        // retrieved from Atlas. Make sure to replace the password placeholder with your password.
        var mongoClient = new MongoClient("YOUR_CONNECTION_STRING");
        // Using the `mongoCLient` we can now access the database.
        var cryptoNewsDatabase = mongoClient.GetDatabase("crypto-news-database");
        // Having a handle to the database we can furthermore get the collection data.
        // Note that this is a generic function that takes `News` as it's parameter
        // to define who the documents in this collection look like.
        var newsCollection = cryptoNewsDatabase.GetCollection<News>("news");
        // Having access to the collection, we issue a `Find` call to find all documents.
        // A `Find` takes a filter as an argument. This filter is written as a `BsonDocument`.
        // Remember, `BSON` is really just a (binary) JSON.
        // Since we don't want to filter anything and get all the news, we pass along an
        // empty / new `BsonDocument`. The result is then transformed into a list with `ToListAsync()`.
        _news = await newsCollection.Find(new BsonDocument()).Limit(10).ToListAsync();
        // And that's it! It's as easy as that using the driver to access the data
        // in your MongoDB Atlas cluster.
    }

}
```

Above, you'll notice the `News` class, which still needs to be created.
In the `Data` folder, add a new C# class, call it `News`, and use the following code.

```csharp
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;

namespace CryptoNewsApp.Data
{
    public class News
    {
        // The attribute `BsonId` signals the MongoDB driver that this field 
        // should used to map the `_id` from the Atlas document.
        // Remember to use the type `ObjectId` here as well.
        [BsonId] public ObjectId Id { get; set; }

        // The two other fields in each news are `title` and `date`.
        // Since the C# coding style differs from the Atlas naming style, we have to map them.
        // Thankfully there is another handy attribute to achieve this: `BsonElement`.
        // It takes the document field's name and maps it to the classes field name.
        [BsonElement("title")] public String Title { get; set; }
        [BsonElement("date")] public DateTime Date { get; set; }
    }
}
```

Now it's time to look at the result. Hit `Run` again.

The website should open automatically. Just add `/news` to the URL to see your new News page.

![Local Website showing news](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/20_news_website_4689c26e69.jpg)

If you want to learn more about how to add the news page to the menu on the left, you can have a look at more of my [Blazor-specific tutorials](https://www.mongodb.com/developer/languages/csharp/microsoft-blazor-tutorial/).

## Deploying the website to Azure App Service

So far, so good. Everything is running locally. Now to the fun part: going live!

Visual Studio makes this super easy. Just click onto your project and choose `Publish...`.

![Context menu to publish the app](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/21_solution_explorer_publish_c9335f7064.jpg)

The `Target` is `Azure`, and the `Specific target` is `Azure App Service (Windows)`.

![Choosing a publishing target](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/22_publishing_target_f962875974.jpg)
![Choosing a specific target](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/23_publishing_service_73e456e549.jpg)

When you registered for Azure earlier, a free subscription should have already been created and chosen here. By clicking on `Create new` on the right, you can now create a new App Service.

![Creating a new App Service](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/24_create_new_app_service_a652f6f1c9.jpg)

The default settings are all totally fine. You can, however, choose a different region here if you want to. Finally, click `Create` and then `Finish`.

![App Service settings](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/25_app_service_settings_b1a05f9379.jpg)
![Final overview before publishing the new app](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/26_finish_service_creation_4b118a8f84.jpg)

When ready, the following pop-up should appear. By clicking `Publish`, you can start the actual publishing process. It eventually shows the result of the publish.

![Publishing summary](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/27_publish_summary_fdc1933648.jpg)
![Publishing result](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/28_publish_succeeded_0b3b26a2b3.jpg)

The above summary will also show you the URL that was created for the deployment. My example: https://cryptonewsapp20230124021236.azurewebsites.net/

Again, add `/news` to it to get to the News page.

![News website deployed on Azure App Service](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/29_published_website_eee29476a0.jpg)

## What's next?

Go ahead and add some more data. Add more fields or style the website a bit more than this default table.

The combination of using [Microsoft Azure](https://azure.microsoft.com/en-us/free/) and [MongoDB Atlas](https://account.mongodb.com/account/register) makes it super easy and fast to create websites like this one. But it is only the start. You can learn more about Azure on the [Learn platform](https://learn.microsoft.com/en-us/training/) and about Atlas on the [MongoDB University](https://learn.mongodb.com/).

And if you have any questions, please reach out to us at the [MongoDB Forums](https://www.mongodb.com/community/forums/) or tweet [@dominicfrei](https://twitter.com/dominicfrei).

This article by Dominic Frei will lead you through creating your first Microsoft Blazor server application and deploying it to Microsoft Azure.

Building a Crypto News Website in C# Using the Microsoft Azure App Service and MongoDB Atlas

This article shows how to integrate the Realm Unity SDK into your Unity game. We will cover everything you need to know to get started: installing the SDK, defining your models, and connecting the database to your GameObjects.

Persistence in Unity Using Realm

This article shows how to migrate from using a local Realm to MongoDB Realm Sync. We will cover everything you need to know to transform your game into a multiplayer experience.

Turning Your Local Game into an Online Experience with MongoDB Realm Sync


<div class="introduction">

In this video, Dominic Frei, iOS engineer on the Realm team, will
introduce you to the Realm SDK for Unity3D. He will be showing you how
to integrate and use the SDK based on a Unity example created during the
video so that you can follow along.

The video is separated into the following sections:  
-   What is Realm and where to download it?
-   Creating an example project
-   Adding Realm to your project
-   Executing simple CRUD operations
-   Recap / Summary

>
>
>Introduction to the Realm SDK for Unity3D
>
>:youtube[]{vid=8jo_S02HLkI}
>
>

For those of you who prefer to read, below we have a full transcript of
the video too. Please be aware that this is verbatim and it might not be
sufficient to understand everything without the supporting video.

>
>
>If you have questions, please head to our [developer community
>website](https://community.mongodb.com/) where the MongoDB engineers and
>the MongoDB community will help you build your next big idea with
>MongoDB.
>
>

</div>

<div class="content">

## Transcript

Hello and welcome to a new tutorial! Today we're not talking about
playing games but rather how to make them. More specifically: how to use
the Realm SDK to persist your data in Unity. I will show you where to
download Realm, how to add it to your project and how to write the
necessary code to save and load your data. Let's get started!

Realm is an open-source, cross-platform database available for many
different platforms. Since we will be working with Unity we'll be using
the Realm .NET SDK. This is not yet available through the Unity package
manager so we need to download it from the Github repository directly. I
will put a link to it into the description. When you go to Releases you
can find the latest release right on the top of the page. Within the
assets you'll find two Unity files. Make sure to choose the file that
says 'unity.bundle' and download it.

Before we actually start integrating Realm into our Unity project let's
create a small example. I'll be creating it from scratch so that you can
follow along all the way and see how easy it is to integrate Realm into
your project. We will be using the Unity Editor version 2021.2.0a10. We
need to use this alpha version because there is a bug in the current
Unity LTS version preventing Realm from working properly. I'll give it a
name and choose a 2D template for this example.

We won't be doing much in the Unity Editor itself, most of the example
will take place in code. All we need to do here is to add a Square
object. The Square will change its color when we click on it and - as
soon as we add Realm to the project - the color will be persisted to the
database and loaded again when we start the game again. The square needs
to be clickable, therefore we need to add a collider. I will choose a
'Box Collider 2D' in this case. Finally we'll add a script to the
square, call it 'Square' and open the script.

The first thing we're going to do before we actually implement the
square's behaviour is to add another class which will hold our data, the
color of our square. We'll call this 'ColorEntity'. All we need for now
are three properties for the colors red, green and blue. They will be of
type float to match the UnityEngine's color properties and we'll default
them to 0, giving us an initial black color. Back in the Square
MonoBehaviour I'll add a ColorEntity property since we'll need that in
several locations. During the Awake of the Square we'll create a new
ColorEntity instance and then set the color of the square to this newly
created ColorEntity by accessing it's SpriteRenderer and setting it's
color. When we go back to the Unity Editor and enter Play Mode we'll see
a black square.

Ok, let's add the color change. Since we added a collider to the square
we can use the OnMouseDown event to listen for mouse clicks. All we want
to do here is to assign three random values to our ColorEntity. We'll
use Random.Range and clamp it between 0 and 1. Finally we need to update
the square with these colors. To avoid duplicated code I'll grab the
line from Awake where we set the color and put it in it's own function.
Now we just call it in Awake and after every mouse click. Let's have a
look at the result.

Initially we get our default black color. And with every click the color
changes. When I stop and start again, we'll of course end up with the
initial default again since the color is not yet saved. Let's do that
next!

We go to Window, Package Manager. From here we click on the plus icon
and choose 'Add package from tarball'. Now you just have to choose the
tarball downloaded earlier. Keep in mind that Unity does not import the
package and save it within your project but uses exactly this file
wherever it is. If you move it, your project won't work anymore. I
recommend moving this file from your Downloads to the project folder
first. As soon as it is imported you should see it in the Custom section
of your package list. That's all we need to do in the Unity Editor,
let's get back to Visual Studio.

Let's start with our ColorEntity. First, we want to import the Realm
package by adding 'using Realms'. The way Realm knows which objects are
meant to be saved in the database is by subclassing 'RealmObjects'.
That's all we have to do here really. To make our life a little bit
easier though I'll also add some more things. First, we want to have a
primary key by which we can later find the object we're looking for
easily. We'll just use the 'ObjectName' for that and add an attribute on
top of it, called 'PrimaryKey'. Next we add a default initialiser to
create a new Realm object for this class and a convenience initialiser
that sets the ObjectName right away. Ok, back to our Square. We need to
import Realm here as well. Then we'll create a property for the Realm
itself. This will later let us access our database. And all we need to
do to get access to it is to instantiate it. We'll do this during awake
as well, since it only needs to be done once.

Now that we're done setting up our Realm we can go ahead and look at how
to perform some simple CRUD operations. First, we want to actually
create the object in the database. We do this by calling add. Notice
that I have put this into a block that is passed to the write function.
We need to do this to tell our Realm that we are about to change data.
If another process was changing data at the same time we could end up in
a corrupt database. The write function makes sure that every other
process is blocked from writing to the database at the time we're
performing this change.

Another thing I'd like to add is a check if the ColorEntity we just
created already exists. If so, we don't need to create it again and in
fact can't since primary keys have to be unique. We do this by asking
our Realm for the ColorEntity we're looking for, identified by it's
primary key. I'll just call it 'square' for now. Now I check if the
object could be found and only if not, we'll be creating it with exactly
the same primary key. Whenever we update the color and therefore update
the properties of our ColorEntity we change data in our database.
Therefore we also need to wrap our mouse click within a write block.
Let's see how that looks in Unity. When we start the game we still see
the initial black state. We can still randomly update the color by
clicking on the square. And when we stop and start Play Mode again, we
see the color persists now.

Let's quickly recap what we've done. We added the Realm package in Unity
and imported it in our script. We added the superclass RealmObject to
our class that's supposed to be saved. And then all we need to do is to
make sure we always start a write transaction when we're changing data.
Notice that we did not need any transaction to actually read the data
down here in the SetColor function.

Alright, that's it for this tutorial. I hope you've learned how to use
Realm in your Unity project to save and load data.

</div>

<div class="summary">

>
>
>If you have questions, please head to our [developer community
>website](https://community.mongodb.com/) where the MongoDB engineers and
>the MongoDB community will help you build your next big idea with
>MongoDB.
>
>

</div>


In this video, Dominic Frei, iOS engineer on the Realm team, will introduce you to the Realm SDK for Unity3D

Introduction to the Realm SDK for Unity3D

Persisting data is an important part of most games. Unity offers only a limited set of solutions, which means we have to look around for other options as well.

In this tutorial series, we will explore the options given to us by Unity and third-party libraries.

Saving Data in Unity3D Using PlayerPrefs

*(Part 2 of the Persistence Comparison Series)*

Persisting data is an important part of most games. Unity offers only a limited set of solutions, which means we have to look around for other options as well.

In Part 1 of this series, we explored Unity's own solution: `PlayerPrefs`. This time, we look into one of the ways we can use the underlying .NET framework by saving files. Here is an overview of the complete series:

- Part 1: [PlayerPrefs](https://www.mongodb.com/developer/how-to/saving-data-in-unity3d-using-playerprefs/)
- Part 2: Files *(this tutorial)*
- Part 3: BinaryReader and BinaryWriter *(coming soon)*
- Part 4: SQL
- Part 5: Realm Unity SDK
- Part 6: Comparison of all those options

Like Part 1, this tutorial can also be found in the https://github.com/realm/unity-examples repository on the [persistence-comparison](https://github.com/realm/unity-examples/tree/persistence-comparison) branch.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/00_project_structure_80449491b4.jpg)

Each part is sorted into a folder. The three scripts we will be looking at are in the `File` sub folder. But first, let's look at the example game itself and what we have to prepare in Unity before we can jump into the actual coding.

## Example game

*Note that if you have worked through any of the other tutorials in this series, you can skip this section since we are using the same example for all parts of the series so that it is easier to see the differences between the approaches.*

The goal of this tutorial series is to show you a quick and easy way to make some first steps in the various ways to persist data in your game.

Therefore, the example we will be using will be as simple as possible in the editor itself so that we can fully focus on the actual code we need to write.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/01_capsule_in_scene_ded3b7afd6.jpg)

A simple capsule in the scene will be used so that we can interact with a game object. We then register clicks on the capsule and persist the hit count.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/02_add_a_capsule_db40af08fb.jpg)

When you open up a clean 3D template, all you need to do is choose `GameObject` -> `3D Object` -> `Capsule`.

You can then add scripts to the capsule by activating it in the hierarchy and using `Add Component` in the inspector.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/03_add_script_866f718104.jpg)

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/04_script_name_992c707274.jpg)

The scripts we will add to this capsule showcasing the different methods will all have the same basic structure that can be found in `HitCountExample.cs`.

```cs
using UnityEngine;

/// <summary>
/// This script shows the basic structure of all other scripts.
/// </summary>
public class HitCountExample : MonoBehaviour
{
    // Keep count of the clicks.
    [SerializeField] private int hitCount; // 1

    private void Start() // 2
    {
        // Read the persisted data and set the initial hit count.
        hitCount = 0; // 3
    }

    private void OnMouseDown() // 4
    {
        // Increment the hit count on each click and save the data.
        hitCount++; // 5
    }
}
```

The first thing we need to add is a counter for the clicks on the capsule (1). Add a `[SerilizeField]` here so that you can observe it while clicking on the capsule in the Unity editor.

Whenever the game starts (2), we want to read the current hit count from the persistence and initialize `hitCount` accordingly (3). This is done in the `Start()` method that is called whenever a scene is loaded for each game object this script is attached to.

The second part to this is saving changes, which we want to do whenever we register a mouse click. The Unity message for this is `OnMouseDown()` (4). This method gets called every time the `GameObject` that this script is attached to is clicked (with a left mouse click). In this case, we increment the `hitCount` (5) which will eventually be saved by the various options shown in this tutorials series.

## File

(See `FileExampleSimple.cs` in the repository for the finished version.)

One of the ways the .NET framework offers us to save data is using the [`File` class](https://docs.microsoft.com/en-us/dotnet/api/system.io.file?view=net-5.0):

> Provides static methods for the creation, copying, deletion, moving, and opening of a single file, and aids in the creation of FileStream objects.

Besides that, the `File` class is also used to manipulate the file itself, reading and writing data. On top of that, it offers ways to read meta data of a file, like time of creation.

When working with a file, you can also make use of several options to change `FileMode` or `FileAccess.`

The `FileStream` mentioned in the documentation is another approach to work with those files, providing additional options. In this tutorial, we will just use the plain `File` class.

Let's have a look at what we have to change in the example presented in the previous section to save the data using `File`:

```cs
using System;
using System.IO;
using UnityEngine;

public class FileExampleSimple : MonoBehaviour
{
    // Resources:
    // https://docs.microsoft.com/en-us/dotnet/api/system.io.file?view=net-5.0

    [SerializeField] private int hitCount = 0;

    private const string HitCountFile = "hitCountFile.txt";

    private void Start()
    {
        if (File.Exists(HitCountFile))
        {
            var fileContent = File.ReadAllText(HitCountFile);
            hitCount = Int32.Parse(fileContent);
        }
    }

    private void OnMouseDown()
    {
        hitCount++;

        // The easiest way when working with Files is to use them directly.
        // This writes all input at once and overwrites a file if executed again.
        // The File is opened and closed right away.
        File.WriteAllText(HitCountFile, hitCount.ToString());
    }

}
```

First we define a name for the file that will hold the data (1). If no additional path is provided, the file will just be saved in the project folder when running the game in the Unity editor or the game folder when running a build. This is fine for the example.

Whenever we click on the capsule (2) and increment the hit count (3), we need to save that change. Using `File.WriteAllText()` (4), the file will be opened, data will be saved, and it will be closed right away. Besides the file name, this function expects the contents as a string. Therefore, we have to transform the `hitCount` by calling `ToString()` before passing it on.

The next time we start the game (5), we want to load the previously saved data. First we check if the file already exists (6). If it does not exist, we never saved before and can just keep the default value for `hitCount`. If the file exists, we use `ReadAllText()` to get that data (7). Since this is a string again, we need to convert here as well using `Int32.Parse()` (8). Note that this means we have to be sure about what we read. If the structure of the file changes or the player edits it, this might lead to problems during the parsing of the file.

Let's look into extending this simple example in the next section.

## Extended example

(See `FileExampleExtended.cs` in the repository for the finished version.)

The previous section showed the most simple example, using just one variable that needs to be saved. What if we want to save more than that?

Depending on what needs to saved, there are several different approaches. You could use multiple files or you can write multiple lines inside the same file. The latter shall be shown in this section by extending the game to recognize modifier keys. We want to detect normal clicks, Shift+Click, and Control+Click.

First, update the hit counts so that we can save three of them:

```cs
[SerializeField] private int hitCountUnmodified = 0;
[SerializeField] private int hitCountShift = 0;
[SerializeField] private int hitCountControl = 0;
```

We also want to use a different file name so we can look at both versions next to each other:

```cs
private const string HitCountFileUnmodified = "hitCountFileExtended.txt";
```

The last field we need to define is the key that is pressed:

```cs
private KeyCode modifier = default;
```

The first thing we need to do is check if a key was pressed and which key it was. Unity offers an easy way to achieve this using the [`Input`](https://docs.unity3d.com/ScriptReference/Input.html) class's `GetKey` function. It checks if the given key was pressed or not. You can pass in the string for the key or to be a bit more safe, just use the `KeyCode` enum. We cannot use this in the `OnMouseClick()` when detecting the mouse click though:

> Note: Input flags are not reset until Update. You should make all the Input calls in the Update Loop.

Add a new method called `Update()` (1) which is called in every frame. Here we need to check if the `Shift` or `Control` key was pressed (2) and if so, save the corresponding key in `modifier` (3). In case none of those keys was pressed (4), we consider it unmodified and reset `modifier` to its `default` (5).

```cs
private void Update() // 1
{
    // Check if a key was pressed.
    if (Input.GetKey(KeyCode.LeftShift)) // 2
    {
        // Set the LeftShift key.
        modifier = KeyCode.LeftShift; // 3
    }
    else if (Input.GetKey(KeyCode.LeftControl)) // 2
    {
        // Set the LeftControl key.
        modifier = KeyCode.LeftControl; // 3
    }
    else // 4
    {
        // In any other case reset to default and consider it unmodified.
        modifier = default; // 5
    }
}
```

Now to saving the data when a click happens:

```cs
private void OnMouseDown() // 6
{
    // Check if a key was pressed.
    switch (modifier)
    {
        case KeyCode.LeftShift: // 7
            // Increment the Shift hit count.
            hitCountShift++; // 8
            break;
        case KeyCode.LeftCommand: // 7
            // Increment the Control hit count.
            hitCountControl++; // 8
            break;
        default: // 9
            // If neither Shift nor Control was held, we increment the unmodified hit count.
            hitCountUnmodified++; // 10
            break;
    }

    // 11
    // Create a string array with the three hit counts.
    string[] stringArray = {
        hitCountUnmodified.ToString(),
        hitCountShift.ToString(),
        hitCountControl.ToString()
    };

    // 12
    // Save the entries, line by line.
    File.WriteAllLines(HitCountFileUnmodified, stringArray);
}
```

Whenever a mouse click is detected on the capsule (6), we can then perform a similar check to what happened in `Update()`, only we use `modifier` instead of `Input.GetKey()` here.

Check if `modifier` was set to `KeyCode.LeftShift` or `KeyCode.LeftControl` (7) and if so, increment the corresponding hit count (8). If no modifier was used (9), increment the `hitCountUnmodified`.

As seen in the last section, we need to create a string that can be saved in the file. There is a second function on `File` that accepts a string array and then saves each entry in one line: `WriteAllLines()`.

Knowing this, we create an array containing the three hit counts (11) and pass this one on to `File.WriteAllLines()`.

Start the game, and click the capsule using Shift and Control. You should see the three counters in the Inspector.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/07_hit_count_extended_editor_dc35120d75.jpg)

After stopping the game and therefore saving the data, a new file `hitCountFileExtended.txt` should exist in your project folder. Have a look at it. It should look something like this:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/08_hit_count_extended_file_da0c062a3e.jpg)

Last but not least, let's look at how to load the file again when starting the game:

```cs
private void Start()
{
    // 12
    // Check if the file exists. If not, we never saved before.
    if (File.Exists(HitCountFileUnmodified))
    {
        // 13
        // Read all lines.
        string[] textFileWriteAllLines = File.ReadAllLines(HitCountFileUnmodified);

        // 14
        // For this extended example we would expect to find three lines, one per counter.
        if (textFileWriteAllLines.Length == 3)
        {
            // 15
            // Set the counters correspdoning to the entries in the array.
            hitCountUnmodified = Int32.Parse(textFileWriteAllLines[0]);
            hitCountShift = Int32.Parse(textFileWriteAllLines[1]);
            hitCountControl = Int32.Parse(textFileWriteAllLines[2]);
        }
    }
}
```

First, we check if the file even exists (12). If we ever saved data before, this should be the case. If it exists, we read the data. Similar to writing with `WriteAllLines()`, we use `ReadAllLines` (13) to create a string array where each entry represents one line in the file.

We do expect there to be three lines, so we should expect the string array to have three entries (14).

Using this knowledge, we can then assign the three entries from the array to the corresponding hit counts (15).

As long as all the data saved to those lines belongs together, the file can be one option. If you have several different properties, you might create multiple files. Alternatively, you can save all the data into the same file using a bit of structure. Note, though, that the numbers will not be associated with the properties. If the structure of the object changes, we would need to migrate the file as well and take this into account the next time we open and read the file.

Another possible approach to structuring your data will be shown in the next section using JSON.

## More complex data

(See `FileExampleJson.cs` in the repository for the finished version.)

JSON is a very common approach when saving structured data. It's easy to use and there are frameworks for almost every language. The .NET framework provides a [`JsonSerializer`](https://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonserializer?view=net-6.0). Unity has its own version of it: [`JsonUtility`](https://docs.unity3d.com/ScriptReference/JsonUtility.html).

As you can see in the documentation, the functionality boils down to these three methods:

- *FromJson*: Create an object from its JSON representation.
- *FromJsonOverwrite*: Overwrite data in an object by reading from its JSON representation.
- *ToJson*: Generate a JSON representation of the public fields of an object.

The `JsonUtility` transforms JSON into objects and back. Therefore, our first change to the previous section is to define such an object with public fields:

```cs
private class HitCount
{
    public int Unmodified;
    public int Shift;
    public int Control;
}
```

The class itself can be `private` and just be added inside the `FileExampleJson` class, but its fields need to be public.

As before, we use a different file to save this data. Update the filename to:

```cs
private const string HitCountFileJson = "hitCountFileJson.txt";
```

When saving the data, we will use the same `Update()` method as before to detect which key was pressed.

The first part of `OnMouseDown()` (1) can stay the same as well, since this part only increments the hit count in depending on the modifier used.

```cs
private void OnMouseDown()
{
    // 1
    // Check if a key was pressed.
    switch (modifier)
    {
        case KeyCode.LeftShift:
            // Increment the Shift hit count.
            hitCountShift++;
            break;
        case KeyCode.LeftCommand:
            // Increment the Control hit count.
            hitCountControl++;
            break;
        default:
            // If neither Shift nor Control was held, we increment the unmodified hit count.
            hitCountUnmodified++;
            break;
    }

    // 2
    // Create a new HitCount object to hold this data.
    var updatedCount = new HitCount
    {
        Unmodified = hitCountUnmodified,
        Shift = hitCountShift,
        Control = hitCountControl,
    };

    // 3
    // Create a JSON using the HitCount object.
    var jsonString = JsonUtility.ToJson(updatedCount, true);

    // 4
    // Save the json to the file.
    File.WriteAllText(HitCountFileJson, jsonString);
}
```

However, we need to update the second part. Instead of a string array, we create a new `HitCount` object and set the three public fields to the values of the hit counters (2).

Using `JsonUtility.ToJson()`, we can transform this object to a string (3). If you pass in `true` for the second, optional parameter, `prettyPrint`, the string will be formatted in a nicely readable way.

Finally, as in `FileExampleSimple.cs`, we just use `WriteAllText()` since we're only saving one string, not an array (4).

Then, when the game starts, we need to read the data back into the hit count:

```cs
private void Start()
{
    // Check if the file exists to avoid errors when opening a non-existing file.
    if (File.Exists(HitCountFileJson)) // 5
    {
        // 6
        var jsonString = File.ReadAllText(HitCountFileJson);
        var hitCount = JsonUtility.FromJson<HitCount>(jsonString);

        // 7
        if (hitCount != null)
        {
            // 8
            hitCountUnmodified = hitCount.Unmodified;
            hitCountShift = hitCount.Shift;
            hitCountControl = hitCount.Control;
        }
    }
}
```

We check if the file exists first (5). In case it does, we saved data before and can proceed reading it.

Using `ReadAllText`, we read the string from the file and transform it via `JsonUtility.FromJson<>()` into an object of type `HitCount` (6).

If this happened successfully (7), we can then assign the three properties to their corresponding hit count (8).

When you run the game, you will see that in the editor, it looks identical to the previous section since we are using the same three counters. If you open the file `hitCountFileJson.txt`, you should then see the three counters in a nicely formatted JSON.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/09_hit_count_extended_json_66a1e47fd6.jpg)

Note that the data is saved in plain text. In a future tutorial, we will look at encryption and how to improve safety of your data.

## Conclusion

In this tutorial, we learned how to utilize `File` to save data. `JsonUtility` helps structure this data. They are simple and easy to use, and not much code is required.

What are the downsides, though?

First of all, we open, write to, and save the file every single time the capsule is clicked. While not a problem in this case and certainly applicable for some games, this will not perform very well when many save operations are made.

Also, the data is saved in plain text and can easily be edited by the player.

The more complex your data is, the more complex it will be to actually maintain this approach. What if the structure of the `HitCount` object changes? You have to change account for that when loading an older version of the JSON. Migrations are necessary.

In the following tutorials, we will (among other things) have a look at how databases can make this job a lot easier and take care of the problems we face here.

Please provide feedback and ask any questions in the [Realm Community Forum](https://www.mongodb.com/community/forums/tags/c/realm/realm-sdks/58/unity).

Persisting data is an important part of most games. Unity offers only a limited set of solutions, which means we have to look around for other options as well. In this tutorial series, we will explore the options given to us by Unity and third-party libraries.

Saving Data in Unity3D Using Files

Saving Data in Unity3D Using BinaryReader and BinaryWriter

Saving Data in Unity3D Using SQLite

Have you ever built an application that consisted of multiple different systems that you had to observe and make sure they run properly? Some services might offer to send notifications, like [MongoDB Atlas](https://www.mongodb.com/atlas) or Microsoft Azure App Service. They might not always offer all the channels you want to use, though, like Slack or Discord. One of the many approaches to always keep track of all the system statuses is to create a status page that lets you see an overview of all systems at once.

This is what this tutorial will be dedicated to. There are several parts to it, each of them being its own small lesson on a specific topic. Go ahead and jump into the one you are interested in. They are more or less independent of each other.

The series consists of the following parts:
- Part 1: Introduction to Blazor: Creating a simple web page *(this tutorial)*
- Part 2: Retrieve data from MongoDB Atlas *(coming soon)*
- Part 3: Retrieve status from healthchecks.io
- Part 4: Retrieve status from sentry.io
- Part 5: Retrieve status from MongoDB Atlas
- Part 6: Retrieve status from Microsoft Azure App Service
- Part 7: Retrieve status from Amazon Web Services

In this first part, we will have a look at Blazor, how to create a new Blazor app, and creating a new page and a very simple, static status page. Each successive part will then be dedicated to making the status page more dynamic step by step and actually retrieving the data that we need.

## Prerequisites

Before we can actually begin, let's point out what you should take care of before starting with the tutorial.

For this part specifically, we need to:
- [Download and install the .NET SDK](https://dotnet.microsoft.com/en-us/download)
- Download and Install an IDE of your choice, like [Microsoft Visual Studio](https://visualstudio.microsoft.com/downloads/) or [JetBrains Rider](https://www.jetbrains.com/rider/download/#section=windows)

Note that I am using Rider for this tutorial. If you use Visual Studio or another IDE, some terms might be slightly different or menus might be in a different location.

## The architecture of our Blazor application

The architecture of the final result is not overly complicated but to give you a quick overview right at the start, let's look into all the components involved.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/architecture_grey_b7c2967a65.svg)

The status page and its services will be built using Blazor. The deployment will then be done using the Microsoft Azure App Service, which hosts the status page on Azure.

The status page retrieves the information about the systems we are interested in via MongoDB Atlas.

Each status is checked by an independent microservice that could theoretically be deployed individually. For the sake of making this tutorial as easy to understand as possible and focusing on the important bits, we will keep everything in one Blazor app for now.

## Create a new Blazor project

Let's start by creating a new project! The Blazor Server app template already contains a good basic structure that we can reuse to create our status page on top of it and also learn the basics of using Blazor at the same time. Great, isn't it?

Depending on your IDE of choice, you want to choose `Blazor Server App` ([Microsoft Visual Studio 2022](https://dotnet.microsoft.com/en-us/learn/aspnet/blazor-tutorial/create) or `ASP.NET Core Web Application` (JetBrain Rider—as can be seen in the screenshot).

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/create_project_wizard_12da42dfd7.png)

Alternatively, if you prefer to work with the terminal, create a new Blazor Server app by calling:
```bash
dotnet new blazorserver -o StatusPage
```

In this tutorial, we will work with JetBrains Rider, but all three of those options will create the same project structure.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/project_structure_d0e67cd6ef.png)

Before we actually change anything, go ahead and run the app to get an idea of what we start with.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/run_8df5288d08.png)

The result should look something like this:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/hello_world_b8a252a452.png)

## Set up the UI for the status page

If you have successfully started and seen the `Hello, world!` template example, you're ready to start creating the actual status page.

Let's first create a simple yet information-packed page that will later on hold all we need on one single page.

Since this tutorial focuses on the backend side of things, we will not spend too much time with the UI. In fact, the template already provides something similar to what we are looking for and you can use it as a reference if your HTML is as rusty as mine!

Have a look at the `Fetch data` page of the template:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/fetch_data_5b04427b91.png)

Let's start by adding a new `Razor Page` to our `Pages`:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/add_a_new_blazor_component_ac49df58f6.png)

Call the new page `Status` and choose the type `Page`:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/name_new_page_8c10d32bcf.png)

The newly created file will contain a couple things.
The keyword `@page` let's Blazor know which link to generate to actually access the page.
If you restart your app (or hot reload), you can now access `https://localhost:7042/status`.

Blazor automatically added the title as an h3 tag into the file as well along with a code block that needs to be filled out by us.

Another convenient feature is that the menu bar is automatically embedded. The new page is missing, though.

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/empty_status_page_510f5e6c7e.png)

When the project was created, the file `Shared/NavMenu.razor` was added as well.
If you jump into it, you will see the three menu items `Home`, `Counter`, and `Fetch data`, each in their own div element containing a `NavLink`.

All we need to do here is add another link within the `nav` block:

```html
<div class="nav-item px-3">
    <NavLink class="nav-link" href="status">
        <span class="oi oi-list-rich" aria-hidden="true"></span> Status Page
    </NavLink>
</div>
```

The file should then look like this:

```html
<div class="top-row ps-3 navbar navbar-dark">
    <div class="container-fluid">
        <a class="navbar-brand" href="">StatusPage</a>
        <button title="Navigation menu" class="navbar-toggler" @onclick="ToggleNavMenu">
            <span class="navbar-toggler-icon"></span>
        </button>
    </div>
</div>

<div class="@NavMenuCssClass" @onclick="ToggleNavMenu">
    <nav class="flex-column">
        <div class="nav-item px-3">
            <NavLink class="nav-link" href="" Match="NavLinkMatch.All">
                <span class="oi oi-home" aria-hidden="true"></span> Home
            </NavLink>
        </div>
        <div class="nav-item px-3">
            <NavLink class="nav-link" href="counter">
                <span class="oi oi-plus" aria-hidden="true"></span> Counter
            </NavLink>
        </div>
        <div class="nav-item px-3">
            <NavLink class="nav-link" href="fetchdata">
                <span class="oi oi-list-rich" aria-hidden="true"></span> Fetch data
            </NavLink>
        </div>
        <div class="nav-item px-3">
            <NavLink class="nav-link" href="status">
                <span class="oi oi-list-rich" aria-hidden="true"></span> Status Page
            </NavLink>
        </div>
    </nav>
</div>

@code {
    private bool collapseNavMenu = true;

    private string? NavMenuCssClass => collapseNavMenu ? "collapse" : null;

    private void ToggleNavMenu()
    {
        collapseNavMenu = !collapseNavMenu;
    }

}
```

Now let’s continue on to the final step: the actual content of the status page. As mentioned before, a simple table like in `Fetch data` will do for this tutorial. To create a table with some stub data in the structure we need later, add the following code just below the h3 tag in `Status.razor`:

```html
<table class="table">
    <thead>
    <tr>
        <th>Server Name</th>
        <th>Healthchecks.io Status</th>
        <th>Sentry.io Issue Count</th>
        <th>Azure Status</th>
        <th>AWS Status</th>
        <th>Atlas Status</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td class="td">Production</td>
        <td class="td">success</td>
        <td class="td">3</td>
        <td class="td">success</td>
        <td class="td">fail</td>
        <td class="td">success</td>
    </tr>
    </tbody>
</table>
```

Here’s our final (mocked) status page for this tutorial:

![](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mocked_status_page_e1d6976d2d.png)

## Your turn!

While this was just a first step in creating the status page, we've got our first layer done: the UI!

Now it's time for you to head over to [Github](https://github.com/mongodb-developer/status-page-blazor-server-app), download the code for this tutorial, and play around with it. Kudos if you've coded along right away! Change the look of the status page, add more pages, or head over to the [Blazor documentation](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor) to find out even more about it.

If you have any questions at any point, please tweet [@dominicfrei](https://twitter.com/dominicfrei) or come visit us in the [MongoDB Developer Community Forums](https://www.mongodb.com/community/forums/)!

This tutorial series leads you through creating your first Microsoft Blazor app by setting up a Status Page for backend services.

Microsoft Blazor Tutorial (1/5): Building a Status Page

<b>(Part 5 of the Persistence Comparison Series)</b>

We started this tutorial series by looking at Unity and .NET native ways to persist data, like `PlayerPrefs`, `File`, and the `BinaryReader` / `BinaryWriter`. In the previous part, we then continued on to external libraries and with that, databases. We looked at ``SQLite` as one example.

This time, we will look at another database. One that makes it very easy and intuitive to work with data: the [Realm Unity SDK](https://www.mongodb.com/docs/realm/sdk/dotnet/unity/).

First, here is an overview over the complete series:

- Part 1: [PlayerPrefs](https://github.com/realm/unity-examples/tree/persistence-comparison/tutorials/persistance-comparison-series/PlayerPrefs)
- Part 2: [Files](https://github.com/realm/unity-examples/blob/persistence-comparison/tutorials/persistance-comparison-series/File/file.md)
- Part 3: [BinaryReader and BinaryWriter](https://github.com/realm/unity-examples/blob/persistence-comparison/tutorials/persistance-comparison-series/BinaryWriterReader/binary_reader_writer.md)
- Part 4: [SQLite](https://github.com/realm/unity-examples/blob/persistence-comparison/tutorials/persistance-comparison-series/Sqlite/sqlite.md)
- Part 5: Realm Unity SDK *(this tutorial)*

Similar to the previous parts, this tutorial can also be found in our [Unity examples repository](https://github.com/realm/unity-examples) on the [persistence-comparison](https://github.com/realm/unity-examples/tree/persistence-comparison) branch.

![Project Structure](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/00_project_structure_a5b40f5fa3.png)

Each part is sorted into a folder. The four scripts we will be looking at in this tutorial are in the `Realm` sub folder. But first, let's look at the example game itself and what we have to prepare in Unity before we can jump into the actual coding.

## Example game

*Note that if you have worked through any of the other tutorials in this series, you can skip this section since we're using the same example for all parts of the series, so that it's easier to see the differences between the approaches.*

The goal of this tutorial series is to show you a quick and easy way to make some first steps in the various ways to persist data in your game.

Therefore, the example we'll be using will be as simple as possible in the editor itself so that we can fully focus on the actual code we need to write.

![Capsule in scene](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/01_capsule_in_scene_4e2e6ea232.jpg)

A simple capsule in the scene will be used so that we can interact with a game object. We then register clicks on the capsule and persist the hit count.

![Add a capsule](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/02_add_a_capsule_4cb724c525.jpg)

When you open up a clean 3D template, all you need to do is choose `GameObject` -> `3D Object` -> `Capsule`.

You can then add scripts to the capsule by activating it in the hierarchy and using `Add Component` in the inspector.

![Add script](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/03_add_script_1781ab5d39.jpg)
![Script name](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/04_script_name_ea706e2de6.jpg)

The scripts we will add to this capsule showcasing the different methods will all have the same basic structure that can be found in `HitCountExample.cs`.

```cs
using UnityEngine;

/// <summary>
/// This script shows the basic structure of all other scripts.
/// </summary>
public class HitCountExample : MonoBehaviour
{
    // Keep count of the clicks.
    [SerializeField] private int hitCount; // 1

    private void Start() // 2
    {
        // Read the persisted data and set the initial hit count.
        hitCount = 0; // 3
    }

    private void OnMouseDown() // 4
    {
        // Increment the hit count on each click and save the data.
        hitCount++; // 5
    }
}
```

The first thing we need to add is a counter for the clicks on the capsule (1). Add a `[SerilizeField]` here so that you can observe it while clicking on the capsule in the Unity editor.

Whenever the game starts (2), we want to read the current hit count from the persistence and initialize `hitCount` accordingly (3). This is done in the `Start()` method that is called whenever a scene is loaded for each game object this script is attached to.

The second part to this is saving changes, which we want to do whenever we register a mouse click. The Unity message for this is `OnMouseDown()` (4). This method gets called every time the `GameObject` that this script is attached to is clicked (with a left mouse click). In this case, we increment the `hitCount` (5) which will eventually be saved by the various options shown in this tutorial series.

## Realm

(See `HitCount.cs` and ``RealmExampleSimple.cs` in the repository for the finished version.)

Now that you have seen the example and the increasing hit counter, the next step will be to actually persist it so that it's available the next time we start the game.

As described in the [documentation](https://www.mongodb.com/docs/realm/sdk/dotnet/unity/), you can install Realm in two different ways:

- Install with NPM
- Manually Install a Tarball

Let's choose option #1 for this tutorial. The first thing we need to do is to import the Realm framework into Unity using the project settings.

Go to `Windows` → `Package Manager` → cogwheel in the top right corner → `Advanced Project Settings`:

![Package Manager](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/05_package_manager_1ffa6cb8e0.jpg)

Within the `Scoped Registries`, you can add the `Name`, `URL`, and `Scope` as follows:

![Project Settings](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/06_project_settings_a3507713f0.jpg)

This adds `NPM` as a source for libraries. The final step is to tell the project which dependencies to actually integrate into the project. This is done in the `manifest.json` file which is located in the `Packages` folder of your project.

Here you need to add the following line to the `dependencies`:

```json
"io.realm.unity": "<version-number>"
```

Replace `<version-number>` with the most recent Realm version found in https://github.com/realm/realm-dotnet/releases and you're all set.

The final `manifest.json` should look something like this:

```json
{
 "dependencies": {
   ...
   "io.realm.unity": "10.13.0"
 },
 "scopedRegistries": [
   {
     "name": "NPM",
     "url": "https://registry.npmjs.org/",
     "scopes": [
       "io.realm.unity"
     ]
   }
 ]
}
```

When you switch back to Unity, it will reload the dependencies. If you then open the `Package Manager` again, you should see `Realm` as a new entry in the list on the left:

![Realm in Project Manager](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/07_realm_in_project_manager_32f162d7d7.jpg)

We can now start using Realm in our Unity project.

Similar to other databases, we need to start by telling the Realm SDK how our database structure is supposed to look like. We have seen this in the previous tutorial with SQL, where we had to define tables and column for each class we want to save.

With Realm, this is a lot easier. We can just define in our code by adding some additional information to let know Realm how to read that code.

Look at the following definition of `HitCount`. You will notice that the super class for this one is `RealmObject` (1). When starting your game, Realm will automatically look for all sub classes of `RealmObject` and know that it needs to be prepared to persist this kind of data. This is all you need to do to get started when defining a new class. One additional thing we will do here, though, is to define which of the properties is the primary key. We will see why later. Do this by adding the attribute `PrimaryKey` to the `Id` property (2).

```cs
using Realms;

public class HitCount: RealmObject // 1
{
    [PrimaryKey] // 2
    public int Id { get; set; }
    public int Value { get; set; }

    private HitCount() { }

    public HitCount(int id)
    {
        Id = id;
    }
}
```

With our data structure defined, we can now look at what we have to do to elevate our example game so that it persists data using Realm. Starting with the `HitCountExample.cs` as the blueprint, we create a new file `RealmExampleSimple.cs`:

```cs
using UnityEngine;

public class RealmExampleSimple : MonoBehaviour
{
    [SerializeField] private int hitCount;

    private void Start()
    {
        hitCount = 0;
    }

    private void OnMouseDown()
    {
        hitCount++;
    }
}
```

First, we'll add two more fields — `realm` and `hitCount` — and rename the `SerializeField` to `hitCounter` to avoid any name conflicts:

```cs
[SerializeField] private int hitCounter = 0;

private Realm realm;
private HitCount hitCount;
```

Those two additional fields will let us make sure we reuse the same realm for load and save. The same holds true for the `HitCount` object we need to create when starting the scene. To do this, substitute the `Start()` method with the following:

```cs
void Start()
{
    realm = Realm.GetInstance(); // 1

    hitCount = realm.Find<HitCount>(1); // 2
    if (hitCount != null) // 3
    {
        hitCounter = hitCount.Value;
    }
    else // 4
    {
        hitCount = new HitCount(1); // 5
        realm.Write(() =>  // 6
        {
            realm.Add(hitCount);
        });
    }
}
```

A new Realm is created by calling `Realm.GetInstance()` (1). We can then use this `realm` object to handle all operations we need in this example. Start by searching for an already existing `HitCount` object. `Realm` offers a `Find<>` function (2) that let's you search for a specific class that was defined before. Additionally, we can pass long a primary key we want to look for. For this simple example, we will only ever need one `HitCount` object and will just assign the primary key `1` for it and also search for this one here.

There are two situations that can happen: If the game has been started before, the realm will return a `hitCount` object and we can use that to load the initial state of the `hitCounter` (3) using the `hitCount.Value`. The other possibility is that the game has not been started before and we need to create the `HitCount` object (4). To create a new object in Realm, you first create it the same way you would create any other object in C# (5). Then we need to add this object to the database. Whenever changes are made to the realm, we need to wrap these changes into a write block to make sure we're prevented from conflicting with other changes that might be going on — for example, on a different thread (6).

Whenever the capsule is clicked, the `hitCounter` gets incremented in `OnMouseDown()`. Here we need to add the change to the database, as well:

```cs
private void OnMouseDown()
{
    hitCounter++;

    realm.Write(() => // 8
    {
        hitCount.Value = hitCounter; // 7
    });
}
```

Within `Start()`, we made sure to create a new `hitCount` object that can be used to load and save changes. So all we need to do here is to update the `Value` with the new `hitCounter` value (7). Note, as before, we need to wrap this change into a `Write` block to guarantee data safety.

This is all you need to do for your first game using Realm. Easy, isn't it?

Run it and try it out! Then we will look into how to extend this a little bit.

## Extended example

(See `HitCountExtended.cs` and ``RealmExampleExtended.cs` in the repository for the finished version.)

To make it easy to compare with the other parts of the series, all we will do in this section is add the key modifiers and save the three different versions:

- Unmodified
- Shift
- Control

As you will see in a moment, this small change is almost too simple to create a whole section around it, but it will also show you how easy it is to work with Realm as you go along in your project.

First, let's create a new `HitCountExtended.cs` so that we can keep and look at both strucutres side by side:

```cs
using Realms;

public class HitCountExtended : RealmObject
{
    [PrimaryKey]
    public int Id { get; set; }
    public int Unmodified { get; set; } // 1
    public int Shift { get; set; } // 2
    public int Control { get; set; } // 3

    private HitCountExtended() { }

    public HitCountExtended(int id)
    {
        Id = id;
    }
}
```

Compared to the `HitCount.cs`, we've renamed `Value` to `Unmodified` (1) and added `Shift` (2) as well as `Control` (3). That's all we need to do in the entity that will hold our data. How do we need to adjust the `MonoBehaviour`?

First, we'll update the outlets to the Unity editor (the `SerializeFields`) by replacing `hitCounter` with those three similar to the previous tutorials:

```cs
[SerializeField] private int hitCountUnmodified = 0;
[SerializeField] private int hitCountShift = 0;
[SerializeField] private int hitCountControl = 0;
```

Equally, we add a `KeyCode` field and use the `HitCountExtended` instead of the `HitCount`:

```cs
private KeyCode modifier = default;
private Realm realm;
private HitCountExtended hitCount;
```

Let's first adjust the loading of the data. Instead of searching for a `HitCount`, we now search for a `HitCountExtended`:

```cs
hitCount = realm.Find<HitCountExtended>(1);
```

If it was found, we extract the three values and set it to the corresponding hit counters to visualize them in the Unity Editor:

```cs
if (hitCount != null)
{
    hitCountUnmodified = hitCount.Unmodified;
    hitCountShift = hitCount.Shift;
    hitCountControl = hitCount.Control;
}
```

If no object was created yet, we will go ahead and create a new one like we did in the simple example:

```cs
else
{
    hitCount = new HitCountExtended(1);
    realm.Write(() =>
    {
        realm.Add(hitCount);
    });
}
```

If you have worked through the previous tutorials, you've seen the `Update()` function already. It will be same for this tutorial as well since all it does it detect whichever key modifier is clicked, independent of the way we later on save that modifier:

```cs
private void Update()
{
    // Check if a key was pressed.
    if (Input.GetKey(KeyCode.LeftShift)) // 1
    {
        // Set the LeftShift key.
        modifier = KeyCode.LeftShift;
    }
    else if (Input.GetKey(KeyCode.LeftControl)) // 2
    {
        // Set the LeftControl key.
        modifier = KeyCode.LeftControl;
    }
    else
    {
        // In any other case reset to default and consider it unmodified.
        modifier = default; // 3
    }
}
```

The important bits here are the check for `LeftShift` and `LeftControl` which exist in the enum `KeyCode` (1+2). To check if one of those keys is pressed in the current frame (remember, `Update()` is called once per frame), we use `Input.GetKey()` (1+2) and pass in the key we're interested in. If none of those two keys is pressed, we use the `Unmodified` version, which is just `default` in this case (3).

The final part that has to be adjusted is the mouse click that increments the counter. Depending on the `modifier` that was clicked, we increase the corresponding `hitCount` like so:

```cs
switch (modifier)
{
    case KeyCode.LeftShift:
        hitCountShift++;
        break;
    case KeyCode.LeftControl:
        hitCountControl++;
        break;
    default:
        hitCountUnmodified++;
        break;
}
```

After we've done this, we once again update the realm like we did in the simple example, this time updating all three fields in the `HitCountExtended`:

```cs
realm.Write(() =>
{
    hitCount.Unmodified = hitCountUnmodified;
    hitCount.Shift = hitCountShift;
    hitCount.Control = hitCountControl;
});
```

With this, the modifiers are done for the Realm example and you can start the game and try it out.

## Conclusion

Persisting data in games leads you to many different options to choose from. In this tutorial, we've looked at Realm. It's an easy-to-use and -learn database that can be integrated into your game without much work. All we had to do was add it via NPM, define the objects we use in the game as `RealmObject`, and then use `Realm.Write()` to add and change data, along with `Realm.Find<>()` to retrieve data from the database.

There is a lot more that Realm can do that would go beyond the limits of what can be shown in a single tutorial.

You can find [more examples for local Realms](https://github.com/realm/unity-examples/blob/3d-chess/local-realm/tutorial/unity_local_realm.md) in the example repository, as well. It  contains examples for one feature you might ask for next after having worked through this tutorial: How do I synchronize my data between devices? Have a look at [Realm Sync](https://www.mongodb.com/docs/atlas/app-services/sync/learn/overview/) and some [examples](https://github.com/realm/unity-examples/blob/3d-chess/synced-realm/tutorial/unity_sync_realm.md).

I hope this series gave you some ideas and insights on how to save and load data in Unity games and prepares you for the choice of which one to pick.

Please provide feedback and ask any questions in the [Realm Community Forum](https://www.mongodb.com/community/forums/tags/c/realm/realm-sdks/58/unity).

Persisting data is an important part of most games. Unity offers only a limited set of solutions, which means we have to look around for other options as well.