Write entities Code First

You write DevForce Code First entities using DevForce "Aspect Oriented Programming" (AOP).  The MS Build process is modified to rewrite classes marked with DevForce AOP attributes.  During class re-write, DevForce injects entity infrastructure into the class and replaces persisted properties with DevForce implementations.

Install DevForce Code First support

You should first install the DevForce 2010 Code First NuGet package to the project which will hold your code first model.  If you are working in Silverlight, you should also install the package to your "linked" Silverlight project.

The package will add an assembly reference to IdeaBlade.AOP (or IdeaBlade.AOP.SL for Silverlight) and add the DevForce *.cf marker file.

The Code First package will also install the EntityFramework NuGet package to add support for Entity Framework 4.x, and install PostSharp from SharpCrafters.  

Both the DevForce and PostSharp packages modify the MSBuild targets for the projects they are installed to.

See Installing the Code First NuGet package for more information.

Apply DevForce AOP attributes

You apply DevForce AOP attributes to the classes that should be rewritten.
 
There are only two DevForce AOP attributes to learn: ProvideEntityAspect and ProvideComplexAspect. ProvideEntityAspect identifies entity classes for rewrite. The ProvideComplexAspect identifies Complex Type  classes for rewrite. 

You can either decorate the class directly or decorate one of its base types. You cannot do both. The AOP attribute can only appear on one of the classes in the inheritance chain. You’ll get a clear, build error if the attribute appears more than once in the chain.

Here are some examples of valid class declarations:

DataContract Attributes

DevForce uses the WCF DataContactSerializer (DCS) to serialize entity classes in n-tier scenarios (e.g., Silverlight), when importing entities from another EntityManager, and when storing entity data locally in offline scenarios.

So far, none of our example entity classes are decorated with DataContract attributes (although we do have one on the EntityBase class). We often omit these attributes from sample model entity classes. However, if you examine the entity classes generated by DevForce, you'll notice that they are always decorated with [DataContract(IsReference=true)] and all of their properties are marked with [DataMember].

Explicit DataContract markup is not required if every property of the class is completely public and can always be serialized. Many developers prefer to omit these attributes because they are noisy clutter that reduces our ability to quickly grasp what the class does.

Beware: if any property is non-public in any way (and a property with an internal setter is not entirely public), you will have to apply explicit DataContract markup. If you neglect to add DataContract attributes, you'll get unexpected behavior such as property updates that don't write through to the database. 

If you want to be absolutely safe, follow the DevForce generated class pattern by adding DataContract attributes to your classes. We cover this subject in a little more detail below.

Dependent libraries

The DevForce AOP attributes are defined in the IdeaBlade.AOP assembly. We use SharpCrafters’ PostSharp product to rewrite your model assemblies. Therefore, you must have references to both the IdeaBlade.AOP assembly and SharpCrafters’ PostSharp.dll in your model projects. The DevForce package includes these two assemblies in both .NET 4 and Silverlight flavors.

Your Code First .NET 4 profile model project must also have a reference to EntityFramework.dll which is the Microsoft Entity Framework "Code First" library. You typically add this library to your model project via NuGet as described above.  DevForce supports any version of this library, from 4.1 through 4.4.x.  There is no EntityFramework.dll library in Silverlight, as Silverlight is a purely client technology. DevForce entity classes do not depend upon any Entity Framework assemblies.

DevForce templates and tooling usually set these references for you but it’s important to understand these dependencies and be prepared to manage them yourself, especially if you intend to build the application on a "Continuous Integration" server.

See Installing the Code First NuGet package for more information.

Persisted properties

"Persisted properties" return values that reside in the database. 

Here are two entity class definitions, Category and Product, to which we'll refer in this discussion.

Each class is mapped to the database entirely by convention. Category, for example, is mapped to a "Categories" table which has a primary key column named CategoryId. Entity Framework figured this out without our help.

Visual Studio IntelliSense reveals that the properties are rewritten by PostSharp; note the light grey lines under the get and set.

Persisted simple properties

Category.CategoryName is one of the simple properties; it returns a string. Note that it is an “auto property” with no getter or setter. If the runtime class were actually implemented as we see here, Category would be unable to notify a UI when someone set the name of a category. 

Surprisingly, the Category class does not appear to implement System.DataComponent.INotifyPropertyChanged nor does it seem to implement that interface’s PropertyChanged event. A listening UI control couldn’t know when a property was reset and therefore would not refresh when the name was changed. Even if the Category did implement that interface, the CategoryName setter is doing nothing to raise the PropertyChanged event. And yet ... it works.

After DevForce AOP rewrites the class with DevForce entity infrastructure, the Category class does implement INotifyPropertyChanged and the CategoryName setter does raise the PropertyChanged event.

The example properties shown above are written as "auto-properties", bare property definitions without implementations. You could implement a simple property with a backing field if you wished [new in version 6.1.4] as in this example:

