UWS Configuration Guide

Every service need an own XML configuration file where all settings are made. When the service was started it looks for a *.config file in the installation directory with the same name as it's service name.

For example: If your service has the service name "uws1" the service looks for a configuration file with name "uws1.config" at the installation directory.

This is an example of a valid XML configuration. The root element of all service settings must be <uws>. This does not mean that this configuration could not be embedded in another XML document but all required settings for universal windws service must be child elements of <uws> element.

<uws>
	<!-- settings of the logging (using log4net) - see log4net documentation for further information -->
	<log4net>
		<appender name="File" type="log4net.Appender.FileAppender">
			<file value="uws.log"/>
			<appendToFile value="true"/>
			<layout type="log4net.Layout.PatternLayout">
				<conversionPattern value="%date [%thread] %-5level %logger - %message%newline"/>
			</layout>
		</appender>
		
		<logger name="uws">
			<level value="ALL"/>
			<appender-ref ref="File"/>
		</logger>
		
		</logger name="Explorer">
			<level value="ALL"/>
			<appender-ref ref="File"/>
		</logger>
		
		</logger name="InvokeMethod1">
			<level value="ALL"/>
			<appender-ref ref="File"/>
		</logger>
		
		</logger name="InvokeMethod2">
			<level value="ALL"/>
			<appender-ref ref="File"/>
		</logger>
	</log4net>
	
	<!-- configuration of global assigned settings -->
	<global>
		<trigger type="uws.Triggers.DailyTrigger">
			<time value="10:00"/>
		</trigger>
		
		<trigger name="2minInterval" type="uws.Trigger.IntervalTrigger">
			<minutes value="2"/>
		</trigger>
	</global>
	
	<!-- configuration of the universal windows service by itself -->
	<application name="Explorer" enabled="true">
		<executable>
			<path value="c:\winnt\explorer.exe"/>
			<windowstyle value="maximized"/>
		</executable>
		
		<triggers>
			<trigger type="uws.Triggers.OneTimeTrigger">
				<date value="10.12.2005"/>
				<time value="10:00"/>
			</trigger>
			
			<trigger type="uws.Triggers.ServerTrigger">
				<monitor ref="Crashed"/>
			</trigger>
			
			<trigger type="uws.Triggers.OnServiceStartTrigger"/>
		</triggers>
		
		<monitors>
			<monitor name="Crashed" type="uws.Monitors.CrashMonitor"/>
		</monitors>
	</application>
	
	<application name="InvokeMethod1" enabled="true">
		<executable>
			<!-- call .NET assembly -->
			<path value="c:\data\myNetSample.dll"/>
			<method name="mySample.TestClass.MyMethod"/>
			<arguments>
				<argument name="arg1" value="test"/>
				<argument name="arg2" value="23"/>
			</arguments>
		</executable>
		
		<triggers>
			<trigger type="uws.Triggers.DailyTrigger">
				<time value="12:00"/>
			</trigger>
		</triggers>
	</application>
	
	<application name="InvokeMethod2" enabled="true">
		<executable>
			<!-- call other library -->
			<path value="c:\data\myCppSample.dll"/>
			<method name="ExportedFunction" returntype="System.Int32"/>
			<arguments>
				<argument name="number" type="System.Double" value="10.3"/>
				<argument name="val" type="System.String" value="test"/>
			</arguments>
		</executable>
		
		<triggers>
			<trigger type="uws.Triggers.OnServiceStartTrigger"/>
		</triggers>
	</application>
</uws>

The <uws> element has no attributes but supports the following child elements:

Element	Description
log4net	All possible logging settings are made here using the apache logging service for .Net. For configuration settings see log4net homepage.
global	An optional feature which allows you to configure global settings which could be used from different applications. Currently only global triggers are supported.
application	Each executable which should be started and watched by universal windows service must have such an element whith all important settings.

log4net

A lot of logging outputs are available. You would found an example configuration at log4net homepage. If no <log4net> element is given no logging output will be done. For each executable should be an own <logger> section with the same name given. This <logger> entry will be used by the referenced application as logging informations. If no <logger> section with the same name of the application is given the default <logger> section for universal windows service by itself with name "uws" is used.

Global

The <global> element is an optional one but if it is used it must be unique. If you do not need some global settings remove this element from your configuration file or leave it empty.

The following child elements are possible:

Element	Description
trigger	Specifies a startup event for an application. Triggers will be used to decide at which time a configured executable should be started. For more detailed information on possible trigger types and settings see the triggers section below.

Application

Each <application> section must be uniquely named.

The following attributes are supported:

