Entity objects

30 min

📘 Note This is the recommended way to work with Business Foundation (BF) because it is a highly extensible and easy-to-use framework, relying on the SQL API. See SQL recordsSQL records for other options for working with data.

Classes in this topic are available in the Mediachase.BusinessFoundation.Data.Business and Mediachase.BusinessFoundation.Data namespaces.

BF includes a request-response system to process entity object methods. You can create a request passing the target entity object and request parameters, and call the Execute method. BF finds the handler to process the request, calls the handler, and returns a response with the execution result.

entity_objects1.png

DataContext initalization

The DataContext class has the User and UserTimeZone properties. Entity objects and modules can use them to provide programmatic access to the current user ID and time zone. You should initialize the User and UserTimeZone properties before working with entity objects.

When you create DateTime or Date meta-fields, you can pass the UserTimeZone and DateTime values, which are automatically converted to user time zone.

🚧 Tip In an ASP.NET application, initialize DataContext in the Global.Application_BeginRequest method.

EntityObject class

The EntityObject class represents a meta-class object. Meta-class is an abstract representation of something, whereas an entity object is a usable example of the item the meta-class represents.

An entity object can be typed or untyped. Use the EntityObject object and its properties to retrieve and update the entity object in the persistent storage. You cannot create a new EntityObject directly. Instead, use the BusinessManager class and request-response system for calling the Entity object methods.

BusinessManager class

The BusinessManager class represents methods for processing the request-response for entity objects. Call the BusinessManager static methods to initialize an entity object, and to create, update, delete, list and execute custom method for entity objects.

Example: Creation of new entity object

EntityObject page = BusinessManager.InitializeEntity("Class_1");
    page["Title"] = "Title Text";
    page["Description"] = "Description Text";
    PrimaryKeyId pageId = BusinessManager.Create(page);

Request-response system

Use the request-response system to process entity object methods.

Example: Load entity object

LoadRequest request = new LoadRequest(new EntityObject(metaClassName, primaryKeyId));
    LoadResponse response = (LoadResponse)BusinessManager.Execute(request);
    EntityObject entityObject = response.EntityObject;

You can override the default method handler, add custom plug-ins, or define a custom method.

Pipeline events

When an instance of a request is created and you call the BusinessManager.Execute method, BusinessManager creates a _pipeline_and the BusinessManager class executes the following events while the request is processed:

Call the PreExecute method of the appropriate IRequestHandler class for the request.

Call the Execute method of the appropriate IPlugin classes that are subscribed to from the PreMainOperation event.

Open Transaction.

Call the PreExecuteInsideTransaction method of the appropriate IRequestHandler class for the request.

Call the Execute method of the appropriate IPlugin classes that are subscribed to from the PreMainOperation (In-Tranasaction) event.

Call the Execute method of the appropriate IRequestHandler class for the request.

Call the PostExecuteInsideTransaction method of the appropriate IRequestHandler class for the request.

Call the Execute method of the appropriate IPlugin classes that are subscribed to from the PostMainOperation (In-Tranasaction) event.

Commit the Transaction.

Call the PostExecute method of the appropriate IRequestHandler class for the request.

Call the Execute method of the appropriate IPlugin classes that are subscribed to from the PostMainOperation event.

entity_objects3.png

Handlers

A request handler is the process (frequently referred to as the endpoint) that runs in response to a request made to a business manager. The most common handler is a default entity object handler that processes default methods. When users execute methods, the request is processed by the business manager through the handler. You can create your own handler that executes custom methods.

Create handlers

To create a custom handler, create a class that implements the IRequestHandler interface. You should also implement the PreExecute, PreExecuteInsideTransaction, Execute, PostExecuteInsideTransaction, PostExecute methods.

BF has BaseRequestHandler helper class that you can use as a base class for a custom handler, and which implements the IRequestHandler together with virtual methods.

Register handlers

After you create a custom handler class, you can add it to list of default handlers using the ConfigureServices section of Startup.cs.

The following example shows how to register a handler that responds to requests for the Test method for Class_1 meta-class. The handler is defined as the SampleHandler class in the SampleHandlerAssembly assembly.

Example: Register a plugin

<businessManager>
  <plugins>
    <add metaClass="*" 
         method="Update;Create" 
         eventStage="PreMainOperationInsideTranasaction" 
         type="SampleHandler, SampleHandlerAssembly" />
  </plugins>
</businessManager>

📘 Note Method attributes support a search mask with * and ? chars and multiple methods separated by semicolons. eventStage supports several event stage items separated by a vertical bar ( | ).

Default methods

BF implements the following methods.

Initialize

Example: Call the Initialize method to create a new instance of entity object.

InitializeEntityResponse response = (InitializeEntityResponse)BusinessManager.Execute(new InitializeEntityRequest(metaClassName));
    EntityObject obj = response.EntityObject;

Load

Example: Call the Load method to load an instance of entity object by primary key.

LoadResponse response = (LoadResponse)BusinessManager.Execute(new LoadRequest(new EntityObject(metaClassName, primaryKeyId)));
    EntityObject obj = response.EntityObject;

Create

Example: Call the Create method to store an entity object in the persistent storage.

CreateResponse response = (CreateResponse)BusinessManager.Execute(new CreateRequest(target));
    PrimaryKeyId newPk = response.PrimaryKeyId;

Update

