Entity Framework Team

We recently shipped Entity Framework 4.1, and it has been exciting to see the reception the new Code First and DbContext APIs have been getting in the developer community. What is also exciting is to be able to start talking more about other features we have been working on, like table-valued functions, unique constraints and spatial types support.

At present, enums support is by far the most requested improvement for Entity Framework. We know it because we get asked about it each time we meet with a customer. We also see questions every week in the comments of our blogs, in our forums, in tweets like this, and likewise in our own feedback site, in which enums currently has more than 1,600 votes. That is about 50% more votes than Code First!

After having had to explain several times why it takes so long for us to add enums support to EF, we are happy to say that we plan to do it in the next version after 4.1.

The goal of this blog post is to describe the design decisions we have made so far and to gather your feedback so that we can refine the design and calibrate the direction we have taken.

Understanding Enums (and why they are so important)

Unlike other things we get to work on, enumerations are an existing programming language feature. Our primary goal is to make sure the feature works as seamlessly as possible with the EF in Object/Relational Mapping scenarios.

At the same time we have to focus on incorporating the concept of enums into the core of the metadata system underlying the EF, the Entity Data Model (EDM), in a manner that serves other key pieces of the EDM ecosystem, such as OData and WCF Data Services.

In order to achieve these goals we had to first recognize what enums are (and what they aren’t) from the language design perspective, look at how they are commonly used within the realm of data oriented applications, understand requirement gaps, prioritize scenarios and come up with a design that can satisfy the most important among them.

A glimpse at enumeration support in the .NET programing languages

The design of enums support in .NET programming languages like C#, VB and F# is amazingly simple. Yet from the perspective of modeling a specific domain, enums unquestionably provide great expressiveness.

This becomes apparent when looking at this straightforward example in C#:

    public enum ShippingMethod

    {

        Express,

        Priority,

        Ground

    }

    [Flags]

    public enum ContentType : byte

    {

        Liquid = 1,

        Perishable = 2,

        Edible = 4

    }

    public class Package

    {

        public int Id { get; set; }

        public string Description { get; set; }

        public ShippingMethod ShippingMethod { get; set; }

        public ContentType? ContentType { get; set; }

        public string Reference { get; set; }

    }

Given this definition of Package, ShippingMethod and ContentType, the code necessary to change the ShippingMethod and ContentType of a package can be as simple as this:

    juiceBox.ShippingMethod = ShippingMethod.Ground;

    juiceBox.ContentType = ContentType.Liquid | ContentType.Perishable | ContentType.Edible;

Structural definition

In C# enums can be structurally described like this:

Instances of enum types present specific characteristics:

• Any enum value can be explicitly casted to its underlying type
• All possible values of an enum type can be obtained by casting any valid value of its underlying type to the enum type (i.e. valid enum values are not limited to the declared members of the enum type)
• However, casting directly between two different enum types is not allowed
• The default value for any enum type is always zero, casted to the enum type, even if there is no declared member in the enum type with a value of zero
• Enum instances are equal-comparable and order-comparable against any other instance of the same enum type

The following comparisons are supported for enums in C#:

• Equality comparison between enums: ==, !=
• Order comparison between enums: <, >, <=, >=

The following operators are supported in C# and return an enum of the same type:

• Simple arithmetic between enums and the underlying type: +, -, ++, --, +=, -=
• Bitwise operators between enums of the same type: ^, &, |, ~

The definition of enums in VB is very similar to C#, although enum types in VB are required to have at least one member, and member names are case insensitive. Operator rules over enums are also different in VB: most arithmetic operators can be applied but the result of the operation will be of the underlying type instead of being an enumeration. In fact, only bitwise operations between two enum instances will result in another enum of the same type.

Independently of the language, the following library methods on System.Enum are particularly useful:

• HasFlag: Used to verify whether an instance of an enum type contains a specific value (see more on enums that can contain multiple values in the next section).
• Parse and TryParse: Converts a valid string representation to an enum instance.
• ToString: Converts an instance of an enum to a string representation.

How enums are used in practice

As simple as enums are, there is a lot of richness in how people think about them and how they are used in real world applications. At a high level, the common usages of enums are characterized by the following notions:

• Enum types in .NET allow grouping a set of named numeric constants associated to the same concepts into a type:
• Like regular constants, enums are a much more manageable alternative to sprinkling magic numbers across your code.
• The ability to group sets of related constants and strong typing enable useful design-time services such as Intellisense and provide compile-time checks that help keep your code organized.
• Enum types in .NET always have an “underlying” integer type that determines the range of values that an instance can store:
• Fundamental aspects of using enums, such as the behavior of comparison, default values, arithmetic and bitwise operators depend on this underlying representation.
• Although this correlation to integers is fundamental to the design, it is often possible to use Enums without paying much attention to it.
• This is all consistent with the design of Enumerations in the C language, but in .NET enums are more type safe (e.g. you cannot assign directly a value of the underlying type to an enum variable without casting it explicitly).
• In some cases, a variable of an enum type is used to simultaneously store a combination of multiple values:
• This is implemented by treating the underlying integer representation as a “bit field”.
• In .NET, it is possible to express the intent of using an enum type in this way by adding the FlagsAttribute to the declaration of the type, and then by declaring each member to have an integer value that represents a different bit position:

    [Flags]

    public enum ContentType : byte

    {

        Liquid = 1,

        Perishable = 2,

        Edible = 4

    }