DevForce AOP wraps your implementation, calling the original code from within the DevForce property interception logic. Whatever you put inside your property get and set methods will be honored. For example, setting ProductName notifies the UI to update controls bound to both ProductName and SomeOtherProperty. You can put breakpoints on your custom code and debug as you would similar properties elsewhere in your application.  We think Property Interceptors are a better way to inject logic into your properties but you are welcome to this approach as well.

Delegation to your implementation is a feature of simple properties only. Navigation property implementations are completely replaced by DevForce code. Do not put custom code inside navigation properties.

Persisted navigation properties

An entity’s navigation properties return other related entities. The two navigation properties of interest in our example are Product.Category and Category.Products.

Category and Product have a one-to-many relationship. A Product has a parent category instance retrieved by means of its Category reference navigation property. The Product.CategoryId is the foreign key property that helps EF relate a product to its parent Category entity. 

On the other hand, a Category instance can retrieve its many products by means of its Products collection navigation property. The two navigation properties are the inverse of each other. 

Notice that the navigation properties lack substantive get and set implementations. Yet if we invoke, say, Product.Category, we expect DevForce to retrieve the product’s category from cache if it can find it and from the database if there is no related category in cache. DevForce can do this because it replaces your implementation of a navigation property with its own.

Notice that neither navigation property is virtual. You do not write virtual properties with DevForce Code First (as you must do with Entity Framework Code First). DevForce doesn’t need virtual properties because it rewrites these properties with the necessary navigation logic rather than trying to override these properties in a derived proxy class.

Look again at the implementation of Category.Products.

Notice that it returns a RelatedEntityList<Product>. Entity Framework Code First only requires that the return type be an ICollection<T>. DevForce honors that as well; we could have returned ICollection<Product>

In practice, the actual object that DevForce returns is a RelatedEntityList<Product> which implements ICollection<Product> as you would expect. Most developers prefer to declare that the property returns the more strongly typed RelatedEntityList<T> because it is more convenient to have access to the full RelatedEntityList API when you're working with this property. You are free to be more opaque if you prefer.

Notice also that Category.Products is a "ReadOnly" property; it has a getter but no setter. The developer chose to write the navigation property without a setter rather than as an auto-property for a good reason. The developer knows that consumers of a Category shouldn’t be able to set the Products collection; they can read the collection, maybe add products to the collection, but they should not replace the collection itself. By omitting the setter, the developer ensures that no one will set a category’s Products collection by accident.  ReadOnly collection navigation properties like this one are a good practice.

Add validation with attributes

You can decorate the properties of an AOP entity with validation attributes in much the same way as you do for generated entities. The only difference – a happy difference – is that you can add the validation attributes directly to the properties in your class: you don’t need a metadata "buddy" class.

Suppose the category name is required and a maximum length of 15 characters. We could enforce these constraints by adding the standard .NET validation attributes to the Category.CategoryName property:

DevForce verifiers are more capable than .NET validation attributes. We recommend that you apply one of the DevForce stock verifier attributes instead:

Of course you can also write your own custom verifiers and verifier attributes and annotate your properties in the same way.

Add property interceptors

The re-written properties of AOP entities participate in the DevForce property interception system.

You could induce the Product.ProductName property to return its value in upper case by adding the following method to the Product class.

This contrived “get interceptor” returns an upper-cased version of the ProductName value. Notice that it can be non-public … and probably should be as there is no good reason for application code to call this method.

DevForce discovers the interceptors by reflection. The method could be private in a full .NET model but not in Silverlight where private reflection is forbidden. Marking it internal gives DevForce a chance to find it in Silverlight when you make your model assembly visible to DevForce.

Map properties explicitly

The Entity Framework Code First mapping mechanisms are at your disposal. The example code relied entirely on Entity Framework Code First naming conventions for mapping the Category class to the “Categories” table. We didn’t have to tell EF that CategoryId is the primary key property corresponding to an integer “CategoryId” column in the “Categories” table.

But we could have made the mapping explicit either declaratively by applying Entity Framework’s mapping attributes or imperatively through configuration with the Entity Framework Fluent API.  Here is the same Category class, decorated with mapping attributes

The Table, Key, and Column attributes were all unnecessary as the class can be mapped by convention without them. But we might apply these attributes if our class and database table defied those conventions, as we see in this example:

What a mess! 

• The Category class maps to a table named “Product.Category”
• The Name property of the Category class maps to the “CategoryName” column
• The Category primary key property is named CategoryKey but the matching column is “CategoryID”
• Product’s foreign key connecting it to its parent Category entity has yet a third spelling, CategoryId (small-d). The ForeignKey attribute informs Entity Framework and DevForce that this is the foreign key property supporting the Category navigation property.

It’s a typical mess and, sadly, it could be worse.

