The first partial method, ObjectContext.OnContextCreated, lets you add custom code that will be executed at the time the context is instantiated. Here is how that is implemented in the generated code.

The method is defined in the class that derives from ObjectContext (e.g., BAEntities). As you can see in the following code, VB and C# differ in their syntax:

VB
Partial Private Sub OnContextCreated()
End Sub

C#
partial void OnContextCreated();

OnContextCreated is called by the context object’s constructor and the constructor overloads, as shown in the following code:

VB
Public Sub New()
  MyBase.New("name=BAEntities", "BAEntities")
  Me.OnContextCreated
End Sub

Public Sub New(ByVal connectionString As String)
  MyBase.New(connectionString, "BAEntities")
    Me.OnContextCreated
End Sub

Public Sub New(ByVal connection _
 As Global.System.Data.EntityClient.EntityConnection)
  MyBase.New(connection, "BAEntities")
  Me.OnContextCreated
End Sub

C#
public BAEntities() : base("name=BAEntities", "BAEntities")
{
   this.OnContextCreated();
}

public BAEntities(string connectionString) : base(connectionString, "BAEntities")
{
  this.OnContextCreated();
}

public BAEntities(global::System.Data.EntityClient.EntityConnection connection)
 : base(connection, "BAEntities")
{
  this.OnContextCreated();
}

By default, the OnContextCreated partial method contains no code because in the generated classes, the partial methods are only being declared. In the partial class that you write, you can add your own code to the method.

VB
Private Sub OnContextCreated()
 'add logic here
End Sub

C#
partial void OnContextCreated()
{
  //add logic here
}

Every scalar property of every entity has its own version of PropertyChanging and PropertyChanged—for example, FirstNameChanged and FirstNameChanging. Like OnContextCreated, there is no default implementation for PropertyChanging and PropertyChanged; only a declaration. The methods exist in case you want to take advantage of them. PropertyChanging lets you insert logic when a property is about to change, and PropertyChanged is hit after the property has changed.

In the generated code, the methods are defined and then called in each property’s setter. The following examples show what this looks like for the ActivityName property of the Activity entity in the generated code. First the two partial methods are declared (see Example 10-2).

VB
Partial Private Sub OnActivityNameChanging(ByVal value As String)
End Sub
Partial Private Sub OnActivityNameChanged()
End Sub

C#
partial void OnActivityNameChanging(string value);
partial void OnActivityNameChanged();

Then the ActivityName property calls those methods just before and after the value is changed (see Example 10-3).

VB
Public Property ActivityName() As String
  Get
    Return Me._ActivityName
  End Get
  Set
    Me.OnActivityNameChanging(value)
    Me.ReportPropertyChanging("ActivityName")
    Me._ActivityName = Global.System.Data.Objects.DataClasses. _
     StructuralObject.SetValidValue(value, true)
    Me.ReportPropertyChanged("ActivityName")
    Me.OnActivityNameChanged
  End Set
End Property

C#
public string ActivityName
{
  get
  {
    return this._ActivityName;
  }
  set
  {
    this.OnActivityNameChanging(value);
    this.ReportPropertyChanging("ActivityName");
    this._ActivityName = global::System.Data.Objects.DataClasses.
     StructuralObject.SetValidValue(value, true);
    this.ReportPropertyChanged("ActivityName");
    this.OnActivityNameChanged();
  }
}

VB
Partial Public Class Activity
End Class

C#
public partial class Activity
{
}

VB
Private Sub OnActivityNameChanging (ByVal value As String)
  If value.Length > 50 Then
    Throw New InvalidOperationException _
     ("Activity Name must be no longer than 50 characters")
  End If
End Sub
Private Sub OnActivityNameChanged ()

End Sub

C#
partial void OnActivityNameChanging (string value)
{
  if ((value.Length) > 50)
    throw new InvalidOperationException
     ("Activity Name must be no longer than 50 characters");
}
partial void OnActivityNameChanged()
{}

Here’s an example of taking advantage of these methods. Many databases use computed columns to perform calculations on the fly. An example of this is in Microsoft’s sample database, AdventureWorksLT. The LineTotal column of the SalesOrderDetail table is a computed column. Figure 10-1 shows the column properties in the database. You can see that the Computed Column Specification property formula calculates the LineTotal based on the UnitPrice, UnitPriceDiscount, and OrderQty columns.

Figure 10-1. The LineTotal column, a computed column in the AdventureWorksLT SalesOrderDetail table

You would likely want to know that value in your application as the order is being created or modified, without depending on a trip to the database to get the LineTotal. Instead, you can create a method or read-only property in the partial class to compute the LineTotal locally, and then call that method anytime the UnitPrice, UnitPriceDiscount, or OrderQty column is changed.

