Taimila.com

MonoDevelop add-in repository for Entify

Now it’s easier than ever to install Entify visual designer to MonoDevelop. I have created MonoDevelop add-in repository for the visual designer add-in. This allows developers to install Entify add-in right from the MonoDevelop Add-in manager.

MonoDevelop add-in manager

Installing add-in is easy. Open Add-in manager from the Tools menu of the MonoDevelop. Click Repositories… and then Add. Insert the repository URL and click Ok to save.

Add Entify repository to MonoDevelop

After adding the repostiory you can install the add-in from the Add-in manager.

Entify add-in installation

Check the Entify Visual Designer and follow the instructions. After installing the add-in you should be able to add Entity set to any C# project. See my previous post for instructions. Just skip the step 2 which is the manual installation instructions for the add-in.

Entify visual designer add-in repository URL is http://www.taimila.com/entify/repository/

Fixing Entify defects

I fixed two defects from Entify today.

1. Relation name must start with uppercase letter or generated code doesn’t compile
2. EntityContext does unnecessary lazy loads when handling entities

The first one was fixed simply by disallowing invalid relation names. Now Entify visual designer gives warning if invalid name is tried to be use as relation name. Before the fix, it didn’t say anything and the generated code didn’t compile. The second one was fixed by removing lazy load calls when they were not needed.

Below is a rerun results of the simple performance tests I introduced in earlier blog post. There are minor improvments after these fixes, but nothing spectacular.

Taimila.com updates

I gave up the idea of having my own WordPress theme since I couldn’t get the RSS-feed to work with it. Now I’m looking for a nice theme to use, so don’t be surprised if my site’s look and feel varies from time to time. If you know any usable, clean and good looking WordPress themes, let me know!

I added my travelling blogs back to online. Those are all written in Finnish, but you can use google translator if Finnish doesn’t happen to be one of the language you understand. I also added projects page, which introduces my latest software projects including Entify.

In the process of updating my site, I accidentally removed all images from old posts. :( I try to find them from somewhere and fix the posts if possible.

Oh, and now the RSS actually works!

Entify – Performance test

I wanted to test Entify‘s performance, so I wrote a simple test application and timed entity context operations of the Entify framework. During this process, I found two defects from the project and fixed them on the way. Fixes are committed to Entify trunk.

Test model

Above is a entity model I used in testing. My testing was by no means complete or scientific, but I wanted to get an overall picture of the performance. I created a model that could be used in music player application. In real applications there would be more properties in each entity type, but this was enough for my testing purposes.

I started by adding 100 artists to the context. Each artist had 10 albums which contained 15 tracks each. So all in all, I added 100 artists, 1000 albums and 15,000 tracks to the entity context. The way I did it is not the fastest, but probably the most intuitive way of doing it. I started by inserting 100 artists with one Add() call. After that I looped over albums and tracks and inserted them seprately. All in all, adding all this stuff to context took 1101 Add() calls. With little performance tweaking we could achieve the same with 3 Add() calls. One for each entity type. This would make it probably a lot faster. Anyhow, I wanted to see the performance of quick and dirty solution. (And I really didn’t have time to optimize the test code) :) Here are the results.

Since Entify uses lazy approach, the time of add operations actually includes also the time that was spent on creating the file for data and creating the entity model (tables and indexes) into the database.

I got these results by executing the Mono console app on my 2 years old iMac.

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.

Entify beta released!

Entify License

I have released the first version of Entify framework with the visual designer add-in for MonoDevelop. I decided to follow the licensing of Mono project and released the whole project under MIT license. It’s an open source license which allows you to do pretty much anything you want with the code. To sum it up, Entify is free, open and yours to enjoy!

Entify project downloads are hosted on GoogleCode service. You can find precompiled binaries from there as well as SVN repository of the source code. I won’t be releasing source code packages separately, since the latest source code is always available in version control.

To get the latest version of Entify source code, use the following SVN command:

svn checkout http://entify.googlecode.com/svn/trunk/ entify

I hope that developers will download Entify and play around with it. There are still some rough edges since this is the first release, but my over all feeling is that the project is quite stable already.

Related links

• Entify website
• Entify forums
• Entify on GoogleCode

Stay tuned for “Getting started with Entify” tutorial.