TypeScript Service Contracts
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
Generates TypeScript structures for input and output data contracts for REST services, as well as methods for all REST operations
on an object or its subobjects that help you to easily call those operations in a structured manner using JQuery Ajax API.
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. For each REST service, there will be a TypeScript class generated based on the object name,
starting with "I", and ending with "Service", e.g. ISalesOrderService. For each service operation that is exposed
via REST, i.e. has a rest:method configuration, this class will contain a method starting with "get", followed
by the operation's fully qualified name, and ending with "Request", e.g. getUpdateRequest(...) which will take
input arguments either as individual parameters, or as structures, and will construct an instance of JQueryAjaxSettings
class with proper URL and body parameters, which can be used to invoke the REST operation asyncronously.
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.
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.
TypeScript types. The primitive properties on the generated structures will be of type any, so there is
no need to map logical types in the model to the TypeScript types. This will NOT allow TypeScript compiler to check the type of the
arguments that you pass to the input structures, or assign from the output structures, but it will provide you with IntelliSense and
compiler checks of the the names for input and output parameters used, which is more important.
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 TypeScript 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 tsOutputPath model configuration attribute
for services. 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 dedicated project for the SPA client.
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 |
TypeScript Service Contracts
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
| Folder Name |
Presentation Layer\SPA
|
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 |
| Add To Project |
../MySolution.Services.Spa /MySolution.Services.Spa.csproj |
Relative path to the project file to add the generated files 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
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 output path for the generated TypeScript files,
which may contain {Module} and {File} placeholders to output them by module and service, as shown below.
Note that this is different from most of the other generators, which specify the output paths as generator parameters
rather than in the model configuration. But, to be able to use the generated classes in other TypeScript files requires
importing the file where the generated class is declared using a relative path to it, so the other generators that use
services, such as Data Objects, also need to know the path to them.
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.
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.