//Only works in an handler that handles the OnBeforeDocumentSave event
public class MyBeforeDocumentSaveHandler : BeforeDocumentSaveSyncHandler
{
  protected override void DoWork()
  {
     if (DocumentType == DocumentTypes.EPT_Document)
     {
        EptContent["DisplayName"] =
             String.Format("{0} {1}", EptContent["FirstName"], EptContent["LastName"]);
     }         
  } 
}

'Only works in an handler that handles the OnBeforeDocumentSave event
Public class MyBeforeDocumentSaveHandler : BeforeDocumentSaveSyncHandler

  Protected Overrides Sub DoWork()
    If DocumentType = DocumentTypes.EPT_Document Then
        EptContent("DisplayName") = _
            String.Format("{0} {1}", EptContent("FirstName"), EptContent("LastName"))
    End If         
  End Sub
  
End Class

'Only works in an handler that handles the OnBeforeDocumentSave event
Public Class MyBeforeDocumentSaveHandler : BeforeDocumentSaveSyncHandler
   Protected Overrides Sub DoWork()
     'Do not forget to check for Nothing!
     If Not SaveOperationArguments Is Nothing Then
        SaveOperationArguments.PublishDate = DateTime.Today.AddDays(1)
        SaveOperationArguments.Keywords = "Content Studio CMS"
     End If
   End Sub
End Class

protected override void Dispose(bool disposing) 
{
   if (disposing) 
   {
      // Release managed resources.
   }
   // Release unmanaged resources.
   // Set large fields to null.
   // Call Dispose on your base class.
   base.Dispose(disposing);
}

Protected Overloads Overrides Sub Dispose(disposing As Boolean) 
   If disposed = False Then
      If disposing Then 
        'Release managed resources.
      End If
   End If
   'Release unmanaged resources.
   'Set large fields to null.
   'Call Dispose on your base class.
   Mybase.Dispose(disposing)
End Sub

void EventHandler(string EventXMLArguments,
                  string CustomData,
                  object Content,
                  ICSCredentialsContainer Credentials,
                  ref bool Cancel,
                  out int Status,
                  out string StatusText)
    

Sub EventHandler(EventXMLArguments As String, _
                 CustomData As String, _
                 Content As Object, _
                 Credentials As ICSCredentialsContainer, _
                 ByRef Cancel As Boolean, _
                 <OutAttribute> ByRef Status As Integer, _
                 <OutAttribute> ByRef StatusText As String)
    

The EventHandler method of the ICSEventHandler2 interface used in Content Studio 5.3 or later has the following declaration:

void EventHandler(
	string eventXmlArguments,
	string customData,
	ICSContentContainer content,
	ICSCredentialsContainer credentials,
	ref bool cancel,
	out int status,
	out string statusText
)       
        

Sub EventHandler ( _
	eventXmlArguments As String, _
	customData As String, _
	content As ICSContentContainer, _
	credentials As ICSCredentialsContainer, _
	ByRef cancel As Boolean, _
	<OutAttribute> ByRef status As Integer, _
	<OutAttribute> ByRef statusText As String _
)
        

EventXMLArguments

String

An xml document sent to the implementer from Content Studio.

The exact content varies between different events. The sample is typical for a document event (ex. OnDocumentSave or OnDocumentApprove).
Xml

<event type="Integer value"
       event="String value"
       msgid="String value">
   <timestamp>Date value</timestamp>
   <connectionid>Integer value</connectionid>
   <callerinfo sid="String value" 
               logonname="String value" 
               email="String value" 
               fullname="String value" 
               userkey="String value" 
               sessionid="Integer value"/>
   <objectdata>
      <documentid>Integer value</documentid>
      <documentname>String value</documentname>
      <filename>String value</filename>
      <encoding>String value</encoding>
      <categoryid>Integer value</categoryid>
      <documenttitle>String value</documenttitle>
      <!-- In version 5.3, additional fields have been added -->
   </objectdata>
</event>
        

Event Xml explained

Element	Attribute	Description
event		This element acts as the root node of the document.
	type	The numeric identifier of the event.
	event	The name the event.
	msgid	A unique identifier of the specific event message.
