Enumeration Constants
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
Generates static C# constants for all enumerations, their items and properties declared in the Xomega model.
This allows using the generated constants in the code to refer to specific items, properties and enumerations,
which provides compile-time validation of the code in cases when any of those get renamed or deleted.
For each static enumeration that is declared in the model using enum element, or dynamic enumeration that is defined
by a xfk:enum-cache config element of a "readlist" operation, the generator will create a static C# class, which
will contain a constant EnumName with the enumeration name, and a nested class Attributes with constants for the
names of enumeration properties. For static enumerations it will also contain string constants for enumeration items, which
will be assigned to the item value. If enumeration inherits from another enumeration, the list of items will be merged with
the base enumeration.
Properties of Static Enumerations. Each enumeration allows declaring a list of addtional properties that
can be specified for each item on top of the standard name and value. They are typically used to filter the list of items, or group
them by certain properties. When stored in a lookup cache, the values for each item's properties are stored as additional
named attributes on each record, so the generator creates constants for each property name to use in the code.
The following example illustrates how a "person type" enumeration has a single-value property "internal" declared,
which defaults to "false", and is set to "true" for the "Sales person" and "Employee" items.
Properties of Dynamic Enumerations. For dynamic enumerations that are based on a "readlist" operation,
additional properties come from the output parameters that are not marked as id-param or desc-param
on the xfk:enum-cache element, as demonstrated below for the output parameters "country region code" and "group".
Items of Static Enumeration. Enumeration items must have unique name and value attributes.
The value is a short code or number that is stored internally in the system, and what the generated constant will be set to.
The name is normally used to display the item to the user, and what the name of the constant is based on. If the displayed text
must be different from the name, e.g. when the generated constant would not be a valid identifier otherwise, then you can
specify it in the text element inside the item, as follows.
Enumeration Inheritance. An enumeration can inherit from another enumeration, and add, remove, or replace items
or their properties. This can be used to minimize duplication between similar enumerations, but with slight differences.
The generated class for the enumeration will contain constants for combined/merged list of items.
The snippet below illustrates how the "sales order status" enumeration extends from the base "order status" enumeration,
removes the "New" item, changes the value for the "Rejected" and "Cancelled" items, and adds new "Backordered" and "Shipped" items.
1.2 Generator outputs
This generator creates a single file with C# classes for all static and dynamic enumerations, which contain constants for the items,
and a nested class with additional property names, as appropriate.
2. Configuration
The following sections describe configuration parameters used by the generator.
2.1 Generator parameters
The following table lists configuration parameters that are set as the generator’s properties.
| Parameter |
Value Example |
Description |
| Generator Name |
Enumeration Constants
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
| Folder |
Static Data
|
Folder path to the generator inside the Model project. The folders are separated by a backslash (\). |
| Include In Build |
True
|
A flag indicating whether or not running this generator should be included in building of the model project. |
| Output |
| Output Path |
../MySolution.Services.Common /Enumerations/Enumerations.cs |
Relative path where to output generated file with enumeration constants. |
| Add To Project |
../MySolution.Services.Common /MySolution.Services.Common.csproj |
Relative path to the project file to add the generated file to. The project will be reloaded every time you run the generator.
Leave it blank if you don't want generated files to be added to your project automatically.
|
2.2 Model configuration
Parameters specified in the model configuration that are used by this generator consist of just the namespace for the classes
that contain enumeration constants. This is specified in the xfk:enumerations-config element under the top level
config model element, which is conventionally placed in the global_config.xom file, as illustrated by the following
snippet.
2.3 Common configurations
There expected to be just one configuration of this generator in the model, with the parameter values as illustrated above.
3. How to use the generator
The sections below provide some details on how to work with the generator.
3.1 Running the generator
You can run this generator for the entire model only.
You can rerun the generator when you add or change enumeration items or properties, or the xfk:enum-cache configuration
of "readlist" operations, or if you change any parameters on those operations. Normally, the latter will require re-running
other generators that depend on the same model elements, such as generators of UI views, data objects, service and data
contracts or the service implementations. Therefore, this generator should be included in the build of the model project
in the configuration, in order to allow to easily regenerate all enumeration constants along with other artifacts.
3.2 Customizing the output
You should never edit generated classes or constants directly to allow re-running the generator at any time without losing
your changes. You should update the model as approriate instead.
3.3 Cleaning generator’s output
This generator does not support separate cleaning, since it always regenerates all enumerations when you rerun it.