Difference: WcfHookExtensions (3 vs. 4)

Revision 417 Jun 2011 - Main.TomGreen

Line: 1 to 1

META TOPICPARENT	name="WebHome"

WCF Hooks Extensions

Line: 25 to 22

Hooks are an optional component of the Enkompass WCF processing architecture. To enable the hooks system, you must add a configuration file to the hooks application path.

You can find your hooks application path by looking in your server's registry:

Changed:

<
<

$cPanelApplicationPath$ = HKLM:SOFTWARE\cPanel, Inc.\cPanel\ApplicationPath

>
>

$cPanelApplicationPath$ = HKLM:SOFTWARE\cPanel, Inc.\cPanel\ApplicationPath

Once you have this value, combine the path listed above with the following:

Changed:

<
<

$cPanelApplicationPath$\Common\Hooks\HookConfiguration.config

>
>

$cPanelApplicationPath$\Common\Hooks\HookConfiguration.config

For example:

Changed:

<
<

$cPanelApplicationPath$ = HKLM:SOFTWARE\cPanel, Inc.\cPanel\ApplicationPath$cPanelApplicationPath$\Common\Hooks\HookConfiguration.config

>
>

\\fileserver\e\ApplicationPath\Common\Hooks\HookConfiguration.config

The configuration file

The HookConfiguration.config configuration file should resemble the following:

Line: 45 to 32

The configuration file

The HookConfiguration.config configuration file should resemble the following:

Deleted:

<
<

Changed:

<
<

<-- SyntaxHighlightingPlugin -->

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="hookLoaderConfiguration" 
             type="cPanel.Core.Hooks.HookLoaderConfigurationSection,cPanel.Core.Hooks" />
  </configSections>
  <hookLoaderConfiguration>
    <hookItems>
    ...
    </hookItems>
  </hookLoaderConfiguration>
</configuration>

<-- end SyntaxHighlightingPlugin -->

>
>

<-- SyntaxHighlightingPlugin -->

<!--l version="1.0" encoding="utf-8--> <?xml version="1.0" encoding="utf-8?><configuration&gt; <configSections> <section name="hookLoaderConfiguration" 
             type="cPanel.Core.Hooks.HookLoaderConfigurationSection,cPanel.Core.Hooks" /> </configSections> <hookLoaderConfiguration> <hookItems> ... </hookItems> </hookLoaderConfiguration> </configuration>

<-- end SyntaxHighlightingPlugin -->

You may configure a few parameters in this file.

Deleted:

<
<

The <hookLoaderConfiguration> tag

You can configure the following attributes of the <hookLoaderConfiguration> tag:

Line: 68 to 41

The <hookLoaderConfiguration> tag

You can configure the following attributes of the <hookLoaderConfiguration> tag:

Deleted:

<
<

Name	Values	Optional	Default	Notes

Changed:

<
<

debug	`true` `false`	yes	`false`	Enables additional logging in the message processing layers. This logging will slow down processing for WCF calls significantly. You should either not include this attribute in the configuration file or make sure to set its value to `false` in most cases. You should only enable this feature when you are trying to diagnose a problem with the hooks system.
logAll	`true` `false`	yes	`false`	Enables verbose logging of unmonitored messages, including the output of their SOAP messages. Enabling this attribute may be useful to developers trying to understand the format of the action names and details of a SOAP message's header or body.

>
>

debug	`true` false=	yes	`false`	Enables additional logging in the message processing layers. This logging will slow down processing for WCF calls significantly. You should either not include this attribute in the configuration file or make sure to set its value to =false in most cases. You should only enable this feature when you are trying to diagnose a problem with the hooks system.
logAll	`true` `false`	yes	`false`	Enables verbose logging of unmonitored messages, including the output of their SOAP messages. Enabling this attribute may be useful to developers trying to understand the format of the action names and details of a SOAP message's header or body.

The <hookItems> tag

The <hookItems> tag is contained in within the <hookLoaderConfiguration> tag. This tag contains the collection of hooks to install on the system. Each hook is added into the <hookItems> tag using an <add> tag like so:

Line: 76 to 47

The <hookItems> tag

Deleted:

<
<

Changed:

<
< %CODE{lang="html"}% <add name="UrlHooks"

>
> %CODE{lang="html"}% <add name="UrlHooks"

type="cPanel.Core.Hooks.UrlHookBehaviour, cPanel.Core.Hooks"

Changed:

<
< externalConfigurationPath="\\10.1.15.101\e\ApplicationPath\Common\Hooks\UrlHookConfiguration.config" /> %ENDCODE%