Attribute	Description
name	A required attribute. The value must be a string name for this application. The name must be unique among all applications which are defined in this configuration file. This name is used to identify the right logger from <log4net> section.
enabled	A required attribute. Possible values are "true" or "false". True means that the <application> section is enabled. If attribute is not found or the value "false" is given the whole <application> section will be ignored.

The <application> section supports the following child elements:

Element	Description
executable	Exactly one element is required. This element includes all necessary information about the executable file which represent the application and some startup settings.
triggers	An optional attribute. Include all local start events called triggers which show the service when this executable should be started. In addition to this local triggers some global triggers would maybe used as start events.
monitors	Also an optional attribute. Include all monitor events which would be used to watch the configured application. Different implementations could be possible with different reactions on some application states.

Executable

The <executable> section could only used as child element of an <application> section. It has no attributes but the following child elements are possible.

Each child elment has a value attribute which contains further informations of the different tags.

Element	Description
path	The "value" attribute of this element specify the path to the executable file of the application or a calling assembly or library. It is a required element and allowed once only. The path must point to an existing file.
arguments	This is an optional argument. It specifies the console line arguments which are given to the executable file if it would be started. <arguments value="-u -s"/> If the method field would be given this tag could contain some function arguments like the following style. <arguments> <argument name="arg1" type="System.String" value="test"/> <argument name="intValue" type="System.Int32" value="23"/> <argument name="doubleValue" type="System.Double" value="5.098"/> <argument name="isOk" type="System.Boolean" value="true"/> </arguments> Name of the argument must be exact the same as specified in the name attribute. The value attribute includes the specified value for the argument. The type attribute must only be entered if another library than a .NET assembly will be called because there no normal reflection calls could be made. Caution: The double value conversion depends on the local language settings! If a argument is optional you don't have to enter it here. If you want to use a more complex type you have to provide a so called type converter which is derived from the base class System.ComponentModel.TypeConverter.
workingdir	An optional argument. It allows you to define a special working directory which the application uses as home directory. If no one is given the system directory will be used as home directory.
windowstyle	Also an optional argument. It describes the window form of the application if it would be started. normal - A normal visible window will be created at appliction startup. User input and application output are displayed on screen. minimized - The application will be started as entry in in task bar but no window will displayed on screen until you click on the minimized application in task bar. maximized - The opposite of minimized. The application will be started as a full screen application. hidden - No desktop window will be created. Therefore it is impossible to enter user input or see application output. No entry in task bar will be made. If no window style is given the normal display mode is used. The value of this parameter is not case sensitive.
instances	An optional argument. It marks the number of instances which will be started every time a trigger matches.
method	The method tag is an optional one. If it is given the path field must contain a path to a class library (for example a dll file). The method field includes the name of an implemented method in this given assembly. <method name="GetScore" returntype="System.Int32"/> The structure of the nameattribute is the following: 'namespace.class.method'. The namespace is only important if a namespace exists in assembly. If you call another library than a .NET assembly you have to enter the return type of the function by returntype attribute. The Name of the function also requires no namespace or class name. The implemented method in the library must be public and static. Different arguments are also possible. These arguments could be given as child tags in the arguments field. All other fields like workingdir, instances will be ignored. A monitor section is also redundant because there is no running application. An example is given in the second and third application section ('InovkeMethod1' and 'InvokeMethod2') above.

Triggers

The <triggers> section contain all local start events for this <application> section. The following configuration of the different triggers is also possible in the <global> section described above.

Each trigger will be defined as an own child element of the <triggers> section:

<triggers>
	<trigger type="uws.Triggers.OneTimeTrigger">
		<date value="13.12.2005"/>
		<time value="10:00"/>
	</trigger>
	
	<trigger ref="2minInterval"/>
</triggers>

Different usages of the triggers are possible.

You define a local trigger shown as the first <trigger> section in the example above. This trigger will only be used from this application.
A global trigger specified like the first <trigger> section in the example at top of this page. This trigger will be configured as every other local trigger in <application> section. It marks a trigger which is used for every application configured in this file. Every enabled application will be started when this start event will be reached.
Another way to define a global trigger is shown in the example at top of this page with the second <trigger> entry. The only difference to other configurations is that there a name will be specified. This name must be unique for all trigger names. This trigger will only be used from referenced applications.
In the <application> section you could reference to a global trigger as shown in the example above with the second <trigger> entry. More than one application could use such global named triggers. Each application uses the same trigger and will be started at the same time.

The following attributes are possible for a <trigger> section:

Attribute	Description
type	A required attribute if no "ref" attribute is given. The value must be the type name of this trigger. If the trigger is not defined in the UWS assembly this type name must be fully assembly qualified.
name	A global named trigger could be referenced from different applications. If a name is given it must be a unique one.
ref	If this attribute is given no further trigger settings could be made. The given name is used to reference on global trigger with the same name.

The following triggers are implemented. The name specify the real type name.

uws.Triggers.OneTimeTrigger

This trigger fires it's event at a configured date and time once only.

Configuration example:

<trigger type="uws.Triggers.OneTimeTrigger">
	<date value="13.12.2005"/>
	<time value="10:00"/>
</trigger>

The following date configurations are possible:

eng - 2005-10-26
us - 26/10/2005
ger - 26.10.2005

Also these configurations are possible for start time:

eng - 11:48 am
eng - 1:30:30 pm
ger - 11:48
ger - 23:30:10

uws.Triggers.IntervalTrigger

This trigger fires it's event each time the interval is over.

Configuration example:

<trigger type="uws.Triggers.IntervalTrigger">
	<days value="1"/>
	<hours value="3"/>
	<minutes value="20"/>
	<seconds value="5"/>
	<milliseconds value="500"/>
</trigger>

All sections which will be found (also more than one time) will be summarized to time interval.

uws.Triggers.DailyTrigger

This trigger fires it's event at a configured time every day.

Configuration example:

<trigger type="uws.Triggers.DailyTrigger">
	<time value="11:00"/>
</trigger>

The following time configurations are possible:

eng - 11:48 am
eng - 1:30:30 pm
ger - 11:48
ger - 23:30:10

uws.Triggers.WeeklyTrigger

This trigger fires it's event at a configured day of week and time every week.

Configuration example:

<trigger type="uws.Triggers.WeeklyTrigger">
	<weekday value="3"/>
	<time value="10:00"/>
</trigger>

The weekday tag must have a value between 1 and 7. 7 is the value for sunday. 3 for example means wednesday.

The following time configurations are possible:

eng - 11:48 am
eng - 1:30:30 pm
ger - 11:48
ger - 23:30:10

uws.Trigger.CronTrigger

This trigger fires it's event each time the crontab matches.

Configuration example:

<trigger type="uws.Triggers.CronTrigger">
	<cron value="10-30/2 12,13,14-18 * * *"/>
</trigger>

The following configurations are possible:

Field	Allowed values
Minute	0 - 59
Hour	0 - 23
Day of month	1 - 31
Month	1 - 12
Day of week	1 - 7 (7 is Sunday)

A field may be an asterisk (*) which always stands for 'first-last'. All fields must be filled and contain a valid value.

Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen. The specified range is inclusive. For example, 8-11 for an 'Hours' entry specifies execution at hours 8, 9, 10 and 11.

Lists are allowed. A list is a set of numbers (or ranges) separated by commas. Examples: '1,2,5,9' or '0-4,8-12'.

Step values can be used in conjunction with ranges. Following a range with '/number' specifies skips of the number's value through the range. For example, '0-23/2' can be used in the hours field to specify command execution every other hour (the alternative in the V7 standard is '0,2,4,6,8,10,12,14,16,18,20,22'). Steps are also permitted after an asterisk, so if you want to say 'every two hours', just use '*/2'.

uws.Triggers.ServerTrigger

This trigger fires it's event ervery time a specified monitor matches.

Configuration example:

<trigger type="uws.Triggers.ServerTrigger">
	<monitor ref="Crashed"/>
</trigger>

uws.Triggers.OnServiceStartTrigger

This trigger fires it's event only when the UWS was started.

Configuration example:

<trigger type="uws.Triggers.OnServiceStartTrigger"/>

No further information are neccessary for this type of trigger.

Monitors

The <monitors> section contain all monitor events for this <application> section which would be used to watch application states and react on it.

Each monitor will be defined as an own child element of the <monitors> section:

<monitors>
	<monitor name="Crashed" type="uws.Monitors.CrashMonitor"/>
</monitors>

The following attributes are possible for a <monitor> section:

Attribute	Description
name	A required attribute. The value must be a unique name of the monitor which will be used to reference the monitor by a trigger or something else.
type	A required attribute. The value must be the type name of this monitor. If the monitor is not defined in the UWS assembly this type name must be fully assembly qualified.

The following monitors are implemented. The name specify the real type name.

uws.Monitors.CrashMonitor

This monitor fires it's event when the specified application will exit.

Configuration example:

<monitor name="Crashed" type="uws.Monitors.CrashMonitor"/>

There are no further information possible.