AI OnAI Off

Creating Analyzers with Basic Functionality 

Product version:

EPiServer CMS 5 SP2

Document version:

1.0

Document last saved:

16-04-2008

Introduction

An analyzer is a component that handles log messages and is responsible for collecting messages, storing statistics and presenting the results. This article presents an overview of Analyzers and their implementation.

Table of Contents

Introduction

The analyzers are the components for handling the log messages and are responsible for:

  • collecting messages
  • storing statistics
  • showing the results

An analyzer has two parts:

  1. the model that is responsible for collecting messages and storing the relevant statistics for this analyzer
  2. the view that is responsible for presenting the data

To simplify the creation of analyzers, basic functionality is located in the class AnalyzerBase and an interface for the view IAnalyzerView. (It is possible to develop analyzers that do not inherit from AnalyzerBase).

Programming

To develop this analyzer sample, create a Class Library in Visual Studio and add the following references.

  • EPiServer.Log.Core – in the file EPiServer.Log.Core.dll located in the installation folder for the Log Service.
  • EPiServer.BaseLibrary – in the file EPiServer.BaseLibrary.dll located in the installation folder for the Log Service.
  • Microsoft.Web.Services3 – is part of Microsoft Web Service Extensions 2.0, which can be downloaded from the Microsoft Web site at the following address: http://www.microsoft.com/downloads/details.aspx?FamilyID=018a09fd-3a74-43c5-8ec1-8d789091255d. After the MSI file has been installed, Microsoft.Web.Services3 will be found under the .NET tab in Add Reference.
  • log4net.dll – in the file log4net.dll located in the /bin folder in the EPiServer Web root.
  • System.Web – a standard library in the .NET framework.

Note that the following must also be carried out:

  • Add an analyzer class to the project. (See the "Analyzer" chapter.)
  • If you want to publish the information with a view, add a view class to the project. (See the "Present the Analyzer in a View" chapter.)

Analyzer

The Analyzer Class

The analyzer has to be thread-safe and handled as a singleton. In this example the base functionality in AnalyzerBase is used, so the analyzer created must inherit from this class. (It is possible to develop analyzers that do not inherit from AnalyzerBase).

Example:

namespace development.Log.SimpleAnalyzer
{
    public class SimpleAnalyzer : EPiServer.Log.Core.AnalyzerBase
    {

Storing Messages

The analyzer must have one method to receive the messages with, which must be declared as:

public void <method name>( 
     Object sender, 
     EPiServer.BaseLibrary.Channel.ChannelEventArgs e)

ChannelEventArgs is the message that is sent, so the first thing that the analyzer should do is to determine that this message should be handled by this analyzer. A simple way to do this is to cast the Item property in ChannelEventArgs to EPiServer.Log.Core.Message and look at it.

Example:
public Int32 Count;
public void StoreMessage( 
     Object sender, 
     EPiServer.BaseLibrary.Channel.ChannelEventArgs e)
{
    EPiServer.Log.Core.IMessage msg = e.Item as EPiServer.Log.Core.Message;
    if (msg == null || !msg.Msg.StartsWith(EPiServer.Log.Core.PageMessage.Id))
    {
        return; // Do not do anything if the message is not an EPiServer.Log.Core.Message
    }
    Count++;
    // To ensure that no overflow exception is thrown 
    if (Count > (Int32)Config["EPnMaxCount"])
    {
        Count = 0;
        Log.Warn("Simple analyzer has reached the maximum count - resetting the counter");
    }
}

The EPiServer.Log.Core.Message Class

The EPiServer.Log.Core.Message class is the message holder and contains the following properties:

  • Time – The time that the message was created.
  • SiteId – A site identification (by default, EPiServerUdpAppender uses EPsSiteName).
  • Msg – The message.

Initialize

If extra initialization is to be handled by the analyzer, the Intialize method can be stored in AnalyzerBase. The Initialize method is called when the analyzer is loaded. If you want to use the functionality in the AnalyzerBase class, you must call this method first.

Example:

public override void Initialize(XmlNode node)
{
    // The base has to be initialized so the Config will work
    base.Initialize(node);
    // TODO: Put your initialize code here
}

Present the Analyzer in a View

If you want to present the result of an analyzer, you must create a view for it. The view must have a connection to the analyzer; this connection is defined by IAnalyzerView.

Connection to the Analyzer

If IAnalyzerView is implemented, a connection to the analyzer is set up automatically.

Example:

namespace development.Log.SimpleAnalyzer
{
    [Microsoft.Web.Services3.Messaging.SoapActor("soap.tcp://localhost/SimpleAnalyzerView")]
    public class SimpleAnalyzerView :
        Microsoft.Web.Services3.Messaging.SoapService,
        EPiServer.Log.Core.IAnalyzerView
    {
        private static EPiServer.Log.Core.AnalyzerBase _analyzer;
        public EPiServer.Log.Core.AnalyzerBase Analyzer
        {
            get { return _analyzer; }
            set { _analyzer = value; }
        }
    }
}

Presentation with TCP/SOAP

The base classes and the examples are set up to communicate with TCP/SOAP, which is a protocol that is easy to develop Web pages with and does not require any external application to work.

To use TCP/SOAP you must add a reference to the Web Services Enhancements library (Microsoft.Web.Services3.dll) and add the Web service attributes to the class and methods you want to publish.

Example:

[Microsoft.Web.Services3.Messaging.SoapActor("soap.tcp://localhost/SimpleAnalyzerView")]
public class MyAnalyzerView : SoapService, IAnalyzerView
{
.
.
.
    [Microsoft.Web.Services3.Messaging.SoapMethod("soap.tcp://localhost/MyAnalyzerView/TestMethod")]
    public Int32 TestMethod() 
    {
        return ((SimpleAnalyzer)Analyzer).Count;
    }
}

Generate a Proxy to Connect to the SOAP Service

To generate the proxies for the SOAP service, there is a tool included in the Web Services Enhancements, normally located in the folder C:\Program Files\Microsoft WSE\v3.0\Tools, called WseWsdl3.exe.

How to create a proxy:

  1. Add configuration so that the analyzer is loaded (see the "Configuration" chapter).
  2. Copy the developed analyzer to the LogService folder.
  3. Start/Restart the Log Service (see Starting the Log Service in Debug Mode). The log message
    "11.9.1 Listening for messages at soap.tcp://localhost/SimpleAnalyzerView for development.Log.Analyzer.SimpleAnalyzerView"
    should be present if the Log Service is started in debug mode.
  4. Create a proxy for the Web service by entering the following on the command line:
    set PATH_TO_WSE=C:\Program Files\Microsoft WSE
    "%PATH_TO_WSE%\v3.0\Tools\WseWsdl3.exe" soap.tcp://localhost/SimpleAnalyzerView /out:SimpleAnalyzerViewClient.cs

Using the Proxy with a Web Application

Include the generated class above for access to the proxy.

Example:

private void Page_Load(object sender, System.EventArgs e)
{
    SimpleAnalyzerView analyzer = new SimpleAnalyzerView();
    Response.Write(analyzer.TestMethod());
.
.
.
}

Configuration

Adding an Analyzer

The analyzers are added as channels in the episerver.baseLibrary session in the configuration for the Log Service (EPiServer.LogService.exe.config).

To add a new analyzer, you must add a new sendListener to the channels. To add a view to that analyzer, the view element is added to the node. Additional configuration is also stored under this node.

Example:

<configuration>
  <configSections>
    <section name="episerver.baseLibrary" …
  </configSections>
  <episerver.baseLibrary>
...
...
...
    <channels>
      <add type="EPiServer.Implementation.SynchronousChannel,…
        <sendListener type="[full class name], [assembly]" method="[method]">
          <view 
             type="[full class name], [assembly]" 
             protocol="[protocol]"
             endpoint="[endpoint]"/>
          [extra initializing variables] 
        </sendListener>
...
...
...

Where

  • [full class name] is the full name to the class, e.g. development.MyClass.
  • [assembly] is the name of the assembly that the class belongs to.
  • [method] is the name of the method that is used to collect messages if a view is specified.
  • [protocol] is the protocol used. Currently, the only implemented protocol is "TCP/SOAP". If this attribute is not given, the SOAP listener in AnalyzerBase is not started automatically.
  • [endpoint] is the endpoint for the SOAP service. If this is not set, the endpoint will be "soap.tcp://localhost/[type.Name]"

The method to receive messages with must be declared as a channel.

Example:

<sendListener 
    type="development.Log.SimpleAnalyzer.SimpleAnalyzer, development.Log.SimpleAnalyzer"
    method="StoreMessage">
    <view 
        type="development.Log.SimpleAnalyzer.SimpleAnalyzerView, development.Log.SimpleAnalyzer"
        protocol="TCP/SOAP" 
        endpoint="soap.tcp://localhost/SimpleAnalyzerView"/>
    <EPnMaxCount>1000</EPnMaxCount>
</sendListener> 

Starting the Log Service in Debug Mode

The Log Service can be started in debug mode by running it from the command line with the "debug" argument

Open a command prompt, navigate to C:\Program Files\EPiServer.LogService5\ and type:

EPiServer.LogService.exe debug

The log service will start and debug messages will be displayed in the console window.