>
> externalConfigurationPath="\\10.1.15.101\e\ApplicationPath\Common\Hooks\UrlHookConfiguration.config" /> %ENDCODE%

The <add> tag

You can use the <add> tag to add a single hook behavior to the Enkompass WCF pipeline. Each behavior represents a complete and independent way that hooks are processed. This <add> tag has the following attributes:

Line: 89 to 55

The <add> tag

Deleted:

<
<

Name	Values	Optional	Default	Notes
name	$string	no	N/A	A unique name for the hook.

Changed:

<
<

enable true
false yes true Selects whether to enable or disable the corresponding hook.

>
>

enable	`true` `false`	yes	`true`	Selects whether to enable or disable the corresponding hook.

type	$fully-qualified-type	no	N/A	The .NET object type that implements the hook behavior. The type may be in any format recognizable the Microsoft .NET framework. For more information, review Microsoft's type documentation.
path	$path	yes	N/A	If provided, this parameter will load the DLL from the specified path instead of the default location. This allows you to install DLLs for hooks outside of Enkompass, but load them into the Enkompass WCF services process. Warning:We have not yet tested this parameter.
externalConfigurationPath	$path	no	N/A	The full path to the configuration file for this hook behavior.

Line: 116 to 76

%CODE{lang="html"}%

Changed:

<
< <section name="commandHookConfiguration" type="cPanel.Core.Hooks.CommandHookConfigurationSection,cPanel.Core.Hooks" /> <add name="BeforeAmIAlive"

>
>

<--l version="1.0-->

<section name="commandHookConfiguration" type="cPanel.Core.Hooks.CommandHookConfigurationSection,cPanel.Core.Hooks" /> <add name="BeforeAmIAlive"

action="http://www.cpanel.net/schemas/2008/03/IServerAdministratorService/AmIAlive"

Changed:

<
< actionType="Before" command="C:\logger\log.exe" args=" -before '{0}'" /> <add name="AfterAmIAlive"

>
> actionType="Before" command="C:\logger\log.exe" args=" -before '{0}'" /> <add name="AfterAmIAlive"

action="http://www.cpanel.net/schemas/2008/03/IServerAdministratorService/AmIAlive"

Changed:

<
< actionType="After" command="C:\logger\log.exe" args=" -after '{0}'" />

>
> actionType="After" command="C:\logger\log.exe" args=" -after '{0}'" />

%ENDCODE%

Line: 140 to 88

The <commandHookConfiguration> tag

The <commandHookConfiguration> tag has the following attributes:

Deleted:

<
<

Name	Values	Optional	Default	Notes

Changed:

<
<

enabled true
false yes true Turns the entire hook behavior on or off. You must restart the WCF service for changes to this attribute to take effect.

>
>

enabled	`true` `false`	yes	`true`	Turns the entire hook behavior on or off. You must restart the WCF service for changes to this attribute to take effect.

The <handledMessages> tag

This tag contains a list of the messages that will be processed by the command hook behavior. Each message must be specified by an <add> tag.

Line: 157 to 101

Name	Values	Optional	Default	Notes
name	$string	no	N/A	The unique name of the message to process. This is something you make up to describe the message you are processing.
action	$string	no	N/A	The internal representation for the WCF message you want to process. This value should be formatted like so: `http://www.cpanel.net/schemas/2008/03/<ServiceInterface>/<MessageName>` Where `<ServiceInterface>` is one of the following: IServerAdministratorService — Methods for SAI IWebSiteOwnerService — Methods for WSOI IMailOwnerService — Methods for MOI The `<MessageName>` tag is the name of the method to call to the API.

Changed:

<
<

actionType Before After yes After This value indicates when the hook should be used, either before or after the API call is processed.
Note: Before action types can cancel the API call; After action types cannot.

>
>

actionType	`Before After`	yes	`After`	This value indicates when the hook should be used, either before or after the API call is processed. Note: `Before` action types can cancel the API call; `After` action types cannot.

