How to create an extractor

An IExtractor is a class whose role is to transfer data coming from a data source (database, LDAP directory, file system, web service, etc.) to the engine's XML stream.

Create the classes

Create a class implementing IExtractor.
Create an IExtractorFactory
This class must inherit from System.Configuration.ConfigurationSection so that it can be declared in the configuration file, and implement the IExtractorFactory interface by returning an instance of the class created at the first step.
If the extractor class is thread independent, you can use the singleton pattern and have only one instance of the extractor class.
For more information about creating a custom ConfigurationSection, you can read this MSDN how-to: creating a custom ConfigurationSection

Extract XML data

The XML stream is exposed as a XmlWriter member of the Config object passed in parameters: OutputDocument.
Extractors are meant to be independent from one another; thus, you must close all your tags before returning to give back the XML stream in the same state you got it.
If this rule is enforced by all extractors, when your Extract method is called, the XmlWriter is positioned directly under the BODY tag (see XML format).
The built-in extractors create tags in upper case and without namespace; this is not mandatory, but you must know that tag names are case sensitive in XML.
You must NOT call the Close, WriteEndDocument, WriteProcessingInstruction, WriteStartDocument methods on the XmlWriter.
The Config object passed as parameter contains the request's parameters, an access to the database and the request context.
Usually, to render HTML pages, only one handler is defined and the StandardExtractorFactory uses the RUBRIQUEID parameter to distinguish between template pages; we advise to use the same behavior, though it is not mandatory.

Use your extractor

Declare a section in the configSections part of the configuration file with your class name and assembly

Copy

<configuration>
  <configSections>
    <section name="myextractor" type="MyNamespace.MyExtractorFactory,MyAssembly"/>
  </configSection>
</configuration>

Use this section name in your handlers extractors list

Copy

<activsoft.engine>
  <handlers>
    <handler name="myhandler" path="myhandler.ashx" defaultTemplate="1">
      ...
      <extractors>
        <extractor section="myextractor"/>
      </extractors>
      ...
    </handler>
  </handlers>
  <loader section=""/>
</activsoft.engine>

Example

This is a simple Hello World extractor with a configuration property.

Extractor

Copy

using Activsoft.Engine;
namespace MyNamespace {
  public class MyExtractor : IExtractor {
    private string myProperty;
    public MyExtractor(string myProperty) {
      this.myProperty = myProperty;
    }
    public void Extract(Config monConfig) {
      monConfig.WriteElementString("HELLO","Hello " + myProperty);
    }
  }
}

Factory

Copy

using Activsoft.Engine;
using System.Configuration;
namespace MyNamespace {
  public class MyExtractorFactory : ConfigurationSection, IExtractorFactory {
    public IExtractor CreateExtractor(Config monConfig) {
      return new MyExtractor(MyProperty);
    }
    [ConfigurationProperty("myProperty", DefaultValue = "foobar")]
    public string MyProperty {
      get {
        return (string) base["myProperty"];
      }
    }
  }
}

Configuration file

Copy

<configuration>
  <configSections>
    <section name="myextractor" type="MyNamespace.MyExtractorFactory,MyAssembly"/>
    <section name="activsoft.engine" type="Activsoft.Engine.EngineSection,Activsoft.Engine"/>
    <section name="secureFactory" type="Activsoft.Engine.Web.SecureDatabaseCookieSessionManagerFactory,Activsoft.Engine.Web"/>
    <section name="xslfilter" type="Activsoft.Engine.XslFilter.XslFilterSection,Activsoft.Engine"/>
    <section name="dashboardRenderer" type="Activsoft.Dashboard.DashboardRendererFactory,Activsoft.Dashboard"/>
    <section name="webLoader" type="Activsoft.Engine.Web.WebConfigLoaderConfigurationSection,Activsoft.Engine.Web"/>
  </configSection>
  <myextractor myProperty="world"/>
  <secureFactory cookieName="mycookie" /> 
  <dashboardRenderer/>
  <activsoft.engine>
    <handlers>
      <handler name="myhandler" path="myhandler.ashx" defaultTemplate="1">
        <actions>
        </actions>
        <extractors>
          <extractor section="myextractor"/>
        </extractors>
        <renderers>
          <renderer section="dashboardRenderer"/>
        </renderers>
        <enginemodule>
          <session section="secureFactory"/>
          <params cookie="mycookie" xslpath="..\xsl"/>
          <database section="db"/>
        </enginemodule>
        <transformgenerator section="xslfilter"/>
      </handler>
    </handlers>
    <loader section="webLoader"/>
  </activsoft.engine>
  <xslfilter>
    <filters>
      <add type="Activsoft.Dashboard.XslFilter,Activsoft.Dashboard">
        <javascript outputDir="..\xsljs"/>
      </add> 
    </filters>
  </xslfilter> 
</configuration>

Result

Copy

<BODY>
  <HELLO>Hello world</HELLO>
</BODY>