Calling all developers! We invite you to provide your input on Feature Experimentation by completing this brief survey.

 

AI OnAI Off

Creating Analyzers with Basic Functionality

Product version:

EPiServer CMS 4.62

Document version:

1.0

Document creation date:

07-06-2006

Document last saved:

04-10-2007

Purpose

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

The contents of this document are directly taken from the EPiServer CMS SDK. Please see the SDK for further technical information about EPiServer CMS.

Table of Contents

Introduction

Programming
    - Analyzer
    - Present the Analyzer in a View

Configuration
    - Adding an Analyzer

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.Services2 – is part of Microsoft Web Service Extensions 2.0, which can be downloaded from the Microsoft Web site.
  • log4net.dll – in the file log4net.dll located in the /bin folder in the 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. (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 ChannelEventArgs to EPiServerMessage 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 a EPiServerMessage

     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 EPiServerMessage Class

The EPiServerMessage 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 value of an analyzer, you must create a view for it. The view must have a connection to the analyzer; this connection is defined in 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.Services2.Messaging.SoapActor("soap.tcp://localhost/SimpleAnalyzerView")]

    public class SimpleAnalyzerView :

        Microsoft.Web.Services2.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 Service Extension library (Microsoft.Web.Services2.dll) and add the Web service attributes to the class and methods you want to publish.

Example:

[Microsoft.Web.Services2.Messaging.SoapActor("soap.tcp://localhost/SimpleAnalyzerView")]

public class MyAnalyzerView : SoapService, IAnalyzerView

{

.

.

.

[Microsoft.Web.Services2.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 Service Extension, normally located in the folder C:\Program Files\Microsoft WSE, called WseWsdl2.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 start 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%\v2.0\Tools\Wsdl\WseWsdl2.exe" soap.tcp://localhost/SimpleAnalyzerView  -name soap.tcp://localhost/SimpleAnalyzerView SimpleAnalyzerViewClient.cs

Using the Proxy with a Web Application

Include the generated class above to access the proxy direct.

Example:

private void Page_Load(object sender, System.EventArgs e)

{

    SimpleAnalyzerView analyzer = new SimpleAnalyzerView();

    Response.Write( analyzer.TestMethod() );

.

.

.

The analyzers are added as channels in the episerver.baseLibrary session in the configuration for the Log Service (EPiServer.Log.Service.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 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>