command	$string	no	N/A	The command to call when the message is received. The command can include optional substitution parameters using {#} syntax. The following are valid substitution parameters. {0} - Message Name {1} - Stage
args	$string	yes	N/A	The arguments to pass to the command. Arguments can include optional substitution parameters using {#} syntax. The following are valid substitution parameters: {0} - Message Name

Changed:

<
<

stripSoapEnvelope	`true` `false`	yes	`true`	WCF processes all messages as SOAP calls. The hook has code to strip out SOAP headers if this is attribute is set to `true`. When set to `false`, the message is passed to the command as-is.
transform	$XSLT	yes	N/A	A valid XSLT transform definition to apply to the message sent to the command. Note: If `stripSoapEnvelope` is enabled, the SOAP headers are stripped before this transform is called.

>
>

stripSoapEnvelope	`true` false=	yes	`true`	WCF processes all messages as SOAP calls. The hook has code to strip out SOAP headers if this is attribute is set to `true. When set to =false`, the message is passed to the command as-is.
transform	$XSLT	yes	N/A	A valid XSLT transform definition to apply to the message sent to the command. Note: If `stripSoapEnvelope` is enabled, the SOAP headers are stripped before this transform is called.

The command, called by the command hook, should expect the incoming message data on standard input. It should send output to standard output and errors to standard error.

For hooks with action Type = Before, the input message format is as follows:

Changed:

<
<

>
>

Log.exe Information: 0 : [ ] 2011-06-07 17:23:45Z [INFO : ] - Command Hook Application - Main - Before 'http://www.cpanel.net/schemas/2008/03/IServerAdministratorService/AmIAlive' Message ID: f9fdae87-eb37-4a54-afa9-665691706297

Line: 177 to 119

Request:

Changed:

<
<

>
>

For hooks with action Type = After, the input message format is as follows:

Changed:

<
<

>
>

Log.exe Information: 0 : [ ] 2011-06-07 17:23:45Z [INFO : ] - Command Hook Application - Main - After 'http://www.cpanel.net/schemas/2008/03/IServerAdministratorService/AmIAlive' Message ID: 27d2a629-8101-4338-bc5a-202fe40ccfd6

Line: 196 to 135

true

Changed:

<
<

>
>

Writing a command

When designing the command to process the hooked event, the process will pass the event name on the command line.

Line: 208 to 144

Key	Value	Description
Message ID	$GUID	The unique identifier for the message in the processing chain.
Action	$URL	The unique name of the event in URL format.

Changed:

<
<

Stage BeforeDispatch
AfterDispatch Indicates whether the hook event is sent before or after the core API is called. BeforeDispatch indicates that the command can be canceled by the hook, as the the hook event is taking place before the API call. AfterDispatch indicates that the hook is called after the core API call is run.

>
>

Stage	`BeforeDispatch` AfterDispatch=	Indicates whether the hook event is sent before or after the core API is called. `BeforeDispatch indicates that the command can be canceled by the hook, as the the hook event is taking place before the API call. =AfterDispatch` indicates that the hook is called after the core API call is run.

Request:/r/n	URL-encoded XML	The request tag is on a line by itself. The request body is on the next line and is URL-encoded.
Response:/rn	URL-encoded XML	The response tag is on a line by itself. The response body is on the next line and is URL-encoded. The response is sent only if the `Stage` is set to `AfterDispatch`.
/r/n/r/n	$EOF	Two consecutive empty lines indicate the end of the file.

Line: 212 to 148

Request:/r/n	URL-encoded XML	The request tag is on a line by itself. The request body is on the next line and is URL-encoded.
Response:/rn	URL-encoded XML	The response tag is on a line by itself. The response body is on the next line and is URL-encoded. The response is sent only if the `Stage` is set to `AfterDispatch`.
/r/n/r/n	$EOF	Two consecutive empty lines indicate the end of the file.

Deleted:

<
<

Sample log

Changed:

<
<

>
>

Before http://tempuri.org/ICalculator/Divide Message ID: edbf2452-36db-4acd-a8ad-96f9f40b30aa

Line: 241 to 174

Changed:

<
<

>
>

URL hooks

URL hooks allow you to send WCF messages to a URL to be processed. The URL should use standard HTTP requests and response mechanisms.

Line: 251 to 181

%CODE{lang="html"}%

Changed:

<
< <section name="urlHookConfiguration" type="cPanel.Core.Hooks.UrlHookConfigurationSection,cPanel.Core.Hooks" /> ...

>
>

<--l version="1.0-->

<section name="urlHookConfiguration" type="cPanel.Core.Hooks.UrlHookConfigurationSection,cPanel.Core.Hooks" /> ...

%ENDCODE%

Deleted:

<
<

The <urlHookConfiguration> tag

Deleted:

<
<

Name	Values	Optional	Default	Notes

Changed:

<
<

enabled true
false yes true Enables or disables the hook behavior. You must restart the WCF service for this to take effect.

>
>

enabled	`true` `false`	yes	true	Enables or disables the hook behavior. You must restart the WCF service for this to take effect.

baseUrl

$URL

yes

N/A

This attribute allows you to define the message URLs as relative to the base URL.

Deleted:

<
<

The <add> tag

This tag configures the URL hook for a single message. Each message you want to process should include an <add> tag.

Line: 279 to 195

Name	Values	Optional	Default	Notes
name	$string	no	N/A	The unique name of the message to process. This is something you make up to describe the message you are processing.
action	$string	no	N/A	The internal representation for the WCF message you want to process. This value should be formatted like so: `http://www.cpanel.net/schemas/2008/03/<ServiceInterface>/<MessageName>` Where `<ServiceInterface>` is one of the following: IServerAdministratorService — Methods for SAI IWebSiteOwnerService — Methods for WSOI IMailOwnerService — Methods for MOI The `<MessageName>` tag is the name of the method to call to the API.

Changed:

<
<

actionType Before
After yes After This value indicates when the hook should be used: either before or after the API call is processed.
Note: Before action types can cancel the API call; After action types cannot.

>
>

actionType	`Before` After=	yes	`After`	This value indicates when the hook should be used: either before or after the API call is processed. Note: `Before action types can cancel the API call; =After` action types cannot.

url

$string

N/A

The URL to call when the message is received. The URL can include optional substitution parameters using {#} syntax. The following are valid substitution parameters:

{0} - Message Name
{1} - Stage

Changed:

<
<

isRelativeUrl	`true` `false`	yes	`false`	If `true`, the URL indicated above is a relative URL and will be combined with `baseUrl` above. If `false`, then the above URL is a fully qualified URL.
stripSoapEnvelope	`true` `false`	yes	`true`	WCF processes all messages as SOAP calls. The hook has code to strip out SOAP headers if this attribute is set to `true`. When set to `false`, the message is passed to the command as-is.
transform	$XSLT	yes	N/A	A valid XSLT transform definition to apply to the message sent to the command. Note: If `stripSoapEnvelope` is enabled, the SOAP headers are stripped before this transform is called.

>
>

isRelativeUrl	`true` false=	yes	`false`	If `true, the URL indicated above is a relative URL and will be combined with =baseUrl` above. If `false`, then the above URL is a fully qualified URL.
stripSoapEnvelope	`true` false=	yes	`true`	WCF processes all messages as SOAP calls. The hook has code to strip out SOAP headers if this attribute is set to `true. When set to =false`, the message is passed to the command as-is.
transform	$XSLT	yes	N/A	A valid XSLT transform definition to apply to the message sent to the command. Note: If `stripSoapEnvelope` is enabled, the SOAP headers are stripped before this transform is called.

The URL called by the command hook should expect incoming message data as part of the HTTP request body and should return data via the HTTP response body.

For hooks with actionType = Before, the input message format is as follows:

Changed:

<
<

>
>

cPanel.Web Information: 0 : [ ] 2011-06-07 17:43:06Z [INFO : ] - Test - LogMessage - http://10.1.15.102:2086/logger/logmessage.aspx?action=Before&message=http://www.cpanel.net/schemas/2008/03/IServerAdministratorService/AmIAlive cPanel.Web Information: 0 : [ ] 2011-06-07 17:43:06Z [INFO : ] - Test - LogMessage - Message ID: dd26771a-63f1-4e3c-bd89-0ab38310c21a

Line: 299 to 213

Request:

Changed:

<
<

>
>

For hooks with actionType = After, the input message format is as follows:

Changed:

<
<

>
>

cPanel.Web Information: 0 : [ ] 2011-06-07 17:43:06Z [INFO : ] - Test - LogMessage - http://10.1.15.102:2086/logger/logmessage.aspx?stage=After&message=http://www.cpanel.net/schemas/2008/03/IServerAdministratorService/AmIAlive cPanel.Web Information: 0 : [ ] 2011-06-07 17:43:06Z [INFO : ] - Test - LogMessage - Message ID: b2cf36ce-8e6c-4b71-981a-f4faeed51f52

Line: 318 to 229

true

Changed:

<
<

>
>

The URL hook should return one of the following HTTP status codes. You may use some of these codes to modify the message's processing cycle.

Deleted:

<
<

HTTP Status	Code	Cancels Operation
Ok	200	No
Created	201	No

Line: 330 to 239

Unauthorized	402	Yes*
Forbidden	403	Yes*

Changed:

<
< Note: Canceling only occurs if the hook took place before the API function was called.

>
> Note: Canceling only occurs if the hook took place before the API function was called.

Hook configuration samples

The following is an example of HookConfiguration.config:

Line: 355 to 263

Changed:

<
<

>
>

The following is an example of CommandHookConfiguration.config:

Changed:

<
<

>
>

Line: 381 to 285

Changed:

<
<

>
>

The following zip files are examples for TestCommand and CommandHook:

Deleted:

<
<

Changed:

<
<

>
>

The following is an example of UrlHookConfiguration.config:

Changed:

<
<

>
>

Line: 415 to 313

Changed:

<
<

>
>

The following zip file is an example of a test page for UrlHook:

Deleted:

<
<

Logger.zip

To make the logger above record information to your SAI log file, you must change system.diagnostics in your SAI web.config to:

Line: 426 to 321

To make the logger above record information to your SAI log file, you must change system.diagnostics in your SAI web.config to:

Changed:

<
<

>
>

Extending hooks

The command and URL hooks classes were designed to allow developers to extend functionality to support the integration scenario beyond our current implementation. There are many extension points in both of these classes.

Line: 436 to 329

The command hook contains three main groups of classes:

Changed:

<
< The CommandHook class summary

>
> The CommandHook class summary

The first class is the CommandHook class, which is derived from the hook class:

Changed:

<
< The CommandHook class

>
> The CommandHook class

The command hook, as described above, provides a way to map a message received by the WCF API to an external, executable command. Out of the box, this class comes with fairly limited command and argument formatting. However, the FormatCommand() and FormatArguments() methods are virtual methods. This means that if the services provided by the class are inadequate, you can create your own CommandHook-derived class as seen below.

Line: 445 to 338

Additionally, if you do not like the current way the command hook writes messages to the input stream or processes the command response, you can override WriteMessage() or ProcessCommandResponse(). A sample custom implementation is shown below:

Deleted:

<
<

Changed:

<
<

%CODE{lang="C"}% using System; using System.Collections.Generic; using System.Linq; using System.Text; using cPanel.Core.Hooks;

namespace Sample { public class CustomCommandHook : CommandHook { protected override string FormatCommand(string command, HookExtension call, Stage stage, CommandHookMessage config) { // Do what you want here to create the command call string return base.FormatCommand(command, call, stage, config); }

protected override string FormatArguments(string arguments, HookExtension call, Stage stage, CommandHookMessage config) { // Do what you want here to create the command arguments string return base.FormatArguments(arguments, call, stage, config); } } }

>
>

%CODE{lang="C"}% using System; using System.Collections.Generic; using System.Linq; using System.Text; using cPanel.Core.Hooks;

%ENDCODE%

Line: 481 to 353

%CODE{lang="C"}%

Changed:

<
<

public class CustomCommandHookBehavior : HookBehaviour { }

public class CustomCOmmandHookBehaviorAttribute : HookOperationBehaviorAttribute { }

>
>

public class CustomCommandHookBehavior : HookBehaviour { }

public class CustomCOmmandHookBehaviorAttribute : HookOperationBehaviorAttribute { }

%ENDCODE%

Line: 493 to 361

With these three classes, you have a complete extension solution for the command hook. You can now add your custom hooks to your $cPanelApplicationPath$\Common\Hooks\HookConfiguration.config file, as you did with the hooks that we provided.

Deleted:

<
<

Changed:

<
<

<-- SyntaxHighlightingPlugin -->

<add name="CustomCommandHooks" type="Sample.UrlHookBehaviour, Sample" externalConfigurationPath="\\10.1.15.101\e\ApplicationPath\Common\Hooks\CommandHookConfiguration.config" />

<-- end SyntaxHighlightingPlugin -->

>
>

<-- SyntaxHighlightingPlugin -->

<add name="CustomCommandHooks" type="Sample.UrlHookBehaviour, Sample" externalConfigurationPath="\\10.1.15.101\e\ApplicationPath\Common\Hooks\CommandHookConfiguration.config" />

<-- end SyntaxHighlightingPlugin -->

META FILEATTACHMENT	attachment="CommandHook.class.png" attr="h" comment="" date="1308180164" name="CommandHook.class.png" path="CommandHook.class.png" size="11293" stream="CommandHook.class.png" tmpFilename="/var/tmp/CGItemp26009" user="JustinSchaefer" version="1"
META FILEATTACHMENT	attachment="CommandHook.Summary.png" attr="h" comment="" date="1308180177" name="CommandHook.Summary.png" path="CommandHook.Summary.png" size="72983" stream="CommandHook.Summary.png" tmpFilename="/var/tmp/CGItemp26031" user="JustinSchaefer" version="1"

View topic | History: r7 < r6 < r5 < r4 | More topic actions...