MvcScaffolding: One-to-Many Relationships

This post is part of a series about the MvcScaffolding NuGet package:

1. Introduction: Scaffold your ASP.NET MVC 3 project with the MvcScaffolding package
2. Standard usage: Typical use cases and options
3. This post: One-to-Many Relationships
4. Scaffolding Actions and Unit Tests
5. Overriding the T4 templates
6. Creating custom scaffolders
7. Scaffolding custom collections of files

Recently I’ve been adding features at a frantic pace, the most significant of which is support for relationships between entities. This means you can quickly create Create-Read-Update-Delete (CRUD) interfaces with drop-down lists, for example to set which “category” a “product” is in, or who is the “manager” or an “employee”.

Installing or Upgrading MvcScaffolding

The features I describe in this post are available in MvcScaffolding 0.9.4 or later. If you already have a previous version installed (find out by typing Get-Package into the NuGet console), you can upgrade it as follows:

Update-Package MvcScaffolding

After upgrading, you must restart Visual Studio, otherwise the old version will still be loaded into the VS appdomain, and bad things will happen. Restart Visual Studio now!

If you’ve never installed MvcScaffolding into your project, install it by entering the following into the NuGet Package Manager Console:

Install-Package MvcScaffolding

Defining simple relations between model classes

I’m going to continue the tutorial in the introductory post, which assumes you’ve already installed created the following model class:

public class Team
{
    public int TeamId { get; set; }
    [Required] public string Name { get; set; }
    public string City { get; set; }
    public DateTime Founded { get; set; }
}

Now I’d like to define another model class, Player. Each Player is associated with a team:

public class Player
{
    public int PlayerId { get; set; }
    public string Name { get; set; }
 
    // Having a property called <entity>Id defines a relationship
    public int TeamId { get; set; }
}

Simply having the TeamId property on Player is enough for both MvcScaffolding and EF Code First to realise there’s a 1:many relationship. Actually MvcScaffolding supports two conventions for defining relations – this is the simple one; I’ll explain the alternative later.

Note that defining TeamId as a non-nullable int, it’s mandatory. Each player must be in a team. If you wanted the relationship to be optional, use a nullable link property instead (i.e., public int? TeamId { get; set; }).

If you scaffold your UI now, by executing the following commands…

Scaffold Controller Team -Force
Scaffold Controller Player

(note the –Force parameter tells scaffolding to overwrite anything you already had for Team)

… then you can go to the URL /Teams and create, read, update, delete teams:

… and then you can go to the URL /Players and do the same for players. When you’re creating or editing a player, you’ll get a drop-down list to choose a team:

So, how does this work? How can the Edit action know what teams to offer in the dropdown? MvcScaffolding has created a PlayersController in which the Create/Edit actions send a list of PossibleTeams to the view to be rendered in a dropdown:

// This is in PlayersController
public ActionResult Create()
{
    ViewBag.PossibleTeams = context.Teams;
    return View();
}

If you wanted to filter the available teams in some way, you could easily edit this and put a .Where(team =>somecondition) clause on the end. Scaffolding isn’t supposed to generate a finished application; it just gives you a useful starting point very quickly!

Showing relationships on Index and Details views

Right now, the Index and Details views don’t show any information about relationships. The list of teams doesn’t tell you about players:

… and the list of players doesn’t tell you about teams:

The reason no relations are shown is that neither the Team nor Player class has a property to hold instances of the related entities, so there’s nowhere to get the information from. We can improve the situation by telling Player to have a property that holds its Team:

public class Player
{
    public int PlayerId { get; set; }
    public string Name { get; set; }
    public int TeamId { get; set; }
 
    public virtual Team Team { get; set; } // This is new
}

… and by telling Team to have a property that holds its Players:

public class Team
{
    public int TeamId { get; set; }
    [Required] public string Name { get; set; }
    public string City { get; set; }
    public DateTime Founded { get; set; }
 
    public virtual ICollection<player> Players { get; set; } // This is new
}

Notice that both of these new properties are marked virtual. This lets Entity Framework use its Lazy Loading feature so the associated entities will be fetched as needed, and spares you having to write code to fetch them in your controller. I’ll talk more about this in a moment.

Now if you were to scaffold the UI with models like this, by issuing the following commands:

Scaffold Controller Team -Force
Scaffold Controller Player -Force

… then you’d find the list of teams now states how many players are associated with each:

…and the list of players now states which team each player belongs to:

Similarly, if you go onto the other views (Details, Delete, etc.), you’ll see the related model objects displayed there too:

This is probably exactly what you expected to see. But pause for a moment and consider: when we want to display a related model object in a grid or in a details view, how do we know how to represent that other object as a string? There could be many properties on “Team” – how do we know which one to display in the Players grid?

