REST Service Clients Generator

The following table of contents provides an outline of the documentation for this generator.

• 1. Overview
  • 1.1 Generator inputs
  • 1.2 Generator outputs
• 2. Configuration
  • 2.1 Generator parameters
  • 2.2 Model configuration
  • 2.3 Common configurations
• 3. How to use the generator
  • 3.1 Running the generator
  • 3.2 Customizing the output
  • 3.3 Cleaning generator’s output

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.

1.1 Generator inputs

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.