timestamp		The date and time of when the event was raised.
connectionid		An identifier of the Web site
callerinfo		This element has attributes that contain data about the caller.
	sid	The caller's security identifier in the SDL format (ex. S-1-5-16).
	logonname	The caller's logon name in the DOMAIN\USERNAME format.
	email	The caller's email address, if registered in CS.
	fullname	The caller's fullname, if registered in CS.
	userkey	The caller's Content Studio userkey (ex. ABCD1).
	sessionid	The caller's session identifier.
objectdata		This element act as root node for elements that contains data about the affected document.
documentid		The identifier of the document
documentname		The logical file name of the affected document (ex. Unit1/Category1/pic1.gif).
filename		The file name of the affected document as it appears on disc.
encoding		The encoding (ex. utf-8), if existing, of the affected document.
categoryid		An identifier of the category where the affected document is placed.
documenttitle		The name of the affected document.

CustomData

String

User defined static data that has been specified for the Event action definition that triggered this event. The data is supplied via the Command text field in the Event actions property window.

Content (in ICSEventHandler) only.

System.Object

The document content as it exists in Content Studio when the event was raised. Not all events supply content.

Content (in ICSEventHandler2) only.

ContentStudio.EventActions.ICSContentContainer

This interface is used to supply the affected document content from Content Studio to the handler and back from the handler to Content Studio. In addition to this you can pass a collection of property names and values back to Content Studio from the event handler. Currently Content Studio only uses returned content and property values in the OnBeforeDocumentSave event.

Credentials

ContentStudio.EventActions.ICSCredentialsContainer

A reference to Content Studio's implementation of the ICSCredentialsContainer interface. This is used to pass system defined credentials to the custom implementation. The event handler can use these credentials when ex. communicating with an external system such as a database or a mail server. This parameter is null (Nothing in Visual Basic) if no credentials has been specified.

Cancel

Boolean

A reference to a Boolean parameter. Event handlers sets this parameter to true to indicate that all changes in the Content Studio event that triggered the event should be rolled back. If the value remains false after the call, the event in Content Studio will not be rolled back, regardless of the outcome of the operation performed by the event handler.

Status

Int32

Implementations should set this parameter to zero to indicate success. All other values will throw an error in the Content Studio event that triggered the event causing data to be rolled back. This parameter is passed uninitialized.

StatusText

String

Implementation sets this parameter to the textual representation of the error indicated in the Status parameter. This parameter is passed uninitialized.

All your logic will be implemented in this method and depending on what you like to do you might not need all of the parameters. However, since both the Status and the StatusText parameters are output parameters, you must provide a value for them. They will inform Content Studio about the outcome of the call - Status = 0 indicates success and any other value is an error. The Cancel parameter is important since it controls whether Content Studio should roll back every change been made in Content Studio. By setting Cancel to true the event handler informs Content Studio that a rollback should be performed.

A small sample is shown below - it is intended to run OnDocumentDelete and effectively prevents any document in the category where it is applied, to be deleted. For demostration purpose the code uses the CustomData parameter to provide a user defined message to the caller. In this particular sample we do not use any of the Xml data passed in via the EventXMLArguments parameter but with this data you can get some information about the document and the user that triggered the event.

Finally the event handler is ready to be compiled and tested.

A sample event handler

using System;
using ContentStudio.EventActions;

namespace SyncEventHandler
{
    public class OnDocumentDeleteHandler : ContentStudio.EventActions.ICSEventHandler2
    {
        void ICSEventHandler.EventHandler(string EventXMLArguments, 
                                          string CustomData, 
                                          ICSContentContainer Content, 
                                          ICSCredentialsContainer Credentials, 
                                          ref bool Cancel, 
                                          out int Status, 
                                          out string StatusText)
        {
            Status = -1;
            //Any custom message passed in?
            if((CustomData != null) || (CustomData.Length == 0))
                StatusText = CustomData;
            else
                StatusText = "Delete is forbidden in this category";
            Cancel = true;
        }
    }
}

