REST Service Clients
Generator
The following table of contents provides an outline of the documentation for this generator.
1. Overview
Generates customizable C# clients for REST services that implement the service interfaces generated by the
Service Contracts generator, and can be registered with the DI container
as implementation of those interfaces on the client side. You can add your customizations to a subclass of a generated
service client, and implement any additional logic for sending HTTP requests or handling HTTP responses as needed.
Since calling HTTP methods is asynchrounous, the generator requires that service operations are defined as async
in the global model configuration global_config.xom, as follows.
You also need to make sure that you register a service with the DI that provides an instance of HttpClient class
configured with the base URI address for the REST API, as well as with any Authorization or other headers set.
The generator creates REST service clients for each service/object that has any operation annotated with a rest:method
configuration element, where you need to provide the verb and a URI template that may contain input parameters in curly braces,
as illustrated below.
There can be only one input parameter that is not present in the URI template, which is usually a structure that goes into
the body of the HTTP request.
For service operations that don't have a rest:method configuration the generator will output a warning,
to catch any mistakes in the model. If you intentionally don't want to expose a certain operation via REST,
then you need to still add a rest:method element with the not-supported attribute set to true.
For example, the authenticate operation below can be used by the Web API internally for the JWT authentication,
but should not be exposed via REST, as shown below.
Whether the REST method is missing or not supported, the generated REST service proxies will still need to have the corresponding
operation generated, which will throw a NotSupportedException, if called.
Note, that this REST configuration for standard CRUD and Read List operations can be added automatically to the model by a special
model enhancement CRUD generator with the Generate Rest Methods parameter set to true.
1.2 Generator outputs
This generator creates C# classes for service clients that call the REST services, as well as a static class
for registering them for Dependency Injection (DI) with the service container, under the specified path
for the client-side project.
For objects that have a rest:client element under their config element with a customize
attribute set to “true”, it also creates a subclass of the generated service client with a postfix Customized appended
to the class name, if one does not exist yet, and will use this name for DI registration.
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 |
REST Service Clients
|
The name of the current configuration of the generator that will appear in the model project and the build output. |
| Folder Name |
Presentation Layer\Common
|
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.Client.Wpf /ServiceClients/{Module/}{File}.cs |
Relative path where to output files with generated REST service clients. The path may contain {Module/} and {File} placeholders
to output files by module and service respectively.
|
| Custom Path |
|
Relative path where to output override classes for the generated service clients. If not set, then the OutputPath
will be used. The path must contain a {File} placeholder to output files by service.
|
| Registry File |
../MySolution.Client.Wpf /ServiceClients/RestClients.cs |
Relative path to the file for service clients registration with the DI service container. The registration extension method
will be derived from the file name.
|
2.2 Model configuration
Parameters specified in the model configuration that are used by this generator consist of just the namespace for the
service contracts, which is specified in the svc:services-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 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 change or add operations with a REST configuration in the model. Normally, this will
require re-running other generators that depend on the same model elements, such as generators of UI views or service and
data contracts as well as 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 clients along with other artifacts.
3.2 Customizing the output
You should never edit generated service clients or the registration class directly. This allows re-running the generator at any
time without losing your customizations.
To add your customizations, you should edit a subclass of the generated service client that was added when you specified
the customize attribute on the rest:client element of the object's config element, as follows.
You can also add your own custom subclass of the generated client in your project, but then you will need to make sure
to register that class with the dependency injection service container after the generated clients are registered.
3.3 Cleaning generator’s output
This generator supports cleaning either all generated clients, 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.
Note, that the customization subclasses that were generated for service clients with a customize attribute set to
“true” will not be cleaned during these operations to prevent any loss of custom code during accidental run of such actions.
Therefore, you may get compilation errors for those classes if you clean your service clients, and will need to delete them
manually as needed.