Because LineTotal is a computed column in the database, the value created on the client side will not be sent to the server upon calling SaveChanges. Thanks to the default dynamic command generation capability, that LineTotal value will be replaced by the value computed by the database when you call SaveChanges.

The custom method or property gives you the ability to calculate that property locally as needed.

Although this computed property works very well for formulas in which the required values are contained within the same entity, you have to be careful if you are calculating data from related entities. The SalesOrderHeader entity in AdventureWorksLT has a SubTotal property that could be populated by summing up the LineTotal properties of all related SalesOrderDetails. But this assumes that all of the related details have been retrieved, and it may require a quick trip to the database to ensure that this is so. Depending on your application’s architecture this could be a bad assumption to make, so this is something to consider before depending on this type of calculation on the client side.

As I mentioned in the preceding chapter, SavingChanges is your only opportunity to validate or affect data before it is persisted to the database. SavingChanges executes just prior to when the SaveChanges method builds the database Insert, Update, and Delete commands. Because this represents a single event for all of the entities in your model, it is possible that you will have quite a lot of code in here, if you need to make some last-minute changes to any or all of the types in your system. Therefore, you’ll want to consider how you organize these validations.

You could perform them per entity type, or you could perform them per EntityState.

You could also build the validators into partial classes for the various entities, and call them from ObjectContext.SavingChanges.

VB
Dim TripEntries = From entry In osm.GetObjectStateEntries _
                  (EntityState.Added Or EntityState.Deleted _
                   Or EntityState.Modified Or EntityState.Unchanged) _
                  Where TypeOf entry.Entity Is Trip

C#
var TripEntities = from entry in osm.GetObjectStateEntries
                   (EntityState.Added | EntityState.Deleted |
                    EntityState.Modified | EntityState.Unchanged)
                   where entry.Entity is Trip
                   select entry;

VB
Private Sub BAEntities_SavingChanges _
 (ByVal sender As Object, ByVal e As System.EventArgs) _
 Handles Me.SavingChanges

  Dim osm = Me.ObjectStateManager
 'get Added or Modified entries
  For Each entry In osm.GetObjectStateEntries _
   (EntityState.Added Or EntityState.Modified)
    If TypeOf entry.Entity Is Contact Then
      Dim con = CType(entry.Entity, Contact)
      With con
     'only update AddDate if it has not been set yet
      If .AddDate = DateTime.MinValue Then .AddDate = Now
        .ModifiedDate = Now
      End With
    End If

    If TypeOf entry.Entity Is Customer Then
      Dim cust = CType(entry.Entity, Customer)
      With cust
        If cust.CustomerTypeReference.EntityKey Is Nothing Then
          cust.CustomerTypeReference.EntityKey =  _
           New EntityKey _
           ("BAEntities.CustomerTypes", "CustomerTypeID", 1)
        End If
      End With
    End If
  Next
End Sub

New EntityKey(“BAEntities.CustomerTypes”, “CustomerTypeID”, CustType.Standard)

C#
partial void OnContextCreated()
{
  this.SavingChanges += new System.EventHandler(mySavingChanges);
}
public void mySavingChanges(object sender, System.EventArgs e)
{
  var osm = this.ObjectStateManager;
 //get Added | Modified entries;
  foreach (var entry in osm.GetObjectStateEntries
  (EntityState.Added | EntityState.Modified))
  {
    if (entry.Entity is Contact)
    {
      var con = (Contact)entry.Entity;
     //only update AddDate if it has not been set yet
      if (con.AddDate == DateTime.MinValue)
        con.AddDate = DateTime.Now;
      con.ModifiedDate = DateTime.Now;
    }

    if (entry.Entity is Customer)
    {
      var cust = (Customer)entry.Entity;
      if (cust.CustomerTypeReference.EntityKey == null)
        cust.CustomerTypeReference.EntityKey =
         new EntityKey("BAEntities.CustomerTypes", "CustomerTypeID", 1);
    }
  }
}

In addition to the Changing and Changed methods for the individual properties of a class, EntityObject has class-level PropertyChanged and PropertyChanging events as well. These two events fire anytime any property in the Address class changes.

VB
Private Sub Address_PropertyChanged(ByVal sender As Object, _
  ByVal e As System.ComponentModel.PropertyChangedEventArgs) _
  Handles Me.PropertyChanged
   Dim propBeingChanged As String = e.PropertyName
   'add your logic here
End Sub

Private Sub Address_PropertyChanging(ByVal sender As Object, _
  ByVal e As System.ComponentModel.PropertyChangingEventArgs) _
  Handles Me.PropertyChanging

  Dim propBeingChanged As String = e.PropertyName
  'add your logic here
End Sub

C#
public partial class Address
{
 //wire up the events inside the Address class constructor
  public Address()
  {
  this.PropertyChanged +=
        new PropertyChangedEventHandler(Address_PropertyChanged);
  this.PropertyChanging +=
        new PropertyChangingEventHandler(Address_PropertyChanging);
}