The answer is that MvcScaffolding uses its own conventions to go looking for a property with a likely name: Name, Title, Surname, Subject, Count. If there’s no matching property, we fall back on using ASP.NET MVC’s Html.DisplayTextFor helper. If you don’t agree with the property it chose, you can either:

• Put a [DisplayColumn] attribute on your model class. For example, by putting [DisplayColumn("SomeProperty")] right before “public class Team…” and then rerunning the scaffolder, you’ll cause it to choose the property SomeProperty, if there is one.
• Or, modify the T4 template to specify your own conventions (see the forthcoming post for info about customising T4 templates)
• Or, just edit the generated views and change them! This is the easiest and best choice normally. Remember, scaffolding just gives you a quick starting point. It’s up to you to work on the code to meet all your own application’s requirements.

Eager Loading and SELECT N+1

If you’ve used ORMs before, then when you heard me talk about lazy loading you probably caught the scent of possible blood. If the Player’s “Team” property is marked virtual and hence lazy loaded, then when we display the grid of Player entities, does rendering each row cause us to issue yet another SQL query to fetch the Team for that Player? That, by the way, is called a “SELECT N+1” problem and leads to serious performance issues.

Fortunately, when the scaffolder generates your Index actions, it anticipates this and instructs EF to “eager load” all the related entities up front in a single SQL query. Example:

// This is on PlayersController
public ViewResult Index()
{
    return View(context.Players.Include(player => player.Team).ToList());
}

If your model has multiple relations, they will all be eager loaded for the grid. However, we don’t eager load for the other actions (Edit, Create, etc.) because there’s no scale problem with those – you’re only loading a single entity, and the code is easier to understand if we use normal lazy loading in those cases.

It also works when you’re generating repository classes, too, by the way. If you were to build everything with repositories like this:

Scaffold Controller Team -Repository -Force
Scaffold Controller Player -Repository -Force

… then your controllers would have constructors that receive all of the repositories they need, e.g.:

public PlayersController(ITeamRepository teamRepository, IPlayerRepository playerRepository)
{
    this.teamRepository = teamRepository;
    this.playerRepository = playerRepository;
}

… and the Index actions would still eager-load relations, using a slightly different syntax that the repository interface understands:

// This is on PlayersController
public ViewResult Index()
{
    return View(playerRepository.GetAllPlayers(player => player.Team));
}

You can thank Scott Hanselman for this feature of doing eager loading automatically. He hassled me about it yesterday, so here it is 

Defining more complex relations between model classes

Depending on what data access technology you’re using, there may be many possible ways of defining how models are related together. If you’re using EF Code First, for example, you could be using its fluent configuration interface, which means writing code with statements like “someEntity.HasOptional(x => x.Players).WithForeignKey(x => x.TeamId).CascadeDelete()” and so on.

MvcScaffolding doesn’t know about all of that. For one thing, fluent configuration exists only at runtime (and scaffolding works at design time), and for another, you might be using any data access technology with its own configuration system. You can still use fluent configuration or anything else; just don’t expect scaffolding to know about it.

Instead, MvcScaffolding supports two simple and broadly applicable conventions that will work fine with most data access technologies, including EF.

(1) You can define a simple parent relation to the model class <SomeEntity> by adding a property called <SomeEntity>Id, as you’ve already seen:

public class Player
{
    public int PlayerId { get; set; }
    public string Name { get; set; }
 
    // This links Player to Team
    public int TeamId { get; set; }
}

Note that if you also have a Team property on Player (as in the code earlier), EF recognizes this convention and populates Team with the entity specified by TeamId. Scaffolding, however, doesn’t need to know or care about this: it just displays Team information in Player views because that property is there.

(2) You can define a complex parent relation by adding a property called <Anything>Id, plus another property called <Anything> that defines the type of the relation. For example, you could make Team objects reference other Team objects, or multiple Person objects:

public class Team
{
    public int TeamId { get; set; }
    // ... other Team properties go here
 
    // Each Team has an optional "next opponent" which is another Team
    public int? NextOpponentId { get; set; }
    [ForeignKey("NextOpponentId")] public virtual Team NextOpponent { get; set; }
 
    // Each Team also has a required Manager and Administrator, both of which are people
    public int ManagerId { get; set; }
    public int AdministratorId { get; set; }
    [ForeignKey("ManagerId")] public virtual Person Manager { get; set; }
    [ForeignKey("AdministratorId")] public virtual Person Administrator { get; set; }
}

The [ForeignKey] attributes are there for EF’s benefit, so it understands what we’re doing. If you’re using another data access technology, you may not need them, or you may need something else. MvcScaffolding doesn’t know or care about those them.

Of course, you don’t have to follow these conventions if you don’t want, but these are the ways that MvcScaffolding knows how to generate typical CRUD UI respecting the associations.

What else is new

There are a lot of other smaller improvements in MvcScaffolding 0.9.4. For example,