• Enumerations that can represent multiple values simultaneously are a powerful concept, but the implementation in .NET is extremely simple: the programing languages handle all enum types in the same way, e.g. bitwise operators can be applied to enums regardless of the presence of FlagsAttribute (in fact, the attribute’s sole impact in the behavior of the Base Class Library is in the conversion of an enum value to a string). In other words, there is no strong contract in using FlagsAttribute, and it is up to the developer to use only enums that were meant for multi-value in such a way.
• Some tend to think of enums types as a way to model constrained categorizations, which assumes variables of an enum type can be guaranteed to only hold instances of its declared members:
• Although enums are strongly typed in .NET, there is currently no way in .NET to express the intent to constrain the values to be only of the declared members. In fact, barring WCF serialization, nothing in .NET will constraint the value of an enum instance in this way.
• That said, this is evidently a very useful thing to do, in particular in cases in which an enum is part of a public contract of a service, or in data centered applications, in which these constraints will often be backed by a database constraint.
• Other languages outside of .NET, such as Java, deviate from the C design of enums based on integer underlying types to instead focus on constraining enums instances to only store declared values.

Use of enums in data oriented applications

Without native support for enums in the current version of Entity Framework, customers have come up with different ways to achieve similar functionality. The workarounds often require writing lots of additional code, and in the end, the experience is not as seamless as we would like it to be.

Incidentally, a common workaround, which consists of creating additional entity types for each of the types you would like to define as enums, can help illustrate the actual role of enums in data oriented applications.

Starting with the previous example, we would create additional entity types for ShippingMethod and ContentType, associating them to Package and then turning the ShippingMethod and ContentTypes properties into navigation properties:

    public class ShippingMethod

    {

        public int Id { get; set; }

        public string Name { get; set; }

    }

    public class ContentType

    {

        public int Id { get; set; }

        public string Name { get; set; }

        public virtual ICollection<Package> Packages { get; set; }

    }

    public class Package

    {

        public int Id { get; set; }

        public virtual ShippingMethod ShippingMethod { get; set; }

        public virtual ICollection<ContentType> ContentTypes { get; set; }

    }

Given this definition for Package, ShippingMethod and ContentType, the code for changing the ShippingMethod and ContentType of a package would be similar to this:

    var ground = context.ShippingMethods.Single(c => c.Name == "Ground");

    var liquid = context.ContentTypes.Single(c => c.Name == "Liquid");

    var perishable = context.ContentTypes.Single(c => c.Name == "Perishable");

    var edible = context.ContentTypes.Single(c => c.Name == "Edible");

    juice.ShippingMethod = ground;

    juice.ContentTypes.Clear();

    juice.ContentTypes.Add(liquid);

    juice.ContentTypes.Add(perishable); 

    juice.ContentTypes.Add(edible);

The solution based on entities is conceptually equivalent to one based on enums: in both cases, the list of all possible ShippingMethods and ContentTypes are used as “reference data” for Package.

However, there are noticeable differences:

• Additional tables and foreign key constraints need to exist in the database and be mapped to the entities.
• In order to establish an association, you need to first retrieve an instance of the related entity, e.g. by executing a query (this part can be made easier by adding an extra foreign key property to the entity, so you can establish an association by just assigning the value of the corresponding key to it, but the value of the key would likely become a magic number in your code).
• Many-to-many associations are necessary to achieve similar results to “flags” enums, such as Package.ContentTypes. Many-to-many associations require twice as many tables and foreign key constraints in the database as regular one-to-many associations.
• While instances of an entity type can have multiple properties, members of an enum type are in general constrained to only have a name and a value.
• In general, an application will only be able to reason about enum members that existed at compile time. On the other hand, a solution based on entities can more easily evolve after the application has been written and compiled, because all the data exist in the database and can be modified at any time.

In summary:

• The main role of enumeration types in data oriented applications is to serve as simple lookup lists for reference data
• Enums require significantly less ceremony than using Entities
• Because they are hardcoded and are constrained to only have names and values they are less broadly applicable

Enums support in Entity Framework and Entity Data Model

Taking into account the design of Enumerations in the .NET programing languages, the typical usage and the role of Enums in data oriented applications we explained above, we have decided to align the structural definition of Enums in the Entity Data Model with their definition in C#.

This means that the declaration of Enums in EDM will have the same elements that they have in C#, including the optionally specified underlying type, case sensitive member names, optional values, etc., and that the same rules are used to choose values not specified, e.g. the default underlying type is also Int32 and the implicit value of members is the previous member plus one, starting with zero for the first member.

This alignment in the design makes satisfying the requirements of O/RM scenarios for our customers much easier to use. It also enables all the richness of enums in the language, including such things as support for multi-valued (flags) enums in LINQ to Entities queries.

When it comes to other consumers and producers of the EDM, like OData, the fact that other languages might have significantly different definitions of enums becomes relevant. In particular, Java 1.5 introduces first-class language support for the “typesafe enum pattern” previously used in Java programs to substitute missing support for enums. Java enums remove the idea of integral underlying types and instead implements enums that are completely constrained to the declared members.

We recognize that there is a going to be a mismatch between the EDM semantics for enums and Java, but we believe the mismatch can be mitigated by the specific library implementations.

Requirements for Enums support in EF

The following is an exhaustive list of the things that we believe developers using EF should be able to do with enumerations:

Models, Metadata and Mapping

Users creating an Entity Data Model should be able to define enum types (optionally specifying their underlying integer type) and their members (optionally specifying member values explicitly).

The following XML fragment is an example of how the definition of a simple enum type looks in CSDL:

<EnumType Name="ShippingMethod">

  <Member Name="Express" />

  <Member Name="Priority" />

  <Member Name="Ground" />

</EnumType>

The corresponding enum type in C# looks like this:

    public enum ShippingMethod

    {

        Express,

        Priority,

        Ground

    }

Notice that the two type definitions above omit underlying type and member values. Since EDM will use the same rules for implicit underlying type and the assignment of unspecified member values as .NET programming languages, the two types above will unambiguously match, i.e. the underlying type for both is a 32 bit integer and the member values are 0, 1 and 2 for Express, Priority and Ground respectively.

Flags enums

When declaring an enum type in EDM, users should also be able to specify the intent to use this type as a “flags” enums:

<EnumType Name="ContentType" IsFlags="true">

  <Member Name="Liquid" Value="1"/>

  <Member Name="Perishable" Value="2"/>

  <Member Name="Edible" Value="4"/>

</EnumType>

The only effect of this attribute in the EnumType element is to drive code generation to include the FlagsAttribute in the enum type definition. For instance, this is the equivalent code in C#:

    [Flags]

    public enum ContentType : byte

    {

        Liquid = 1,

        Perishable = 2,

        Edible = 4

    }

Nullable enums

Once an enum type has been defined, it should be possible to declare nullable or non-nullable properties of this type in entities or complex types.

Example:

<EntityType Name="Package">

  <Key>

    <PropertyRef Name="Id" />

  </Key>

  <Property Name="Id" Nullable="false" Type="Int32" />

  <Property Name="ShippingMethod" Type="Model.ShippingMethod" Nullable="false"/>

  <Property Name="ContentType" Type="Model.ContentType" Nullable="true"/>

  …

</EntityType>

Enums as keys

In addition, properties of enum types can participate in the definition of primary keys, unique constraints and foreign keys, as well as take part in concurrency control checks, and have declared default values.

Mapping

Properties of enum types support all the same mapping scenarios as properties of the underlying type:

• An enum property in EDM can be mapped to any of the store integral types supported by EF: Byte, Int16, Int32 and Int64
• Entities with enum properties can be mapped using stored procedures and query views
• For object to conceptual mapping, both attribute-based (most commonly used in EntityObject code generated entities) and convention (most commonly used for POCO types) based mapping are available.

Note: We expect that customers will use enums in many cases in which previously they would have used entities with reference data. Unlike entities, enum types are not mapped to tables in the database. Users are free to have tables and foreign key constraints, or check constraints in the database that enforce enum values. However Entity Framework will not reason about these constraints at runtime, so it is up to the user to keep rows in those tables and enum members in sync.

New metadata APIs

The metadata API has been updated to be able to reason about enum types. The following classes, EnumType and EnumMember are used to represent enums in the EDM layer:

• System.Data.Metadata.Edm.EnumType class represents an enum type
• System.Data.Metadata.Edm.EnumMember class represents an enum member
• New overloads of MetadataWorkspace.GetObjectSpaceType(), MetadataWorkspace.GetEdmSpaceType() and ObjectItemCollection.GetClrType() have been added that allow navigating the mapping between enums the EDM layer and the object layer.

Code First APIs

Code First’s property mapping fluent APIs have been extended to support enum types.

Example:

    public class ShippingContext : DbContext

    {

        public DbSet<Package> Packages { get; set; }

        protected override void OnModelCreating(DbModelBuilder modelBuilder)

        {

            modelBuilder.Entity<Package>().Property(p => p.ShippingMethod).HasColumnName("sm");

        }

    }

Query

All types of Entity Framework queries (including EntityClient queries and object layer queries written in LINQ or Entity SQL) can refer to enums. For instance, the following operations are allowed:

• Projection of enum properties, constants and parameters
• Use of enum properties, constants and parameters in filtering predicates
• Use of enums as parameters and in the return type of Functions
• Use of enums as parameters and in the return type of pass-through SQL APIs such as ExecuteStoreQuery, ExecuteStoreCommand, SqlQuery, etc.
• Cast explicitly between enum instances and the underlying type of the enum (or types that support explicit cast from underlying type of the enum) in queries
• Use of equality and order comparisons: ==, !=, <, >, <=, >=
• Use of arithmetic and bitwise operators in LINQ queries: +, -, ^, &, |, ~ (the exact behavior and result type depends on the .NET language being used)

Note: Increment and decrement operators such as ++, --, += and -= have side effects and therefore cannot be supported in queries.

Example:

        var groundPackages =

            from p in context.Packages

            where p.ShippingMethod == ShippingMethod.Ground

            select p;

Update

Entity Framework entities and complex types that contain enum properties can be inserted, updated and deleted. In addition, enum properties can be store generated and used for concurrency control.

Example:

        var juiceBox = context.Packages.Where(p => p.Name == "Juice box");

        juiceBox.ShippingMethod = ShippingMethod.Ground;

        juiceBox.ContentType = ContentType.Liquid | ContentType.Perishable | ContentType.Edible;

        context.SaveChanges();

Designer support

The Entity Designer has been extended to support the definition of enum types. An upcoming blog post will contain more details about designer support.

Note: Reverse engineering a database into a model (usually called “database first”) never introduces enums into the model automatically. Users need to manually specify which properties represent enum types.

Code generation

Code generation, including EdmGen.exe, EntityObject template, Self-Tracking Entities template and DbContext template have been updated to generate enum type definitions and properties of enum types.

Limitations

There are several features we considered that will not be included in the upcoming release of EF:

ToString() and Parse()/TryParse() won’t be supported in queries

