Understanding Business Entities

Code Only vs. EDMX-Generated Entities

In earlier versions of Entity Framework, you designed your entities on an EDMX design surface and then generated entity classes from the EDMX. Microsoft has moved away from this approach in more recent versions of Entity Framework, however, we still provide this ability in MM .NET for those who have legacy business object projects (see the Dev Guide topic Entity Framework Entities w/ EDMX.

The more modern approach for creating entity classes is called "Code First", though it's a misnomer so I prefer to call it "Code Only". "Code First" sounds like you code your entity objects first then generate a database from those entities. Although you can use that workflow, you can also generate your entities from an existing database. Code Only is also fully supported in MM .NET.

For more information on the Entity Framework, check out Microsoft's documentation:

https://docs.microsoft.com/en-us/ef/core/get-started/?tabs=netcore-cli

Entity Objects

Entity objects are mostly comprised of properties that represent the attributes of real-world entities and provide strongly typed access to data associated with a business object. Entity objects are very light weight and serializable so they can be passed between physical tiers of an n-tier application. You can choose to use POCO (Plain-Old-CLR-Object) entities which are subclassed directly from System.Object, or you can subclass from the mmBusinessEntity class. Here is an example of an EmployeeEntity object:

The Benefits of Entity Objects

In classic ADO.NET, data is untyped and fraught with potential run-time exceptions. Take for example the following line of code that accesses a column from a data row:

string CustomerID = (string)Row["CustomerID"];

The first thing to note is that "CustomerID" is a string that is evaluated at run time. If you mistype the column name, (for example, "CustID"), the compiler will not catch the error and you will get a run time exception when this line of code executes.

The second thing to note is the explicit cast to a string. When you perform an explicit cast, the compiler assumes you know what you're doing. So, if you incorrectly specify the type as shown in the following line of code, the compiler will not catch the error, and you will get a run time exception:

int CustomerID = (int)Row["CustomerID"];

In contrast, when using MM .NET Entity objects, you solve both of the problems mentioned above. Take for example the following line of code:

string customerID = OrderEntity.CustomerID;

In this case, CustomerID is a property on an object, so Visual Studio IntelliSense shows you a list of OrderEntity properties to choose from (you no longer have to go to the Server Explorer to see what the table column names are):

Even if you ignore IntelliSense and have a typo on the property name, the compiler catches the error at compile time rather than run time.

Also, when it comes to strong typing, the compiler also catches an error where you specify the wrong type:

int customerID = OrderEntity.CustomerID;

In summary, MM .NET Entity objects allow you to write code that can be verified by the compiler to help avoid runtime exceptions!

Specifying the Type of the Entity Class Associated with a Business Object

Notice the top panel of the Employee business object declares the associated entity class as EmployeeEntity:

That's because the type of the entity object is specified in the class declaration by means of .NET Generics:

Here it is in C# code:

public partial class Employee : ABusinessObject<EmployeeEntity>

And in VB .NET:

Partial Public Class Employee
    Inherits ABusinessObject(Of EmployeeEntity)

Defining the associated entity object in this way allows MM .NET Framework-level code to work with application-specific entity objects.

The Business Object's Entity Property

The Business Layer Generator automatically generates an associated entity object for each of your business objects. An Entity property is generated on your business object that contains a reference to the associated entity. When viewed on a class diagram, the relataionship looks like this:

And here is the Entity property in code:

For example, in C#:

/// <summary>
/// Business Entity object
/// </summary>
public override OrderEntity Entity
{
	get
	{
		if (this._entity == null)
		{
			this._entity = this.CreateEntityObject();
		}
		return this._entity;
	}
	set
	{
		this._entity = value;
	}
}
private OrderEntity _entity;

And in VB .NET:

Public Overrides Property Entity() As OrderEntity
	Get
		If Me._entity Is Nothing Then
			Me._entity = Me.CreateEntityObject()
		End If
		Return Me._entity
	End Get
	Set
		Me._entity = value
	End Set
End Property
Private _entity As OrderEntity

You must first call one of the business object's data retrieval methods such as GetEntity() before the associated entity object contains data (this code assumes the business object's DefaultCommandType (usually specified at the ABusinessObject level) is set to CommandType.StoredProcedure):

For example, in C#:

this.GetEntity("GetOrderByOrderID", this.CreateParameter("@OrderID", orderID));
 
var ShipAddress = this.Entity.ShipAddress;
var ShipCity = this.Entity.ShipCity;

And in VB .NET:

Me.GetEntity("GetOrderByOrderID", Me.CreateParameter("@OrderID", orderID))
 
Dim ShipAddress = Me.Entity.ShipAddress
Dim ShipCity = Me.Entity.ShipCity

The Business Object's EntityList Property

Business objects inherit an EntityList property from the mmBusinessObjectGeneric class. When you call the business object's GetEntityList() method it automatically populates the EntityList property.

For example, in C#:

string firstName, lastName;
Employee employee = new Employee();
 
// You can store entities in a local list
var entityList = employee.GetAllEntities();
 
// You can also access entities on the EntityList property
foreach (var employeeEntity in employee.EntityList)
{
	firstName = employeeEntity.FirstName;
	lastName = employeeEntity.LastName;
}

And in VB .NET:

Dim firstName, lastName As String
Dim employee = New Employee()
 
'' You can store entities in a local list
Dim EntityList = Employee.GetAllEntities()
 
'' You can also access entities on the EntityList property
For Each employeeEntity In Employee.EntityList
	firstName = employeeEntity.FirstName
	lastName = employeeEntity.LastName
Next