Entity Framework Code First mapping is a big topic, beyond our ability to adequately cover in the DevForce Resource Center. Please review external sources, starting with Microsoft’s ADO.NET Entity Framework website, to learn more.

Guid keys

Guid keys are a common approach to client-side key specification. They are particularly useful in offline scenarios in which the user may create a new record but can't reach the database to save it. The application can serialize the entity to a local file temporarily until the server becomes available; DevForce supports this approach with temporary integer keys. But the developer may prefer the certainty of an assigned key that is both unique and permanent. 

EF does not assign Guid key values by default. The developer takes care of that. While key assignment can occur anywhere, many developers will set the key in the entity constructor as seen here:

Guid keys are also popular where database replication could result in integer key collisions; different databases might assign the same integer key values. You could choose Guids to forestall key value conflicts and also let EF assign these values with what appears to be a sequential Guid generator.

If you want Entity Framework to assign the keys, you can apply a DatabaseGenerated attribute to the property with the DataBaseGeneratedOption.Identity as follows:

You do not need ... or want ... the constructor assignment from the example above.

Default constructor required

 Both Entity Framework and DevForce require a default constructor in order to materialize your entities from query results. You don't have to write a constructor ... because you have one implicitly. Just don't block it completely by writing a constructor with parameters and neglecting to add a parameterless constructor.

Your default constructor does not have to be public. You can hide it from application developers with a non-public modifier. Here are some examples:

Unmapped properties

Many entity classes will be enriched with additional properties that express some business logic or make the entity easier to work with. We neither retrieve nor store such property values in the database. These properties are “unmapped” and we have to tell both DevForce AOP and EntityFramework that they shouldn’t rewrite these properties nor look for corresponding data in the database. The easy way to make these points clear is to annotate the property with the NotMapped attribute.

For example, suppose we add an IsProductOfTheDay property to the Product class. The value of IsProductOfTheDay is calculated; it is not retrieved from the Products table and it can’t be saved there either. We don’t want DevForce AOP to rewrite it. We don’t want EF to try to map it to the database. So we add the NotMapped attribute. The property might be written as follows:

Non-public properties

You can limit access to your persisted properties if you wish ... at the cost of adding WCF DataContract attributes.

Most DevForce applications are n-tier and all Silverlight applications are n-tier. They serialize entities across process and network boundaries. No markup is necessary when the entity classes conform to WCF requirements for default serialization. The following model classes do NOT require markup:

Note that all of the persisted simple properties (e.g., Product.ProductName) and reference navigation properties (Product.Supplier) have public getters and setters. Collection navigation properties (Supplier.Products) can do without setters but their getters must be public.

The Supplier.UnmappedPoperty is not persisted but it is serialized and its value is available on client and server.

If you prefer to hide access to some properties, you'll have to annotate the classes with DataContract attributes. We've redefined the example model to reduce access to some of the properties.

Notice that:

• The DataContract attribute specifies "(IsReference=true)". This is essential to support serialization of entities with circular references. You have a circular reference if two entities have navigation properties to each other ... as is typical in entity models.
  
  
• If any property has reduced access, the entire class must be marked up.
  
  
• We had to map the completely hidden Product.SecretProductName property with a custom DbContext using the Code First Fluent API. Entity Framework maps the public properties with internal setters by convention but won't map an entirely non-public property except via the Fluent API.
  
  
• You'd have to markup the class if it contains a public property that you do not want to serialize. Omitting the [DataMember] attribute on Supplier.UnmappedProperty excludes it from serialization.
   
• You can specify either internal or public access but you cannot specify protected or private.
  
  

The only non-public property access modifier is internal

You can make a property private in Entity Framework Code First but you can't do so in DevForce. A property must either be public or internal.

There are two primary reasons for DevForce's more limited choice:

1. DevForce only rewrites properties that are public or internal. This is our design choice; there is a tiny performance cost to a rewritten property and we think you shouldn't pay that price for private properties. Nor did we think that private properties benefit from rewriting with notification, interception, and validation logic as they can't participate in the binding scenarios where those capabilities are useful.
   
   
2. DevForce could not serialize private properties of entities in Silverlight applications ... but it can serialize internal properties as explained below.
   
   

Make internal properties visible in Silverlight clients

Silverlight prohibits private reflection, which means that DevForce cannot serialize/deserialize into the private properties of Silverlight entity classes. But internal properties can be read and written if and when the model project is made visible to the .NET serialization libraries, as you must do if you consume these classes in a Silverlight client.

Code First entities in DevForce also contain injected methods to handle serialization and deserialization.  These methods - OnSerializing, OnSerialized, OnDeserializing and OnDeserialized - have internal access.  If you use ImportEntities, faking, or the EntityCacheState, you must grant DevForce access to these internal members.

Add the following attributes to the Silverlight model project's AssemblyInfo file.