Translation into store queries would require very complex expressions to achieve fidelity with the behavior of these methods in the CLR.

Mapping Enums to strings and arbitrary types

We consider the general ability to perform property type transformations in the mapping to be an important feature, but it wasn’t a priority this time around. Barring type transformations the most natural thing to do for enums is to support mapping to integer numeric types.

Using enum properties as mapping discriminators is not supported

The Entity Framework runtime supports the use of Boolean properties as mapping discriminators, i.e. the value of the property in an entity is used to decide in what table in the store that entity instance should stored. We could consider adding the same capability for enum properties, but this wasn’t a priority in this release.

Feedback requested

As always, your opinions on all aspects of this design are welcome. However, there are specific areas in which we are seeking your help in deciding where to take the design. Please, take some time to answer them in the comments.

Checked or Strict enums

As we explained before, constraining the value of an enum to the declared members is one of the common notions of enums, however in .NET we don’t provide a way to express this intent. One thing we could consider doing is to enable this in EF:

When declaring an enum property, users should also be able to declare the intent to constrain the values of the property. They could do this using adding a new “Checked” facet to properties.

Example:

<EntityType Name="Package">

  <Key>

    <PropertyRef Name="Id" />

  </Key>

  <Property Name="Id" Nullable="false" Type="Int32" />

  <Property Name="ShippingMethod" Type="Model.ShippingMethod" Nullable="false" Checked="true" />

  <Property Name="ContentType" Type="Model.ContentType" Nullable="true" Checked="true" />

  …

</EntityType>

The only practical effect of the Checked attribute in the Property element of an enum type would be to enable the DbContext API to perform data validation in the property. DbContext performs data validation automatically by default on SaveChanges and can also perform it on demand. For an enum property that has this attribute, if the property value does not correspond to a declared member (or to a valid combination if the enum type is “flags”) validation will fail and SaveChanges will abort.

The equivalent behavior could be obtained when using Code First by adding a new validation data annotation or using a fluent API.

Example:

    public class Package

    {

        public int Id { get; set; }

        public string Description { get; set; }

        [Checked]

        public ShippingMethod ShippingMethod { get; set; }

        [Checked]

        public ContentType? ContentType { get; set; }

        public string Reference { get; set; }

    }

Note: The data validation feature in DbContext is explained in more details here and here.

Question: How important is it to validate enum values in this way for you? Would you give up any of the other features explained in this post for it?

HasFlag support

.NET 4.0 introduced this new method in System.Enum that makes it possible to detect whether an instance of a “flags” enum contains a value without having to resort to or think about bitwise operators. We could consider adding support for this method on LINQ to Entities.

Example:

        var perishableLiquids =

            from p in context.Packages

            where p.ContentType.HasFlag(ContentType.Perishable | ContentType.Liquid)

            select p;

This is equivalent to:

        var perishableLiquids =

            from p in context.Packages

            where p.ContentType & (ContentType.Perishable | ContentType.Liquid) ==

                (ContentType.Perishable | ContentType.Liquid)

            select p;

Question: How important is it to be able to use HasFlag in LINQ queries for you? Would you give up any of the other features explained in this post for it?

Options to disable code generation for specific types

Enum types are primarily a code construct and therefore their existence is commonly independent of an EF model. If you try to use an enum type that is already declared with your code-generated entities it can become very difficult because EF code generation will always generate a new enum type for the type defined in the EDM model.

We could consider improving this by defining an annotation that you could easily put on specific types (enum, entity or complex type) in your model that would signal EF code generation templates to ignore that type.

Question: How important is it to you to be able to skip generating specific types from your model? Would you give up any of the other features explained in this post for it?

Thanks,

Diego Vega
Program Manager
Entity Framework Team

We’d like to show you what is coming your way for Spatial types in the Entity Designer and of course, let us know what you think and give us feedback on the experience!

Goals

The goals for supporting Spatial types in the Entity Designer align with Entity Framework design goals for Spatial as well:

• First class support for Spatial types in the Entity Designer
• Model-first and Database-first support through the Entity Designer

Spatial Types

• Geometry
• Geography

Experience

Since the Entity Framework adds Spatial types as primitive EDM types, we treat them exactly as you are used to using primitive types in the Entity Designer.

1. Add Property to Entity Type
2. Set Data Type as Geography through the Property Window

Restrictions

Spatial types cannot be used as entity keys, in associations, or as discriminators. We give design-time validation errors if you attempt to use one of those invalid patterns.

1. Attempt to set property of type Geometry as entity key
2. Validation error in Error List

Feedback

As always, please let us know what is most valuable to you in the Entity Designer for using Spatial data types. Feedback is always appreciated!

Thank you,

Sarah McDevitt

Program Manager

Unique Constraints in the Entity Framework

We’ve been busy working on enabling unique constraints in the Entity Framework. Unique Constraints allow you to model candidate keys (also known as alternate keys, or natural keys). This post covers the design of the feature so that we can get some early thoughts and opinions on what you’d like to see in this feature.

Note: Tooling and the design time experience is an essential part of any Entity Framework feature that we do. However, the motivation of the Design blog is to take a look under the hood of the features as we build them, and therefore we cover XML metadata and code as opposed to what the design time experience will look like. We will have subsequent posts that cover the designer experience.

Background

Being able to model and use Unique Constraints is one of the top requests we hear from the community using Entity Framework. Like a primary key, a unique constraint is a set of properties on an entity whose values identify the entity as unique. Examples of unique constraints might be Social Security Number, Employee Number, Serial Number, etc. Unique constraints are often used to represent a natural and meaningful key, when a generated key is used as a primary key.