Example: Call the Update method to update an entity object in the persistent storage.

BusinessManager.Execute(new UpdateRequest(target));

Delete

Example: Call the Delete method to delete an entity object from the persistent storage.

BusinessManager.Execute(new DeleteRequest(target));

List

Example: Call the List method to select a collection of entity objects from the persistent storage.

ListResponse response = (ListResponse)BusinessManager.Execute(new ListRequest(metaClassName, filters, sorting));
    EntityObject[] objs = response.EntityObjects;

Custom methods

To create a custom method, create and register a custom handler and define a custom request and response. Requests should be inherited from the Request class, and responses should be inherited from the Response class.

Filter and sort

Call the List method to return an array of entity objects from the meta-class. See the Filter and sortFilter and sort.

Typed entity objects

Entity objects used in your applications can be either typed or untyped. However, BF has other tools to support typed entity objects, with which programming is easier and less error-prone.

To use typed entity objects:

Run McCodeGen to create typed entity object C# class.

McCodeGen.exe

The McCodeGen application reads the mcgen file, extracts the meta-model, and generates a template and an output text file.

McCodeGen.exe-mcgen:mcgenFile-out:outputFile

Parameter	Description
mcgenFile	The meta model file
outputFile	The output file

Use mcgen file to create a typed entity object

The McCodeGen application can generate C# classes from the mcgen file. A typed entity object class is very similar to the EntityObject untyped class, but includes properties mapped to column values and column name constant string.

The mcgen file should include this:

<?xml version="1.0" encoding="utf-8" ?>
      <mcgen xmlns="mediachase.codegen.config" extension="cs" template="Templates\BusinessFoundationEntityObject.aspx">
        <EntityObject>
          <ConnectionString> Data Source=(local);Initial Catalog=TestDB;User ID=sa;Password=; </ConnectionString>
          <MetaClass>Book</MetaClass>
            <Params>
              <add key="Namespace" value="Test.MetaClass"/>
            </Params>
        </EntityObject>
      </mcgen>

Parameter	Description
ConnectionString	The connection string
MetaClass	The name of meta-class
Namespace	The typed row C# class namespace

Paste your connection string and meta-class name, declare an output class namespace, then execute McCodeGen from the command line.

McCodeGen.exe -mcgen:BookEntity.mcgen -out:BookEntity.cs

Then you can add a typed entity object class to your .NET project.

Typed entity object registration

After you create a typed entity object, register it in the application. Create a new handler based on EntityObjectDefaultRequestHandler and override the CreateEntityObject method, which creates and returns a typed entity object. After you create a handler, register it.

📘 Note BF allows for executing entity object methods through Web Service.

Visual Studio integration

📘 Note For Visual Studio integration to work, McCodeGen should be installed.

You can integrate the McCodeGen application with Visual Studio by adding the mcgen file to a Visual Studio project.

sqlrecords1.png

Check the properties for your mcgen file (in this case a CategoryRow.mcgen), the Custom Tool field should be blank. Enter the name McCodeGenerator.

sqlrecords2.png

The tool runs automatically. Check to make sure that the output was created by opening the Solution Explorer.

sqlrecords3.png

MetaObject class

The MetaObject class allows low-level access to entity object persistent storage. The default handler uses MetaObject to load and save entity objects to a persistent storage. You can use MetaObject to call, get, update or delete low-level methods.

MetaObject extensions

// Add MetaObject Extension
       metaClass.Extensions.Add(new MetaObjectExtensionInfo(HistoryManager.ModuleName,
                                    AssemblyUtil.GetTypeString(typeof (HistoryExtension)),
                                    MetaObjectExtensionActivationType.OnSave));

The MetaObject extension allows for capturing meta-object events, and the MetaObject extension is registered in the meta-class.

To create a custom MetaObject extension, first create a class that implements the IMetaObjectExtension interface. You should also implement the Init, PreSave, Save, PreDelete, Delete and Clone methods. Use the BaseMetaObjectExtension class as a base class for your extension.

After you create a custom extension class, register it in the MetaClass. Add the MetaObjectExtensionInfo object to the MetaClass.Extensions collection, passing extension name, extension type and activation type. This enables the extension to receive metaobject events.

Example: Add metaobject extension

//Add MetaObject Extension
      metaClass.Extensions.Add(new MetaObjectExtensionInfo(HistoryManager.ModuleName,
                                   AssemblyUtil.GetTypeString(typeof (HistoryExtension)),
                                   MetaObjectExtensionActivationType.OnSave));

📘 Note You can modify a meta-model only in Design mode. See the MetaClassManager classMetaClassManager class section.

Extension supports several activation types:

ByRequest(default). The extension is loaded on any meta object event.

OnSave. The extension is loaded on save event.

OnLoad. The extension is loaded on load meta object event.

Activation types enable you to optimize application performance.

Triggers

A trigger_is procedural code that is automatically executed in response to certain events on a particular meta-object in a persistent storage. The trigger is used mostly for keeping the integrity of the information on the persistent storage. If you have an_employee meta-class, when a new meta-object is added to the employee's meta-class, a new meta-object should also be created in the meta-class of the taxes, vacations, and salaries.

Call AddTrigger of the TriggerManager class to add a custom trigger.

Call RemoveTrigger of the TriggerManager class to remove a custom trigger.

A trigger can be registered on create, update, and delete events for the meta-object.