ServerExtentions¶
{note:title=Work in progress}
This documentation is in the process of being developed. As such it may omit details or be incomplete in areas.
{note}
Introduction¶
As of release 1.4.4, it is possible to build server extensions for both the console and the Windows service.
An extension is different from a plug-in. A plug-in must be referenced by a project in ccnet.config, and as such works within the framework of the server. An extension on the other hand is added in the config file for the application (either ccnet.exe.config or ccservice.exe.config) and modifies the functionality of the entire server (i.e. it is not project specific).
This means an extension can modify the underlying behaviour of the server, although it doesn't have to. Examples of extensions include build throttling, new transport transports, expanded logging, and pre/post build processing.
When an extension is initialised, it is passed a reference to the main server, so it can call any server methods or subscribe to any events. Additionally the extension must implement a number of events, which allows the server to interact with the extension.
The Basics¶
A basic extension must implement ICruiseServerExtension. This interface has four methods:- Initialise(): called when the server is initially loaded, passes in an ICruiseServer reference and allows the extension to perform any custom initialisation (e.g. load config settings, etc.)
- Start(): called when the server starts up - tells the extension the server is now running. This allows the extension to also start processing.
- Stop(): called then the server stops - tells the extension that the server will no longer handle requests. This allows the extension to stop any processing gracefully.
- Abort(): called when the server is aborting - similar to Stop(), but means all functionality must be terminated immediately.
The Initialise() method is called with two parameters: a ICruiseServer reference and any configuration for the extension. The configuration is any sub-elements defined in the application config file. If the extension needs to interact with the server, then it must store the ICruiseServer reference.
Interacting with the Server¶
There are two basic ways of interacting with the server - calling methods or listening to events.
There is a wide range of methods available, most of them are used by the client applications for calling the server. However they can all be used by an extension.
Method categories include:- Informational: retrieve information about what is happening in the server, logs or results from projects, lists of builds, etc.
- Control: force or abort builds, start or stop projects (or the entire server), send messages, etc.
- Configuration: add, update or delete projects.
As work progresses on the server new methods will be added over time.
Handling Server Events¶
Methods provide a proactive way for extensions to work with the server, events provide a reactive way - that is they allow the extension to handle events that have been raised from somewhere else. Available events are:- ProjectStarting/ProjectStarted
- ProjectStopping/ProjectStopped
- ForceBuildReceived/ForceBuildProcessed
- AbortBuildReceived/AbortBuildProcessed
- SendMessageReceived/SendMessageProcessed
- IntegrationStarted/IntegrationCompleted
Each event has a start of event/end of event pair. In the start of event handler it is possible to cancel an event, while the end of event is purely informational.
All of the events, except for IntegrationStarted/IntegrationCompleted, are fired when the relevant method on CruiseServer is called. The IntegrationStarted/IntegrationCompleted are fired when an integration is started and finished - these events are not related to any methods on CruiseServer.
Limitations¶
Currently there are still a few limitations on server extensions.- An extension cannot interact with the configuration, nor can they see the list of projects. As such it only has a very limited view of what is in a project.
- An extension cannot see inside a project. Currently it is only limited to the project name and the details available in a request.
- The extension cannot monitor any CruiseServer methods except for Start(project), Stop(project), ForceBuild(project, enforcer), AbortBuild(project, enforcer) and SendMessage(project, message).
Configuring the Extension¶
{note:title=To-do}
Show how to configure an extension so it will be registered by the server.
{note}
Custom Configuration Elements¶
{note:title=To-do}
Explain how to load custom configuration information, where this happens and the underlying principals of configuration.
{note}