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/

Entify works now with MonoDevelop 2.4

What’s new in 0.6 release

• Visual designer updated to support MonoDevelop 2.4
• Bugfix to issue 4: Entify did some unneeded lazy loading for entities (performance issue)
• Bugfix to issue 5: GetEntityId() method was not visible for client application
• Bugfix to issue 6: To-Many relation lead to crash when no related entities were set for an entity
• Bugfix to issue 7: Entify didn’t show up in MonoDevelop for MonoTouch projects
• Bugfix to issue 9: Invalid relation name could lead to malfunctioning generated code

In the next version of Entify, I’ll concentrate fixing visual designer stability issues under OSX. This is crusial for MonoTouch developers. So, don’t expect any new features in the next release either. Version 0.8 will contain new features when we get there!

I recommend everyone to update to the latest version. There shouldn’t be any compatibility issues between versions 0.5 and 0.6 except with MonoDevelop. MonoDevelop API has changed and therefore the new visual desinger add-in won’t work with older versions of MonoDevelop. This is not a big problem, since you should use the latest version of MonoDevelop anyway.

Get Entify 0.6 beta from Entify website

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.

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!

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.

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 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.

Entify website

I have also created a Google code page for the project. Google code will be used as a issue tracker of the project. It also provides download repository for the releases as well as SVN repository of the project.

Entify will be released in the near future. Stay tuned.

How lazy Entify really is?

As it turns out, very lazy! When the application that uses Entify is executed for the very first time, the database simply doesn’t exist yet. Database isn’t created until the entity context is created in the application for the first time. This action only creates an empty database file to the disk. There are no tables for entities at this point.

When the first entity is added to the context, Entify asks it’s internal type coordinator to prepare database for type of the received entity object. Type coordinator checks is the type already known and if not, it generates the tables needed to store the object into persistent store. Therefore, Entify database never contains tables just sitting and waiting for entities to show up. Instead, tables are created only when they are really needed. In fact, Entify doesn’t even know what types application may give it to it.

So, the database is generated on the fly as needed, but how about fetching entities from the entity context? Entities are fetched from the entity context by creating Entity requests, which are object oriented queries. Programmer can also get all the entities of given type by calling GetAll<EntityType>(); method of the EntityContext instance. This returns a list of entity objects. But what if entities have other entities as relations? Then all the related entities are lazy loaded and cached when needed. Below is a short code snippet with comments to show how it works.

ShoppingCart cart = new ShoppingCart();

context.Add(cart); // Generates tables for cart type

Product p1 = new Product() { Name = "Movie" };
Product p2 = new Product() { Name = "Candy" };

context.Add(p1, p2);

cart.Products.Add(p1); // ShoppingCart has to-many
cart.Products.Add(p2); // relation to Product type.

context.Update(cart);

Now somewhere in the application we need to handle those objects, so let’s load them into memory from entity context.

ShoppingCart[] carts = context.GetAll<ShoppingCart>();
ShoppingCart ourCart = carts[0]; // Our cart is the first one

// This activates lazy load to database, because products
// are not in memory yet. From the application's point of view
// lazy loading is completely transparent.
List<Products> products = ourCart.Products; 

// Products were loaded and cached in previous statement.
// No lazy load here.
List<Products> sameProducts = ourCart.Products;

That’s all I got to say about laziness this time. Take care, and don’t be as lazy as Entify!

What is a snapshot?

Snapshot is a state of the entity context in some point of time. You can think it as a backup copy of the entity context. Snapshot is something that can be taken at any point of application execution. Application can also revert back to any of the taken snapshots when ever it needs to. To sum up, snapshots are a way to preserve entity context state and revert to that state later on.

How to use snapshots with Entify?

Entify has a concept entity context. Entity context is a place where all the entities live. It’s a persistent store of the entities and it supports snapshots.

Taking a snapshot from entity context is as easy as calling one mehtod as shown here.

long snapshotId = context.TakeSnapshot();

Taking a snapshot locks entity context to prevent modification meanwhile snapshot is taken. The time it takes to make a snapshot depends on how many entities entity context contains. The time required is pretty much the time it takes to copy the data of the whole state. Taking a snapshot returns snapshot identifier. This is an unique identifier within the application and can be used later on when reverting to the taken snapshot.

Revering to any snapshot is as simple as creating one.

context.RevertToSnapshot(snapshotId);

Snapshots are files in the filesystems. This allows application to revert back to taken snapshots even if application is quitted between taking a snapshot and reverting back to it. This also means that taking snapshots creates new files to the filesystem. It’s a good practice to keep track of the snapshots and remove them when they are not needed anymore. Entify allows you to remove taken snapshots like this.

context.RemoveSnapshot(snapshotId);

That’s it! Snapshot feature consists of three powerful methods. Simple and usable API is one of the most important features of the Entify and this is a nice demonstration of how things can be easy-to-use and still provide enough funtionality.

Setting validation rules

Validation rules define allowed values for each entity property. Let’s say we have Customer entity that has Firstname and Lastname properties. Both of these properties are type of string. We can set most common validation rules with visual designer as shown below.

Validation rules for firstname property

These settings state that customer’s firstname should never be null or empty string (since minimum length is one). As long as the string length is in the specified range it can contain any characters wanted. In most cases it’s enough to set these kind of rules, but sometimes there is need for more complex validation rules.

Entify allows developer to extend validation rules with custom validation methods. These methods are written to partial entity classes and marked with EntityValidator attribute as illustrated below. Each validation method must return ValidationError which is null if value was valid, otherwise it contains information what was wrong with the value(s).