Most databases support unique constraints today.  Foreign key constraints can generally be based on any unique constraint (as opposed to only on the Primary Key) on the principal side.  

A key difference between a unique constraint and an entity key is that null values are allowed in columns that participate in the unique constraint.

Consider the following example. Here, I have an Employee entity type which includes an EmployeeId, as well as a Name and a Social Security Number.

The EmployeeId is the entity key, and it serves the purpose of uniquely identifying each Employee entity. However, I also have a SocialSecurityNumber property that can be used to uniquely identify the entity. This is a unique constriant, and today in the Entity Framework there is no way to specify that this is unique field.

This requirement itself is actually pretty self-explanatory, and we might as well say that what’s needed is a way to represent this “uniqueness” in the metadata that describes the entity data model. However, the fact that you can make assumptions about the uniqueness of a given property allows you to take advantage of that fact in interesting ways. For example, DDL generation could leverage this information to generate the corrsponding database constructs .

Taking this example further, let’s say I have the following entity data model.

In this case, I now have a few associations that are based on the EmployeeId. What I might actually want in this case is to build one of the associations using EmployeeId as the foreign key, but build the other association using the SocialSecurityNumber as the foreign key value – i.e. in this particular example, it might make sense to build my data model like this instead:

So what I’ve done here is that I’ve used the unique constriant on SocialSecurityNumber as the basis for the association between TaxWithholding and Employee. In this particular case, the SocialSecurityNumber property seems to be more appropriate and pertinent information defining the TaxWitholding entity type. It is also the perfect for acting as a “foreign key” to the parent Employee.  Because I have a first class association based on this constraint, I am also able to take advantage of the richness in the conceptual model – like being able to navigate the association using a Navigation Property.

Unique Constraints in the Model

Let’s take a look at CSDL metadata for Employee and TaxWithholding types, and the association between them:

<EntityType Name="Employee">

  <Key>

    <PropertyRef Name="EmployeeId" />

  </Key>

  <UniqueConstraint Name="SocialSecurityNumber">

    <PropertyRef Name="SocialSecurityNumber"></PropertyRef>

  </UniqueConstraint>

  <Property Type="Int32" Name="EmployeeId" Nullable="false" />

  <Property Type="String" Name="Name" Nullable="false" />

  <Property Type="String" Name="SocialSecurityNumber" Nullable="false" />

  <NavigationProperty Name="EmployeeDetail"

                      Relationship="UniqueModel.EmployeeEmployeeDetail"

                      FromRole="Employee" ToRole="EmployeeDetail" />

  <NavigationProperty Name="TaxWithholding"

                      Relationship="UniqueModel.EmployeeTaxWithholding"

                      FromRole="Employee" ToRole="TaxWithholding" />

</EntityType>

<EntityType Name="TaxWithholding">         

  <Key>

    <PropertyRef Name="SocialSecurityNumber" />

  </Key>

  <Property Type="Int32" Name="SocialSecurityNumber" Nullable="false" />

  <Property Type="Int32" Name="NumberOfDependents" Nullable="false" />

  <NavigationProperty Name="Employee"

                      Relationship="UniqueModel.EmployeeTaxWithholding"

                      FromRole="TaxWithholding" ToRole="Employee" />         

</EntityType>

<Association Name="FK_Employee_TaxWithholding">

  <End Type="Model.Employee"

       Role="Employee"

       Multiplicity="1" />

  <End Type="Model.TaxWithholding"

       Role="TaxWithholding"

       Multiplicity="0..1" />

  <ReferentialConstraint>

    <Principal Role="Employee">

      <PropertyRef Name="SocialSecurityNumber" />

    </Principal>

    <Dependent Role="TaxWithholding">

      <PropertyRef Name="SocialSecurityNumber" />

    </Dependent>

  </ReferentialConstraint>

</Association>

Foreign Key Associations may be based on a Unique Constraint on the principal end. The ReferentialConstraint element above shows exactly this scenario.

In order to represent unique constraints as they are defined in the store / database, Store Metadata (SSDL) also includes the ability to specify unique constraints as they are defined on the database schema. Here’s the corresponding SSDL for the above example:

<EntityType Name="Employees">

  <Key>

    <PropertyRef Name="EmployeeId" />

  </Key>

  <UniqueConstraint Name=“SocialSecurityNumber">

    <PropertyRef Name="SocialSecurityNumber" />

  </UniqueConstraint>

  <Property Name="EmployeeId" Type="int" Nullable="false" />

  <Property Name="Name" Type="nvarchar(max)" Nullable="false" />

  <Property Name="SocialSecurityNumber" Type="nvarchar(max)" Nullable="false" />

</EntityType>

<EntityType Name="TaxWithholdings">

  <Key>

    <PropertyRef Name="EmployeeId" />

  </Key>

  <Property Name="EmployeeId" Type="int" Nullable="false" />

    <Property Name="SocialSecurityNumber" Type="nvarchar(max)" Nullable="false" />

    <Property Name="NumberOfDependents" Type="nvarchar(max)" Nullable="false" />

    <Property Name="NumberOfAllowances" Type="nvarchar(max)" Nullable="false" />

</EntityType>

<Association Name="TaxWithholdingEmployee">

  <End Role="TaxWithholding"

       Type="Store.TaxWithholdings" Multiplicity="0..1" />

  <End Role="Employee" Type="Store.Employees" Multiplicity="1" />

  <ReferentialConstraint>

    <Principal Role="Employee">

      <PropertyRef Name="SocialSecurityNumber" />

    </Principal>

    <Dependent Role="TaxWithholding">

      <PropertyRef Name="SocialSecurityNumber" />

    </Dependent>

  </ReferentialConstraint>

