Service Contracts
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
Generates C# service interfaces with methods for all operations on an object or its subobjects, as well as data structures
for input and output of such operations, and for any standalone reusable structures declared in the model.
To allow exposing the services through WCF, those interfaces and data structures can be also decorated with
ServiceContract or DataContract attributes, or other WCF attributes as needed.
Any object in the Xomega model that has operations, or subobjects with operations, represents a service. Configuration of
such operations and any supporting structures in the model is used to generate the service and data contracts.
Operations. The service name will be based on the object name with a "Service" postfix, and an "I" prefix following .Net
standards, e.g. ISalesOrderService. The name of a service method will be based on the name of the corresponding operation, potentially with
the name of the subobject prepended to ensure that they don't clash with other methods. For the input and output structures, as well as any
inline structures nested within those, there will be generated a dedicated structure with a fully qualified name. For example, for the inline
structure data nested inside the input of the sales order's update operation that is shown below, the name of the generated structure
will be SalesOrder_UpdateInput_Data.
Structures. Instead of inline structures defined directly inside the service operations, you can just reference a named
structure that is defined globally in the model. For example, the customer update and payment update structures that
are referenced in the previous example, can be defined under the structs top-level element in the model as follows.
The name of the generated class will be based on the name of the structure, e.g. CustomerUpdate, which should be unique as long
as there are no other classes with this name defined in the services' namespace. Note, that the standalone structures can in turn have
parameters referencing other standalone structures, or can have other inline structures nested inside of them, which will be also
generated using their fully qualified name.
CLR types. The CLR types that are used on the generated structures are determined based on the configuration
of their logical types in the model. If the logical type is not specified on the structure's parameter, then the type of
the field with the same name on the corresponding object will be used, which is either the object that the operation
is defined on, or the object referenced by the object attribute on a standalone structure. The logical types usually
inherit such configurations from their base types, but can override the CLR types to use as needed. You need to add
the clr:type element under the config element of the type, and specify the CLR type's name and namespace,
as well as whether it's a value type, as follows.
Note, that standard CRUD and Read List operations for an object can be easily added automatically to the model by a special
model enhancement CRUD generator.
1.2 Generator outputs
This generator creates C# classes for service and data contracts, which can be placed in separate files by service, grouped by module,
or output to a single file, depending on how you set up your Output Path parameter. The standalone structures will be output
in a separate file by module with a "Structures" postfix. The generated classes will be added to the specified project,
which is usually a separate shared project that can be used by both the client and the server-side projects.
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 |
Service Contracts
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
| Folder Name |
Service Layer
|
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 /ServiceContracts/{Module/}{File}.cs |
Relative path where to output files with generated service and data. The path may contain {Module/} and {File} placeholders
to output files by module and data object respectively.
|
| Parameters |
2.2 Model configuration
Configuration parameters for the generator that need to be also accessible to other generators are specified in the Xomega
model in the svc:services-config element under the top level config element, which is conventionally
placed in the global_config.xom file. These parameters include the namespace for the generated classes, as shown below.
The generated service interface and structures will be decorated with WCF attributes for service and data contracts
only if WCF configuration is defined in the global model configuration wcf:config element under the top level
config element, as illustrated below.
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 either for the entire model, or for individual files by selecting them in the model project,
and running the generator from the context menu.
You can rerun the generator when you add or change object operations or structures in the model, which will require re-running
other generators that depend on the same model elements, such as generators of UI views, data objects as well as 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 service and data contracts along with other artifacts.
3.2 Customizing the output
You should never edit generated service and data contracts directly. This allows re-running the generator at any
time without losing your customizations.
WCF Attributes. If you need to provide additional custom WCF attributes beyond the basic
ServiceContract and DataContract that will be generated if you have a wcf:config
element in the model configuration, then you can add a wcf:operation-attributes element in the model to
the config element of individual operations, or a wcf:service-attributes element to
the config element of the object, as illustrated below.
You can also exclude some operations from being exposed via WCF by adding a wcf:operation element
to the operation's config with a not-supported attribute set to true, as follows.
REST Attributes. If you want to expose some services via REST interface, you will need to add
rest:method element to the config of each operation that you need exposed, as follows.
3.3 Cleaning generator’s output
This generator supports cleaning either all generated service contracts, or only the ones from the selected model files using
the Clean context menu for that generator. Normally, cleaning the generated files makes sense if you are planning to change
the output path for the generator. Also, it can be used as part of Regenerate action, which runs the Clean and then Generate
actions, when you have removed some of the services from the model, and want the generated classes deleted and removed
from the target project.