Imports System
Imports ContentStudio.EventActions

Namespace SyncEventHandler
    Public Class OnDocumentDeleteHandler 
                 Implements ContentStudio.EventActions.ICSEventHandler2
        Private Sub EventHandler(EventXMLArguments As String, _ 
                                 CustomData As String, _
                                 Content As ICSContentContainer, _
                                 Credentials As ICSCredentialsContainer, _
                                 ByRef Cancel As Boolean, _
                                 <OutAttribute> ByRef Status As Integer, _
                                 <OutAttribute> ByRef StatusText As String) _
                    Implements ICSEventHandler.EventHandler
        
            Status = -1
            'Handle the case when CustomData is Nothing
            If CustomData Is Nothing Then 
                CustomData = String.Empty
            End If
            'Any custom message passed in?
            If CustomData.Length = 0 Then
               StatusText = "Delete is forbidden in this category"
            Else
                StatusText = CustomData
            End If
            Cancel = True
        End Sub
    End Class
End Namespace

Installing the event handler

Compile the code as a class library (.dll file). In Visual Studio this is done automatically for you and outside Visual Studio you can use one of the compilers that is a part of the freely .NET Framework SDK. For more information about the command line compilers see the .NET Framework SDK documentation. You can name your .dll SyncEventHandler.dll, the name of the file is normally also the Assembly name and the assembly name is important when you use the event handler from Content Studio later.
NOTE
You must use at least version 2.0 of the .NET Framework SDK or Visual Studio 2005 or later to be able to build the event handler.

Now, locate the installation directory of the Content Studio Server service (CS5ServiceHost.exe) that normally gets installed in the C:\Program files\Teknikhuset\Content Studio 5\CSServer folder. Copy the dll into this directory and you are ready to go!

Use the event handler

When you have properly installed your event handler in Content Studio it is time to test it.
Select a category where you would like the event handler to be used. Be default only members of the administrators group has permissions to manage event handlers in Content Studio. This permission can be delegated on the site root level or on a single category but event actions permissions are not inherited to child categories.
On the category of choise, create a new Event handler. This will bring up the "Properties for Event actions" dialog.

• Name your event handler Prohibit document delete
• Select the OnDocumentDelete event
• Set the type to Synchronous Event handler object

The User data button opens up the User Credentials dialog that makes it possible to provide credentials that the event handler receives through the ICSCredentials interface but in this case there is no need for this functionality. Credentials, however, can be useful if you need to communicate with an external system and could contain login credentials for that system.

The ProgID field specifies the programmatic name of your event handler and can be written in serveral ways where the simplest form is

The complete format looks like:

Examples

The first example is as simple as it gets where only the full name and the assembly name are given. The assembly name is normally the same as the name of the dll file minus the .dll extension.

SyncEventHandler.OnDocumentDelete, SyncEventHandler

The second example is more specific an specifies that the event handler has been given a strong name and we also needs a specific version of the assembly to be loaded with a specific culture. This advanced type info is needed when your event handler assembly has been registered in the global assembly cache (GAC).

SyncEventHandler.OnDocumentDelete, SyncEventHandler, Culture=neutral, Version=1.0.0.0, PublicKeyToken=feea6d462bd740da

Finally, if everything is OK so far Content Studio will throw an error message when you delete any document located in the category in question.

Debugging the event handler

In order to be able to debug your event handler from Visual Studio you must have Content Studio installed locally on your machine and the services Content Studio server and Content Studio Service Manager must be running.

• Change the output directory of your event handler's assembly to the same directory where the Content Studio services are installed. ex. C:\Program Files\Teknikhuset\Content Studio 5\CSServer, look for the file CS5ServiceHost.exe
• Rebuild your project, with debugging information, at the new location.
• Start the debugging session from Visual Studio by clicking the Debug - Attach to Process... menu alternative. A new dialog shows up and from that dialog you select the CS5ServiceHost.exe process and press the Attach button.
• You now can set breakpoints in your code and the breakpoints should be hit whenever Content Studio raises a event that is set up to be handled by your event handler.

See Also

Creating an asynchronous event handler.