</Association>

The details specified in SSDL are very similar to what is specified in the CSDL. A Unique Constraint in CSDL can map to a Unique constraint on the SSDL implicitly, based on how the columns are mapped in the MSL metadata. Nothing additional needs to be specified.

Here are some more details with regards to how Unique constraints can be specified:

• In many ways unique constraints are similar to entity keys:
  • Unique constraints will be supported on Entity Type
  • More than one scalar property may compose a Unique constraint.
  • Server generated values can participate in a unique constraint
  • Navigation Properties may not participate in a unique constraint.
  • Associations can be based on unique constraints
• However, unlike Entity Keys:
  • Unique constraints have names to identify them. These names should be unique within a type hierarchy.
  • Nullable properties may participate in unique constraints
• A given property can participate in more than one unique constraint.
• Properties participating in unique constraint may be mutable
• Unique constraints may include properties from a base type

Support for OnUpdate cascading behavior

Unlike Primary Keys, Entity Framework will support mutability on properties that participate in a unique constraint.

Along with that, we plan on supporting OnUpdate cascading behavior.  This is something that is supported by databases. It simply allows you to specify that when the principal end of the relationship changes, the dependent end should be automatically updated accordingly as well.

Cascading is only handled for entities and relationships that are loaded into the object state manager. If you have OnUpdate Cascade behavior specified in the model, it will most certainly also make sense to make sure that the database itself has the same OnUpdate Cascade specification so that the database will manage the referential integrity of your data. This is equivalent to the OnDelete Cascade behavior supported today for associations based on primary keys.

This is how you can specify OnUpdate Cascade behavior:

<Association Name="TaxWithholdingEmployee">

  <End Role="TaxWithholding"

       Type="Store.TaxWithholdings" Multiplicity="0..1" />

  <End Role="Employee" Type="Store.Employees" Multiplicity="1">

     <OnUpdate Action="Cascade" />

  </End>

  <ReferentialConstraint>

    <Principal Role="Employee">

      <PropertyRef Name="SocialSecurityNumber" />

    </Principal>

    <Dependent Role="TaxWithholding">

      <PropertyRef Name="SocialSecurityNumber" />

    </Dependent>

  </ReferentialConstraint>

</Association>

The default Action for OnUpdate is “None”.

What mapping scenarios are not supported?

We are still contemplating exactly what set of capabilities might not make it into the next release with regards to the unique constraint support– therefore your feedback on this will be of significant value to us.

As it stands right now, the following scenarios will *NOT* be supported:

• Split Entities based on Unique Constraints – this is the scenario where a single entity is split across multiple tables on the database, where the split/join is based on a Unique Constraint instead of Primary Key.
• Inheritance Support with Unique Constraints – Support mapping inheritance based on unique constraints as opposed to primary key 
•  Independent Association based on Unique Constraints – This is the association type that was present in Entity Framework 3.5SP1 (as opposed to the Foreign Key Associations that we released in Entity Framework 4.0). In theory it is possible to enable Independent associations to store the foreign key values based on unique constraints but we are considering not supporting it because of the popularity of Foreign Key Associations as the standard way of representing associations.

We would like to know more about whether you need the following capabilities:

• Associations based on unique constraints – Do you see the need to form associations using unique constraints where you are associating to a unique constraint on the principal end instead of the primary key on that entity? Is this something you see in existing/legacy databases?
• Mutability of Unique Constraints – Mutability of unique constraints are important. However, if you are associating to a unique constraint on the principal end, how important is mutability in this scenario?

 
Once again, the purpose of this post is to find out how you’d like to see the feature built – so please feel free to tell us what your own preferences would be around this feature.

Please let us know what you think!

Faisal Mohamood – Program Manager, Entity Framework

Kati Iceva – Software Design Engineer, Entity Framework

This article will explore the design of the feature in the framework, so we will focus on the metadata within the EDMX as opposed to the designer experience in Visual Studio.  We will cover that experience in a later post.  Other topics we will cover in the future include QueryViews and other complex Function Mapping scenarios.

With that said, here are the specific areas we will cover now:

·         A basic overview of TVFs; pros and cons vs. Stored Procedures and Views

·         How to call a TVF Directly

·         Mapping a TVF to a Collection of Complex type

·         Mapping a TVF to a Collection of Entity type and performing CRUD on the Entity

We’d love to hear your thoughts, so please feel free to comment and make suggestions about any part of this design.

What Are TVFs?

TVFs are User Defined Functions (UDFs) which live in the target database and whose return type is a table.  UDFs are constructs made up of one or more T-SQL statements.  In the context of a T-SQL query, TVFs can be used anywhere a View or a Table would be used.  Although there is some overlap between TVFs, Views, and Stored Procedures, there are key advantages which make TVFs appealing in certain scenarios.  Let’s look at how TVFs stack up against Views and Stored Procedures:

TVFs vs. Views
TVFs and Views are similar in that they are both composable.  This means that you can use the function—or the view—anywhere within the body of a T-SQL query.  Their major differences are, first, that SQL Views can only have one SELECT statement, whereas TVFs can have multiple statements as well as procedural code.  This makes it possible to design more complex logic with TVFs than with Views.  Additionally, TVFs can take parameters, whereas Views cannot.

