Adrienne Tacke and Sam Julien show you how to add Auth0's Universal Login to a ASP.NET Core application. Learn how to configure the OpenID Connect middleware and add a Login and Logout flow to your .NET Core app! 

Subscribe to MongoDB ►►► <a href="https://bit.ly/3bpg1Z1" target="_blank" rel="noreferrer">https://bit.ly/3bpg1Z1</a>

Connect with MongoDB:
Website: <a href="https://bit.ly/2LjtNBZ" target="_blank" rel="noreferrer">https://bit.ly/2LjtNBZ</a>
Twitter: <a href="https://bit.ly/3fH87gR" target="_blank" rel="noreferrer">https://bit.ly/3fH87gR</a>
Facebook: <a href="https://bit.ly/3fEaIsd" target="_blank" rel="noreferrer">https://bit.ly/3fEaIsd</a>
Linkedin: <a href="https://bit.ly/2SY9w90" target="_blank" rel="noreferrer">https://bit.ly/2SY9w90</a>
Instagram: <a href="https://bit.ly/3bn9bDv" target="_blank" rel="noreferrer">https://bit.ly/3bn9bDv</a>
TikTok: <a href="https://bit.ly/3fHoqdJ" target="_blank" rel="noreferrer">https://bit.ly/3fHoqdJ</a>

CSharp

How to Add a User Login to a  NET Core App (with Auth0's Sam Julien)

In this session, we will build a data-driven ASP.NET web app using the MongoDB driver to connect to MongoDB Atlas. You will learn how to incorporate the driver in your project and use both standard CRUD methods and the Aggregation Framework to work with the data.

We will keep this project small enough that attendees can follow along on their own laptops if they want (but they must have Visual Studio 2019 installed ahead of time). This session assumes only a basic familiarity with C# and MongoDB.

Build an ASP.NET app with the Mongo C# Driver

Nic Raboy

Learn how to build a space shooter game that synchronizes between clients and the cloud using MongoDB, Unity, and Realm Sync.

Building a Space Shooter Game that Syncs with Unity and MongoDB Realm

Nikola Irinchev

Realm's intuitive data model approach means that in most cases, you don't even think of Realm models as entities. You just declare your POCOs, have them inherit from `RealmObject`, and you're done. Now you have persistable models, with `INotifyPropertyChanged` capabilities all wired up, that are also "live"—i.e., every time you access a property, you get the latest state and not some snapshot from who knows how long ago. This is great and most of our users absolutely love the simplicity. Still, there are some use cases where being aware that you're working with a database can really bring your data models to the next level. In this blog post, we'll evaluate three techniques you can apply to make your models fit your needs even better.

## Constructor Validation

One of the core requirements of Realm is that all models need to have a parameterless constructor. This is needed because Realm needs to be able to instantiate an object without figuring out what arguments to pass to the constructor. What not many people know is that you can make this parameterless constructor private to communicate expectations  to your callers. This means that if you have a `Person` class where you absolutely expect that a `Name` is provided upon object creation, you can have a public constructor with a `name` argument and a private parameterless one for use by Realm:

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

    public Person(string name)
    {
        ValidateName(name);

        Name = name;
    }

    // This is used by Realm, even though it's private
    private Person()
    {
    }
}
```

And I know what some of you may be thinking: "Oh no! 😱 Does that mean Realm uses the suuuuper slow reflection to create object instances?" Fortunately, the answer is no. Instead, at compile time, Realm injects a nested helper class in each model that has a `CreateInstance` method. Since the helper class is nested in the model classes, it has access to private members and is thus able to invoke the private constructor.

## Property Access Modifiers

Similar to the point above, another relatively unknown feature of Realm is that persisted properties don't need to be public. You can either have the entire property be private or just one of the accessors. This synergizes nicely with the private constructor technique that we mentioned above. If you expose a constructor that explicitly validates the person's name, it would be fairly annoying to do all that work and have some code accidentally set the property to `null` the very next line. So it would make sense to make the setter of the name property above private:

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

    public Person(string name)
    {
        // ...
    }
}
```

That way, you're communicating clearly to the class consumers that they need to provide the name at object creation time and that it can't be changed later. A very common use case here is to make the `Id` setter private and generate a random `Id` at object creation time:

```csharp
class Transaction : RealmObject
{
    public Guid Id { get; private set; } = Guid.NewGuid();
}
```

Sometimes, it makes sense to make the entire property private—typically, when you want to expose a different public property that wraps it. If we go back to our `Person` and `Name` example, perhaps we want to allow changing the name, but we want to still validate the new name before we persist it. Then, we create a private autoimplemented property that Realm will use for persistence, and a public one that does the validation:

```csharp
class Person : RealmObject
{
    [MapTo("Name")]
    private string _Name { get; set; }

    public string Name
    {
        get => _Name;
        set
        {
            ValidateName(value);
            _Name = value;
        }
    }
}
```

This is quite neat as it makes the public API of your model safe, while preserving its persistability. Of note is the `MapTo` attribute applied to `_Name`. It is not strictly necessary. I just added it to avoid having ugly column names in the database. You can use it or not use it.  It's totally up to you. One thing to note when utilizing this technique is that Realm is completely unaware of the relationship between `Name` and `_Name`. This has two implications. 1) Notifications will be emitted for `_Name` only, and 2) You can't use LINQ queries to filter `Person` objects by name. Let's see how we can mitigate both:

For notifications, we can override `OnPropertyChanged` and raise a notification for `Name` whenever `_Name` changes:

```csharp
class Person : RealmObject
{
    protected override void OnPropertyChanged(string propertyName)
    {
        base.OnPropertyChanged(propertyName);

        if (propertyName == nameof(_Name))
        {
            RaisePropertyChanged(nameof(Name));
        }
    }
}
```

The code is fairly straightforward. `OnPropertyChanged` will be invoked whenever any property on the object changes and we just re-raise it for the related `Name` property. Note that, as an optimization, `OnPropertyChanged` will only be invoked if there are subscribers to the `PropertyChanged` event. So if you're testing this out and don't see the code get executed, make sure you added a subscriber first.

The situation with queries is slightly harder to work around. The main issue is that because the property is private, you can't use it in a LINQ query—e.g., `realm.All<Person>().Where(p => p._Name == "Peter")` will result in a compile-time error. On the other hand, because Realm doesn't know that `Name` is tied to `_Name`, you can't use `p.Name == "Peter"` either. You can still use the string-based queries, though. Just remember to use the name that Realm knows about—i.e., the string argument of `MapTo` if you remapped the property name or the internal property (`_Name`) if you didn't:

```csharp
// _Name is mapped to 'Name' which is what we use here
var peters = realm.All<Person>().Filter("Name == 'Peter'");
```

## Using Unpersistable Data Types

Realm has a wide variety of supported data types—most primitive types in the Base Class Library (BCL), as  well as advanced collections, such as sets and dictionaries. But sometimes, you'll come across a data type that Realm can't store yet, the most obvious example being enums. In such cases, you can build on top of the previous technique to expose enum properties in your models and have them be persisted as one of the supported data types:

```csharp
enum TransactionState
{
    Pending,
    Settled,
    Error
}

class Transaction : RealmObject
{
    private string _State { get; set; }

    public TransactionState State
    {
        get => Enum.Parse<TransactionState>(_State);
        set => _State = value.ToString();
    }
}
```

Using this technique, you can persist many other types, as long as they can be converted losslessly to a persistable primitive type. In this case, we chose `string`, but we could have just as easily used integer. The string representation takes a bit more memory but is also more explicit and less error prone—e.g., if you rearrange the enum members, the data will still be consistent.

All that is pretty cool, but we can take it up a notch. By building on top of this idea, we can also devise a strategy for representing complex data types, such as `Vector3` in a Unity game or a `GeoCoordinate` in a location-aware app. To do so, we'll take advantage of embedded objects—a Realm concept that represents a complex data structure that is owned entirely by its parent. Embedded objects are a great fit for this use case because we want to have a strict 1:1 relationship and we want to make sure that deleting the parent also cleans up the embedded objects it owns. Let's see this in action:

```csharp
class Vector3Model : EmbeddedObject
{
    // Casing of the properties here is unusual for C#,
    // but consistent with the Unity casing.
    private float x { get; set; }
    private float y { get; set; }
    private float z { get; set; }

    public Vector3Model(Vector3 vector)
    {
        x = vector.x;
        y = vector.y;
        z = vector.z;
    }

    private Vector3Model()
    {
    }

    public Vector3 ToVector3() => new Vector3(x, y, z);
}

class Powerup : RealmObject
{
    [MapTo("Position")]
    private Vector3Model _Position { get; set; }

    public Vector3 Position
    {
        get => _Position?.ToVector3() ?? Vector3.zero;
        set => _Position = new Vector3Model(value);
    }

    protected override void OnPropertyChanged(string propertyName)
    {
        base.OnPropertyChanged(propertyName);

        if (propertyName == nameof(_Position))
        {
            RaisePropertyChanged(nameof(Position));
        }
    }
}
```

In this example, we've defined a `Vector3Model` that roughly mirrors Unity's `Vector3`. It has three float properties representing the three components of the vector. We've also utilized what we learned in the previous sections. It has a private constructor to force consumers to always construct it with a `Vector3` argument. We've also marked its properties as private as we don't want consumers directly interacting with them. We want users to always call `ToVector3` to obtain the Unity type. And for our `Powerup` model, we're doing exactly that in the publicly exposed `Position` property. Note that similarly to our `Person` example, we're making sure to raise a notification for `Position` whenever `_Position` changes.

And similarly to the exaple in the previous section, this approach makes querying via LINQ impossible and we have to fall back to the string query syntax if we want to find all powerups in a particular area:

```csharp
IQueryable<Powerup> PowerupsAroundLocation(Vector3 location, float radius)
{
    // Note that this query returns a cube around the location, not a sphere.
    var powerups = realm.All<Powerup>().Filter(
        "Position.x > $0 AND Position.x < $1 AND Position.y > $2 AND Position.y < $3 AND Position.z > $4 AND Position.z < $5",
        location.x - radius, location.x + radius,
        location.y - radius, location.y + radius,
        location.z - radius, location.z  + radius);
}
```

## Conclusion

The list of techniques above is by no means meant to be exhaustive. Neither is it meant to imply that this is the only, or even "the right," way to use Realm. For most apps, simple POCOs with a list of properties is perfectly sufficient. But if you need to add extra validations or persist complex data types that you're using a lot, but Realm doesn't support natively, we hope that these examples will give you ideas for how to do that. And if you do come up with an ingenious way to use Realm, we definitely want to hear about it. Who knows? Perhaps we can feature it in our "Advanced^2 Data Modeling" article!

Learn how to structure your Realm models to add validation, protect certain properties, and even persist complex objects coming from third-party packages.

Advanced Data Modeling with Realm .NET

Dominic Frei

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

Adrienne Tacke

Learn how to use Azure Key Vault as your remote key management system with MongoDB's client-side field level encryption, step-by-step.

Integrate Azure Key Vault with MongoDB Client-Side Field Level Encryption

Ken W. Alger

Learn how to perform CRUD operations using C Sharp for MongoDB databases.

MongoDB & C Sharp: CRUD Operations Tutorial

Learn how to use Unity and the Realm SDK for Unity to build an infinite runner style game.

Build an Infinite Runner Game with Unity and the Realm Unity SDK

Learn how to use MongoDB client-side field level encryption (CSFLE) with a C# application.

How to Use MongoDB Client-Side Field Level Encryption (CSFLE) with C#



<div class="introduction">

When it comes to game development, you should probably have some ideas written down before you start writing code or generating assets. The same could probably be said about any kind of development, unless of course you're just messing around and learning something new.

So what should be planned before developing your next game?

Depending on the type of game, you're probably going to want a playable frontend, otherwise known as the game itself, some kind of backend if you want an online component such as multiplayer, leaderboards, or similar, and then possibly a web-based dashboard to get information at a glance if you're on the operational side of the game and not a player.

[Adrienne Tacke](https://www.twitter.com/adriennetacke), [Karen Huaulme](https://www.twitter.com/youoldmaid), and myself ([Nic Raboy](https://www.nraboy.com)) are in the process of building a game. We think [Fall Guys: Ultimate Knockout](https://fallguys.com/) is a very well-made game and thought it'd be interesting to create a tribute game that is a little more on the retro side, but with a lot of the same features. The game will be titled, Plummeting People. This article explores the planning, design, and development process!

Take a look at the [Jamboard](https://jamboard.google.com/d/1CdF-ZbegRWjsttwLExgt5VZBNC0ss3SAEBsKMBX5a8Q/viewer?f=1) we've created so far:

![Game Development Planning Board](https://www.mongodb.com/developer/images/how-to/gamedev-jamboard.gif)

The above Jamboard was created during a [planning stream on Twitch](https://www.youtube.com/watch?v=XAvy2BouZ1Q) where the community participated. The content that follows is a summary of each of the topics discussed and helpful information towards planning the development of a game.

## Planning the Game Experience with a Playable Frontend

The game is what most will see and what most will ever care about. It should act as the driver to every other component that operates behind the scenes.

Rather than try to invade the space of an already great game that we enjoy (Fall Guys), we wanted to put our own spin on things by making it 2D rather than 3D. With Fall Guys being the basic idea behind what we wanted to accomplish, we needed to further break down what the game would need. We came to a few conclusions.

**Levels / Arenas**

We need a few arenas to be able to call it a game worth playing, but we didn't want it to be as thought out as the game that inspired our idea. At the end of the day, we wanted to focus more on the development journey than making a blockbuster hit.

Fall Guys, while considered a battle royale, is still a racing game at its core. So what kind of arenas would make sense in a 2D setting?

![Fall Guys Door Dash](https://www.mongodb.com/developer/images/how-to/fall-guys-door-dash.png)

Our plan is to start with the simplest level concepts to save us from complicated game physics and engineering. There are two levels in particular that have basic collisions as the emphasis in Fall Guys. These levels include "Door Dash" and "Tip Toe" which focus on fake doors and disappearing floor tiles. Both of which have no rotational physics and nothing beyond basic collisions and randomization.

![Fall Guys Tip Toe](https://www.mongodb.com/developer/images/how-to/fall-guys-tip-toe.png)

While we could just stick with two basic levels as our proof of concept, we have a goal for a team arena such as scoring goals at soccer (football).

**Assets**

The arena concepts are important, but in order to execute, game assets will be necessary.

We're considering the following game assets a necessary part of our game:

-   Arena backgrounds
-   Obstacle images
-   Player images
-   Sound effects
-   Game music

To maintain the spirit of the modern battle royale game, we thought player customizations were a necessary component. This means we'll need customized sprites with different outfits that can be unlocked throughout the gameplay experience.

**Gameplay Physics and Controls**

Level design and game assets are only part of a game. They are quite meaningless unless paired with the user interaction component. The user needs to be able to control the player, interact with other players, and interact with obstacles in the arena. For this we'll need to create our own gameplay logic using the assets that we create.

## Maintaining an Online, Multiplayer Experience with a Data Driven Backend

We envision the bulk of our work around this tribute game will be on the backend. Moving around on the screen and interacting with obstacles is not too difficult of a task as demonstrated in a [previous tutorial](https://developer.mongodb.com/how-to/maintaining-geolocation-specific-game-leaderboard-phaser-mongodb) that I wrote.

Instead, the online experience will require most of our attention. Our first round of planning came to the following conclusions:

**Real-Time Interaction with Sockets**

When the player does anything in the game, it needs to be processed by the server and broadcasted to other players in the game. This needs to be real-time and sockets is probably the only logical solution to this. If the server is managing the sockets, data can be stored in the database about the players, and the server can also validate interactions to prevent cheating.

**Matchmaking Players with Games**

When the game is live, there will be simultaneous games in operation, each with their own set of players. We'll need to come up with a matchmaking solution so that players can only be added to a game that is accepting players and these players must fit certain criteria.

The matchmaking process might serve as a perfect opportunity to use [aggregation
pipelines](https://docs.mongodb.com/manual/core/aggregation-pipeline/) within MongoDB. For example, let's say that you have 5 wins and 1000 losses. You're not a very good player, so you probably shouldn't end up in a match with a player that has 1000 wins and 5 losses. These are things that we can plan for from a database level.

**User Profile Stores**

User profile stores are one of the most common components for any online game. These store information about the player such as the name and billing information for the player as well as gaming statistics. Just imagine that everything you do in a game will end up in a record for your player.

So what might we store in a user profile store? What about the following?:

-   Unlocked player outfits
-   Wins, losses, experience points
-   Username
-   Play time

The list could go on endlessly.

The user profile store will have to be carefully planned because it is the baseline for anything data related in the game. It will affect the matchmaking process, leaderboards, historical data, and so much more.

To get an idea of what we're putting into the user profile store, check out a [recorded Twitch stream](https://youtu.be/XUQCOf3NuJQ) we did on the topic.

**Leaderboards**

Since this is a competitive game, it makes sense to have a leaderboard. However this leaderboard can be a little more complicated than just your name and your experience points. What if we wanted to track who has the most wins, losses, steps, play time, etc.? What if we wanted to break it down further to see who was the leader in North America, Europe, or Asia? We could use [MongoDB geospatial queries](https://docs.mongodb.com/manual/geospatial-queries/) around the location of players.

As long as we're collecting game data for each player, we can come up with some interesting leaderboard ideas.

**Player Statistics**

We know we're going to want to track wins and losses for each player, but we might want to track more. For example, maybe we want to track how many steps a player took in a particular arena, or how many times they fell. This information could be later passed through an aggregation pipeline in MongoDB to determine a rank or level which could be useful for matchmaking and leaderboards.

**Player Chat**

Would it be an online multiplayer game without some kind of chat? We were thinking that while a player was in matchmaking, they could chat with each other until the game started. This chat data would be stored in MongoDB and we could implement [Atlas Search](https://docs.atlas.mongodb.com/atlas-search/) functionality to look for signs of abuse, foul language, etc., that might appear throughout the chat.

## Generating Reports and Logical Metrics with an Admin Dashboard

As an admin of the game, we're going to want to collect information to make the game better. Chances are we're not going to want to analyze that information from within the game itself or with raw queries against the database.

For this, we're probably going to want to create dashboards, reports, and other useful tools to work with our data on a regular basis. Here are some things that we were thinking about doing:

**MongoDB Atlas Charts**

If everything has been running smooth with the game and the data-collection of the backend, we've got data, so we just need to visualize it. [MongoDB Atlas Charts](https://www.mongodb.com/products/charts) can take that data and help us make sense of it. Maybe we want to show a heatmap at different hours of the day for different regions around the world, or maybe we want to show a bar graph around player experience points. Whatever the reason may be, Atlas Charts would make sense in an admin dashboard setting.

**Offloading Historical Data**

Depending on the popularity of the game, data will be coming into MongoDB like a firehose. To help with scaling and pricing, it will make sense to offload historical data from our cluster to a cloud object storage in order to save on costs and improve our cluster's performance by removing historical data.

In MongoDB Atlas, the best way to do this is to enable [Online Archive](https://docs.atlas.mongodb.com/online-archive/manage-online-archive/) which allows you to set rules to automatically archive your data to a fully-managed cloud storage while retaining access to query that data.

You can also leverage [MongoDB Atlas Data Lake](https://www.mongodb.com/atlas/data-lake) to connect your own S3 buckets and run [Federated Queries](https://docs.mongodb.com/datalake/query/query-data-lake) to access your entire data set using MQL and the Aggregation Framework.

## Conclusion

Like previously mentioned, this article is a starting point for a series of articles that are coming from [Adrienne Tacke](https://www.twitter.com/adriennetacke), [Karen
Huaulme](https://www.twitter.com/youoldmaid), and myself ([Nic Raboy](https://www.nraboy.com)), around a Fall Guys tribute game that we're calling Plummeting People. Are we trying to compete with Fall Guys? Absolutely not! We're trying to show the thought process around designing and developing a game that leverages MongoDB and since Fall Guys is such an awesome game, we wanted to pay tribute to it.

The next article in the series will be around designing and developing the user profile store for the game. It will cover the data model, queries, and some backend server code for managing the future interactions between the game and the server.

Want to discuss this planning article or the Twitch stream that went with it? Join us in the [community thread](https://developer.mongodb.com/community/forums/t/gamedev-episode-1-designing-a-strategy-for-building-a-game-with-mongodb-and-unity/9179) that we created.

Learn how to design a strategy towards developing the next big online game that uses MongoDB.

Designing a Strategy to Develop a Game with Unity and MongoDB



<div class="introduction">

Did you know that MongoDB has a [Realm
SDK](https://www.mongodb.com/realm) for the
[Unity](https://www.unity.com) game development framework that makes
working with game data effortless? The Realm SDK is currently an alpha
release, but you can already start using it to build persistence into
your cross platform gaming projects.

A few weeks ago I [streamed](https://youtu.be/8S0NuFwFazY) about and
wrote about [creating an infinite
runner](https://developer.mongodb.com/how-to/build-infinite-runner-game-unity-realm-unity-sdk/)
type game using Unity and the Realm SDK for Unity. Realm was used for
storing the score between scenes and sessions within the game.

There were a lot of deep topics in the infinite runner (think Temple Run
or Subway Surfer) example, so I wanted to take a step back. In this
tutorial, we're going to spend less time making an interesting game and
more time including and using Realm within a [Unity](https://unity.com/)
project.

To get an idea of what we're going to accomplish, take a look at the
following animated image:

![MongoDB Realm with Unity Example](https://www.mongodb.com/developer/images/how-to/realm-example.gif)

In the above example, we have three rectangles, each of a different
color. When clicking our mouse on a rectangle, the numeric values
increase. If the game were to be closed and then opened again, the
numeric values would be retained.

</div>

<div class="prerequisites">

## The Requirements

There aren't many requirements to using Realm with Unity, and once Realm
becomes production ready, those requirements will be even less. However,
for now you need the following:

-   [Unity](https://www.unity.com) 2020.2.4f1+
-   [Realm SDK for
    Unity](https://github.com/realm/realm-dotnet/releases) 10.1.1+

For now, the Realm SDK for Unity needs to be downloaded and imported
manually into a project. This will change when the SDK can be added
through the Unity Asset Store.

When you download Unity, you'll likely be using a different and
potentially older version by default. Within the Unity Hub software, pay
attention to the version you're using and either upgrade or downgrade as
necessary.

</div>

<div class="content">

## Adding the Realm SDK for Unity to a Project

From GitHub, [download the
latest](https://github.com/realm/realm-dotnet/releases) Realm SDK for
Unity tarball. If given the option, choose the **bundle** file. For
example, **realm.unity.bundle-10.1.1.tgz** is what I'm using.

Create a new Unity project and use the 2D template when prompted.

Within a Unity project, choose **Window -> Package Manager** and then
click the plus icon to add a tarball.

![Unity Add Custom Package](https://www.mongodb.com/developer/images/how-to/unity-add-realm-sdk.png)

The process of importing the tarball should only take a minute or two.
Once it has been added, it is ready for use within the game. Do note
that adding the tarball to your project only adds a reference based on
its current location on your disk. Moving or removing the tarball on
your filesystem will break the link.

## Designing a Data Model for the Realm Objects Within the Game

Before we can start persisting data to Realm and then accessing it
later, we need to define a model of what our data will look like. Since
Realm is an object-oriented database, we're going to define a class with
appropriate member variables and methods. This will represent what the
data looks like when persisted.

To align with the basic example that we're interested in, we essentially
want to store various score information.

Within the Unity project, create a new script file titled
**GameModel.cs** with the following C# code:

``` csharp
using Realms;

public class GameModel : RealmObject {

    [PrimaryKey]
    public string gamerTag { get; set; }

    public int redScore { get; set; }
    public int greenScore { get; set; }
    public int whiteScore { get; set; }

    public GameModel() { }

    public GameModel(string gamerTag, int redScore, int greenScore, int whiteScore) {
        this.gamerTag = gamerTag;
        this.redScore = redScore;
        this.greenScore = greenScore;
        this.whiteScore = whiteScore;
    }

}
```

The `redScore`, `greenScore`, and `whiteScore` variables will keep the
score for each square on the screen. Since a game is usually tied to a
person or a computer, we need to define a [primary
key](https://docs.mongodb.com/realm-sdks/java/10.0.1/io/realm/annotations/PrimaryKey.html)
for the associated data. The Realm primary key uniquely identifies an
object within a Realm. For this example, we're use a `gamerTag` variable
which represents a person or player.

To get an idea of what our model might look like as JSON, take the
following:

``` json
{
    "gamerTag": "poketrainernic",
    "redScore": 0,
    "greenScore": 0,
    "whiteScore": 0
}
```

For this example, and many Realm with Unity examples, we won't ever have
to worry about how it looks like as JSON since everything will be done
locally as objects.

With the `RealmObject` class configured, we can make use of it inside
the game.

## Interacting with Persisted Realm Data in the Game

The `RealmObject` only represents the storage model for our data. There
are extra steps when it comes to interacting with the data that is
modeled using it.

Within the Unity project, create a **GameController.cs** file with the
following C# code:

``` csharp
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Realms;
using UnityEngine.UI;

public class GameController : MonoBehaviour {

    private Realm _realm;
    private GameModel _gameModel;

    public Text scoreText;

    void OnEnable() {
        _realm = Realm.GetInstance();
        _gameModel = _realm.Find<GameModel>("poketrainernic");
        if(_gameModel == null) {
            _realm.Write(() => {
                _gameModel = _realm.Add(new GameModel("poketrainernic", 0, 0, 0));
            });
        }
    }

    void OnDisable() {
        _realm.Dispose();
    }

    public void SetButtonScore(string color, int inc) {
        switch(color) {
            case "RedSquare":
                _realm.Write(() => {
                    _gameModel.redScore++;
                });
                break;
            case "GreenSquare":
                _realm.Write(() => {
                    _gameModel.greenScore++;
                });
                break;
            case "WhiteSquare":
                _realm.Write(() => {
                    _gameModel.whiteScore++;
                });
                break;
            default:
                Debug.Log("Color Not Found");
                break;
        }
    }

    void Update() {
        scoreText.text = "Red: " + _gameModel.redScore + "\n" + "Green: " + _gameModel.greenScore + "\n" + "White: " + _gameModel.whiteScore;
    }

}
```

In the above code, we have a few things going on, all related to
interacting with Realm.

In the `OnEnable` method, we are getting an instance of our Realm
database and we are finding an object based on our `GameModel` class.
The primary key is the `gamerTag` string variable, so we are providing a
value to query on. If the query returns a null value, it means that no
data exists based on the primary key used. In that circumstance, we
create a `Write` block and add a new object based on the constructor
within the `GameModel` class. By the end of the query or creation of our
data, we'll have a `_gameModel` object that we can work with in our
game.

We're hard coding the "poketrainernic" value because we don't plan to
use any kind of authentication in this example. Everyone who plays this
game is considered the "poketrainernic" player.

The `OnDisable` method is for cleanup. It is important to dispose of the
Realm instance when the game ends to prevent any unexpected behavior.

For this particular game example, most of our logic happens in the
`SetButtonScore` method. In the `SetButtonScore` method, we are checking
to see which color should be incremented and then we are doing so. The
amazing thing is that changing the `_gameModel` object changes what is
persisted, as long as the changes happen in a `Write` block. No having
to write queries or do anything out of the ordinary beyond just working
with your objects as you would normally.

While we don't have a `Text` object configured yet within our game, the
`Update` method will update the text on the screen every frame. If one
of the values in our Realm instance changes, it will be reflected on the
screen.

## Adding Basic Logic to the Game Objects Within the Scene

At this point, we have a `RealmObject` data model for our persisted data
and we have a class for interacting with that data. We don't have
anything to tie it together visually like you'd expect in a game. In
other words, we need to be able to click on a colored sprite and have it
persist something new.

Within the Unity project, create a **Button.cs** file with the following
C# code:

``` csharp
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class Button : MonoBehaviour {

    public GameController game;

    void OnMouseDown() {
        game.SetButtonScore(gameObject.name, 1);
    }

}
```

The `game` variable in the above code will eventually be from a game
object within the scene and configured through a series of dragging and
dropping, but we're not there yet. As of right now, we're focusing on
the code, and less on game objects.

The `OnMouseDown` method is where the magic happens for this script. The
game object that this script will eventually be attached to will have a
[collider](https://docs.unity3d.com/ScriptReference/Collider2D.OnCollisionEnter2D.html)
which gives us access to the `OnMouseDown` method. When the game object
is clicked, we use the `SetButtonScore` method to send the name of the
current game object as well as a value to increase the score by.
Remember, inside the `SetButtonScore` method we are expecting a string
value for our switch statement. In the next few steps, naming the game
objects appropriately is critical based on our already applied logic.

If you're not sure where `gameObject` is coming from, it is inherited as
part of the `MonoBehavior` class, and it represents the current game
object to which the script is currently attached to.

## Game Objects, Colliders, and the Gaming Wrap-Up

The Unity project has a bunch of short scripts sitting out in the ether.
It's time to add game objects to the scene so we can attach the scripts
and do something interesting.

By the time we're done, our Unity editor should look something like the
following:

![Realm Unity Example, Editor](https://www.mongodb.com/developer/images/how-to/unity-inspector-realm-example.png)

We need to add a few game objects, add the scripts to those game
objects, then reference a few other game objects. Yes, it sounds
complicated, but it really isn't!

Within the Unity editor, add the following game objects to the scene.
We'll walk through adding them and some of the specifics next:

-   GameController
-   RedSquare
-   GreenSquare
-   WhiteSquare
-   Canvas
    -   Scores
-   EventSystem

Now the `Scores` game object is for our text. You can add a `Text` game
object from the menu and it will add the `Canvas` and `EventSystem` for
you. You don't need to add a `Canvas` or `EventSystem` manually if Unity
created one for you. Just make sure you name and position the game
object for scores appropriately.

If the `Scores` text is too small or not visible, make sure the
rectangular boundaries for the text is large enough.

![Resize Text Area in Unity](https://www.mongodb.com/developer/images/how-to/unity-resize-text-field.gif)

The `RedSquare`, `GreenSquare`, and `WhiteSquare` game objects are
`Square` sprites, each with a different color. These sprites can be
added using the **GameObject -> 2D Object -> Sprites -> Square** menu
item. You'll need to rename them to the desired name after adding them
to the scene. Finally, the `GameController` is nothing more than an
empty game object.

Drag the **Button.cs** script to the inspector panel of each of the
colored square sprites. The sprites depend on being able to access the
`SetButtonScore` method, so the `GameController` game object must be
dragged onto the **Score Text** field within the script area on each of
the squares as well. Drag the **GameController.cs** script to the
`GameController` game object. Next, drag the `Scores` game object into
the scripts section of the `GameController` game object so that the
`GameController` game object can control the score text.

We just did a lot of drag and drop on the game objects within the scene.
We're not quite done yet though. In order to use the `OnMouseDown`
method for our squares, they need to have a collider. Make sure to add a
**Box Collider 2D** to each of the squares. The **Box Collider 2D** is a
component that can be added to the game objects through the inspector.

You should be able to run the game with success as of now! You can do
this by either creating and running a build from the **File** menu, or
by using the play button within your editor to preview the game.

</div>

<div class="summary">

## Conclusion

You just saw how to get started with the Realm SDK for
[Unity](https://unity.com/). I wrote another example of using Realm with
Unity, but the game was a little more exciting, which added more
complexity. Once you have a firm understanding of how Realm works in
Unity, it is worth checking out [Build an Infinite Runner Game with
Unity and the Realm Unity
SDK](https://developer.mongodb.com/how-to/build-infinite-runner-game-unity-realm-unity-sdk/).

As previously mentioned, the Realm SDK for Unity is currently an alpha
release. Expect that there will be problems at some point, so it
probably isn't best to use it in your production ready game. However,
you should be able to get comfortable including it.

For more examples on using the Realm SDK, check out the [C#
documentation](https://docs.mongodb.com/realm/sdk/dotnet/quick-start-local/).

Questions? Comments? We'd love to connect with you. Join the
conversation on the [MongoDB Community
Forums](https://developer.mongodb.com/community/forums/).

</div>


Learn how to get started with the Realm SDK for Unity for data persistance in your game.

Getting Started with the Realm SDK for Unity

Learn how to create a 2D side-scrolling platformer game with MongoDB and Unity.

Developing a Side-Scrolling Platformer Game with Unity and MongoDB Realm

If you've been keeping up with the game development series that me ([Nic Raboy](https://www.nraboy.com)) and [Adrienne Tacke](https://www.twitter.com/adriennetacke) have been creating, you've probably seen how to [create a user profile store for a game](https://developer.mongodb.com/how-to/creating-user-profile-store-game-nodejs-mongodb) and [move a player around on the screen with Unity](https://developer.mongodb.com/how-to/getting-started-unity-creating-2d-game).

To continue with the series, which is also being streamed on [Twitch](https://www.twitch.tv/mongodb), we're at a point where we need to worry about designing a level for gameplay rather than just exploring a blank screen.

In this tutorial, we're going to see how to create a level, which can also be referred to as a map or world, using simple C# and the Unity Tilemap Editor.

To get a better idea of what we plan to accomplish, take a look at the following animated image.

![Unity Tilemap Level Example](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_tilemap_level_example_f544522660.gif)

You'll notice that we're moving a non-animated sprite around the screen. You might think at first glance that the level is one big image, but it is actually many tiles placed carefully within Unity. The edge tiles have collision boundaries to prevent the player from moving off the screen.

If you're looking at the above animated image and wondering where [MongoDB](https://www.mongodb.com) fits into this, the short answer is that it doesn't. The game that Adrienne and I are building will leverage MongoDB, but some parts of the game development process such as level design won't need a database. We're attempting to tell a story with this series.

## Using the Unity Tilemap Editor to Draw 2D Game Levels

There are many ways to create a level for a game, but as previously mentioned, we're going to be using tilemaps. Unity makes this easy for us because the software provides a paint-like experience where we can draw tiles on the canvas using any available images that we load into the project.

For this example, we're going to use the following texture sheet:

![Plummeting People Doordash Level](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/doordash_level_ae923dd2df.png)

Rather than creating a new project and repeating previously explained steps, we're going to continue where we left off from the [previous tutorial](https://developer.mongodb.com/how-to/getting-started-unity-creating-2d-game). The **doordash-level.png** file should be placed in the **Assets/Textures** directory of the project.

While we won't be exploring animations in this particular tutorial, if you want the spritesheet used in the animated image, you can download it below:

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

The **plummie.png** file should be added to the project's **Assets/Textures** directory. To learn how to animate the spritesheet, take a look at a [previous tutorial](https://www.thepolyglotdeveloper.com/2020/10/animate-spritesheets-unity-2d-game/) I wrote on the topic.

Inside the Unity editor, click on the **doordash-level.png** file that was added. We're going to want to do a few things before we can work with each tile as independent images.

-   Change the sprite mode to **Multiple**.
-   Define the actual **Pixels Per Unit** of the tiles in the texture packed image.
-   Split the tiles using the **Sprite Editor**.

![Define Spritesheet Information in Unity](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_spritesheet_edit_0716a89e40.jpg)

In the above image, you might notice that the **Pixels Per Unit** value is **255** while the actual tiles are **256**. By defining the tiles as one pixel smaller, we're attempting to remove any border between the tile images that might make the level look weird due to padding.

When using the **Sprite Editor**, make sure to slice the image by the cell size using the correct width and height dimensions of the tiles. For clarity, the tiles that I attached are 256x256 in resolution.

![Unity Sprite Editor](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_sprite_editor_c1d14aeaee.jpg)

If you plan to use the spritesheet for the Plummie character, make sure to repeat the same steps for that spritesheet as well. It is important we have access to the individual images in a spritesheet rather than treating all the images as one single image.

With the images ready for use, let's focus on drawing the level.

Within the Unity menu, choose **Component -> Tilemap -> Tilemap** to add a new tilemap and parent grid object to the scene. To get the best results, we're going to want to layer multiple tilemaps on our scene. Right click on the **Grid** object in the scene and choose **2D Object -> Tilemap**. You'll want three tilemaps in total for this particular example.

![Unity New Tilemap](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_new_tilemap_43965a5517.jpg)

We want multiple tilemap layers because it will add depth to the scene and more control. For example, one layer will represent the furthest part of our background, maybe dirt or floors. Another layer will represent any kind of decoration that will sit on top of the floors — aay, for example, arrows. Then, the final tilemap layer might represent our walls or obstacles.

To make sure the layers get rendered in the correct order, the **Tilemap Renderer** for each tilemap should have a properly defined **Sorting Layer**. If continuing from the previous tutorial, you'll remember we had created a **Background** layer and a **GameObject** layer. These can be used, or you can continue to create and assign more. Just remember that the render order of the sorting layers is top to bottom, the opposite of what you'd experience in photo editing software like Adobe Photoshop.

The next step is to open the **Tile Palette** window within Unity. From the menu, choose **Window -> 2D -> Tile Palette**. The palette will be empty to start, but you'll want to drag your images either one at a time or multiple at a time into the window.

![Unity Tile Palette Images](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_tile_palette_images_2d48870d09.jpg)

With images in the tile palette, they can be drawn on the scene like painting on a canvas. First click on the tile image you want to use and then choose the painting tool you want to use. You can paint on a tile-by-tile basis or paint multiple tiles at a time.

It is important that you have the proper **Active Tilemap** selected when drawing your tiles. This is important because of the order that each tile renders and any collision boundaries we add later.

Take a look at the following possible result:

![Unity Tilemaps for Level Design](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_tilemap_layer_results_3c4a4df5de.jpg)

Remember, we're designing a level, so this means that your tiles can exceed the view of the camera. Use your tiles to make your level as big and extravagant as you'd like.

Assuming we kept the same logic from the previous tutorial, [Getting Started with Unity for Creating a 2D Game](https://developer.mongodb.com/how-to/getting-started-unity-creating-2d-game), we can move our player around in the level, but the player can exceed the screen. The player may still be a white box or the Plummie sprite depending on what you've chosen to do. Regardless, we want to make sure our layer that represents the boundaries acts as a boundary with collision.

## Adding Collision Boundaries to Specific Tiles and Regions on a Level

Adding collision boundaries to tiles in a tilemap is quite easy and doesn't require more than a few clicks.

Select the tilemap that represents our walls or boundaries and choose to **Add Component** in the inspector. You'll want to add both a **Tilemap Collider 2D** as well as a **Rigidbody 2D**. The **Body Type** of the **Rigidbody 2D** should be static so that gravity and other physics-related events are not applied.

After doing these short steps, the player should no longer be able to go beyond the tiles for this layer.

We can improve things!

Right now, every tile that is part of our tilemap with the **Tilemap Collider 2D** and **Rigidbody 2D** component has a full collision area around the tile. This is true even if the tiles are adjacent and parts of the tile can never be reached by the player. Imagine having four tiles creating a large square. Of the possible 16 collision regions, only eight can ever be interacted with. We're going to change this, which will greatly improve performance.

On the tilemap with the **Tilemap Collider 2D** and **Rigidbody 2D** components, add a **Composite Collider 2D** component. After adding, enable the **Used By Composite** field in the **Tilemap Collider 2D** component.

![Unity Composite Collider 2D on Tilemap](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_tilemap_composite_collider_2d_fcf5f8e3a9.jpg)

Just like that, there are fewer regions that are tracking collisions, which will boost performance.

## Following the Player While Traversing the 2D Game Level using C#

As of right now, we have our player, which might be a Plummie or might be a white pixel, and we have our carefully crafted level made from tiles. The problem is that our camera can only fit so much into view, which probably isn't the full scope of our level.

What we can do as part of the gameplay experience is have the camera follow the player as it traverses the level. We can do this with C#.

Select the **Main Camera** within the current scene. We're going to want to add a new script component.

Within the C# script that you'll need to attach, include the following code:

``` csharp
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class CameraPosition : MonoBehaviour
{

   public Transform player;

   void Start() {}

   void Update()
   {
      transform.position = new Vector3(player.position.x, 0, -10);
   }
}
```

In the above code, we are looking at the transform of another unrelated game object. We'll attach that game object in just a moment. Every time the frame updates, the position of the camera is updated to match the position of the player in the x-axis. In this example, we are fixing the y-axis and z-axis so we are only following the player in the left and right direction. Depending on how you've created your level, this might need to change.

Remember, this script should be attached to the **Main Camera** or whatever your camera is for the scene.

![Unity Camera to Player Transform](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/unity_camera_transform_71b2136131.jpg)

Remember the `player` variable in the script? You'll find it in the inspector for the camera. Drag your player object from the project hierarchy into this field and that will be the object that is followed by the camera.

Running the game will result in the camera being centered on the player. As the player moves through the tilemap level, so will the camera. If the player tries to collide with any of the tiles that have collision boundaries, motion will stop.

## Conclusion

You just saw how to create a 2D world in Unity using tile images and the Unity Tilemap Editor. This is a very powerful tool because you don't have to create massive images to represent worlds and you don't have to worry about creating worlds with massive amounts of game objects.

The assets we used in this tutorial are based around a series that myself ([Nic Raboy](https://www.nraboy.com)) and [Adrienne Tacke](https://www.twitter.com/adriennetacke) are building titled Plummeting People. This series is on the topic of building a multiplayer game with Unity that leverages MongoDB. While this particular tutorial didn't include MongoDB, plenty of other tutorials in the series will.

If you feel like this tutorial skipped a few steps, it did. I encourage you to read through some of the previous tutorials in the series to catch up.

If you want to build Plummeting People with us, follow us on [Twitch](https://www.twitch.tv/mongodb) where we work toward building it live, every other week.


Learn how to use Unity tilemaps to create complex 2D worlds for your game.

Designing and Developing 2D Game Levels with Unity and C#

If you've been keeping up with the content on the [MongoDB Developer Portal](https://developer.mongodb.com), you'll know that a few of us at MongoDB ([Nic Raboy](https://www.nraboy.com), [Adrienne Tacke](https://www.twitter.com/adriennetacke), [Karen Huaulme](https://www.twitter.com/youoldmaid)) have been working on a game titled Plummeting People, a [Fall Guys: Ultimate Knockout](https://fallguys.com/) tribute game. Up until now we've focused on [game planning](https://developer.mongodb.com/how-to/designing-strategy-develop-game-unity-mongodb) and part of our backend infrastructure with a user profile store.

As part of the natural progression in our development of the game and part of this tutorial series, it makes sense to get started with the actual gaming aspect, and that means diving into [Unity](https://unity.com/), our game development framework.

In this tutorial, we're going to get familiar with some of the basics behind Unity and get a sprite moving on the screen as well as handing collision. If you're looking for how we plan to integrate the game into MongoDB, that's going to be saved for another tutorial.

An example of what we want to accomplish can be seen in the following animated image:

![Unity 2D Game Example](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-2d-game-example.gif)

The framerate in the image is a little stuttery, but the actual result is quite smooth.

## The Requirements

Before we get started, it's important to understand the requirements for creating the game.

-   Unity 2020+
-   Image to be used for player
-   Image to be used for the background

I'm using Unity 2020.1.6f1, but any version around this particular version should be fine. You can download [Unity](https://unity.com/) at no cost for macOS and Windows, but make sure you understand the licensing model if you plan to sell your game.

Since the goal of this tutorial is around moving a game object and handling collisions with another game object, we're going to need images. I'm using a 1x1 pixel image for my player, obstacle, and background, all scaled differently within Unity, but you can use whatever images you want.

## Creating a New Unity Project with Texture and Script Assets

To keep things easy to understand, we're going to start with a fresh project. Within the **Unity Hub** application that becomes available after installing Unity, choose to create a new project.

![Unity Create New 2D Project](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-new-2d-project.png)

You'll want to choose **2D** from the available templates, but the name and project location doesn't matter as long as you're comfortable with it.

The project might take a while to generate, but when it's done, you should be presented with something that looks like the following:

![Unity Empty New Project](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-empty-2d-project.png)

As part of the first steps, we need to make the project a little more development ready. Within the **Project** tree, right click on **Assets** and choose to create a new folder for **Textures** as well as **Scripts**.

![Create New Unity Asset Folder](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-new-asset-folder.jpg)

Any images that we plan to use in our game will end up in the **Textures** folder and any game logic will end up as a script within the **Scripts** folder. If you have your player, background, and obstacle images, place them within the **Textures** directory now.

As of right now there is a single scene for the game titled **SampleScene**. The name for this scene doesn't properly represent what the scene will be responsible for. Instead, let's rename it to **GameScene** as it will be used for the main gaming component for our project. A scene for a game is similar to a scene in a television show or movie. You'll likely have more than one scene, but each scene is responsible for something distinct. For example, in a game you might have a scene for the menu that appears when the user starts the game, a scene for game-play, and a scene for what happens when they've gotten game over. The use cases are limitless.

With the scene named appropriately, it's time to add game objects for the player, background, and obstacle. Within the project hierarchy panel, right click underneath the **Main Camera** item (if your hierarchy is expanded) or just under **GameScene** (if not expanded) and choose **Create Empty** from the list.

![Create Empty Game Object in Unity](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-create-empty-gameobject.jpg)

We'll want to create a game object for each of the following: the player, background, and obstacle. The name isn't too important, but it's probably a good idea to give them names based around their purpose.

To summarize what we've done, double-check the following:

-   Created a **Textures** and **Scripts** directory within the **Assets** directory.
-   Added an image that represents a player, an obstacle, and a background to the **Textures** directory.
-   Renamed **SampleScene** to **GameScene**.
-   Created a **Player** game object within the scene.
-   Created an **Obstacle** game object within the scene.
-   Created a **Background** game object within the scene.

At this point in time we have the project properly laid out.

## Adding Sprite Renders, Physics, Collision Boxes, and Scripts to a Game Object

We have our game objects and assets ready to go and are now ready to configure them. This means adding images to the game object, physics properties, and any collision related data.

With the player game object selected from the project hierarchy, choose **Add Component** and search for **Sprite Renderer**.

![Add Sprite Renderer to Game Object](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-2d-sprite-renderer-component.png)

The **Sprite Renderer** allows us to associate an image to our game object. Click the circle icon next to the **Sprite** property's input box. A panel will pop up that allows you to select the image you want to associate to the selected game object. You're going to want to use the image that you've added to the **Textures** directory. Follow the same steps for the obstacle and the background.

You may or may not notice that the layering of your sprites with images are not correct in the sense that some images are in the background and some are in the foreground. To fix the layering, we need to add a **Sorting Layer** to the game objects.

![Add Sorting Layer to Sprite Rendering in Unity](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-sprite-renderer-sorting-layer.png)

Rather than using the default sorting layer, choose to **Add Sorting Layer...** so we can use our own strategy. Create two new layers titled **Background** and **GameObject** and make sure that **Background** sits above **GameObject** in the list. The list represents the rendering order so higher in the list gets rendered first and lower in the list gets rendered last. This means that the items rendering last appear at the highest level of the foreground. Think about it as layers in Adobe Photoshop, only reversed in terms of which layers are most visible.

With the sorting layers defined, set the correct **Sorting Layer** for each of the game objects in the scene.

For clarity, the background game object should have the **Background** sorting layer applied and the obstacle as well as the player game object should have the **GameObject** sorting layer applied. We are doing it this way because based on the order of our layers, we want the background game object to truly sit behind the other game objects.

The next step is to add physics and collision box data to the game objects that should have such data. Select the player game object and search for a **Rigidbody 2D** component.

![Add Rigid Body 2D to Game Object in Unity](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-rigidbody2d-component.png)

Since this is a 2D game that has no sense of flooring, the **Gravity Scale** for the player should be zero. This will prevent the player from falling off the screen as soon as the game starts. The player is the only game object that will need a rigid body because it is the only game object where physics might be important.

In addition to a rigid body, the player will also need a collision box.  Add a new **Box Collider 2D** component to the player game object.

![Add Box Collider 2D to Game Object in Unity](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-box-collider-2d.png)

The **Box Collider 2D** component should be added to the obstacle as well. The background, since it has no interaction with the player or obstacle does not need any additional component added to it.

The final configuration for the game objects is the adding of the scripts for game logic.

Right click on the **Scripts** directory and choose to create a new **C# Script**. You'll want to rename the script to something that represents the game object that it will be a part of. For this particular script, it will be associated to the player game object.

![Add Script to Game Object in Unity](https://www.mongodb.com/developer/images/how-to/getting-started-unity-creating-2d-game/unity-new-script.png)

After selecting the game object for the player, drag the script file to the **Add Component** area of the inspector to add it to the game object.

At this point in time everything for this particular game is configured.  However, before we move onto the next step, let's confirm the components added to each of the game objects in the scene.

-   Background has one sprite renderer with a **Background** sorting layer.
-   Player has one sprite renderer, one rigid body, and one box collider with the **GameObject** sorting layer.
-   Obstacle has one sprite renderer, and one box collider with the **GameObject** sorting layer.

The next step is to apply some game logic.

## Controlling a Game Object with a Unity C# Script

In Unity, everything in a scene is controlled by a script. These scripts exist on game objects which make it easy to separate the bits and pieces that make up a game. For example the player might have a script with logic. The obstacles might have a different script with logic. Heck, even the grass within your scene might have a script. It's totally up to you how you want to script every part of your scene.

In this particular game example, we're only going to add logic to the player object script.

The script should already be associated to a player object, so open the script file and you should see the following code:

``` csharp
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class Player : MonoBehaviour
{

    void Start()
    {
        // ...
    }

    void Update()
    {
        // ...
    }

}
```

To move the player we have a few options. We could transform the position of the game object, we can transform the position of the rigid body, or we can apply physics force to the rigid body. Each will give us different results, with the force option being the most unique.

Because we do have physics, let's look at the latter two options, starting with the movement through force.

Within your C# script, change your code to the following:

``` csharp
using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class Player : MonoBehaviour
{

    public float speed = 1.5f;

    private Rigidbody2D rigidBody2D;

    void Start()
    {
        rigidBody2D = GetComponent<Rigidbody2D>();
    }

    void Update()
    {

    }

    void FixedUpdate() {
        float h = 0.0f;
        float v = 0.0f;
        if (Input.GetKey("w")) { v = 1.0f; }
        if (Input.GetKey("s")) { v = -1.0f; }
        if (Input.GetKey("a")) { h = -1.0f; }
        if (Input.GetKey("d")) { h = 1.0f; }

        rigidBody2D.AddForce(new Vector2(h, v) * speed);
    }

}
```

We're using a `FixedUpdate` because we're using physics on our game object. Had we not been using physics, the `Update` function would have been fine.

When any of the directional keys are pressed (not arrow keys), force is applied to the rigid body in a certain direction at a certain speed. If you ran the game and tried to move the player, you'd notice that it moves with a kind of sliding on ice effect. Rather than moving the player at a constant speed, the player increases speed as it builds up momentum and then when you release the movement keys it gradually slows down. This is because of the physics and the applying of force.

Moving the player into the obstacle will result in the player stopping.  We didn't even need to add any code to make this possible.

So let's look at moving the player without applying force. Change the `FixedUpdate` function to the following:

``` csharp
void FixedUpdate() {
    float h = 0.0f;
    float v = 0.0f;
    if (Input.GetKey("w")) { v = 1.0f; }
    if (Input.GetKey("s")) { v = -1.0f; }
    if (Input.GetKey("a")) { h = -1.0f; }
    if (Input.GetKey("d")) { h = 1.0f; }

    rigidBody2D.MovePosition(rigidBody2D.position + (new Vector2(h, v) * speed * Time.fixedDeltaTime));
}
```

Instead of using the `AddForce` method we are using the `MovePosition` method. We are now translating our rigid body which will also translate our game object position. We have to use the `fixedDeltaTime`, otherwise we risk our translations happening too quickly if the `FixedUpdate` is executed too quickly.

If you run the game, you shouldn't get the moving on ice effect, but instead nice smooth movement that stops as soon as you let go of the keys.

In both examples, the movement was limited to the letter keys on the keyboard.

If you want to move based on the typical WASD letter keys and the arrow keys, you could do something like this instead:

``` csharp
void FixedUpdate() {
    float h = Input.GetAxis("Horizontal");
    float v = Input.GetAxis("Vertical");

    rigidBody2D.MovePosition(rigidBody2D.position + (new Vector2(h, v) * speed * Time.fixedDeltaTime));
}
```

The above code will generate a value of -1.0, 0.0, or 1.0 depending on if the corresponding letter key or arrow key was pressed.

Just like with the `AddForce` method, when using the `MovePosition` method, the collisions between the player and the obstacle still happen.

## Conclusion

You just saw how to get started with Unity and building a simple 2D game. Of course what we saw in this tutorial wasn't an actual game, but it has all of the components that can be applied towards a real game.  This was discussed by [Karen Huaulme](https://www.twitter.com/youoldmaid) and myself ([Nic Raboy](https://www.nraboy.com)) in the fourth part of our [game development Twitch stream](https://www.youtube.com/watch?v=wDRf2jHrCPM).

The player movement and collisions will be useful in the Plummeting People game as players will not only need to dodge other players, but obstacles as well as they race to the finish line.

Learn how to get started with Unity for moving an object on the screen with physics and collisions.

Getting Started with Unity for Creating a 2D Game

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

If you've been keeping up with my development content, you'll remember that I recently wrote [Build Your First .NET Core Application with MongoDB Atlas](https://www.mongodb.com/developer/how-to/build-first-dotnet-core-application-mongodb-atlas/), which focused on building a console application that integrated with MongoDB. While there is a fit for MongoDB in console applications, many developers are going to find it more valuable in web applications.

In this tutorial, we're going to expand upon the previous and create a RESTful API with endpoints that perform basic create, read, update, and delete (CRUD) operations against MongoDB Atlas.

## The Requirements

To be successful with this tutorial, you'll need to have a few things taken care of first:

- A deployed and configured MongoDB Atlas cluster, M0 or higher
- .NET Core 6+

We won't go through the steps of deploying a MongoDB Atlas cluster or configuring it with user and network rules. If this is something you need help with, check out a [previous tutorial](https://www.mongodb.com/developer/article/5-different-ways-deploy-free-database-mongodb-atlas/) that was published on the topic.

We'll be using .NET Core 6.0 in this tutorial, but other versions may still work. Just take the version into consideration before continuing.

## Create a Web API Project with the .NET Core CLI

To kick things off, we're going to create a fresh .NET Core project using the web application template that Microsoft offers. To do this, execute the following commands from the CLI:

```bash
dotnet new webapi -o MongoExample
cd MongoExample
dotnet add package MongoDB.Driver
```

The above commands will create a new web application project for .NET Core and install the latest MongoDB driver. We'll be left with some boilerplate files as part of the template, but we can remove them.

Inside the project, delete any file related to `WeatherForecast` and similar.

## Designing a Document Model and Database Service within .NET Core

Before we start designing each of the RESTful API endpoints with .NET Core, we need to create and configure our MongoDB service and define the data model for our API.

We'll start by working on our MongoDB service, which will be responsible for establishing our connection and directly working with documents within MongoDB. Within the project, create "Models/MongoDBSettings.cs" and add the following C# code:

```csharp
namespace MongoExample.Models;

public class MongoDBSettings {

    public string ConnectionURI { get; set; } = null!;
    public string DatabaseName { get; set; } = null!;
    public string CollectionName { get; set; } = null!;

}
```

The above `MongoDBSettings` class will hold information about our connection, the database name, and the collection name. The data we plan to store in these class fields will be found in the project's "appsettings.json" file. Open it and add the following:

```json
{
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "MongoDB": {
        "ConnectionURI": "ATLAS_URI_HERE",
        "DatabaseName": "sample_mflix",
        "CollectionName": "playlist"
    }
}
```

Specifically take note of the `MongoDB` field. Just like with the [previous example project](https://www.mongodb.com/developer/how-to/build-first-dotnet-core-application-mongodb-atlas/), we'll be using the "sample_mflix" database and the "playlist" collection. You'll need to grab the `ConnectionURI` string from your MongoDB Atlas Dashboard.

![MongoDB Atlas Connection String](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mongodb_atlas_connection_string_801c3bdc01.jpg "MongoDB Atlas Connection String")

With the settings in place, we can move onto creating the service.

Create "Services/MongoDBService.cs" within your project and add the following:

```csharp
using MongoExample.Models;
using Microsoft.Extensions.Options;
using MongoDB.Driver;
using MongoDB.Bson;

namespace MongoExample.Services;

public class MongoDBService {

    private readonly IMongoCollection<Playlist> _playlistCollection;

    public MongoDBService(IOptions<MongoDBSettings> mongoDBSettings) {
        MongoClient client = new MongoClient(mongoDBSettings.Value.ConnectionURI);
        IMongoDatabase database = client.GetDatabase(mongoDBSettings.Value.DatabaseName);
        _playlistCollection = database.GetCollection<Playlist>(mongoDBSettings.Value.CollectionName);
    }

    public async Task<List<Playlist>> GetAsync() { }
    public async Task CreateAsync(Playlist playlist) { }
    public async Task AddToPlaylistAsync(string id, string movieId) {}
    public async Task DeleteAsync(string id) { }

}
```

In the above code, each of the asynchronous functions were left blank on purpose. We'll be populating those functions as we create our endpoints. Instead, make note of the constructor method and how we're taking the passed settings that we saw in our "appsettings.json" file and setting them to variables. In the end, the only variable we'll ever interact with for this example is the `_playlistCollection` variable.

With the service available, we need to connect it to the application. Open the project's "Program.cs" file and add the following at the top:

```csharp
using MongoExample.Models;
using MongoExample.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<MongoDBSettings>(builder.Configuration.GetSection("MongoDB"));
builder.Services.AddSingleton<MongoDBService>();
```

You'll likely already have the `builder` variable in your code because it was part of the boilerplate project, so don't add it twice. What you'll need to add near the top is an import to your custom models and services as well as configuring the service.

Remember the `MongoDB` field in the "appsettings.json" file? That is the section that the `GetSection` function is pulling from. That information is passed into the singleton service that we created.

With the service created and working, with the exception of the incomplete asynchronous functions, we can focus on creating a data model for our collection.

Create "Models/Playlist.cs" and add the following C# code:

```csharp
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using System.Text.Json.Serialization;

namespace MongoExample.Models;

public class Playlist {

    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string? Id { get; set; }

    public string username { get; set; } = null!;

    [BsonElement("items")]
    [JsonPropertyName("items")]
    public List<string> movieIds { get; set; } = null!;

}
```

There are a few things happening in the above class that take it from a standard C# class to something that can integrate seamlessly into a MongoDB document.

First, you might notice the following:

```csharp
[BsonId]
[BsonRepresentation(BsonType.ObjectId)]
public string? Id { get; set; }
```

We're saying that the `Id` field is to be represented as an ObjectId in BSON and the `_id` field within MongoDB. However, when we work with it locally in our application, it will be a string.

The next thing you'll notice is the following:

```csharp
[BsonElement("items")]
[JsonPropertyName("items")]
public List<string> movieIds { get; set; } = null!;
```

Even though we plan to work with `movieIds` within our C# application, in MongoDB, the field will be known as `items` and when sending or receiving JSON, the field will also be known as `items` instead of `movieIds`.

You don't need to define custom mappings if you plan to have your local class field match the document field directly. Take the `username` field in our example. It has no custom mappings, so it will be `username` in C#, `username` in JSON, and `username` in MongoDB.

Just like that, we have a MongoDB service and document model for our collection to work with for .NET Core.

## Building CRUD Endpoints that Interact with MongoDB Using .NET Core

When building CRUD endpoints for this project, we'll need to bounce between two different locations within our project. We'll need to define the endpoint within a controller and do the work within our service.

Create "Controllers/PlaylistController.cs" and add the following code:

```csharp
using System;
using Microsoft.AspNetCore.Mvc;
using MongoExample.Services;
using MongoExample.Models;

namespace MongoExample.Controllers; 

[Controller]
[Route("api/[controller]")]
public class PlaylistController: Controller {
    
    private readonly MongoDBService _mongoDBService;

    public PlaylistController(MongoDBService mongoDBService) {
        _mongoDBService = mongoDBService;
    }

    [HttpGet]
    public async Task<List<Playlist>> Get() {}

    [HttpPost]
    public async Task<IActionResult> Post([FromBody] Playlist playlist) {}

    [HttpPut("{id}")]
    public async Task<IActionResult> AddToPlaylist(string id, [FromBody] string movieId) {}

    [HttpDelete("{id}")]
    public async Task<IActionResult> Delete(string id) {}

}
```

In the above `PlaylistController` class, we have a constructor method that gains access to our singleton service class. Then we have a series of endpoints for this particular controller. We could add far more endpoints than this to our controller, but it's not necessary for this example.

Let's start with creating data through the POST endpoint. To do this, it's best to start in the "Services/MongoDBService.cs" file:

```csharp
public async Task CreateAsync(Playlist playlist) {
    await _playlistCollection.InsertOneAsync(playlist);
    return;
}
```

We had set the `_playlistCollection` in the constructor method of the service, so we can now use the `InsertOneAsync` method, taking a passed `Playlist` variable and inserting it. Jumping back into the "Controllers/PlaylistController.cs," we can add the following:

```csharp
[HttpPost]
public async Task<IActionResult> Post([FromBody] Playlist playlist) {
    await _mongoDBService.CreateAsync(playlist);
    return CreatedAtAction(nameof(Get), new { id = playlist.Id }, playlist);
}
```

What we're saying is that when the endpoint is executed, we take the `Playlist` object from the request, something that .NET Core parses for us, and pass it to the `CreateAsync` function that we saw in the service. After the insert, we return some information about the interaction.

It's important to note that in this example project, we won't be validating any data flowing from HTTP requests.

Let's jump to the read operations.

Head back into the "Services/MongoDBService.cs" file and add the following function:

```csharp
public async Task<List<Playlist>> GetAsync() {
    return await _playlistCollection.Find(new BsonDocument()).ToListAsync();
}
```

The above `Find` operation will return all documents that exist in the collection. If you wanted to, you could make use of the `FindOne` or provide filter criteria to return only the data that you want. We'll explore filters shortly.

With the service function ready, add the following endpoint to the "Controllers/PlaylistController.cs" file:

```csharp
[HttpGet]
public async Task<List<Playlist>> Get() {
    return await _mongoDBService.GetAsync();
}
```

Not so bad, right? We'll be doing the same thing for the other endpoints, more or less.

The next CRUD stage to take care of is the updating of data. Within the "Services/MongoDBService.cs" file, add the following function:

```csharp
public async Task AddToPlaylistAsync(string id, string movieId) {
    FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("Id", id);
    UpdateDefinition<Playlist> update = Builders<Playlist>.Update.AddToSet<string>("movieIds", movieId);
    await _playlistCollection.UpdateOneAsync(filter, update);
    return;
}
```

Rather than making changes to the entire document, we're planning on adding an item to our playlist and nothing more. To do this, we set up a match filter to determine which document or documents should receive the update. In this case, we're matching on the id which is going to be unique. Next, we're defining the update criteria, which is an `AddToSet` operation that will only add an item to the array if it doesn't already exist in the array.

The `UpdateOneAsync` method will only update one document even if the match filter returned more than one match.

In the "Controllers/PlaylistController.cs" file, add the following endpoint to pair with the `AddToPlayListAsync` function:

```csharp
[HttpPut("{id}")]
public async Task<IActionResult> AddToPlaylist(string id, [FromBody] string movieId) {
    await _mongoDBService.AddToPlaylistAsync(id, movieId);
    return NoContent();
}
```

In the above PUT endpoint, we are taking the `id` from the route parameters and the `movieId` from the request body and using them with the `AddToPlaylistAsync` function.

This brings us to our final part of the CRUD spectrum. We're going to handle deleting of data.

In the "Services/MongoDBService.cs" file, add the following function:

```csharp
public async Task DeleteAsync(string id) {
    FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("Id", id);
    await _playlistCollection.DeleteOneAsync(filter);
    return;
}
```

The above function will delete a single document based on the filter criteria. The filter criteria, in this circumstance, is a match on the id which is always going to be unique. Your filters could be more extravagant if you wanted.

To bring it to an end, the endpoint for this function would look like the following in the "Controllers/PlaylistController.cs" file:

```csharp
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(string id) {
    await _mongoDBService.DeleteAsync(id);
    return NoContent();
}
```

We only created four endpoints, but you could take everything we did and create 100 more if you wanted to. They would all use a similar strategy and can leverage everything that MongoDB has to offer.

## Conclusion

You just saw how to create a simple four endpoint RESTful API using .NET Core and MongoDB. This was an expansion to the [previous tutorial](https://www.mongodb.com/developer/how-to/build-first-dotnet-core-application-mongodb-atlas/), which went over the same usage of MongoDB, but in a console application format rather than web application.

Like I mentioned, you can take the same strategy used here and apply it towards more endpoints, each doing something critical for your web application.

Got a question about the driver for .NET? Swing by the [MongoDB Community Forums](https://community.mongodb.com)!

Learn how to create a RESTful web API with .NET Core that interacts with MongoDB through each of its endpoints.

Create a RESTful API with .NET Core and MongoDB

If you've ever glanced at a map to find the closest lunch spots to you, you've most likely used a geospatial query under the hood! In this tutorial, we'll learn how to store geospatial data in MongoDB Atlas and how to work with geospatial queries in the MongoDB C# driver.

MongoDB Geospatial Queries in C#

*(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

If you've been keeping up with my .NET Core series on MongoDB, you'll remember that we explored [creating a simple console application](https://www.mongodb.com/developer/how-to/build-first-dotnet-core-application-mongodb-atlas/) as well as [building a RESTful API](https://www.mongodb.com/developer/how-to/create-restful-api-dotnet-core-mongodb/) with basic CRUD support. In both examples, we used basic filters when interacting with MongoDB from our applications.

But what if we need to do something a bit more complex, like join data from two different MongoDB collections?

In this tutorial, we're going to take a look at aggregation pipelines and some of the ways that you can work with them in a .NET Core application.

## The Requirements

Before we get started, there are a few requirements that must be met to be successful:

- Have a MongoDB Atlas cluster deployed and configured.
- Install .NET Core 6+.
- Install the MongoDB sample data sets.

We will be using .NET Core 6.0 for this particular tutorial. Older or newer versions might work, but there's a chance that some of the commands may be a little different. The expectation is that you already have a MongoDB Atlas cluster ready to go. This could be a free M0 cluster or better, but you'll need it properly configured with user roles and network access rules. You'll also need the MongoDB sample data sets to be attached.

If you need help with this, check out a [previous tutorial](https://www.mongodb.com/developer/article/5-different-ways-deploy-free-database-mongodb-atlas/) I wrote on the topic.

## A Closer Look at the Data Model and Expected Outcomes

Because we're expecting to accomplish some fairly complicated things in this tutorial, it's probably a good idea to break down the data going into it and the data that we're expecting to come out of it.

In this tutorial, we're going to be using the **sample_mflix** database and the **movies** collection. We're also going to be using a custom **playlist** collection that we're going to add to the **sample_mflix** database.

To give you an idea of the data that we're going to be working with, take the following document from the **movies** collection:

```json
{
    "_id": ObjectId("573a1390f29313caabcd4135"),
    "title": "Blacksmith Scene",
    "plot": "Three men hammer on an anvil and pass a bottle of beer around.",
    "year": 1893,
    // ...
}
```

Alright, so I didn't include the entire document because it is actually quite huge. Knowing every single field is not going to help or hurt the example as long as we're familiar with the `_id` field.

Next, let's look at a document in the proposed **playlist** collection:

```json
{
    "_id": ObjectId("61d8bb5e2d5fe0c2b8a1007d"),
    "username": "nraboy",
    "items": [
        "573a1390f29313caabcd42e8",
        "573a1391f29313caabcd8a82"
    ]
}
```

Knowing the fields in the above document is important as they'll be used throughout our aggregation pipelines.

One of the most important things to take note of between the two collections is the fact that the `_id` fields are `ObjectId` and the values in the `items` field are strings. More on this as we progress.

Now that we know our input documents, let's take a look at what we're expecting as a result of our queries. If I were to query for a playlist, I don't want the id values for each of the movies. I want them fully expanded, like the following:

```json
{
    "_id": ObjectId("61d8bb5e2d5fe0c2b8a1007d"),
    "username": "nraboy",
    "items": [
        {
            "_id": ObjectId("573a1390f29313caabcd4135"),
            "title": "Blacksmith Scene",
            "plot": "Three men hammer on an anvil and pass a bottle of beer around.",
            "year": 1893,
            // ...
        },
        {
            "_id": ObjectId("573a1391f29313caabcd8a82"),
            "title": "The Terminator",
            "plot": "A movie about some killer robots.",
            "year": 1984,
            // ...
        }
    ]
}
```

This is where the aggregation pipelines come in and some joining because we can't just do a normal filter on a `Find` operation, unless we wanted to perform multiple `Find` operations.

## Creating a New .NET Core Console Application with MongoDB Support

To keep things simple, we're going to be building a console application that uses our aggregation pipeline. You can take the logic and apply it towards a web application if that is what you're interested in.

From the CLI, execute the following:

```bash
dotnet new console -o MongoExample
cd MongoExample
dotnet add package MongoDB.Driver
```

The above commands will create a new .NET Core project and install the latest MongoDB driver for C#. Everything we do next will happen in the project's "Program.cs" file.

Open the "Program.cs" file and add the following C# code:

```csharp
using MongoDB.Driver;
using MongoDB.Bson;

MongoClient client = new MongoClient("ATLAS_URI_HERE");

IMongoCollection<BsonDocument> playlistCollection  = client.GetDatabase("sample_mflix").GetCollection<BsonDocument>("playlist");

List<BsonDocument> results = playlistCollection.Find(new BsonDocument()).ToList();

foreach(BsonDocument result in results) {
    Console.WriteLine(result["username"] + ": " + string.Join(", ", result["items"]));
}
```

The above code will connect to a MongoDB cluster, get a reference to our **playlist** collection, and dump all the documents from that collection into the console. Finding and returning all the documents in the collection is not a requirement for the aggregation pipeline, but it might help with the learning process.

The `ATLAS_URI_HERE` string can be obtained from the [MongoDB Atlas Dashboard](https://cloud.mongodb.com/) after clicking "Connect" for a particular cluster.

## Building an Aggregation Pipeline with .NET Core Using Raw BsonDocument Stages

We're going to explore a few different options towards creating an aggregation pipeline query with .NET Core. The first will use raw `BsonDocument` type data.

We know our input data and we know our expected outcome, so we need to come up with a few pipeline stages to bring it together.

Let's start with the first stage:

```csharp
BsonDocument pipelineStage1 = new BsonDocument{
    {
        "$match", new BsonDocument{
            { "username", "nraboy" }
        }
    }
};
```

The first stage of this pipeline uses the `$match` operator to find only documents where the `username` is "nraboy." This could be more than one because we're not treating `username` as a unique field.

With the filter in place, let's move to the next stage:

```csharp
BsonDocument pipelineStage2 = new BsonDocument{
    { 
        "$project", new BsonDocument{
            { "_id", 1 },
            { "username", 1 },
            { 
                "items", new BsonDocument{
                    {
                        "$map", new BsonDocument{
                            { "input", "$items" },
                            { "as", "item" },
                            {
                                "in", new BsonDocument{
                                    {
                                        "$convert", new BsonDocument{
                                            { "input", "$$item" },
                                            { "to", "objectId" }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
};
```

Remember how the document `_id` fields were ObjectId and the `items` array were strings? For the join to be successful, they need to be of the same type. The second pipeline stage is more of a manipulation stage with the `$project` operator. We're defining the fields we want passed to the next stage, but we're also modifying some of the fields, in particular the `items` field. Using the `$map` operator we can take the string values and convert them to ObjectId values.

If your `items` array contained ObjectId instead of string values, this particular stage wouldn't be necessary. It might also not be necessary if you're using POCO classes instead of `BsonDocument` types. That is a lesson for another day though.

With our item values mapped correctly, we can push them to the next stage in the pipeline:

```csharp
BsonDocument pipelineStage3 = new BsonDocument{
    {
        "$lookup", new BsonDocument{
            { "from", "movies" },
            { "localField", "items" },
            { "foreignField", "_id" },
            { "as", "movies" }
        }
    }
};
```

The above pipeline stage is where the JOIN operation actually happens. We're looking into the **movies** collection and we're using the ObjectId fields from our **playlist** collection to join them to the `_id` field of our **movies** collection. The output from this JOIN will be stored in a new `movies` field.

The `$lookup` is like saying the following:

```
SELECT movies
FROM playlist
JOIN movies ON playlist.items = movies._id
```

Of course there is more to it than the above SQL statement because `items` is an array, something you can't natively work with in most SQL databases.

So as of right now, we have our joined data. However, its not quite as elegant as what we wanted in our final outcome. This is because the `$lookup` output is an array which will leave us with a multidimensional array. Remember, `items` was an array and each `movies` is an array. Not the most pleasant thing to work with, so we probably want to further manipulate the data in another stage.

```csharp
BsonDocument pipelineStage4 = new BsonDocument{
    { "$unwind", "$movies" }
};
```

The above stage will take our new `movies` field and flatten it out with the `$unwind` operator. The `$unwind` operator basically takes each element of an array and creates a new result item to sit adjacent to the rest of the fields of the parent document. So if you have, for example, one document that has an array with two elements, after doing an `$unwind`, you'll have two documents.

Our end goal, though, is to end up with a single dimension array of movies, so we can fix this with another pipeline stage.

```csharp
BsonDocument pipelineStage5 = new BsonDocument{
    {
        "$group", new BsonDocument{
            { "_id", "$_id" },
            { 
                "username", new BsonDocument{
                    { "$first", "$username" }
                } 
            },
            { 
                "movies", new BsonDocument{
                    { "$addToSet", "$movies" }
                }
            }
        }
    }
};
```

The above stage will group our documents and add our unwound movies to a new `movies` field, one that isn't multidimensional.

So let's bring the pipeline stages together so they can be run in our application.

```csharp
BsonDocument[] pipeline = new BsonDocument[] { 
    pipelineStage1, 
    pipelineStage2, 
    pipelineStage3, 
    pipelineStage4, 
    pipelineStage5 
};

List<BsonDocument> pResults = playlistCollection.Aggregate<BsonDocument>(pipeline).ToList();

foreach(BsonDocument pResult in pResults) {
    Console.WriteLine(pResult);
}
```

Executing the code thus far should give us our expected outcome in terms of data and format.

Now, you might be thinking that the above five-stage pipeline was a lot to handle for a JOIN operation. There are a few things that you should be aware of:

- Our id values were not of the same type, which resulted in another stage.
- Our values to join were in an array, not a one-to-one relationship.

What I'm trying to say is that the length and complexity of your pipeline is going to depend on how you've chosen to model your data.

## Using a Fluent API to Build Aggregation Pipeline Stages

Let's look at another way to accomplish our desired outcome. We can make use of the Fluent API that MongoDB offers instead of creating an array of pipeline stages.

Take a look at the following:

```csharp
var pResults = playlistCollection.Aggregate()
    .Match(new BsonDocument{{ "username", "nraboy" }})
    .Project(new BsonDocument{
            { "_id", 1 },
            { "username", 1 },
            {
                "items", new BsonDocument{
                    {
                        "$map", new BsonDocument{
                            { "input", "$items" },
                            { "as", "item" },
                            {
                                "in", new BsonDocument{
                                    {
                                        "$convert", new BsonDocument{
                                            { "input", "$$item" },
                                            { "to", "objectId" }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        })
    .Lookup("movies", "items", "_id", "movies")
    .Unwind("movies")
    .Group(new BsonDocument{
            { "_id", "$_id" },
            {
                "username", new BsonDocument{
                    { "$first", "$username" }
                }
            },
            {
                "movies", new BsonDocument{
                    { "$addToSet", "$movies" }
                }
            }
        })
    .ToList();

foreach(var pResult in pResults) {
    Console.WriteLine(pResult);
}
```

In the above example, we used methods such as `Match`, `Project`, `Lookup`, `Unwind`, and `Group` to get our final result. For some of these methods, we didn't need to use a `BsonDocument` like we saw in the previous example.

## Conclusion

You just saw two ways to do a MongoDB aggregation pipeline for joining collections within a .NET Core application. Like previously mentioned, there are a few ways to accomplish what we want, all of which are going to be dependent on how you've chosen to model the data within your collections.

There is a third way, which we'll explore in another tutorial, and this uses LINQ to get the job done.

If you have questions about anything you saw in this tutorial, drop by the [MongoDB Community Forums](https://community.mongodb.com) and get involved!

Learn how to use the MongoDB aggregation pipeline to create stages that will join documents and collections in a .NET Core application.

Joining Collections in MongoDB with .NET Core and an Aggregation Pipeline



<div class="introduction">

Are you working on a game in [Unity](https://unity.com/) and finding yourself needing to make use of a database in the cloud? Storing your data locally works for a lot of games, but there are many gaming scenarios where you'd need to leverage an external database. Maybe you need to submit your high score for a leaderboard, or maybe you need to save your player stats and inventory so you can play on numerous devices. There are too many reasons to list as to why a remote database might make sense for your game.

If you've been keeping up with the content publishing on the [MongoDB Developer Hub](https://developer.mongodb.com) and our [Twitch](https://www.twitch.tv/mongodb) channel, you'll know that I'm working on a game development series with [Adrienne Tacke](https://www.twitter.com/adriennetacke). This series is centered around creating a 2D multiplayer game with Unity that uses MongoDB as part of the online component. Up until now, we haven't actually had the game communicate with MongoDB.

In this tutorial, we're going to see how to make HTTP requests from a Unity game to a back end that communicates with [MongoDB](https://www.mongodb.com). The back end was already developed in a tutorial titled, [Creating a User Profile Store for a Game With Node.js and MongoDB](https://developer.mongodb.com/how-to/creating-user-profile-store-game-nodejs-mongodb). We're now going to leverage it in our game.

To get an idea where we're at in the tutorial series, take a look at the animated image below:

![Plummeting People Fake Doors Example](https://www.mongodb.com/developer/images/how-to/plummeting-people-fake-doors-example.gif)

To take this to the next level, it makes sense to send data to MongoDB when the player crosses the finish line. For example, we can send how many steps were taken by the player in order to reach the finish line, or how many times the player collided with something, or even what place the player ranked in upon completion. The data being sent doesn't truly matter as of now.

The assumption is that you've been following along with the tutorial series and are jumping in where we left off. If not, some of the steps that refer to our project may not make sense, but the concepts can be applied in your own game. The tutorials in this series so far are:

-   [Designing a Strategy to Develop a Game with Unity and MongoDB](https://developer.mongodb.com/how-to/designing-strategy-develop-game-unity-mongodb)
-   [Creating a User Profile Store for a Game with Node.js and MongoDB](https://developer.mongodb.com/how-to/creating-user-profile-store-game-nodejs-mongodb)
-   [Getting Started with Unity for Creating a 2D Game](https://developer.mongodb.com/how-to/getting-started-unity-creating-2d-game)
-   [Designing and Developing 2D Game Levels with Unity and C#](https://developer.mongodb.com/how-to/designing-developing-2d-game-levels-unity-csharp)

If you'd like to view the source code to the project, it can be found on [GitHub](https://github.com/mongodb-developer/plummeting-people-game).

## Creating a C# Class in Unity to Represent the Data Model Within MongoDB

Because Unity, as of now, doesn't have an official MongoDB driver, sending and receiving MongoDB data from Unity isn't handled for you. We're going to have to worry about marshalling and unmarshalling our data as well as making the request. In other words, we're going to need to manipulate our data manually to and from JSON and C# classes.

To make this possible, we're going to need to start with a class that represents our data model in MongoDB.

Within your project's **Assets/Scripts** directory, create a **PlayerData.cs** file with the following code:

``` csharp
using UnityEngine;

public class PlayerData
{
    public string plummie_tag;
    public int collisions;
    public int steps;
}
```

Notice that this class does not extend the `MonoBehavior` class. This is because we do not plan to attach this script as a component on a game object. The `public`-defined properties in the `PlayerData` class represent each of our database fields. In the above example, we only have a select few, but you could add everything from our user profile store if you wanted to.

It is important to use the `public` identifier for anything that will have relevance to the database.

We need to make a few more changes to the `PlayerData` class. Add the following functions to the class:

``` csharp
using UnityEngine;

public class PlayerData
{
    // 'public' variables here ...

    public string Stringify() 
    {
        return JsonUtility.ToJson(this);
    }

    public static PlayerData Parse(string json)
    {
        return JsonUtility.FromJson<PlayerData>(json);
    }
}
```

Notice the function names are kind of like what you'd find in JavaScript if you are a JavaScript developer. Unity expects us to send string data in our requests rather than objects. The good news is that Unity also provides a helper `JsonUtility` class that will convert objects to strings and strings to objects.

The `Stringify` function will take all `public` variables in the class and convert them to a JSON string. The fields in the JSON object will match the names of the variables in the class. The `Parse` function will take a JSON string and convert it back into an object that can be used within C#.

## Sending Data with POST and Retrieving Data with GET in a Unity Game

With a class available to represent our data model, we can now send data to MongoDB as well as retrieve it. Unity provides a [UnityWebRequest](https://docs.unity3d.com/ScriptReference/Networking.UnityWebRequest.html) class for making HTTP requests within a game. This will be used to communicate with either a back end designed with a particular programming language or a [MongoDB Realm](https://www.mongodb.com/realm) webhook. If you'd like to learn about creating a back end to be used with a game, check out my [previous tutorial](https://developer.mongodb.com/how-to/creating-user-profile-store-game-nodejs-mongodb) on the topic.

We're going to spend the rest of our time in the project's **Assets/Scripts/Player.cs** file. This script is attached to our player as a component and was created in the tutorial titled, [Getting Started with Unity for Creating a 2D Game](https://developer.mongodb.com/how-to/getting-started-unity-creating-2d-game). In your own game, it doesn't really matter which game object script you use.

Open the **Assets/Scripts/Player.cs** file and make sure it looks similar to the following:

``` csharp
using UnityEngine;
using System.Text;
using UnityEngine.Networking;
using System.Collections;

public class Player : MonoBehaviour
{
    public float speed = 1.5f;

    private Rigidbody2D _rigidBody2D;
    private Vector2 _movement;

    void Start()
    {
        _rigidBody2D = GetComponent<Rigidbody2D>();
    }

    void Update()
    {
        // Mouse and keyboard input logic here ...
    }

    void FixedUpdate() {
        // Physics related updates here ...
    }
}
```

I've stripped out a bunch of code from the [previous tutorial](https://developer.mongodb.com/how-to/designing-developing-2d-game-levels-unity-csharp) as it doesn't affect anything we're planning on doing. The previous code was very heavily related to moving the player around on the screen and should be left in for the real game, but is overlooked in this example, at least for now.

Two things to notice that are important are the imports:

``` csharp
using System.Text;
using UnityEngine.Networking;
```

The above two imports are important for the networking features of Unity. Without them, we wouldn't be able to properly make GET and POST requests.

Before we make a request, let's get our `PlayerData` class included. Make the following changes to the **Assets/Scripts/Player.cs** code:

``` csharp
using UnityEngine;
using System.Text;
using UnityEngine.Networking;
using System.Collections;

public class Player : MonoBehaviour
{
    public float speed = 1.5f;

    private Rigidbody2D _rigidBody2D;
    private Vector2 _movement;
    private PlayerData _playerData;

    void Start()
    {
        _rigidBody2D = GetComponent<Rigidbody2D>();
        _playerData = new PlayerData();
        _playerData.plummie_tag = "nraboy";
    }

    void Update() { }

    void FixedUpdate() { }

    void OnCollisionEnter2D(Collision2D collision) 
    {
        _playerData.collisions++;
    }
}
```

In the above code, notice that we are creating a new `PlayerData` object and assigning the `plummie_tag` field a value. We're also making use of an `OnCollisionEnter2D` function to see if our game object collides with anything. Since our function is very vanilla, collisions can be with walls, objects, etc., and nothing in particular. The collisions will increase the `collisions` counter.

So, we have data to work with, data that we need to send to MongoDB. To do this, we need to create some `IEnumerator` functions and make use of coroutine calls within Unity. This will allow us to do asynchronous activities such as make web requests.

Within the **Assets/Scripts/Player.cs** file, add the following `IEnumerator` function:

``` csharp
IEnumerator Download(string id, System.Action<PlayerData> callback = null)
{
    using (UnityWebRequest request = UnityWebRequest.Get("http://localhost:3000/plummies/" + id))
    {
        yield return request.SendWebRequest();

        if (request.isNetworkError || request.isHttpError)
        {
            Debug.Log(request.error);
            if (callback != null)
            {
                callback.Invoke(null);
            }
        }
        else
        {
            if (callback != null)
            {
                callback.Invoke(PlayerData.Parse(request.downloadHandler.text));
            }
        }
    }
}
```

The `Download` function will be responsible for retrieving data from our database to be brought into the Unity game. It is expecting an `id` which we'll use a `plummie_id` for and a `callback` so we can work with the response outside of the function. The response should be `PlayerData` which is that of the data model we just made.

After sending the request, we check to see if there were errors or if it succeeded. If the request succeeded, we can convert the JSON string into an object and invoke the callback so that the parent can work with the result.

Sending data with a payload, like that in a POST request, is a bit different. Take the following function:

``` csharp
IEnumerator Upload(string profile, System.Action<bool> callback = null)
{
    using (UnityWebRequest request = new UnityWebRequest("http://localhost:3000/plummies", "POST"))
    {
        request.SetRequestHeader("Content-Type", "application/json");
        byte[] bodyRaw = Encoding.UTF8.GetBytes(profile);
        request.uploadHandler = new UploadHandlerRaw(bodyRaw);
        request.downloadHandler = new DownloadHandlerBuffer();
        yield return request.SendWebRequest();

        if (request.isNetworkError || request.isHttpError)
        {
            Debug.Log(request.error);
            if(callback != null) 
            {
                callback.Invoke(false);
            }
        }
        else
        {
            if(callback != null) 
            {
                callback.Invoke(request.downloadHandler.text != "{}");
            }
        }
    }
}
```

In the `Upload` function, we are expecting a JSON string of our profile. This profile was defined in the `PlayerData` class and it is the same data we received in the `Download` function.

The difference between these two functions is that the POST is sending a payload. For this to work, the JSON string needs to be converted to `byte[]` and the upload and download handlers need to be defined. Once this is done, it is business as usual.

It is up to you what you want to return back to the parent. Because we are creating data, I thought it'd be fine to just return `true` if successful and `false` if not. To demonstrate this, if there are no errors, the response is compared against an empty object string. If an empty object comes back, then false. Otherwise, true. This probably isn't the best way to respond after a creation, but that is up to the creator (you, the developer) to decide.

The functions are created. Now, we need to use them.

Let's make a change to the `Start` function:

``` csharp
void Start()
{
    _rigidBody2D = GetComponent<Rigidbody2D>();
    _playerData = new PlayerData();
    _playerData.plummie_tag = "nraboy";
    StartCoroutine(Download(_playerData.plummie_tag, result => {
        Debug.Log(result);
    }));
}
```

When the script runs—or in our, example when the game runs—and the player enters the scene, the `StartCoroutine` method is executed. We are providing the `plummie_tag` as our lookup value and we are printing out the results that come back.

We might want the `Upload` function to behave a little differently. Instead of making the request immediately, maybe we want to make the request when the player crosses the finish line. For this, maybe we add some logic to the `FixedUpdate` method instead:

``` csharp
void FixedUpdate() 
{
    // Movement logic here ...

    if(_rigidBody2D.position.x > 24.0f) {
        StartCoroutine(Upload(_playerData.Stringify(), result => {
            Debug.Log(result);
        }));
    }
}
```

In the above code, we check to see if the player position is beyond a certain value in the x-axis. If this is true, we execute the `Upload` function and print the results.

The above example isn't without issues though. As of now, if we cross the finish line, we're going to experience many requests as our code will continuously execute. We can correct this by adding a boolean variable into the mix.

At the top of your **Assets/Scripts/Player.cs** file with the rest of your variable declarations, add the following:

``` csharp
private bool _isGameOver;
```

The idea is that when the `_isGameOver` variable is true, we shouldn't be executing certain logic such as the web requests. We are going to initialize the variable as false in the `Start` method like so:

``` csharp
void Start()
{
    // Previous code here ...
    _isGameOver = false;
}
```

With the variable initialized, we can make use of it prior to sending an HTTP request after crossing the finish line. To do this, we'd make a slight adjustment to the code like so:

``` csharp
void FixedUpdate() 
{
    // Movement logic here ...

    if(_rigidBody2D.position.x > 24.0f && _isGameOver == false) {
        StartCoroutine(Upload(_playerData.Stringify(), result => {
            Debug.Log(result);
        }));
        _isGameOver = true;
    }
}
```

After the player crosses the finish line, the HTTP code is executed and the game is marked as game over for the player, preventing further requests.

## Conclusion

You just saw how to use the `UnityWebRequest` class in Unity to make HTTP requests from a game to a remote web server that communicates with MongoDB. This is valuable for any game that needs to either store game information remotely or retrieve it.

There are plenty of other ways to make use of the `UnityWebRequest` class, even in our own player script, but the examples we used should be a great starting point.

This tutorial series is part of a series streamed on Twitch. To see these streams live as they happen, follow the [Twitch](https://www.twitch.tv/mongodb) channel and tune in.

Learn how to interact with MongoDB from a Unity game with C# and the UnityWebRequest class.

Sending and Requesting Data from MongoDB in a Unity Game

Robert Walters

>Update 10/2019: This article's code example has been updated to include
the required handing of the session handle to database methods.

<div class="introduction">

C# applications connected to a MongoDB database use the MongoDB .NET driver. To add the .NET driver to your Visual Studio Application, in the NuGet Package Manager, search for "MongoDB".

<figure>
<img src="https://www.mongodb.com/developer/images/driverdownload.png" width="300" />
</figure>

Make sure you choose the latest version (>=2.7) of the driver, and press *Install*.

Prior to MongoDB version 4.0, MongoDB was transactionally consistent at the document level. These existing atomic single-document operations provide the transaction semantics to meet the data integrity needs of the majority of applications. This is because the flexibility of the document model allows developers to easily embed related data for an entity as arrays and sub-documents within a single, rich document. That said, there are some cases where splitting the content into two or more collections would be appropriate, and for these cases, [multi-document ACID transactions](https://www.mongodb.com/transactions) makes it easier than ever for developers to address the full spectrum of use cases with MongoDB. For a deeper discussion on MongoDB document model design, including how to represent one-to-many and many-to-many relationships, check out [this article on data model design](https://docs.mongodb.com/manual/core/data-model-design).

In the following code we will create a Product object and perform a MongoDB transaction that will insert some sample data into MongoDB then update the prices for all products by 10%.

``` csp
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Driver;
using System;
using System.Threading.Tasks;

namespace MongoDBTransaction
{
    public static class Program
    {
        public class Product
        {
            [BsonId]
            public ObjectId Id { get; set; }
            [BsonElement("SKU")]
            public int SKU { get; set; }
            [BsonElement("Description")]
            public string Description { get; set; }
            [BsonElement("Price")]
            public Double Price { get; set; }
        }

        // replace with your connection string if it is different
        const string MongoDBConnectionString = "mongodb://localhost"; 

        public static async Task Main(string[] args)
        {
            if (!await UpdateProductsAsync()) { Environment.Exit(1); }
            Console.WriteLine("Finished updating the product collection");
            Console.ReadKey();
        }

        private static async Task<bool> UpdateProductsAsync()
        {
            // Create client connection to our MongoDB database
            var client = new MongoClient(MongoDBConnectionString);

            // Create the collection object that represents the "products" collection
            var database = client.GetDatabase("MongoDBStore");
            var products = database.GetCollection<Product>("products");

            // Clean up the collection if there is data in there
            await database.DropCollectionAsync("products");

            // collections can't be created inside a transaction so create it first
            await database.CreateCollectionAsync("products"); 

            // Create a session object that is used when leveraging transactions
            using (var session = await client.StartSessionAsync())
            {
                // Begin transaction
                session.StartTransaction();

                try
                {
                    // Create some sample data
                    var tv = new Product { Description = "Television", 
                                    SKU = 4001, 
                                    Price = 2000 };
                    var book = new Product { Description = "A funny book", 
                                    SKU = 43221, 
                                    Price = 19.99 };
                    var dogBowl = new Product { Description = "Bowl for Fido", 
                                    SKU = 123, 
                                    Price = 40.00 };

                    // Insert the sample data 
                    await products.InsertOneAsync(session, tv);
                    await products.InsertOneAsync(session, book);
                    await products.InsertOneAsync(session, dogBowl);

                    var resultsBeforeUpdates = await products
                                    .Find<Product>(session, Builders<Product>.Filter.Empty)
                                    .ToListAsync();
                    Console.WriteLine("Original Prices:\n");
                    foreach (Product d in resultsBeforeUpdates)
                    {
                        Console.WriteLine(
                                    String.Format("Product Name: {0}\tPrice: {1:0.00}", 
                                        d.Description, d.Price)
                        );
                    }

                    // Increase all the prices by 10% for all products
                    var update = new UpdateDefinitionBuilder<Product>()
                            .Mul<Double>(r => r.Price, 1.1);
                    await products.UpdateManyAsync(session, 
                            Builders<Product>.Filter.Empty, 
                            update); //,options);

                    // Made it here without error? Let's commit the transaction
                    await session.CommitTransactionAsync();
                }
                catch (Exception e)
                {
                    Console.WriteLine("Error writing to MongoDB: " + e.Message);
                    await session.AbortTransactionAsync();
                    return false;
                }

                // Let's print the new results to the console
                Console.WriteLine("\n\nNew Prices (10% increase):\n");
                var resultsAfterCommit = await products
                        .Find<Product>(session, Builders<Product>.Filter.Empty)
                        .ToListAsync();
                foreach (Product d in resultsAfterCommit)
                {
                    Console.WriteLine(
                        String.Format("Product Name: {0}\tPrice: {1:0.00}", 
                                                    d.Description, d.Price)
                    );
                }

                return true;
            }
        }
    }
}
```

Source Code available on [Gist](https://gist.github.com/codepope/1366893d703a0be57953545619e87eea). Successful execution yields the following:

<figure>
<img src="https://www.mongodb.com/developer/images/ExecutionResults-5aao2jdet7.png" width="400" />
</figure>

## Key points:

-   You don't have to match class properties to JSON objects - just define a class object and insert it directly into the database. There is no need for an Object Relational Mapper (ORM) layer.
-   MongoDB transactions use snapshot isolation meaning only the client involved in the transactional session sees any changes until such time as the transaction is committed.
-   The MongoDB .NET Driver makes it easy to leverage transactions and leverage LINQ based syntax for queries.

Additional information about using C# and the .NET driver can be found in the [C# and .NET MongoDB Driver](https://docs.mongodb.com/ecosystem/drivers/csharp/) documentation.

Walk through an example of how to use transactions in C#.

Working with MongoDB Transactions with C# and the .NET Framework

Ferdinando Papale

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

How to Use Realm Effectively in a Xamarin.Forms App

# Introducing the MongoDB Analyzer for .NET
Correct code culprits at compile time!

As C# and .NET developers, we know that it can sometimes be frustrating to work idiomatically with MongoDB queries and aggregations. Without a way to see if your LINQ query or Builder expression corresponds to the [MongoDB Query API](https://www.mongodb.com/mongodb-query-api) (formerly known as MQL) during development, you previously had to wait for runtime errors in order to troubleshoot your queries. We knew there had to be a way to work more seamlessly with C# and MongoDB.

That’s why we’ve built the [MongoDB Analyzer for .NET](https://docs.mongodb.com/mongodb-analyzer/current/)! Instead of mentally mapping the idiomatic version of your query in C# to the MongoDB Query API, the MongoDB Analyzer can do it for you - and even provide the generated Query API expression right in your IDE. The MongoDB Analyzer even surfaces useful information and helpful warnings on invalid expressions at compile time, bringing greater visibility to the root causes of bugs. And when used together with the recently released [LINQ3](https://mongodb.github.io/mongo-csharp-driver/2.14/reference/driver/crud/linq3/) provider (now supported in [MongoDB C#/.NET Driver](https://docs.mongodb.com/drivers/csharp/) 2.14.0 and higher), you can compose and understand queries in a much more manageable way.

Let’s take a look at how to install and use the new MongoDB Analyzer as a NuGet package. We’ll follow with some code samples so you can see why this is a must-have tool for Visual Studio!

## Install MongoDB Analyzer as a NuGet Package
In Visual Studio, install the `MongoDB.Analyzer` [NuGet package](https://www.nuget.org/packages/MongoDB.Analyzer/1.0.0):

*Package Manager*

```
Install-Package MongoDB.Analyzer -Version 1.0.0
```

*.NET CLI*

```
dotnet add package MongoDB.Analyzer --version 1.0.0
```

Once installed, it will be added to your project’s Dependencies list, under Analyzers:
![MongoDB.Analyzer shown within the Dependencies/Analyzers folder](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mongodb_analyzer_dependencies_c12f40e5e3.png)

After installing and once the analyzer has run, you’ll find all of the diagnostic warnings output to the Error List panel. As you start to inspect your code, you’ll also see that any unsupported expressions will be highlighted.

## Inspecting Information Messages and Warnings
As you write LINQ or Builders expressions, an information tooltip can be accessed by hovering over the three grey dots under your expression:

*Accessing the tooltip for a LINQ expression*
![Accessing the tooltip for a LINQ expression](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_linq_tooltip_0c75054f92.gif)

This tooltip displays the corresponding Query API language to the expression you are writing and updates in real-time! With the translated query at your tooltips, you can confirm the query being generated (and executed!) is the one you expect. 

This is a far more efficient process of composing and testing queries—focus on the invalid expressions instead of wasting time translating your code for the Query API! And if you ever need to copy the resulting queries generated, you can do so right from your IDE (from the Error List panel).

Another common issue the MongoDB Analyzer solves is surfacing unsupported expressions and invalid queries at compile time. You’ll find all of these issues listed as warnings:

*Unsupported expressions shown as warnings in Visual Studio’s Error List*
![Unsupported expressions shown as warnings in Visual Studio’s Error List](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/error_list_warnings_2b5ab48b2a.png)

This is quite useful as not all LINQ expressions are supported by the MongoDB C#/.NET driver. Similarly, supported expressions will differ depending on which version of LINQ you use.

## Code Samples—See the MongoDB Analyzer for .NET in Action
Now that we know what the MongoDB Analyzer can do for us, let’s see it live!

### Builder Expressions
These are a few examples that show how Builder expressions are analyzed. As you’ll see, the MongoDB Analyzer provides immediate feedback through the tooltip. Hovering over your code shows you the supported Query API language that corresponds to the query/expression you are writing.

*Builder Filter Definition - Filter movies by matching genre, score that is greater than or equal to minimum score, and a match on the title search term.*
![GIF showing a builder filter being implemented. Alternates between hovering over expression to show the tooltip and corresponding MongoDB Query API expression generated and adding to the builder filter.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_builder_filter_2f9735637d.gif)

*Builder Sort Definition - Sort movies by score (lowest to highest) and title (from Z to A).*
![GIF showing a builder sort definition being implemented. Tooltip is then shown with genereated MongoDB Query API expression.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_builder_sort_9754e9c33b.gif)

*Unsupported Builder Expression - Highlighted and shown as warning in Error List.*
![GIF showing unsupported builder expression being implemented. After being written, unsupported code is correctly highlighted; tooltip is shown warning developer of the unsupported expression and the warning is added to the Error List panel of the IDE.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_builder_unsupported_85c6967ea9.gif)

### LINQ Queries
The MongoDB Analyzer uses the default LINQ provider of the C#/.NET driver (LINQ2). Expressions that aren’t supported in LINQ2 but are supported in LINQ3 will show the appropriate warnings, as you’ll see in one of the following examples. If you’d like to switch the LINQ provider the MongoDB Analyzer uses, set` “DefaultLinqVersion”: “V3” `in the `mongodb.analyzer.json` file.

*LINQ Filter Query - Aggregation pipeline.*
![GIF showing a LINQ query being implemented with multiple conditions. Afterward, a tooltip with the corresponding MongoDB Query API expression is shown.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_linq_aggregation_79fa4031ee.gif)

*LINQ Query - Get movie genre statistics; uses aggregation pipeline to group by and select a dynamic object.*
![GIF showing a LINQ query being implemented that uses a group by statement and selection of a dynamic object. Afterward, a tooltip with the corresponding MongoDB Query API expression is shown.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_linq_groupby_select_f4711d32cd.gif)

*Unsupported LINQ Expression - GetHashCode() method unsupported.*
 ![GIF showing unsupported LINQ expression being implemented. After being written, unsupported code is correctly highlighted; tooltip is shown warning developer of the unsupported expression and the warning is added to the Error List panel of the IDE.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_linq_unsupported_bbd62a00fc.gif)

*Unsupported LINQ Expression - Method referencing a lambda parameter unsupported.*
![GIF showing unsupported LINQ expression being implemented. After being written, unsupported code is correctly highlighted; tooltip is shown warning developer of the unsupported expression and the warning is added to the Error List panel of the IDE.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_linq_unsupported_2_ea584e3fac.gif)

*Unsupported LINQ2, but supported LINQ3 Expression - Trim() is not supported in LINQ2, but is supported in LINQ3.*
![GIF showing an expression that is unsupported in LINQ2, but supported in LINQ3, being implemented. After being written, unsupported code is correctly highlighted; tooltip warns developer of the unsupported expression in LINQ2 but not LINQ3 and the warning is added to the Error List panel of the IDE.](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_only_linq3_bc033bd4f1.gif)

## MongoDB Analyzer + New LINQ3 Provider = 💚
If you’d rather not see those “unsupported in LINQ2, but supported in LINQ3” warnings, now is also a good time to update to the [latest MongoDB C#/.NET driver](https://www.nuget.org/packages/mongodb.driver) (2.14.1) which has LINQ3 support! While the full transition from LINQ2 to LINQ3 continues, you can explicitly configure your [MongoClient](https://mongodb.github.io/mongo-csharp-driver/2.14/getting_started/quick_tour/#mongoclient) to use the new LINQ provider like so:

```csharp
var connectionString = "mongodb://localhost";
var clientSettings = MongoClientSettings.FromConnectionString(connectionString);
clientSettings.LinqProvider = LinqProvider.V3;
var client = new MongoClient(clientSettings);
```

## Integrate MongoDB Analyzer for .NET into Your Pipelines
The MongoDB Analyzer can also be used from the CLI which means integrating this static analysis tool into your continuous integration and continuous deployment pipelines is seamless! For example, running `dotnet build` from the command line will output MongoDB Analyzer warnings to the terminal:

*Running dotnet build command outputs warnings from the MongoDB Analyzer*
![*Running dotnet build command outputs warnings from the MongoDB Analyzer*](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mdb_analyzer_build_output_terminal_52965c0a24.gif)

Adding this as a step in your build pipeline can be a valuable gate check for your build. You’ll save yourself a potential headache and catch unsupported expressions and invalid queries much earlier.

Another idea: Output a Static Analysis Results Interchange Format ([SARIF](https://github.com/microsoft/sarif-tutorials/blob/main/docs/1-Introduction.md#:%7E:text=What%20is%20SARIF%3F,for%20use%20by%20simpler%20tools)) file and use it to generate explain plans for all of your queries. SARIF is a standard, JSON-based format for the output of static analysis tools, making a SARIF file an ideal place to grab the supported queries generated by the MongoDB Analyzer. 

To output a SARIF file for your project, you’ll need to add the `ErrorLog` option to your `.csproj` file. You’ll be able to find it at the root of your project (unless you’ve specified otherwise) the next time you build your project.

With this file, you can load it via a [mongosh](https://docs.mongodb.com/mongodb-shell/) script, process the file to find and “clean” the found MongoDB Query API expressions, and generate [explain plans](https://docs.mongodb.com/manual/reference/method/db.collection.explain/#mongodb-method-db.collection.explain) for the list of queries. What can you do with this? A great example would be to output a build warning (or outright fail the build) if you catch any missing indexes! Adding steps like these to your build and using the information from the expain plans, you can prevent potential performance issues from ever making it to production.

## We Want to Hear From You!
With the release of the MongoDB Analyzer for .NET, we hope to speed up your development cycle and increase your productivity in three ways: 1) by making it easier for you to see how your idiomatic queries map to the MongoDB Query API, 2) by helping you spot unsupported expressions and invalid queries faster (at compile time, baby), and 3) by streamlining your development process by enabling static analysis for your MongoDB queries in your CI/CD pipelines!

We’re quite eager to see the .NET and C# communities use this tool and are even more eager to hear your feedback. The MongoDB Analyzer is ready for you to install as a [NuGet package](https://www.nuget.org/packages/MongoDB.Analyzer/1.0.0) and can be added to any existing project that uses the MongoDB .NET driver. We want to continue improving this tool and that can only be done with your help. If you find any issues, are missing critical functionality, or have an edge case that the MongoDB Analyzer doesn’t fulfill, [please let us know](https://feedback.mongodb.com/forums/940188-mongodb-analyzer-for-net)! You can alsopost in our [Community Forums](https://www.mongodb.com/community/forums/).

**Additional Resources**

* [MongoDB Analyzer Docs](https://docs.mongodb.com/mongodb-analyzer/current/)

Say hello to the MongoDB Analyzer for .NET. This tool translates your C# queries to their MongoDB Query API equivalent and warns you of unsupported expressions and invalid queries at compile time, right in Visual Studio.

Introducing the MongoDB Analyzer for .NET

So you're a .NET Core developer or you're trying to become one and you'd like to get a database included into the mix. MongoDB is a great choice and is quite easy to get started with for your .NET Core projects.

In this tutorial, we're going to explore simple CRUD operations in a .NET Core application, something that will make you feel comfortable in no time!

## The Requirements

To be successful with this tutorial, you'll need to have a few things ready to go.

- .NET Core installed and configured.
- MongoDB Atlas cluster, M0 or better, deployed and configured.

Both are out of the scope of this particular tutorial, but you can refer to [this tutorial](https://www.mongodb.com/developer/article/5-different-ways-deploy-free-database-mongodb-atlas/) for more specific instructions around MongoDB Atlas deployments. You can validate that .NET Core is ready to go by executing the following command:

```bash
dotnet new console --output MongoExample
```

We're going to be building a console application, but we'll explore API development in a later tutorial. The "MongoExample" project is what we'll use for the remainder of this tutorial.

## Installing and Configuring the MongoDB Driver for .NET Core Development

When building C# applications, the common package manager to use is NuGet, something that is readily available in Visual Studio. If you're using Visual Studio, you can add the following:

```bash
Install-Package MongoDB.Driver -Version 2.14.1
```

However, I'm on a Mac, use a variety of programming languages, and have chosen Visual Studio Code to be the IDE for me. There is no official NuGet extension for Visual Studio Code, but that doesn't mean we're stuck.

Execute the following from a CLI while within your project directory:

```bash
dotnet add package MongoDB.Driver
```

The above command will add an entry to your project's "MongoExample.csproj" file and download the dependencies that we need. This is valuable whether you're using Visual Studio Code or not.

If you generated the .NET Core project with the CLI like I did, you'll have a "Program.cs" file to work with. Open it and add the following code:

```csharp
using MongoDB.Driver;
using MongoDB.Bson;

MongoClient client = new MongoClient("ATLAS_URI_HERE");

List<string> databases = client.ListDatabaseNames().ToList();

foreach(string database in databases) {
    Console.WriteLine(database);
}
```

The above code will connect to a MongoDB Atlas cluster and then print out the names of the databases that the particular user has access to. The printing of databases is optional, but it could be a good way to make sure everything is working correctly.

If you're wondering where to get your `ATLAS_URI_HERE` string, you can find it in your MongoDB Atlas dashboard and by clicking the connect button on your cluster.

![MongoDB Atlas Connection String](https://mongodb-devhub-cms.s3.us-west-1.amazonaws.com/mongodb_atlas_connection_string_801c3bdc01.jpg "MongoDB Atlas Connection String")

The above image should help when looking for the Atlas URI.

## Building a POCO Class for the MongoDB Document Model

When using .NET Core to work with MongoDB documents, you can make use of the `BsonDocument` class, but depending on what you're trying to do, it could complicate your .NET Core application. Instead, I like to work with classes that are directly mapped to document fields. This allows me to use the class naturally in C#, but know that everything will work out on its own for MongoDB documents.

Create a "playlist.cs" file within your project and include the following C# code:

```csharp
using MongoDB.Bson;

public class Playlist {

    public ObjectId _id { get; set; }
    public string username { get; set; } = null!;
    public List<string> items { get; set; } = null!;

    public Playlist(string username, List<string> movieIds) {
        this.username = username;
        this.items = movieIds;
    }

}
```

In the above `Playlist` class, we have three fields. If you want each of those fields to map perfectly to a field in a MongoDB document, you don't have to do anything further. To be clear, the above class would map to a document that looks like the following:

```json
{
    "_id": ObjectId("61d8bb5e2d5fe0c2b8a1007d"),
    "username": "nraboy",
    "items": [ "1234", "5678" ]
}
```

However, if you wanted your C# class field to be different than the field it should map to in a MongoDB document, you'd have to make a slight change. The `Playlist` class would look something like this:

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

public class Playlist {

    public ObjectId _id { get; set; }

    [BsonElement("username")]
    public string user { get; set; } = null!;

    public List<string> items { get; set; } = null!;

    public Playlist(string username, List<string> movieIds) {
        this.user = username;
        this.items = movieIds;
    }

}
```

Notice the new import and the use of `BsonElement` to map a remote document field to a local .NET Core class field.

There are a lot of other things you can do in terms of document mapping, but they are out of the scope of this particular tutorial. If you're curious about other mapping techniques, check out the [documentation](https://mongodb.github.io/mongo-csharp-driver/2.14/reference/bson/mapping/) on the subject.

## Implementing Basic CRUD in .NET Core with MongoDB

Since we're able to connect to Atlas from our .NET Core application and we have some understanding of what our data model will look like for the rest of the example, we can now work towards creating, reading, updating, and deleting (CRUD) documents.

We'll start by creating some data. Within the project's "Program.cs" file, make it look like the following:

```csharp
using MongoDB.Driver;

MongoClient client = new MongoClient("ATLAS_URI_HERE");

var playlistCollection = client.GetDatabase("sample_mflix").GetCollection<Playlist>("playlist");

List<string> movieList = new List<string>();
movieList.Add("1234");

playlistCollection.InsertOne(new Playlist("nraboy", movieList));
```

In the above example, we're connecting to MongoDB Atlas, getting a reference to our "playlist" collection while noting that it is related to our `Playlist` class, and then making use of the `InsertOne` function on the collection.

If you ran the above code, you should see a new document in your collection with matching information.

So let's read from that collection using our C# code:

```csharp
// Previous code here ...

FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("username", "nraboy");

List<Playlist> results = playlistCollection.Find(filter).ToList();

foreach(Playlist result in results) {
    Console.WriteLine(string.Join(", ", result.items));
}
```

In the above code, we are creating a new `FilterDefinition` filter to determine which data we want returned from our `Find` operation. In particular, our filter will give us all documents that have "nraboy" as the `username` field, which may be more than one because we never specified if the field should be unique.

Using the filter, we can do a `Find` on the collection and convert it to a `List` of our `Playlist` class. If you don't want to use a `List`, you can work with your data using a cursor. You can learn more about cursors in the [documentation](https://mongodb.github.io/mongo-csharp-driver/2.14/apidocs/html/T_MongoDB_Driver_IFindFluent_2.htm).

With a `Find` out of the way, let's move onto updating our documents within MongoDB.

We're going to add to our "Program.cs" file with the following code:

```csharp
// Previous code here ...

FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("username", "nraboy");

// Previous code here ...

UpdateDefinition<Playlist> update = Builders<Playlist>.Update.AddToSet<string>("items", "5678");

playlistCollection.UpdateOne(filter, update);

results = playlistCollection.Find(filter).ToList();

foreach(Playlist result in results) {
    Console.WriteLine(string.Join(", ", result.items));
}
```

In the above code, we are creating two definitions, one being the `FilterDefinition` that we had created in the previous step. We're going to keep the same filter, but we're adding a definition of what should be updated when there was a match based on the filter.

To clear things up, we're going to match on all documents where "nraboy" is the `username` field. When matched, we want to add "5678" to the `items` array within our document. Using both definitions, we can use the `UpdateOne` method to make it happen.

There are more update operations than just the `AddToSet` function. It is worth checking out the [documentation](https://docs.mongodb.com/manual/reference/operator/update/) to see what you can accomplish.

This brings us to our final basic CRUD operation. We're going to delete the document that we've been working with.

Within the "Program.cs" file, add the following C# code:

```csharp
// Previous code here ...

FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("username", "nraboy");

// Previous code here ...

playlistCollection.DeleteOne(filter);
```

We're going to make use of the same filter we've been using, but this time in the `DeleteOne` function. While we could have more than one document returned from our filter, the `DeleteOne` function will only delete the first one. You can make use of the `DeleteMany` function if you want to delete all of them.

Need to see it all together? Check this out:

```csharp
using MongoDB.Driver;

MongoClient client = new MongoClient("ATLAS_URI_HERE");

var playlistCollection = client.GetDatabase("sample_mflix").GetCollection<Playlist>("playlist");

List<string> movieList = new List<string>();
movieList.Add("1234");

playlistCollection.InsertOne(new Playlist("nraboy", movieList));

FilterDefinition<Playlist> filter = Builders<Playlist>.Filter.Eq("username", "nraboy");

List<Playlist> results = playlistCollection.Find(filter).ToList();

foreach(Playlist result in results) {
    Console.WriteLine(string.Join(", ", result.items));
}

UpdateDefinition<Playlist> update = Builders<Playlist>.Update.AddToSet<string>("items", "5678");

playlistCollection.UpdateOne(filter, update);

results = playlistCollection.Find(filter).ToList();

foreach(Playlist result in results) {
    Console.WriteLine(string.Join(", ", result.items));
}

playlistCollection.DeleteOne(filter);
```

The above code is everything that we did. If you swapped out the Atlas URI string with your own, it would create a document, read from it, update it, and then finally delete it.

## Conclusion

You just saw how to quickly get up and running with MongoDB in your .NET Core application! While we only brushed upon the surface of what is possible in terms of MongoDB, it should put you on a better path for accomplishing your project needs.

If you're looking for more help, check out the [MongoDB Community Forums](https://community.mongodb.com) and get involved.

Learn how to quickly and easily start building .NET Core applications that interact with MongoDB Atlas for create, read, update, and delete (CRUD) operations.

Build Your First .NET Core Application with MongoDB Atlas

# Using LINQ to Query MongoDB in a .NET Core Application

If you've been keeping up with my series of tutorials around .NET Core and MongoDB, you'll likely remember that we explored [using the Find operator to query for documents](https://www.mongodb.com/developer/how-to/build-first-dotnet-core-application-mongodb-atlas/) as well as [an aggregation pipeline](https://www.mongodb.com/developer/how-to/joining-collections-mongodb-dotnet-core-aggregation-pipeline/). Neither of these previously explored subjects are too difficult, but depending on what you're trying to accomplish, they could be a little messy. Not to mention, they aren't necessarily "the .NET way" of doing business.

This is where LINQ comes into the mix of things!

With Language Integrated Queries (LINQ), we can use an established and well known C# syntax to work with our MongoDB documents and data.

In this tutorial, we're going to look at a few LINQ queries, some as a replacement to simple queries using the MongoDB Query API and others as a replacement to more complicated aggregation pipelines.

## The requirements

To be successful with this tutorial, you should already have the following ready to go:

- [.NET Core](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) 6+
- [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/signup), the free tier or better

When it comes to MongoDB Atlas, you'll need to have a cluster deployed and properly configured with user roles and network rules. If you need help with this, take a look at my [previous tutorial](https://www.mongodb.com/developer/article/5-different-ways-deploy-free-database-mongodb-atlas/) on the subject. You will also need the sample datasets installed.

While this tutorial is part of a series, you don't need to have read the others to be successful. However, you'd be doing yourself a favor by checking out the other ways you can do business with .NET Core and MongoDB.

## Creating a new .NET Core console application with the CLI

To keep this tutorial simple and easy to understand, we're going to create a new console application and work from that.

Execute the following from the CLI to create a new project that is ready to go with the MongoDB driver:

```bash
dotnet new console -o MongoExample
cd MongoExample
dotnet add package MongoDB.Driver
```

For this tutorial, our MongoDB Atlas URI string will be stored as an environment variable on our computer. Depending on your operating system, you can do something like this:

```bash
export ATLAS_URI="YOUR_ATLAS_URI_HERE"
```

The Atlas URI string can be found in your MongoDB Atlas Dashboard after clicking the "Connect" button and choosing your programming language.

Open the project's **Program.cs** file and add the following C# code:

```csharp
using MongoDB.Bson;
using MongoDB.Driver;
using MongoDB.Driver.Linq;

MongoClientSettings settings = MongoClientSettings.FromConnectionString(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

settings.LinqProvider = LinqProvider.V3;

MongoClient client = new MongoClient(settings);
```

In the above code, we are explicitly saying that we want to use LINQ Version 3 rather than Version 2, which is the default in MongoDB. While you can accomplish many LINQ-related tasks in MongoDB with Version 2, you'll get a much better experience with Version 3.

## Writing MongoDB LINQ queries in your .NET Core project

We're going to take it slow and work our way up to bigger and more complicated queries with LINQ.

In case you've never seen the "sample_mflix" database that is part of the sample datasets that MongoDB offers, it's a movie database with several collections. We're going to focus strictly on the "movies" collection which has documents that look something like this:

```json
{
    "_id": ObjectId("573a1398f29313caabceb515"),
    "title": "Batman",
    "year": 1989,
    "rated": "PG-13",
    "runtime": 126,
    "plot": "The Dark Knight of Gotham City begins his war on crime with his first major enemy being the clownishly homicidal Joker.",
    "cast": [ "Michael Keaton", "Jack Nicholson", "Kim Basinger" ]
}
```

There are quite a bit more fields to each of the documents in that collection, but the above fields are enough to get us going.

To use LINQ, we're going to need to create mapped classes for our collection. In other words, we won't want to be using `BsonDocument` when writing our queries. At the root of your project, create a **Movie.cs** file with the following C# code:

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

[BsonIgnoreExtraElements]
public class Movie {

    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; }

    [BsonElement("title")]
    public string Title { get; set; } = null!;

    [BsonElement("year")]
    public int Year { get; set; }

    [BsonElement("runtime")]
    public int Runtime { get; set; }

    [BsonElement("plot")]
    [BsonIgnoreIfNull]
    public string Plot { get; set; } = null!;

    [BsonElement("cast")]
    [BsonIgnoreIfNull]
    public List<string> Cast { get; set; } = null!;

}
```

We used a class like the above in our previous tutorials. We've just defined a few of our fields, mapped them to BSON fields in our database, and told our class to ignore any extra fields that may exist in our database that we chose not to define in our class.

Let's say that we want to return movies that were released between 1980 and 1990. If we weren't using LINQ, we'd be doing something like the following in our **Program.cs** file:

```csharp
using MongoDB.Bson;
using MongoDB.Driver;

MongoClient client = new MongoClient(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

IMongoCollection<Movie> moviesCollection = client.GetDatabase("sample_mflix").GetCollection<Movie>("movies");

BsonDocument filter = new BsonDocument{
    { 
        "year", new BsonDocument{
            { "$gt", 1980 },
            { "$lt", 1990 }
        } 
    }
};

List<Movie> movies = moviesCollection.Find(filter).ToList();

foreach(Movie movie in movies) {
    Console.WriteLine($"{movie.Title}: {movie.Plot}");
}
```

However, since we want to use LINQ, we can update our **Program.cs** file to look like the following:

```csharp
using MongoDB.Driver;
using MongoDB.Driver.Linq;

MongoClientSettings settings = MongoClientSettings.FromConnectionString(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

settings.LinqProvider = LinqProvider.V3;

MongoClient client = new MongoClient(settings);

IMongoCollection<Movie> moviesCollection = client.GetDatabase("sample_mflix").GetCollection<Movie>("movies");

IMongoQueryable<Movie> results =
            from movie in moviesCollection.AsQueryable()
            where movie.Year > 1980 && movie.Year < 1990
            select movie;

foreach(Movie result in results) {
    Console.WriteLine("{0}: {1}", result.Title, result.Plot);
}
```

In the above code, we are getting a reference to our collection and creating a LINQ query. To break down the LINQ query to see how it relates to MongoDB, we have the following:

1. The "WHERE" operator is the equivalent to doing a "$MATCH" or a filter within MongoDB. The documents have to match the criteria in this step.
2. The "SELECT" operator is the equivalent to doing a projection or using the "$PROJECT" operator. We're defining which fields should be returned from the query—in this case, all fields that we've defined in our class.

To diversify our example a bit, we're going to change the match condition to match within an array, something non-flat.

Change the LINQ query to look like the following:

```csharp
var results =
            from movie in moviesCollection.AsQueryable()
            where movie.Cast.Contains("Michael Keaton")
            select new { movie.Title, movie.Plot };
```

A few things changed in the above code along with the filter. First, you'll notice that we are matching on the `Cast` array as long as "Michael Keaton" exists in that array. Next, you'll notice that we're doing a projection to only return the movie title and the movie plot instead of all other fields that might exist in the data.

We're going to make things slightly more complex now in terms of our query. This time we're going to do what would have been a MongoDB aggregation pipeline, but this time using LINQ.

Change the C# code in the **Program.cs** file to look like the following:

```csharp
using MongoDB.Driver;
using MongoDB.Driver.Linq;

MongoClientSettings settings = MongoClientSettings.FromConnectionString(
    Environment.GetEnvironmentVariable("ATLAS_URI")
);

settings.LinqProvider = LinqProvider.V3;

MongoClient client = new MongoClient(settings);

IMongoCollection<Movie> moviesCollection = client.GetDatabase("sample_mflix").GetCollection<Movie>("movies");

var results = 
            from movie in moviesCollection.AsQueryable()
            where movie.Cast.Contains("Ryan Reynolds")
            from cast in movie.Cast
            where cast == "Ryan Reynolds"
            group movie by cast into g
            select new { Cast = g.Key, Sum = g.Sum(x => x.Runtime) };

foreach(var result in results) {
    Console.WriteLine("{0} appeared on screen for {1} minutes!", result.Cast, result.Sum);
}
```

In the above LINQ query, we're doing a series of steps, just like stages in an aggregation pipeline. These stages can be broken down like the following:

1. Match all documents where "Ryan Reynolds" is in the cast.
2. Unwind the array of cast members so the documents sit adjacent to each other. This will flatten the array for us.
3. Do another match on the now smaller subset of documents, filtering out only results that have "Ryan Reynolds" in them.
4. Group the remaining results by the cast, which will only be "Ryan Reynolds" in this example.
5. Project only the group key, which is the cast member, and the sum of all the movie runtimes.

If you haven't figured it out yet, what we attempted to do was determine the total amount of screen time Ryan Reynolds has had. We isolated our result set to only documents with Ryan Reynolds, and then we summed the runtime of the documents that were matched.

While the full scope of the MongoDB aggregation pipeline isn't supported with LINQ, you'll be able to accomplish quite a bit, resulting in a lot cleaner looking code. To get an idea of the supported operators, take a look at the [MongoDB LINQ documentation](https://mongodb.github.io/mongo-csharp-driver/2.5/reference/driver/crud/linq/#project).

## Conclusion

You just got a taste of LINQ with MongoDB in your .NET Core applications. While you don't have to use LINQ, as demonstrated in a few previous tutorials, it's common practice amongst C# developers.

Got a question about this tutorial? Check out the [MongoDB Community Forums](https://community.mongodb.com) for help!

Learn how to use LINQ to interact with MongoDB in a .NET Core application.

Using LINQ to Query MongoDB in a .NET Core Application

Saving Data in Unity3D Using SQLite

A general-purpose, multi-paradigm programming language. C# is a particularly useful language to learn for developing apps based on the .NET framework

CSharp

Featured

Using LINQ to Query MongoDB in a .NET Core Application

Saving Data in Unity3D Using SQLite

How to Use MongoDB Client-Side Field Level Encryption (CSFLE) with C#

CSharp Tutorials

Using LINQ to Query MongoDB in a .NET Core Application

Joining Collections in MongoDB with .NET Core and an Aggregation Pipeline

MongoDB Geospatial Queries in C#

All CSharp Content