Generated code - Tapping into actions on entities and collections

Preface

With .Net 2.0, partial classes are a reality. This gives the ability to write code in a separate file which will be merged at compile time with an existing code file. To be able to extend the generated code to its fullest, it's key that the developer can override a set of routines which are called by the generated code to perform additional things, like do additional initialization or perform actions when a related entity is set or unset.

In the framework there are a lot of areas where a developer might want to add code. Below, you'll find two lists: one for events and one for methods to override. Every defined element has a description and when the method is called or the event is raised as well as the the purpose of the element so the user can choose the right method/event to use.

Users of .NET 1.x can also override the methods, for example in user code regions or a in derived class of an entity, or through an include template.

Events

• Entity: Initializing. Event which is raised from the protected method OnInitializing (see below), and which is raised at the start of the initialization routine of an entity: InitClassEmpty (for SelfServicing also InitClassFetch)). The entity is clean and has no Fields object yet.
• Entity: Initialized. Event which is raised from the protected method OnInitialized (see below) and which is raised at the end of the initialization routine, also after InitClassMembers. The entity has a Fields object and if the field object was pre-filled (this is the case in fetch routines), the fields are already filled with values. Used to do additional initialization.
• Entity collection: EntityRemoving. Raised from the protected method OnEntityRemoving (see below) and which is a cancelable event. OnEntityRemoving is called from Remove or RemoveAt at the start of these routines. If canceled, the remove is aborted.
• Entity collection: EntityRemoved. Raised from the protected method OnEntityRemoved (see below), which is called at the end of Remove and RemoveAt.
• Entity collection: EntityAdding. Raised from the protected method OnEntityAdding (see below) and which is a cancelable event. OnEntityAdding is called from Add and Insert at the start of these routines. If canceled, the addition is aborted.
• Entity collection: EntityAdded. Raised from the protected method OnEntityAdded (see below) , which is called at the end of the Add or Insert routine. Only raised if the entity is actually added.

Overridable methods

• Entity: OnGetValue. Method which is called at the start of the GetValue routine which is the routine used to obtain the value for an entity field. Method offers teh ability to cancel the GetValue action.
• Entity: OnGetValueComplete. Method which is called at the end of the GetValue routine.
• Entity: OnInitializing. Method which is called at the start of the initialization routine of the entity. The base class method raises the Initializing event
• Entity: OnInitialized. Method which is called at the end of the initialization routine of the entity. The base class method raises Initialized event.
• Entity: OnInitClassMembersComplete. Method which is called at the end of InitClassMembers, and which is a virtual method in EntityBase(2)
• Entity: OnFieldValueChanged. Method which is called right after a field's value has been changed. There are a couple of methods called in the process of setting a field's value. This particular method is solely there to act on a field's value set action. It doesn't raise an event, though it receives the old and new value of the field. Not called if a fieldvalue set action failed. This method is called before changed events are raised.
• Entity: OnRelatedEntitySet. Method which is called at the end of the SetRelatedEntity() routine. Usable to act on the fact that a related entity has been set.
• Entity: OnRelatedEntityUnset. Method which is called at the end of the UnsetRelatedEntity() routine. Usable to act on the fact that an entity has been de-referenced as a related entity by the containing entity.
• Entity: OnSetValue. Method which is called at the start of the SetValue routine which is the routine used to set the value of an entity field. Method offers the ability to cancel the SetValue action.
• Entity: OnSetValueComplete. Method which is called at the end of the SetValue routine.
• Entity (adapter): OnBeforeEntitySave. This method is called from the DataAccessAdapter method OnBeforeEntitySave(), unless that method is overriden. You can override this OnBeforeEntitySave method instead, which allows you to make last minute changes, though keep the logic to do that in the entity. SelfServicing already has this method since 1.0.2005.1 where it is called OnSave.
• Entity / entity collection: OnGetObjectData. Method which is called at the end of the GetObjectData() method which is used when an entity is serializing.
• Entity / entity collection: OnDeserialized. Method which is called at the end of the deserialization constructor (binary/soap formatter).
• Entity collection: OnEntityRemoving. Method which is called at the start of Remove and RemoveAt. The base class method raises EntityRemoving event, a cancelable event. This method returns false if the event was canceled.
• Entity collection: OnEntityRemoved. Method which is called at the end of Remove and RemoveAt. The base class method raises EntityRemoved event.
• Entity collection: OnEntityAdding. Method which is called at the start of Add and Insert. The base class method raises EntityAdding event, a cancelable event. This method returns false if the event was canceled.
• Entity collection: OnEntityAdded. Method which is called at the end of Add and Insert. The base class method raises EntityAdded event.
• DataAccessAdapter: OnInsertPersistenceInfoObjects. Method which is called from the default clause (Case Else clause) of the switch statement (Select Case statement) in the InsertPersistenceInfoObjects(predicate) routine in the generated DataAccessAdapter class, which is useful for people who implement their own Predicate objects.
• TypedList: OnResultsetBuilt. Method which is called at the end of the generated BuildResultset method and which can be used to add additional fields to the fields object for the typed list, or to manipulate the field objects added to the typed list.
• TypedList: OnRelationSetBuilt. Method which is called at the end of the generated BuildRelationSet method and which can be used to add additional relations to the relationcollection of the typedlist.
• TypedList: OnInitialized. Method which is called at the end of the InitClass() method. This method can be used to add additional DataColumn definitions to the typedlist's base class, which is a datatable. This method is also called by InitMembers, so a typed list is properly initialized during deserialization as well.
• TypedView: OnInitialized. Method which is called at the end of the InitClass() method. This method can be used to add additional DataColumn definitions to the typedview's base class, which is a datatable.