TVFs vs. Stored Procedures
TVFs and stored procedures may both contain procedural code, but unlike stored procedures, TVFs can be used anywhere in a query.  This allows us to both compose queries using TVFs and filter the result set of a TVF.  One advantage of stored procedures over TVFs is that stored procedures are capable of returning multiple result sets.

Background: TVF declaration and usage in SQL

TVFs allow you to write complex statements and queries, all in the same place.  In this post we will use relatively simple TVFs in order to keep complexity low.  Please read this article to learn more about TVFs in SQL.

Throughout the post we will use these two TVFs to showcase functionality:

·         GetCategories() returns all of the entries in the Categories table.

·         GetDetailsForOrder(int) returns the Order Details for a given order for Id equal to Oid.

Typical usage of a TVF in T-SQL as follows:

This simple statement returns the category ID and Category Name from our TVF.

Note that we were able to call the TVF in the FROM clause of our T-SQL query, as we would a table.  Also note that we were able to pass in parameters, and that the result of the query was a table.  This combination of factors, as well as the possibility to have procedural code within your function, is what makes TVFs appealing.

Why Should You Use TVFs in EF?

If you already use TVFs, the advantages of having EF support are obvious: You will now be able to use your TVFs as the source for materializing entity types and complex types via queries in EF – giving you the ability to use LINQ and Entity SQL against them.  If you don’t already use TVFs, think about the potential we get from creating Entity or Complex type that is backed by a function instead of an entity.  TVF support enables interesting scenarios such as Full-Text search since in SQL, it is implemented using TVFs.

Using TVFs in Entity Framework

Now that we’ve established what a TVF is, let’s see what artifacts we need in order to use one in an EF app:

·         Metadata describing the store function and its return type.

·         A function stub is required to call the function from a LINQ query.  The stub is not required for Entity SQL queries.

These two items are all we need if we want to call the TVF directly in a LINQ or Entity SQL query.  However, to truly take advantage TVFs in EF (reusability, change tracking, CUD), we also need to describe the mapping of the function to a Collection of Entity Type or Collection of Complex Type.

TVFs as Functions in SSDL returning RowType

Storage Layer
In order to make the TVF visible to Entity Framework, we must declare the store function in the storage layer (SSDL).  We must specify the function name, whether or not it is composable, and the schema it belongs to.  Up until version 4 of EF, the Function node was only capable of returning a scalar.  Our new design required us to make two changes to this node: First, we can now set IsComposable to true, and therefore we are able to compose functions.  Second, the return type is no longer a property of Function, but instead a child node in which we can describe the rich return types produced by TVFs.

Here is how we declare the store function called GetCategories in our SSDL:

Here we specify the ReturnType of the Function.  In this case it will be a collection of RowTypes.

Object Layer
We need a function stub to refer to the store function from a LINQ query.  The result of calling the function stub is a set of unstructured rows.  See this design blog to learn more about function stubs.  Here is what the stub will look like:

This stub will usually reside within your strongly typed ObjectContext class.  Here are a few things to take note of:

·         The stub returns a collection of DbDataRecord.  These records aren’t richly typed and therefore only provide us with limited functionality.

·         The EdmFunction attribute is the store’s namespace since we are calling a store function.

·         Our function stub contains a meaningful body, as opposed to an exception (see here for an example).  This ‘bootstrapping’ allows us to call the function in the FROM clause of our LINQ query.  Here is exactly how we would call our TVF:

The stub is not required when using Entity SQL for our queries.  Here is how to call the same TVF in Entity SQL:

The functionality above is useful, but only to a limited extent since unstructured data records are read only.

Mapping TVF to Complex Types and Entity Types

Function Mapping is a new feature which allows us to map the TVF’s results to a collection of Complex Type as well as a collection of Entity Type.  By mapping to an Entity Type, we gain full CRUD functionality against our entities.  The first step is to specify the function mapping in the mapping layer.

Result Type Mapping

Below we map a function in the conceptual layer to a function in the storage layer with an explicit return type mapping.  Explicit mapping is supported for conceptual functions returning collection of Complex Type or a collection of Entity Type.  Using explicit mapping, we describe how each property in the conceptual function will map to a property in the store function.  We could use implicit mapping, but only for conceptual functions returning a scalar or a collection of Rowtype with primitive properties.

Collection of Complex Type

A TVF’s result set can map to a collection Complex Type.  This is the default behavior when using Model First or EDMGen.  Let’s explore this mapping using GetDetailsForOrder:

Storage Layer

Mapping Layer

To tie the function to a collection of Complex Types, we need to create a mapping between our store function and a conceptual function.  We do that in the following way:

The explicit mapping above describes how to map the columns returned by the TVF to our Complex Type’s properties.  It also describes the parameters.  In this iteration we will only support parameters of Primitive type.

Conceptual Layer

Finally we need a conceptual function whose return type is a collection of Complex Types.  The Complex type and the function look like the following:

In the code above we declared a complex type then we created a function which returns a collection of such type.  EDMGen uses “<FunctionMame>_result” as the Complex Type’s name by default when generating metadata.

Object Layer

Once these are in place we can use call TVF using Entity SQL.  However, we need a new function stub to use the TVF in a LINQ query:

The noteworthy differences from our first stub are that this one returns a collection of Complex Type, rather than a collection of unstructured records.  Also, note that the first parameter in the EdmFunction attribute is the conceptual function, as opposed to the store function.

Usage
Let’s have a look at the basic usage of our function in LINQ and Entity SQL.

Both samples do the same.  They call GetDetailsForOrder with an OrderId of 10248 and then iterate over the result.

