Business ComponentsExtensions Framework (XF)Getting StartedManipulations

eXtensions Framework. Manipulations

Access in Code

There are two techniques to operate with XF: Data Accessor and IObjectSpace Xafari Helper.

  • Data Accessor is recommended.
  • IObjectSpace Xafari Helper (Xafari.BC.Helpers.IObjectSpaceHelper) is implemented for easier use. It duplicates capabilities Data Accessor and implemented using the Data Accessor.

In both cases, for data manipulation considering XF are the following methods:

  • CreateObject<>() is analogous to IObjectSpace.CreateObject<>(). An alternative way is IObjectSpace.DataAccessor().CreateObject().
  • GetObjects<>() is analogous to IObjectSpace.GetObjects<>()
  • FindObject<>() is analogous to IObjectSpace.FindObject<>()
  • Evaluate<>() is analogous to Session.Evaluate()
  • SelectData<>() is analogous to Session.SelectData()
  • SelectDataAsync<>() is analogous to Session.SelectDataAsync()
  • GetObjectsQuery<>() is analogous to IObjectSpace.GetObjectsQuery<>()

Note

There is a situation that may cause an exception. It is when object of the NNN type is not created by the CreateEntity() method. Then the exception will occur when the system attempts to access Extensions of the Entity. To avoid this situation, it is required to convert the database and replace the NNN type to the _NNN.  

The code snippet below demonstrates how to create Entity and set properties for various Extensions

  • c#
  • VB

public void CreateContactObject()
{
  var contact = ObjectSpace.Xafari().CreateObject<Contact>();
  contact.FirstName = "Mark";
  contact.LastName = "Miller";
  contact.Address().City = "Moscow";
  contact.Address().Country = "Russia";
  contact.Titles().Title = "Mr.";
  contact.CustomerInfo().Customer = customer;
}

Public Sub CreateContactObject()
  Dim contact = ObjectSpace.Xafari().CreateObject(Of Contact)()
  contact.FirstName = "Mark"
  contact.LastName = "Miller"
  contact.Address().City = "Moscow"
  contact.Address().Country = "Russia"
  contact.Titles().Title = "Mr."
  contact.CustomerInfo().Customer = customer
End Sub

Extensions in Application Model

Information about all Entities and Extensions a represented in Application Model. Entity has a special calculated property for each of the Extensions, the name of this property consists of a double underscore and the name that was specified when registering the Extension: "__ExtName".

extensions_framework_20

If the Entity1 has Ext1 and Ext2 extensions, the navigation to the Extensions properties will be provided with the following constructions: "Entity1.__Ext1.Property1" and "Entity1.__Ext2.Property2".

Criteria strings, which involve the Extensions, will be as follows:

  • example

ObjectSpace.GetObjects<DC1>("__Ext1.PropExt1 = ‘1’");
 ObjectSpace.GetObjects<DC1>("__Ext1.__BackEntity1.PropDC1 = ‘1’");

Note

In the fields of the DB tables, the names don't use double underscores ("__").

Compatibility with Previous Versions (Exts)

In versions prior to Xafari x011, all of the Extensions formed a single list of properties available in the Exts node. For instance, if the Ext1 Extension contains Property1 and Ext2 contains Property2, then the navigation to both properties was provided via the Exts property: "Entity1.Exts.Property1" and "Entity1.Exts.Property2".

Since Xafari x011, the Exts property is not added by default. For compatibility with previous versions, you should explicitly specify in code to generate the Exts property.

If Exts is required only at the runtime, use the following code during your application initialization:

  • example

...
 winApplication.Xafari().BC().IsGenerateCustomMemberExts = true;
 winApplication.Setup();
 winApplication.Start();
 ...

If Exts is required at design-time and runtime, use the following code when initializing a custom module

  • example

public override void Setup(ApplicationModulesManager moduleManager)
 {
     base.Setup(moduleManager);
     moduleManager.Modules.FindModule<XafariBCModule>().IsGenerateCustomMemberExts = true;
 }

Advice

It is not recommended to add Exts at design-time, because it requires to generate XFAssebly.dll and increases the load time of the Model Editor.

Entities and CriteriaOperator

The Entities is fully compatible with CriteriaOperator.

Example 1

Select Contact objects where Customer name is «John Smith»

  • c#
  • VB

// use properties from persistent extensions to select Contact objects
var criteria = CriteriaOperator.Parse("CustomerInfo.Customer.FullName = ?", "John Smith");
var objs = this.ObjectSpace.Xafari().GetObjects<Contact>(criteria);
// or by original GetObjects
var criteria = CriteriaOperator.Parse("Exts.CustomerInfo.Customer.FullName = ?", "John Smith");
var objs = this.ObjectSpace.GetObjects<Contact>(criteria);

