Persistent Entities

Modeling your persistent entities (classes) is the same experience as most any other modeling tool – you drag the class onto the design surface from the toolbox, name it, and start adding properties. You won’t model operations (methods), though, since our focus is on creating code for Entity Framework. If you want to add operations, you’ll do that in partial classes.

Adding an Entity

With the designer open, find the Entity tool in your toolbox. Click and hold down the left button, then drag it to the design surface.

You should see a new class appear on the design surface:

You can change the width of the entity on the designer to make things more readable. Height is automatic and can’t be changed manually - it will be as tall as needed to show all the properties. But the entity may be collapsed down to its name bar by clicking the chevron at the top right of its display. When collapsed, it may be expanded back to its original size by clicking the chevron again.

You can collapse and expand the Properties and Associations compartments by clicking the small + (or -) icon to the left of their gray title bars.

A quick note about the Associations compartments. You’ll note that they’re divided into Association Sources and Association Targets. This really isn’t a big distinction … it has to do with how you started drawing the association and is an artifact of the Microsoft Modeling SDK. One day (hopefully) they’ll be combined into just Associations, but that will take a refactoring of the inner structure of the designer and is a Big Deal. There’s more about Associations later.

Removing an Entity

To remove an entity, simply select it (from either the design surface or the model explorer) and hit the Delete key. It will be removed from the model completely without confirmation, as will its associations with other classes. If you do this by accident, you can undo it (Ctrl-Z or Edit/Undo from the menu).

If that entity is the superclass (base class) for other entities, you’ll be asked if you want to push its attributes and associations down to those other entities prior to its removal.

Entity Properties

Selecting the entity from either the design surface or the model explorer allows you to edit its various properties:

Context Menu

Right-clicking on an entity displays a Visual Studio context menu with some new choices pertinent to that entity.

INotifyPropertyChanged

You can optionally implement the standard INotifyPropertyChanged interface, especially useful for data binding in WinForms applications. By changing that property to True (by default it’s False), the standard T4 templates will generate code you can customize by implementing a partial method.

The shape on the diagram will change to have a dashed blue border, helping you immediately see which classes will generate change notification code. Since INotifyPropertyChanged requires a bit of logic, the properties of that class won’t be autoproperties. Each property will be set to AutoProperty = False when Implement INotifyPropertyChanged is set to True; if you set AutoProperty to True while indicating that you want INotifyPropertyChanged code, you’ll get a warning on model validation indicating that said property won’t participate in change notification since it’s an autoproperty.

The generated code for a property will look like the following:

   /// <summary>
   /// Backing field for Foo
   /// </summary>
   protected string _Foo;
   /// <summary>
   /// When provided in a partial class, allows value of _Foo to be changed before setting.
   /// </summary>
   partial void SetFoo(string oldValue, ref string newValue);
   /// <summary>
   /// When provided in a partial class, allows value of _Foo to be changed before returning.
   /// </summary>
   partial void GetFoo(ref string result);

   public string Foo
   {
      get
      {
         string value = _Foo;
         GetFoo(ref value);
         return (_Foo = value);
      }
      set
      {
         string oldValue = _Foo;
         SetFoo(oldValue, ref value);
         if (oldValue != value)
         {
            _Foo = value;
            OnPropertyChanged();
         }
      }
   }

   public virtual event PropertyChangedEventHandler PropertyChanged;

   protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null)
   {
      PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
   }

Note that this interface doesn’t give you sufficient detail to know how a property changed, only which property changed; Microsoft never intended it to. Its initial purpose was to support data binding, so it’s an important part of .NET, but you need more info to handle property change notifications outside of a data binding context. You have that in the code that’s generated when you set AutoProperty = False in the model for an entity’s property.

Any generated property with a backing field gives you the chance to do work (log, massage the return value, etc.) in their get and set methods by implementing the corresponding GetXXX and SetXXX partial functions. In those partials, you have access to the old and new values (for the SetXXX method) and can implement whatever logging, etc. you need. Therefore, when tracking changes, the generated OnPropertyChanged method will be used when the .NET Framework finds it appropriate but your work should go in the SetXXX partial method.

Next Step

Properties