 //create the methods that will be used to handle the events
  private void Address_PropertyChanged(object sender,
   System.ComponentModel.PropertyChangedEventArgs e)
  {
    string propBeingChanged = e.PropertyName;
    //add your logic here
  }
  private void Address_PropertyChanging(object sender,
   System.ComponentModel.PropertyChangingEventArgs e)
  {
    string propBeingChanged = e.PropertyName;
    //add your logic here
  }
}

Another critical data event exposed through Object Services is AssociationChanged.

You can create an AssociationChanged event for any navigation property of an entity. There is no way to have an overall event to capture all association changes in an ObjectContext.

You’ll need to wire this up manually in both VB and C#. Example 10-10 demonstrates creating an AssociationChanged event handler for the ContactReference property of the Address. In the partial class for the Address, create a method (here it’s called ContactRef_AssociationChanged) to execute the desired logic; then in the class constructor, add code to wire up the event handler to this method.

The implementation is the same for EntityReferences as it is for EntityCollection.

VB
Imports System.ComponentModel;
Partial Public Class Address

 'wire up the event handler in the class constructor
  Public Sub New()
    AddHandler Me.ContactReference.AssociationChanged, _
               AddressOf ContactRef_AssociationChanged
  End Sub

  the method that will be executed when the event is fired
  Private Sub ContactRef_AssociationChanged _
   (ByVal sender As Object, _
    ByVal e As ComponentModel.CollectionChangeEventArgs)
    Dim act As System.ComponentModel.CollectionChangeAction = e.Action
    Dim custOnOtherEnd = CType(e.Element, Customer)
    'add your logic here
  End Sub
End Class




Partial Public Class Customer

  Public Sub New()
    AddHandler Me.Addresses.AssociationChanged, _
     AddressOf Addresses_AssociationChanged
  End Sub

  Private Sub Addresses_AssociationChanged(ByVal sender As Object, _
   ByVal e As System.ComponentModel.CollectionChangeEventArgs)
    Dim act As CollectionChangeAction = e.Action
    Dim addressOnOtherEnd = CType(e.Element, Address)
    'add your logic here
  End Sub
End Class

C#
using System.ComponentModel;
namespace BAEntities
{
  public partial class Address
  {
    public Address()
    {
      this.CustomerReference.AssociationChanged +=
         new CollectionChangeEventArgs(Add_CustRefChanged);
    }
    private void Add_CustRefChanged
       (object sender,CollectionChangeEventArgs e)
    {
      CollectionChangeAction act  = e.Action;
      Customer custOnOtherEnd = (Customer)e.Element;
      //add your logic here
    }

  public partial class Customer
  {
    public Customer()
    {
      this.Addresses.AssociationChanged +=
         new CollectionChangeEventHandler(Addresses_AssociationChanged);
    }
    Private void Addresses_AssociationChanged
       (object sender, CollectionChangeEventArgs e)
    {
      CollectionChangeAction act  = e.Action;
      Address addOnOtherEnd = (Address)e.Element;
      //add your logic here
    }
  }
}

Partial classes are useful as a way to work around the limitations of the EDM. An example of such a limitation is the model’s inability to create properties as a result of an expression.

For example, it would be very nice to be able to create a FullName property that is the result of concatenating FirstName and LastName, but the schema of the Entity Framework’s EDM doesn’t support this.

Instead, you can create a FullName property directly in the partial class. Keep in mind that these properties, even if they are not marked as read-only, will not be included in updates or inserts when you call SaveChanges. A ReadOnly FullName property would be appropriate for display purposes. You could then write your code to modify the FirstName and LastName properties, and those would be sent to the database when SaveChanges is called.

Also handy would be a second property that you could use when you need to list full names alphabetically. The properties shown in Example 10-11 are part of the Contact partial class.

VB
Public ReadOnly Property FullName() As String
  Get
    Return Me.FirstName.Trim & " " & Me.LastName
  End Get
End Property
Public ReadOnly Property FullNameAlpha() As String
  Get
    Return Me.LastName.Trim & ", " & Me.FirstName
  End Get
End Property

C#
public string FullName
{
  get
  {
    return this.FirstName.Trim() + " " + this.LastName;
  }
}
public string FullNameAlpha
{
  get
  {
    return this.LastName.Trim() + ", " + this.FirstName;
  }
}

Some properties that you will be able to use in a number of samples as the book progresses are those that display the details of a Reservation. The Reservation entity does not contain much interesting information in its scalar properties. The useful details are in the Trip navigation property (start and end dates, trip cost) and in the Destination property of the Trip (the destination name).

Rather than reconstruct this information over and over again, you can create a property of Reservation that will give this to you already concatenated. The same information is convenient to concatenate from the Trip entity. After adding a TripDetails property to the Trip entity, you can then add a TripDetails property to Reservation that reads the Trip.TripDetails.

The Trip.TripDetails property in Example 10-12 protects itself from an exception if the destination information hasn’t been loaded.

VB
Partial Public Class Trip
  Public ReadOnly Property TripDetails() As String
    Get
      Try
        Return Destination.DestinationName.Trim  _
         & " (" & StartDate.ToShortDateString & "-" _
         & EndDate.ToShortDateString  _
         & ";  " & String.Format("{0:C}", TripCostUSD.Value) & ")"
      Catch ex As Exception
        Return Destination.DestinationName
      End Try
    End Get
  End Property
End Class

Partial Public Class Reservation
  Public ReadOnly Property TripDetails() As String
    Get
      Return Trip.TripDetails
    End Get
  End Property
End Class

C#
using System;
namespace BAGA
{
  public partial class Trip
  {
    public string TripDetails
    {
      get
      {
        try
        {
          return Destination.DestinationName.Trim()
                 + " (" + StartDate.ToShortDateString()
                 + "-" + EndDate.ToShortDateString() + ";  "
                 + string.Format("{0:C}", TripCostUSD.Value) + ")";
        }
        catch (Exception ex)
          {
            return Destination.DestinationName;
          }
        }
      }
    }
  }
  public partial class Reservation
  {
    public string TripDetails
    {
      get
      {
        return Trip.TripDetails;
      }
    }
  }
}

