Zerto.WebApi.Rpc.ControllerBuilder 2.2.0.20

Zerto.WebApi.ControllerBuilder:

About:

The purpose of this project is to allow .NET developers to create HTTP based services that are defined using interfaces.

.NET interfaces and data contracts are very convenient to work with when communicating between .NET applications, and both this project and Zerto.WebApi.ClientBuilder were created with the purpose of providing a simple way to publish and consume such services, without requiring the developer to be familiar with HTTP, JSON, ASP.NET and etc.

This project is a .NET Standard 2.0 project that builds upon the capabilities of Microsoft ASP.NET Core MVC Web API v2.2. This project contain both the controller generation logic and the web application that publish those controllers.

Glossary:

Controller - Class that handles incoming HTTP requests and send response back to the caller. Action - All the public methods of the controller are called action methods. Middleware - Allows adding extra logic into an ASP.NET web application pipeline to handle all requests and responses. Filter - Allows adding extra logic before or after a controller action. Action Filter - The last filter type in the ASP.NET pipeline, invoked immediately before and after the controller action. Action filters execute after the model binding stage (where the HTTP content has been serialized to .NET objects). Service Name - The name of the published service from the point of view of the service consumer. Each action is exposed as a URL, where the controller appears to be the parent directory of the action. We publish the controller (this "parent directory") using a service name that can be set during service registration.

Diagram:

╔════════╗   Request   ┌───────────┐   Request    ┌─────────────┐       ┌────────────────┐
║  HTTP  ║ ──────────> │ Action    │ ───────────> │             │ ────> │    Service     │
║ Client ║             │ Filter(s) │              │ Controller* │       │ Implementation │
║        ║ <────────── │           │ <─────────── │             │ <──── │  (Singleton)   │
╚════════╝   Response  └───────────┘   Response   └─────────────┘       └────────────────┘

* Auto-generated

External Components:

WebApiControllerBuilder - This is the main component of this project, this class use reflection to generate a controller for a given interface, each interface method becomes a controller action.

ControllerBuilderWebApplicationStartup - This class contains the startup logic of the web application that publishes the controllers. This class implements the IStartup interface in order to allow easier integration with web hosts.

Internal Components:

ControllerTypeRegistry - This class holds a reference to all the controllers that were generated, and is used to locate the controllers when starting the web application.

ServiceInstanceRegistry - We allow the developer to provide an instance of each service (that implements the interface) he wishes to expose, this class holds a reference to all the instances.

ActionFiltersRegistry - This class holds a reference to all the IActionFilter implementations provided by the caller.

Usage:

The developer should use WebApiControllerBuilder to register the services he wish to publish, and then start the web application by starting a web host that will execute the application Startup logic.

• The same service can be published multiple times using different service names. (Useful when you wish to expose two instances of the same service or the same instance using different action filters)

• It is possible to start multiple web applications, each publishes its own services (using a different port).

Limitations:

• It is currently not possible to associate additional controllers with a web application once it has started, removal of controllers from a running web application is also not currently possible.

• A service name must be unique within the scope of the process.

Interface definition rules:

Interface inheritence is supported, multiple input parameters are supported (both primitives and complex types), for complex types it is encouraged (but not mandatory) to use the DataContract class attribute.

Streaming: Only a single input stream and / or a single output stream is supported. (The same interface can contain both streaming and non-streaming methods)

An interface exposed via WebApiControllerBuilder must not contain any of the following:

• Method overloading
• Events
• Method with ref parameter
• Method with out parameter
• Method with multiple input parameters that one of them is Stream.
• Method declaring input / output parameter type that inherits from Stream (such parameter must be explicitly declared as Stream).

Note regarding Streams:

If your interface method returns a Stream, please note that Web API will call Stream.Close after the TCP connection using that stream is terminated. You should not close this Stream yourself or otherwise it may not be available to the client. If you wish to execute any post-close logic (e.g. deleting a temporary file), the best approach would be to implement a wrapper over the returned stream, override the Close method, and trigger any post-close logic there.

If your interface method accepts a Stream, there is no requirement to call Stream.Close.