' use properties from persistent extensions to select Contact objects
Private criteria As var = CriteriaOperator.Parse("CustomerInfo.Customer.FullName = ?", "John Smith")
Private objs As var = Me.ObjectSpace.Xafari().GetObjects(Of Contact)(criteria)
' or by original GetObjects
Private criteria As var = CriteriaOperator.Parse("Exts.CustomerInfo.Customer.FullName = ?", "John Smith")
Private objs As var = Me.ObjectSpace.GetObjects(Of Contact)(criteria)

Example 2

Select Contact objects where Title  is «Mr.» and City is «Paris»

  • c#
  • VB

// use properties from nonpersistent extensions to select Contact objects
var criteria = CriteriaOperator.Parse("Title = ? AND City = ?", "Mr.", "Moscow");
var objs = this.ObjectSpace.Xafari().GetObjects<Contact>(criteria);
// or by original GetObjects
var criteria = CriteriaOperator.Parse("Exts.Title = ? AND Exts.City = ?", "Mr.", "Moscow");
var objs = this.ObjectSpace.GetObjects<Contact>(criteria);

' use properties from nonpersistent extensions to select Contact objects
Private criteria As var = CriteriaOperator.Parse("Title = ? AND City = ?", "Mr.", "Moscow")
Private objs As var = Me.ObjectSpace.Xafari().GetObjects(Of Contact)(criteria)
' or by original GetObjects
Private criteria As var = CriteriaOperator.Parse("Exts.Title = ? AND Exts.City = ?", "Mr.", "Moscow")
Private objs As var = Me.ObjectSpace.GetObjects(Of Contact)(criteria)

Example 3

How to apply join to the Entity properties

  • c#
  • VB

// use join query to select Contacts objects
var criteria = CriteriaOperator.Parse("[<Customer>][^.CustomerInfo.Customer=This]", "1");
var objs = this.ObjectSpace.Xafari().GetObjects<Contact>(criteria);
// or by original GetObjects
var criteria = CriteriaOperator.Parse("[<Customer>][^.Exts.CustomerInfo.Customer=This]", "1");
var objs = this.ObjectSpace.GetObjects<Contact>(criteria);

' use join query to select Contacts objects
Private criteria As var = CriteriaOperator.Parse("[<Customer>][^.CustomerInfo.Customer=This]", "1")
Private objs As var = Me.ObjectSpace.Xafari().GetObjects(Of Contact)(criteria)
' or by original GetObjects
Private criteria As var = CriteriaOperator.Parse("[<Customer>][^.Exts.CustomerInfo.Customer=This]", "1")
Private objs As var = Me.ObjectSpace.GetObjects(Of Contact)(criteria)

Entities and LINQ

Example 1

Select Contact objects where Customer name is «John Smith»

  • c#
  • VB

// use properties from persistent extensions to select Contact objects
var contacts = this.ObjectSpace.Xafari().GetObjectsQuery<Contact>();
var objs2 = from contact in contacts where contact.CustomerInfo().Customer.FullName == "John Smith" select contact;

' use properties from persistent extensions to select Contact objects
Private contacts As var = Me.ObjectSpace.Xafari().GetObjectsQuery(Of Contact)()
Private objs2 As var = From contact In contacts _
Where contact.CustomerInfo().Customer.FullName = "John Smith" _
Select contact

Example 2

Select Contact objects where Title  is «Mr.» and City is «Paris»

  • c#
  • VB

// use properties from nonpersistent extensions to select Contact objects
var contacts = this.ObjectSpace.Xafari().GetObjectsQuery<Contact>();
var objs2 = from contact in contacts where contact.Titles().Title == "Mr." && contact.Address().City == "Moscow" select contact;

' use properties from nonpersistent extensions to select Contact objects
Private contacts As var = Me.ObjectSpace.Xafari().GetObjectsQuery(Of Contact)()
Private objs2 As var = From contact In contacts _
Where contact.Titles().Title = "Mr." AndAlso contact.Address().City = "Moscow" _
Select contact

Example 3

How to apply join to the Entity properties

  • c#
  • VB

// use join query to select Contacts objects
var contacts = this.ObjectSpace.Xafari().GetObjectsQuery<Contact>();
var customers = this.ObjectSpace.Xafari().GetObjectsQuery<Customer>();
var objs2 = from contact in contacts join customer in customers on contact.CustomerInfo().Customer equals customer select contact;

' use join query to select Contacts objects
Private contacts As var = Me.ObjectSpace.Xafari().GetObjectsQuery(Of Contact)()
Private customers As var = Me.ObjectSpace.Xafari().GetObjectsQuery(Of Customer)()
Private objs2 As var = From contact In contacts _
Join customer In customers _
On contact.CustomerInfo().Customer Equals customer _
Select contact

Note

To use Extensions in LINQ, it is necessary to specify a lambda-expression to associate Entity and Extension. This should be done when registering the Extension.                    

Send Feedback on this topic to Galaktikasoft.