Collection of Entity Type

We can also make our TVF return entities.  We get all of the functionality we would expect from entities, such as reading, writing, and navigation provided by using NavigationProperties.  EDMGen does not map to Entities by default, but we intend to provide tooling support to create such mapping without having to edit the EDMX.

Storage Layer
The store function definition remains the same as described above.

Mapping Layer
Now we need to describe the mapping between the store function and the conceptual function.

This mapping describes the TVF’s parameters and maps the function’s result to a collection of Entity types named OrderDetails.  Each ScalarProperty node has two properties, Name and ColumnName.  Name refers to the EntityType and ColumnName refers to the Store function.  Function Mapping supports Table-Per-Hierarchy inheritance, much like in FunctionImportMapping.  This topic will be covered in a later post.

Conceptual Layer
When you map a function to a collection of Entity types, you get the following in the CSDL:

This metadata is similar to our previous example.  However, when mapping to Entity types, we must list two additional properties in our Function node: an EntityContainer and an EntitySet.  These two values must refer to existing artifacts in the conceptual layer.

Object Layer
Here is our function stub for a TVF’s result set mapped to a collection of Entity Types:

Usage
With our mapping in place, we can begin using our Entities in the usual fashion.  In the following example we will call our TVF and do some simple update to the resulting Entities:

In this example we get the products in Order #10248 with a quantity greater than 1.  Then we change each quantity to 1.   The important thing to note about this scenario is that we were able to query for a specific set of order details –those with a quantity greater than 1—using a TVF.  Then we edited the resulting entities to which the TVFs result set was mapped.

Wrap-Up

In this article we have covered:

·         Background on TVFs in SQL

·         Calling a TVF directly from a LINQ or Entity SQL query

·         Metadata for mapping a collection of Complex Type to a TVF, and subsequent usage

·         Metadata for mapping a collection of Entity Type to a TVF, and subsequent usage including CUD

TVF support will be a key component of Entity Framework’s next release.  Our goal is to provider first-class support for TVFs by allowing users to map the function’s result set to Entity types and Complex types.  We look forward to getting your feedback, so feel free to make any comments or ask questions about this design.

Pedro Ardila
Program Manager
ADO.Net Entity Framework Team

Our team is looking at a few different options in this area and we really want to get your feedback on one of the options we are considering that takes a somewhat different approach to most existing migration solutions. 

We’ve put together a screen cast to walk you through a storyboard style mock-up we built that shows this solution being used to build and deploy an application. We really want your feedback to help us shape and evaluate this option, you can provide feedback using the comment functionality on this post. 

This is the first time our team has used a storyboard screencast to share proposed designs so we’d also love to hear your feedback on whether this is an effective way to share our ideas. 

ADO.NET Entity Framework Team

(HD option is available in lower right corner of player while the screencast is playing)

We’ll start with the small, fun things, and build up to a grand finale.

1. Association Highlighting

Let’s start with this. Consider the following model:

We would like to rename the navigation properties to something meaningful, as well as the foreign keys. But which navigation property is related to which foreign key? And to which association connector?

So, now you can select an association or navigation property and find out. Here, we select the “Address.Person” navigation property, and the designer highlights the two entity types involved in the association, the association connector, the navigation property on the other side, as well as the foreign keys that hold the navigation information.

This makes it easier for us to rename things to:

2. Property Reordering

Imagine that you want to add a “Name” property to the “Property” type above. You do this and end up with a type that looks like this:

 But of course, you want this new property to be the second one in the type, below “Id”. Well, now you can select this property and, for example, press Alt + Home, which will move that property to the top of the type, then on Alt + Down Arrow to move it down one slot. Here is a screenshot of the type, along with the new “Move Properties” menu:

You can now select multiple properties at the same time and move them.  For example:

3. Entity Shape Coloring

 Imagine, now, that our model has gotten more complex, and viewing it all in one window renders areas of the diagram hard to distinguish:

Entity shape coloring allows us to visually divide a single diagram into multiple meaningful areas by color coding them. You can select one or more entities and in their property sheet, change their color, which lets us do something like this:

4. Multiple Diagrams!

But what if you just want to look at subject areas within a diagram? Say, the product catalog entities, or the sales types. In that case, you can select any number of entities and move them into a new diagram by right-clicking and selecting the new “Move to new Diagram” menu item. If we do this to our “Property” type, we’ll see it appear in a new diagram. And, if we make the model browser tool window visible, we’ll see this:

Note that we now have a new “Diagrams” folder in the model browser, and that the new diagram opens in its own tab, allowing you to have multiple windows open at once against the same model. This diagram is a little sparse. Let’s bring into it any types related to “Property” by right-clicking it and selecting “Include Related”:

Now, color the “Person” type green, then bring its related type, and see how they pick up the original type’s color:

(Note that this models is not a real-world one and only intended for visualization purposes.)

Some additional notes:

-          You can also drag and drop associations, types, and entity sets from the model browser.

-          You can cut or copy and paste objects from one diagram to another.

-          Deleting objects from a diagram will no longer delete them from the model, but only from the diagram.

-          You can delete objects from the model by using Shift+Del, right clicking and selecting “Delete from Model”, or deleting them from the model browser.

-          Diagrams are stored in a child file of the edmx for new edmx files. For backwards compatibility, models created in previous versions of visual studio will keep the diagram information in the EDMX file itself. However, you can move the diagram information from the EDMX to a child file by right clicking and selecting the “Move Diagrams to Separate File” context menu.

We look forward to your feedback!

  Noam