In the BreakAway model, you could create custom read-only properties in the Reservation entity for TotalPaid and PaidinFull that would be calculated based on the sum of the payments for that reservation. As mentioned earlier in the discussion of computed columns, the data would be valid only if you could ensure that all of the payments are accounted for. If there is a chance that some of the payments have not been retrieved from the database, you shouldn’t use this.

.NET’s method extensions provide another way to add logic to your entity classes.

As an example, let’s overload an entity’s factory method. These are the Shared/Static methods for each entity that let you quickly create a new entity. The parameter list for these factory methods consists of all of the non-nullable properties in the class.

The entire set of non-nullable properties isn’t always the most desirable list of fields to populate when creating a new class. For example, in the BreakAway model classes, the Contact.CreateContact factory method has the signature shown in Example 10-13.

VB
Public Shared Function CreateContact _
 (ByVal contactID As Integer, ByVal firstName As String, _
  ByVal lastName As String, ByVal addDate As Date, _
  ByVal modifiedDate As Date) As Contact

C#
public static Contact CreateContact
(int contactID, string firstName, string lastName,
 global::System.DateTime addDate, global::System.DateTime modifiedDate)

In most cases, the ContactID will be 0, and if your SavingChanges event handler takes care of the AddDate and ModifiedDate fields, why be forced to enter them when you create a new Contact? You may also have some of the other information available, which means that after calling CreateContact, you still have to set more properties.

Creating an overload of the method would be very convenient. You can place the new version of the method in the Contact’s partial class. Example 10-14 shows a more useful CreateContact method.

VB
Public Shared Function CreateContact(ByVal firstName As String,  _
     ByVal lastName As String) As Contact
  Dim contact As Contact = New Contact
  contact.FirstName = firstName
  contact.LastName = lastName
  Return contact
End Function

C#
public static Contact CreateContact(string firstName, string lastName)
{
  Contact contact = new Contact();
  contact.FirstName = firstName;
  contact.LastName = lastName;
  return contact;
}

When you call the CreateContact method, two signatures will be available, as shown in Figure 10-2.

Figure 10-2. The new CreateContact overload as shown by IntelliSense

As you are using the different methods that the entities inherit from EntityObject or ObjectContext, keep your mind open to the idea of being able to enhance them to suit your purposes.

You can, of course, create all kinds of new logic in partial classes, whether the logic pertains to properties or to methods.

For example, perhaps you want to perform some validation logic without saving changes, such as supplying default values for entities. You could place methods for this within an entity’s partial class and then call that class as needed. If you like the idea of having validation performed on a number of entities at once, or even on a variety of entity types (as SaveChanges can do), you could place the method in the ObjectContext’s partial class. Keep in mind that only attached entities will be available.

Other than creating your own classes, the partial classes are the primary mechanism in the Entity Framework for adding business logic to entities.

It is possible to override EDM code generation completely so that you can define what the generated classes look like. As you’ll learn in Chapter 19, you will need to follow some rules.

The code generator is based on the System.Data.Entity.Design API, and you can use it directly. A sample code generator is available on the Entity Framework team’s Code Gallery page at http://code.msdn.com/adonetefx/ to get you started.

If you have a method or property that you would like to be able to perform on any entity, rather than adding that method to each entity’s partial class, you can create a common method. Here are a few ways in which you can do that: