Getting started with Entify

In this blog post I will explain, how to use Entify visual designer to define domain model for your application. And how Entify framework is used to operate with that model. This post won’t cover all the features Entify has, but gives an idea of the basic features and is therefore, a good starting point for those developers who want to utilize Entify in their own projects.

I will give you step-by-step guide so it’s as easy to follow as possible.

Step 1: Download

The very first thing you need to do, is download and install MonoDevelop if you don’t already have it on your computer. You also need to download Entify framework library and Entify visual designer add-in for MonoDevelop.

Step 2: Install MonoDevelop add-in

Installing Entify visual designer add-in is as simple as copying a downloaded DLL file to the correct folder. Below is instructions for each operation system.

Linux
Create a new folder called MonoDevelop.EntifyEditor under ~/.config/MonoDevelop/addins (create it if it doesn’t exists already) and copy the DLL file into folder you just created. After that restart MonoDevelop and you should be able to see Entify visual designer in MonoDevelop add-in manager.

OSX
Second click on MonoDevelop application icon and select Show Package Contents. Navigate to Contents -> MacOS -> lib -> monodevelop -> AddIns. Create a new folder there called MonoDevelop.EntifyEditor and copy downloaded DLL into that new folder. Restart MonoDevelop and open Add-in manager. You should be able to see Entify visual designer there.

Windows
Navigate to folder C:\Program Files\MonoDevelop\AddIns (assuming you installed MonoDevelop to it’s default location). Create a new folder MonoDevelop.EntifyEditor there and copy the downloaded file to that directory. Restart MonoDevelop and open Add-in manager. You should be able to see Entify visual designer there.

Step 3: Create a new project

Open MonoDevelop and create a new C# Console project and give it a name EntifySample. The very first thing you need to do, is to add reference to the Entify library. So, right-click on References folder, select Edit references and navigate to the folder where you have Taimila.Entify.dll file. Add that file to your references. After that your solution should look like this.




Sample project solution

Step 4: Add new entity set to the project

Next we will add Entity set item to our project. This is the file that defines all the entities that our application needs. You can add Entity set by right-clicking on the project and selecting Add -> New File. Select Entity set from Misc. category and give it name “Entities”.




Adding entity set


After this step you should have Entities.xes file in your project.

Step 5: Define your entities

This is the part where you need to stop and think. What are the entities you need? In this example, I will create a simple address book so I’ll need just two entities Contact and ContactGroup. Later contains 0…n contacts. I’ll create these entities by using Entify visual designer. You should be able to figure out how to use it after playing around with it for a while. The basic idea is that first you create an entity and then you add properties to that entity. In this example, I’ll also add one To-many relation from ContactGroup to Contact.




Sample entities


I added four properties for Contact and only one for ContactGroup. Contact has two string properties which are Firstname and Lastname. It also has one UInt32 property called Age and DateTime property called Birthdate. ContactGroup has only one property called Name that is type of string. It also has one To-many relation which target type is Contact. The diagram above, doesn’t display the name of the relation, but it’s used in code later on. The name of the relation is Contacts.

When you are ready with defining entities, you must save the file. This is important, because Entify generates C# classes from the model when saving the file. If you don’t save the model, you won’t be able to use your entities from the code.

Step 6: Define settings for Entify framework

Now that we have entity model defined, we are ready to use it in our code. The first thing to do is to add using statement for entify library. Let’s add it like this.

using Taimila.Entify;

Next, we need to create settings for Entify. Settings should be created only once, when the application starts. Later on you can access entity context with the name defined in these settings.

EntityContextSettings settings = new EntityContextSettings()
{
  ContextName = "MyContext",
  EnforceValidationRules = false;
  PersistentStoreLocation = "/home/late/entities.entify"
};

Now that we have settings, let’s ask new entity context from Entify. Entity context is a singleton (not really, but you can think it as such) object that you will use for saving, updating, removing and querying entities. You can get entity context from EntityContextFactory as illustrated below.

EntityContext c = EntityContextFactory.GetContext(settings);

The first time you request entity context, you must give settings as a parameter. Later on, you can access the same entity context simply with it’s name. EntityContextFactory will always give you a reference to the same context object.

EntityContext c = EntityContextFactory.GetContext("MyContext");

Step 7: Create and add entities to entity context

Remember those entities we defined in Step 5? Let’s create few instances and add them to the context. Creating a new entity is as easy as creating a new instance of a class. I will create one ContactGroup and two Contacts and add them to the entity context. Adding entities to the context saves them to the persistent store on disk.

Contact contact1 = new Contact()
{
  Firstname = "Lauri",
  Lastname = "Taimila",
  Age = 28,
  Birthdate = DateTime.Now
};

Contact contact2 = new Contact()
{
  Firstname = "John",
  Lastname = "Smith",
  Birthdate = DateTime.Now
};

ContactGroup group = new ContactGroup()
{
  Name = "Friends"
};

And now, let’s add them to the entity context.

context.Add(contact1, contact2);
context.Add(group);

I recommend that when ever you create an new entity you add it to the context as soon as possible. If you need to create multiple entities at once, it’s more efficient to add them to the context with one Add call instead of calling Add for each entity separately. Notice that you can give an array of entity objects to the Add method of entity context.

Now let’s add one of the contacts to the group we created.

group.Contacts.Add(contact1);
context.Update(group);

The first call updates entity model in-memory and the second one saves the defined relation to the persistent store. It’s important to notice that contact1 was added to the context before it was added to the group. Only entities in context can be linked to another entities.

Step 8: Request entities from context

Now that we have created entities and added them to context, we probably want to access them later on in our application. In the next code snippet I will request all contacts from context that have firstname “Lauri”. I will also request all groups without any limitations.

var context = EntityContextFactory.GetContext("MyContext");

// Request to get contacts from context
EntityRequest<Contact> request = new EntityRequest<Contact>();
request.DataFilter = new ValueFilter("Firstname",
			                         "Lauri",
			                         FilterRule.Equal);

// contacts will contain one object
Contact[] contacts = context.GetEntities(request);
Contact c1 = contacts[0];

ContactGroup[] groups = context.GetAll<ContactGroup>();
ContactGroup friends = groups[0];

Contact c2 = friends.Contacts[0];

// c1 and c2 actually represents the same entity
bool same = c1.IsSame(c2);

// Prints "true"
Console.WriteLine(same);

As you can see there are two ways to request entities from entity context. You can use GetAll() method to get all the entities of specified type or you can create EntityRequest to get only the entities that match the request. You can create very simple entity requests as one above or you can assemble more complex ones with multiple filters and conditions. You could for example request first 10 contacts in alphabetical order that are older than 25 and last name starts with “Ta”.

I won’t go into the details of entity requests here. Instead, I will write another blog post later dedicated to that subject.

Final words

I hope that this short tutorial helped you to understand how Entify can be used in your project. If you are interested to learn more about Entify, you should read other posts in my blog and leave comments if you can’t figure out something on your own.