Using the Designer

Let’s add a design surface to our new project.

• Right-click the project root and select Add/New Item… from the dropdown menu.
• Find the Data folder under Visual C# Items in the tree to the left and select Entity Framework Visual Editor from the list.
• Name the file to your liking. The name of the file will become the default name of the generated DbContext, though you can change that later. For our example we’ll call it MyModel.
• Click Add.

Three files will be added to your project: MyModel.efmodel, MyModel.efmodel.diagramx and MyModel.tt

• The .efmodel file holds the details of your design
• The .efmodel.diagramx file holds the details of the visual representations of your design, defining what you see on the screen
• The .tt file is a T4 template, the entry point into code generation. Other T4 templates were installed, but those are in a common location where your Visual Studio extensions reside

Should you decide to rename these files later, it’s important that the file names stay in sync. In fact, if you do rename them, you’ll need to make a manual edit to the .tt to let it know the name of the .efmodel file, since it needs to find that when you want to generate code. That’s in line 13 of the .tt file (line 17 for legacy projects), but we’ll talk more about that later.

Open the .efmodel file and – so exciting! – you’re presented with a blank screen. No worries – this is where you’ll model your classes. In your toolbox, you’ll see various items that can be added to model.

• Entity : A persistent class
• Unidirectional Association : A navigation property that only goes one way. The starting class will have a property of the type of the ending class (or a collection of them, depending on cardinality), but not the other way around.
• Bidirectional Association : A navigation property that will create properties in classes on both ends.
• Inheritance : Standard .NET inheritance (and its associated constraints). Start the line at the derived class and point to the base class
• Comment : Add a comment box anywhere on the model
• Comment Link : Link an existing comment to an Entity or Enum. Not required since comments can be free-floating, but nice to have if the comment refers to something specific on the diagram.
• Enum : An enumeration

Design Surface Properties

A peek at the Property page when you have the design surface selected (the background, rather than anything on it), shows the properties pertinent to the model itself and the DbContext class you’ll generate. These are as follows:

Things you’ll want to set first

There are a number of the designer properties you’ll want to set early, for various reasons:

• DbContext, Entity, Enum and Struct output directories
  • Set these earlier rather than later. You don’t want to generate a whole bunch of files in the wrong place, although if you do it isn’t the end of the world … the tool will remove them when you change the directory target, or you can always move them manually.
• EntityFramework version and EntityFramework Package Version
  • Setting these early on will ensure you get all the validations for the technology you’re targeting
• Generate Code on Save
  • If you’re going to do a bunch of edits and save often (as you should!), you’ll speed things up by turning this off until you’re ready for it.
• Warn on Missing Documentation
  • For when you know you’ll not by typing in the docs (like you shouold be doing, right?), leaving this on can flood you with warnings that hide messages you might otherwise really want to see.

Context Menu

Right-clicking on the design surface displays a Visual Studio context menu with some new choices pertinent to the designer.

Selecting Design Elements

You can select design elements from the visual designer, and their properties will appear in the standard Visual Studio property editor window. You’re able to select classes, their attributes and associations, enumerations and their values, comments, and lines connecting any model element; each has its own properties to display. Clicking onto the background of the designer will de-select any elements on it and show the properties of the designer itself.

Double-clicking an element, however, will take you to the code that you’ve generated for that element, if it exists. If it doesn’t, you’ll be asked if you want to generate the code, then you’ll go there.

The Entity Model Explorer Window

When you have a design surface open, Visual Studio will give you a new window under View / Other Windows / Entity Model Explorer. It’s a tree view of the diagrams, classes and enumerations in your model.

Selecting any class will show you the attributes of that class, as well as selecting that element on the design surface and displaying its properties in Visual Studio’s property window. Perfect for those too big models where you have to zoom out to see the whole picture but then can’t find anything because the text is too small to read.

You can add elements here as well by right-clicking the top tree node (with the name of your model) and selecting one of the menu choices.

Diagrams

On the topic of too-big models, you can now add multiple diagrams to your model (as of version 2.0). The diagrams are views on the model data, and can display any subset of your model to help create a laser focus on those things you want to see without the clutter of the rest of the elements.

Add a diagram by right-clicking the model explorer and selecting (oddly enough) “Add New Diagram”. You’ll get an empty design surface with a default name that you can change in the Property window.

We’ll go into more details of diagrams later.

Generating Code

Once you have your model the way you want it (and we’ll talk how to do that during the rest of this documentation), you can generate the code in one of three ways:

• If you’ve set the Generate Code On Save property of the design surface to true, just save the file
• At any time, you can right click the design surface and choose Generate Code from the context menu
• As with any T4 file, you can always right click the [Model Name].tt file in your project and choose Run Custom Tool from the context menu

Note: if you haven’t set up target project directories for your files, they’ll be dropped in the same directory that contains your .csproj file. Unfortunately, when that happens Visual Studio tries to be “helpful” and tucks them under the .tt file in the Solution Explorer tree, so you may not realize that they’ve been created. It’s a good practice to create a subdirectory for them and target the output there. Minimally setting the Entity Output Directory property on the design surface will default all the other output directories, and you’ll get visual confirmation in the Solution Explorer tree when you generate your code files.

Next Step

Diagrams