--- title: Entity objects slug: commerce-connect-15/docs/entity-objects docTags: createdAt: 2026-07-30T20:34:45.000Z --- :::hint{type="info"} **Note** This is the recommended way to work with BF because it is a highly extensible and easy-to-use framework, relying on the SQL API. See [SQL records](docId\:K9aK1N2aHC81l4u9pfu2L) for other options for working with data. ::: Classes in this topic are available in the following namespaces: - `Mediachase.BusinessFoundation.Data.Business` - `Mediachase.BusinessFoundation.Data` Business Foundation (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. ![Diagram of the Business Foundation request-response system showing how a request flows through the BusinessManager to a handler and back as a response.](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/tIq7_2jNAitFWieVG27Qp-20260723-164629.png "entity_objects1.png") ## DataContext initialization 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. :::hint{type="warning"} **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 `EntityObject` 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 an entity object: ```csharp 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 `EntityObject` methods. **Example:** Load entity object: ```csharp 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: 1. Call the `PreExecute` method of the appropriate `IRequestHandler` class for the request. 2. Call the `Execute` method of the appropriate `IPlugin` classes that are subscribed to from the `PreMainOperation` event. 3. Open `Transaction`. 4. Call the `PreExecuteInsideTransaction` method of the appropriate `IRequestHandler` class for the request. 5. Call the `Execute` method of the appropriate `IPlugin` classes that are subscribed to from the `PreMainOperation` (`In-Transaction`) event. 6. Call the `Execute` method of the appropriate `IRequestHandler` class for the request. 7. Call the `PostExecuteInsideTransaction` method of the appropriate `IRequestHandler` class for the request. 8. Call the `Execute` method of the appropriate `IPlugin` classes that are subscribed to from the `PostMainOperation` (`In-Transaction`) event. 9. Commit the `Transaction`. 10. Call the `PostExecute` method of the appropriate `IRequestHandler` class for the request. 11. Call the `Execute` method of the appropriate `IPlugin` classes that are subscribed to from the `PostMainOperation` event. ![Diagram of the Business Foundation pipeline events showing the sequence of PreExecute, Execute, and PostExecute stages during request processing.](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/XvoY6WvbIWVBstiCOkeTC-20260723-164630.png "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 a `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 the 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: ```csharp services.Configure(x => { x.Handlers.Add(new RequestHandler() { MetaClass = "", Method = "Insert", TypeName = "TypeName" }); }); services.Configure(x => { x.Plugins.Add(new RequestPlugin() { MetaClass = "*", Method = "Update;Create", EventStage = EventPipeLineStage.PreMainOperationInsideTransaction, TypeName = "SampleRequestPlugin, SampleHandlerAssembly" }); }); ``` :::hint{type="info"} **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 Business Foundation implements the following methods. ### Initialize **Example:** Call the `Initialize` method to create an instance of `EntityObject`: ```csharp 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: ```csharp 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: ```csharp 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: ```csharp BusinessManager.Execute(new UpdateRequest(target)); ``` ### Delete **Example:** Call the `Delete` method to delete an entity object from the persistent storage: ```csharp BusinessManager.Execute(new DeleteRequest(target)); ``` ### List **Example:** Call the List method to select a collection of entity objects from the persistent storage: ```csharp 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. ### Filtration and sort Call the `List` method to return an array of entity objects from the meta-class. See the [Filter and sort](docId\:D-RH7Dg09iQf3Obd3QgnL). ## 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 ```csharp // 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 ```csharp //Add MetaObject Extension metaClass.Extensions.Add(new MetaObjectExtensionInfo(HistoryManager.ModuleName, AssemblyUtil.GetTypeString(typeof (HistoryExtension)), MetaObjectExtensionActivationType.OnSave)); ``` :::hint{type="info"} **Note** You can modify a meta-model only in Design mode. See the [MetaClassManager class](docId\:NP7et4GlIKzHCSUK2aXTB) 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.