Business Numerators. Getting Started

This topic describes how to add a new Numerator and assign it to a business object's property using the Model Editor.

Add two platform-agnostic modules (Xafari.BC.Numerators and Xafari.BC.Numerators.Xpo) to the required project.

numerator_31

Important

Xafari Business Numerators support both XPO and Domain Components data access technologies. For the DC-based applications, use the Xafari.BC.Numerators.DC module.

The new Numerator is intended for the SimpleNumber property of the SimpleNumeration business class that is defined in the code snippet below:

  • c#
  • VB

[DefaultClassOptions]
public class SimpleNumeration : BaseObject
{
  public SimpleNumeration(Session session)
    : base(session)
  {
  }
  public string Name
  {
    get
    {
      return this.GetPropertyValue<string>("Name");
    }
    set
    {
      this.SetPropertyValue<string>("Name", value);
    }
  }
  public string SimpleNumber
  {
    get
    {
      return this.GetPropertyValue<string>("SimpleNumber");
    }
    set
    {
      this.SetPropertyValue<string>("SimpleNumber", value);
    }
  }
}

<DefaultClassOptions> _
Public Class SimpleNumeration
  Inherits BaseObject
  Public Sub New(ByVal session As Session)
    MyBase.New(session)
  End Sub
  Public Property Name As String
    Get
      Return Me.GetPropertyValue(Of String)("Name")
    End Get
    Set
      Me.SetPropertyValue(Of String)("Name", value)
    End Set
  End Property
  Public Property SimpleNumber As String
    Get
      Return Me.GetPropertyValue(Of String)("SimpleNumber")
    End Get
    Set
      Me.SetPropertyValue(Of String)("SimpleNumber", value)
    End Set
  End Property
End Class

Note

A complete demo project is available at BusinessNumerators. You can find the code used in this lesson in the BusinessNumerators.Module|BusinessObjects|Objects.cs file.

Numerator Settings

Invoke the Model Editor using either Visual Studio or DevExpress.ExpressApp.ModelEditor.vXX.X.exe. Navigate to the Xafari|Services|Numerators node.

numerator_4

The Numerators node shows the default values of the service settings. Each individual Numerator can have its own settings, as described below in this section.

The AutoApply option requires an individual description. The Xafari.BC.Numerators.NumeratorManager service exposes the Apply() method to populate the objects with generated values. By default, the framework calls this method in all corresponded situations to perform the numbering automatically both when the user creates new objects via the UI and when the objects are created in code. You can specify that the Numerators apply at one of the possible stages as follows. However, the default behavior is canceled if AutoApply is "false", so the framework shifts the responsibility to the developer who is obliged to call the Apply() method in accordance with the custom logic. To see the samples, refer to the following topics: Custom Apply, Custom Numerator.

Note

The AutoApply option is relevant only if Data Accesor is activated, otherwise it is ignored.

To add a new Numerator, right-click the Numeratos node, and select the New item. The image below shows the node of the created Numerator; the exposed properties are described right after the picture.

numerator_5

  • The DerivedClassesBehavior property determines whether to apply Numerator to the descendant classes. Numerator node defines the common behavior and each NumeratorLink node allows to override this value. See NumeratorLink Settings section below.  
  • The KeyTemplate property specifies the template for the key value. See Learn More. Key Template.
  • The StartValue property specifies the start value for the Numerator's index.
  • The Step property specifies the numeration step.
  • The Template property specifies the format of the generated string value. See Formatting Final String below and Learn More. Template for additional information.
  • The ThroughNumeration property specifies a flag to indicate whether or not to apply the Numerator to the objects of different types. See Learn More. Through Numeration for more details.  
  • The UseDeletedNumbers property specifies the scenario to use the Deleted Numbers functionality. Refer to Learn More. Deleted Numbers to get extra info.

NumeratorLink Settings

The next step is to associate the Numerator with the object property. This task should be solved via NumeratorLink. Expand the Numerator node, right-click the Links item, and select Add|ServiceNumeratorLink in the invoked context menu.

The image below shows the NumeratorLink node, the exposed properties are listed hereinafter.

numerator_6

  • The ModelClass property specifies the type that requires the automatic objects numbering.
  • The Property specifies the property of a business object which to enumerate.
  • The ApplyStrategy property specifies the strategy of applying the Numerator to the object, two available values are OnSave and AfterCreate.
  • The DerivedClassesBehavior property determines whether to apply the Numerator to the ModelClass descendans. Available descendants must be added to the DerivedClasses collection. Each derived class may have its own value of the DerivedClassesBehavior property.
  • The Id property specifies the NumeratorLink identifier.
  • The Index property specifies the position applied when sorting the NumeratorLink nodes.

Run the appropriate application (Windows Forms or ASP.NET). Select the Simple Numeration item in the navigation control and click the New Action. In the invoked Detail View it is visible that the SimpleNumber value was generated automatically.

numerator_7

Formatting Final String

The main use case of the Business Numerators is to generate a formatted string using sequential numbers. The format is defined in the Template property, which is interpreted by the Xafari Object Formatter. This section describes how to design a formatted Numerator for the SimpleNumberTemplate property of the SimpleNumeration_Template object.

The code snippet below implements the SimpleNumeration_Template class:

  • c#
  • VB

[DefaultClassOptions]
public class SimpleNumeration_Template : BaseObject
{
  public SimpleNumeration_Template(Session session)
    : base(session)
  {
  }
  public string Name
  {
    get
    {
      return this.GetPropertyValue<string>("Name");
    }
    set
    {
      this.SetPropertyValue<string>("Name", value);
    }
  }
  public string SimpleNumberTemplate
  {
    get
    {
      return this.GetPropertyValue<string>("SimpleNumberTemplate");
    }
    set
    {
      this.SetPropertyValue<string>("SimpleNumberTemplate", value);
    }
  }
}

<DefaultClassOptions> _
Public Class SimpleNumeration_Template
  Inherits BaseObject
  Public Sub New(ByVal session As Session)
    MyBase.New(session)
  End Sub
  Public Property Name As String
    Get
      Return Me.GetPropertyValue(Of String)("Name")
    End Get
    Set
      Me.SetPropertyValue(Of String)("Name", value)
    End Set
  End Property
  Public Property SimpleNumberTemplate As String
    Get
      Return Me.GetPropertyValue(Of String)("SimpleNumberTemplate")
    End Get
    Set
      Me.SetPropertyValue(Of String)("SimpleNumberTemplate", value)
    End Set
  End Property
End Class

Invoke the Model Editor and navigate to the Xafari|Services|Numerators node. Add a new Numerator, and set its properties as shown in the image below:

numerator_71

Note the Template property which specifies the numeric format as "000000".

Right-click the Links item, select Add|ServiceNumeratorLink in the invoked context menu, and set the properties for the new NumeratorLink as shown in the image below:

numerator_72

Run the application to see the result:

numerator_73

For more information, refer to Learn More. Template and Xafari Object Formatter.