Example method below checks that value has been set to at least one of the name properties. Notice that with custom validators you can create validation rules that depend on more than one property.

public partial class Customer : Entity
{
	// Custom validation method for Customer
	[EntityValidator]
	private ValidationError ValidateCustomerNames()
	{
		if(string.IsNullOrEmpty(this.Firstname) &&
		   string.IsNullOrEmpty(this.Lastname))
		{
			return new ValidationError(
					ValidationErrorReason.CustomError,
		            null,
			        "At least one of the names must be set.");
		}

		return null; // No error
	}
}

Validating entities

Entify supports automatic entity validation. Automatic validation can be enabled with EntityContextSettings. When automatic validation is enabled, Entify validates each entity object that is added to entity context or updated in context. If any of the given entities contain validation errors, then EntityContext throws ValidationException that contains validation results. Below is an example code to illustrate this.

Customer c = new Customer();

try
{
	context.Add(c);
}
catch(ValidationException e)
{
	ValidationResults r = e.ValidationResults;
}

If validation would be disabled, Add() wouldn’t throw exception and entity object would be added successfully even in case it contains invalid values.

It’s also possible to validate entity objects manually from code. Here is a code snippet to show how it’s done.

Customer c = new Customer();
Customer c2 = new Customer();
Product p = new Product();

ValidationResults results = EntityValidator.Validate(c, c2);
ValidationResults results2 = EntityValidator.Validate(p);

As you can see, EntityValidator takes objects of any type and validates them. Compile time error is given, if parameter type is not entity type.

Handling validation results

Now we know how to define validation rules and how to validate entities. Next I will discuss, how to process validation results so that application can properly notify user of invalid values. Multiple entities can be validated with a single method call. Therefore, validation results can contain results of multiple entities. This need lead to hierarchal validation results in Entify.

There are three classes in the hierarchy:

• ValidationResults – contains results of all validated entities
• ValidationResult – contains all validation errors of one entity
• ValidationError – represents one specific validation error

Below is a code snippet that prints all validation errors to console.

Customer[] c = GetCustomers(); // Method returns 100 customers
ValidationResults r = EntityValidator.Validate(c);

// Check was validation successful
if(!r.IsValid)
{
	// Iterate results one entity at time
	foreach(var result in r)
	{
		// Iterate all errors in one entity
		foreach(var error in result)
		{
			Console.WriteLine(error.Message);
		}
	}
}

Comments are welcome

That covers validation in Entify quite well. Please, leave a comment no matter if you like it or dislike it. Can you think of any ways to improve it?

What is it?

Main focus of the Entify project is to deliver simple and easy-to-use entity framework for Mono and .NET applications. It’s important to understand that Entify is not designed for enterprise applications. Instead the focus is strictly desktop and mobile applications. This in mind, Entify doesn’t support all the advanced features enterprise applications might require, but it’s a perfect solution for most of the non-enterprise applications. Entify is built on top of the SQLite database, so if SQLite would be suitable solution for your project so is Entify.

Entify is compiled into one dll-file and it doesn’t have any external dependencies. Therefore, it’s very easy to deploy it with any application. It doesn’t require any configuration files, data mapping definitions (ORM), confusing XML-files or other boring stuff you hate to do anyway. All you need to do is define entities with the visual designer, add reference to Entify library and start using it!

Below is a code snippet to illustrate, what it’s like to work with the Entify framework.

EntityContextSettings s = new EntityContextSettings()
{
	PersistentStoreLocation = "/path/example.entifydb",
	EnforceValidationRules = false
};

// Get entity context with given settings
EntityContext context = EntityContextFactory.GetContext(s);

// Create entity objects
Customer c1 = new Customer();
c1.Name = "Bill Gates";
c1.Age = 36;

Customer c2 = new Customer();
c2.Name = "Steve Jobs";

// Add entities to entity context (saves them to database)
context.Add(c1, c2);

c1.Age = 39;

// Updates changed information to context
context.Update(c1);

// Get all customers from context
Customer[] customers = context.GetAll<Customer>();

// Removes given customers from context
context.Remove(customers);

Visual designer integrated to MonoDevelop

Entify framework is all great, but what makes it even better is the visual designer tool integrated right into the MonoDevelop IDE. With this tool you can add entity set item to your existing project and define entities without writing a single line of code. It doesn’t only make developing applications faster, but it also works as a visual documentation of the application’s entity model. From the model you can instantly see what are the entities and how they are related to each other. Reading the same information from the code could take hours.

Visual designer for Entify

Entify also supports entity validation. Validation can be done manually or automatically. Developer can define property specific validation rules with the visual designer tool. Available validation rules depend on the type of the property. Tool provides only the most common validation rules for each type, but developer can extend validation rules with his own validation methods. Entify framework automatically calls those custom validation methods when it’s validating entities.

Below is a example screenshot that shows validation rules for string property.

Visual designer makes it easy to define validation rules for entity properties

So, when it’s released?

I won’t be giving any specific dates, since after all this is just a hobby of mine and I don’t want to stress about it. What I know is that the Entify framework itself is done and quite well tested with over 160 unit tests. I will write more tests and do some exploratory testing before release. Also the visual designer add-in for MonoDevelop is pretty much done. There are still some GTK-issues I have to take care of before the release, but nothing major.

So, all the hard work is done and I’m now concentrating to make it polished and stable product. Any suggestions which license I should use when releasing the project?