• Based on your feedback, controller names are now pluralized by default (e.g., you get PeopleController rather than PersonController for a model of type Person, unless you explicitly enter PersonController as the controller name when scaffolding)
• There’s now a single CreateOrEdit partial shared by both the Create and Edit views
• Support for master pages in ASPX views is better
• It runs on NuGet 1.1 now
• You no longer need to compile (or even save!) your code before scaffolding it. Because it now uses the VS CodeModel API, compilation is irrelevant. However, make sure your code is syntactically valid when you scaffold, otherwise you’ll get a big spew of errors.

In fact, there are loads of improvements so I won’t list them all – see the source code log if you want to know everything!

In the next post I’ll show how you can customise the T4 templates and possibly even how to create completely new scaffolders of your own.

Data Annotations in the Entity Framework and Code First

Data annotation attributes were introduced in .NET 3.5 as a way to add validation to classes used by ASP.NET applications. Since that time, RIA Services has begun using data annotations and they are now part of Silverlight.  Code First allows you to build an EDM Entity Framework model using code (C# or VB.NET) and is now in its thirdCTP.

Feedback we’ve received from these CTPs shows demand for Code First to read data annotation attributes from class and property definitions to configure aspects such as maximum string length, which properties are keys, or the table name in which to store a type of entity.
This post outlines which existing data annotation attributes we’ll adopt and which new attributes we are proposing.
Using Data Annotations
When building a model using Code First, you start by writing a set of entity classes. For example:

public class Book
{
    public string ISBN { get; set; }
    public string Title { get; set; }
    public string AuthorSSN { get; set; }
    public Person Author { get; set; }
}

public class Person
{
    public string SSN { get; set; }
    public string Name { get; set; }
    public ICollection<Book> Books { get; set; }
}

When using this class model with Code First in CTP3, you would need to use the fluent API to describe which properties are keys, which relationships exist, and the length of each string property if you wanted these to be constrained. These are very common tasks and we’d like users of Code First to be able to make these kinds of configuration without having to use the fluent API to describe the model. Using data annotation attributes, the above model characteristics can be made declaratively as part of the class definition:

public class Book
{
    [Key]
    public string ISBN { get; set; }

    [StringLength(256)]
    public string Title { get; set; }

    public string AuthorSSN { get; set; }

    [RelatedTo(RelatedProperty=“Books”, Key=”AuthorSSN”, RelatedKey=”SSN”)]
    public Person Author { get; set; }
} 
public class Person
{
    [Key]
    public string SSN { get; set; }

    [StringLength(512)]
    public string Name { get; set; }

    [RelatedTo(RelatedProperty=”Author”)]
    public ICollection<Book> Books { get; set; }
}

Existing Data Annotation Attributes
There are several existing data annotation attributes in the System.ComponentModel.DataAnnotations namespace that can be used by Code First. These are:
KeyAttribute
KeyAttribute is used to specify that a property/column is part of the primary key of the entity and applies to scalar properties only.
StringLengthAttribute
StringLengthAttribute is used to specify the maximum length of a string. As there is no minimum length in Code First or EF, the “MinimumLength” property on the attribute would be ignored. This attribute applies only to properties that are of type string.
In .NET 4.0, a negative MaximumValue is not allowed. but in the next version of the framework the recommendation is to change this behavior so that a value of ‘-1’ means “max”. This isn’t ideal, so another idea we are considering is to make a MaxStringLengthAttribute that derives from StringLengthAttribute. The MaxStringLengthAttribute wouldn’t take parameters, but would just assume the maximum allowable value.
ConcurrencyCheckAttribute
ConcurrencyCheckAttribute is used to specify that a property/column has a concurrency mode of “fixed” in the EDM model. A fixed concurrency mode means that this property is part of the concurrency check of the entity during save operations and applies to scalar properties only.
RequiredAttribute
RequiredAttribute is used to specify that a property/column is non-nullable and applies to scalar, complex, and navigation properties:

• Scalar properties: means this property is non-nullable (even if the CLR type says it is nullable).
• Complex properties: the attribute is not allowed here so we would throw an exception
• Navigation properties
  • Collection property: the attribute is not allowed here so we would throw an exception
  • Reference property: this means the backing FK property is non-null, and that the end of the association is cardinality “1” (instead of 0..1).

TimestampAttribute
The TimestampAttribute is used to specify that a byte[] property/column has a concurrency mode of “fixed” in the model and that it should be treated as a timestamp column on the store model (non-nullable byte[] in the CLR type). This attribute applies to scalar properties of type byte[] only. and only one TimestampAttribute can be present on an entity as this is what is allowed on most database platforms.
DataMemberAttribute
The DataMemberAttribute, while not strictly part of the data annotation collection, can be used to help specify the ordinal of primary keys. This is important on entities where there is a composite primary key and you want to make an assertion about the order the keys are specified on the database or are used in your application. This attribute applies only to scalar properties only that are part of the key. Ordinals do not need to be consecutive, they only specify the relative order of the key properties in metadata.
Ideally we’d like to be able to specify the key order as part of the KeyAttribute via an “Ordinal” property, but we can’t make changes to KeyAttribute until the next release of the .NET framework.
New Data Annotation Attributes
While the existing data annotation attributes provide many useful options for defining your model, there are still several common cases where we’d like to be able to make model changes with annotation attributes. Our goal with data annotation support in Code First is not to provide another way to completely specify a model, but to provide a mechanism that addresses the most common kinds of configurations that developers need to influence their model.
This is an area where it would be great to get early feedback so we can incorporate your ideas into our data annotation plan - below are descriptions of the annotation attributes we are proposing for Code First.
RelatedToAttribute
The RelatedToAttribute is used for two things:

• To assign bi-directionality to certain relationships where the built-in convention doesn’t detect it
• To associate a navigation property with its foreign key(s)

The RelatedToAttribute is placed on navigation properties and can be present on zero, one, or both ends of a relationship. There are a few parameters on the RelatedToAttribute:

• A property to optionally specify the RelatedProperty on the target type.
  This is to support bi directionality in relationships (Book.Author is related to Person.Books, for example).
• A property to optionally specify the keys on this entity that constrain the relationship.
  This can be either the primary key(s) if the attribute is on a navigation property on the principal end of a relationship, or the foreign key(s) if the attribute is on a navigation property on the dependent end of a relationship.
• A property to optionally specify the keys on the related entity that constrain the relationship.
  This can be either the primary key(s) if the attribute is on a navigation property on the dependent end of a relationship, or the foreign key(s) if the attribute is on a navigation property on the principal end of a relationship.
• A property to optionally specify cascade delete behavior.
  When this property is set to true and the principal entity is deleted, the dependent end of the relationship will also be deleted.

In the example at the beginning of the blog post, the RelatedToAttribute was used to related the Book.Author and Person.Books navigation properties so that all of Book.AuthorSSN, Book.Author, and Person.Books represent the same relationship in the model.
We also considered using the existing AssociationAttribute to specify relationships. however this attribute assumes that there already is a backing model and requires a relationship name and required key properties which are not needed when describing your model with Code First.
LengthAttribute
LengthAttribute can be used to specify the maximum length of an array type, such as a byte[] and applies only to properties. A value of ‘-1’ means “max” and all other negative values are not allowed. There is overlap here with the StringLengthAttribute: when the LengthAttribute is specified on a property of type string, the semantics will be the same as StringLengthAttribute.
StoreGeneratedAttribute
The StoreGeneratedAttribute can be used to specify that a property’s value is generated on the database store and the only store generated pattern supported in the first version is “identity”. This attribute applies to properties only and has a single optional nullable boolean property Identity. A null value for Identity means that no decision should be made for Identity: the convention or an explicit API call will be made to turn the identity pattern on or off.
StoreNameAttribute
The StoreNameAttribute can be used to specify a name for a store/database item. This attribute has different meanings depending on the kind of thing this attribute applies to:

• If the attribute is on a context class, it means “database name”.
• If the attribute is on an entity class, it means “table name”.
• If the attribute is on a property in an entity class, it means “column name”.

StoreIgnoreAttribute
StoreIgnoreAttribute can be used to specify that a CLR type or property should not be included when reading type or property metadata from a CLR type. This attribute can apply to classes, which means they should not be considered as an EntityType or ComplexType object but can also apply to properties, which means that property should not be part of the EntityType or ComplexType. We haven’t finalized the name of this attribute yet, so if you have suggestions, please let us know.
StoreInlineAttribute
StoreInlineAttribute can be used to specify that a CLR type should be considered as a ComplexType when reading type metadata from CLR types. Complex types can be thought of as a class without an identity/keys, or a logic grouping of properties (such as an Address or PhoneNumber) and applies only to class definitions. ComplexTypes are stored inline with the entity. We may choose not to include this attribute as the convention we are thinking of adding to Code First should detect most cases where a complex type is being used.
Other Possibilities
There may be other kinds of model definition that you’d like to be able to do using data annotation attributes. Some other candidates are:

• Being able to specify whether a string is unicode or not
• Being able to specify whether a type is variable or fixed length
• Having data annotation attributes put CSDL annotations in your model that other systems (such as OData) can read. An example of this is the RangeAttribute.

Let us know if any of these options sound interesting or if there is something else you’d like us to consider.
Summary
Code First will offer a few different ways of configuring a model: purely by built-in conventions, using dataannotation attributes to make certain kinds of model changes, or by using a fluent API to fully customize the model. To provide more flexibility over the existing data annotation attributes, we are adding new attributes that Code First can use.