The ZPT-Sharp configuration file

 

NAME

ZptSharp.config - configuration file for ZPT-Sharp  

SYNOPSIS

The filename applicable to the configuration file depends upon your use-case:

ZptBuilder.exe.config

Web.config

[YourApplication].config

 

DESCRIPTION

The ZPT-Sharp configuration file is primarily used for indicating which ZPT-Sharp plugins are installed. The listed plugins are loaded at run-time by the core logic and used for rendering documents.

Other uses of the configuration file depend upon your installation scenario and requirements. If the CSharp expressions plugin is installed then the configuration file controls application-wide settings related to assembly references and namespace imports. Additionally, the configuration may be used in order to configure the capture and recording of diagnostic/logging information from ZPT-Sharp.

The filename for the configuration file depends upon the use-case. When using the ZptBuilder.exe application, the configuration file must be named ZptBuilder.exe.config. When using the ASP.NET MVC ViewEngine, the content documented here must be integrated into your web application's Web.config file. When using ZPT-Sharp as an API, the applicable content must be integrated into your own application's configuration file.

This file is written using the .NET XML configuration file format. Full coverage of this format is beyond the scope of this manual; refer to the appropriate .NET framework documentation where applicable.  

INSTALLING PLUGINS

The mandatory part of the configuration file is the section which installs plugins - document providers and expression evaluators. At a minimum for any useful operation, at least one document provider and one expression evaluator plugin must be installed. One expression evaluator must be nominated as the default plugin; this default evaluator is used for expressions which are not qualified with an expression prefix. In order to comply with the TALES specification, you should choose CSF.Zpt.ExpressionEvaluators.PathExpressions.PathExpressionEvaluator as the default expression evaluator. This will make path: the default expression type, where no prefix is given. You should also nominate the default HTML and XML document provider plugins. These default providers are used when a ZPT document is to be created, a provider type has not been explicitly specified, but it is known whether it is either HTML or XML formatted.

The following example shows the relevant content to install four expression evaluator plugins, two document provider plugins, and nominate the defaults accordingly.

<configuration>
  <configSections>
    <sectionGroup name="CSF">
      <sectionGroup name="Zpt">
          <section name="PluginConfigurationSection"
                   type="CSF.Zpt.PluginConfigurationSection, CSF.Zpt" />
      </sectionGroup>
    </sectionGroup>
  </configSections>

  <CSF>
    <Zpt>
      <PluginConfigurationSection DefaultHtmlDocumentProvider="CSF.Zpt.DocumentProviders.HtmlZptDocumentProvider"
                                  DefaultXmlDocumentProvider="CSF.Zpt.DocumentProviders.XmlLinqZptDocumentProvider"
                                  DefaultExpressionEvaluator="CSF.Zpt.ExpressionEvaluators.PathExpressions.PathExpressionEvaluator">
        <PluginAssemblies>
          <Assembly Path="CSF.Zpt.DocumentProviders.HtmlHAP" />
          <Assembly Path="CSF.Zpt.DocumentProviders.XmlLinq" />
          <Assembly Path="CSF.Zpt.ExpressionEvaluators.CSharpExpressions" />
          <Assembly Path="CSF.Zpt.ExpressionEvaluators.PathExpressions" />
          <Assembly Path="CSF.Zpt.ExpressionEvaluators.StringExpressions" />
          <Assembly Path="CSF.Zpt.ExpressionEvaluators.NotExpressions" />
        </PluginAssemblies>
      </PluginConfigurationSection>
    </Zpt>
  </CSF>
</configuration>

Each <Assembly> element indicates the name of a single .NET assembly which contains one or more plugins. The assembly must be located in the application's "private bin" directory, which is typically the same directory which contains the CSF.Zpt.dll assembly. The assembly name is the result which would be obtained by interrogating Assembly.FullName for that assembly. Typically though, this will be the same as the assembly's filename, without the .dll extension. The default expression evaluator, XML document provider and HTML document provider are indicated by listing their namespace-qualified type names in the appropriate configuration attributes.  

CONFIGURING CSHARP EXPRESSIONS

If the plugin CSF.Zpt.ExpressionEvaluators.CSharpExpressions.dll is installed, then CSharp expressions are available. There are two settings affecting CSharp expressions which may be specified in the configuration file. These are the default assemblies which will be referenced by compiled expressions and also the namespaces which will be imported into those expressions. The settings made in the configuration file will affect all CSharp expressions evaluated by the application. Effectively, the configuration specifies the baseline assembly references and namespace imports. Further assemblies/namespaces may be chosen via expressions in ZPT documents.

The default configuration (which is also used if the configuration section below is not present) is as follows:

The assembly System will be referenced

The namespaces System and System.Linq will be imported (without aliases)

For more information please consult the documentation for writing CSharp expressions. These two configuration options are roughly equivalent to the expression types csassembly and csnamespace. Each permits as many or as few entries as desired; repeat the Assembly or Namespace XML element for each item you wish to specify.

<configuration>
  <configSections>
    <sectionGroup name="CSF">
      <sectionGroup name="Zpt">
          <sectionGroup name="ExpressionEvaluators">
            <sectionGroup name="CSharpExpressions">
              <section name="ExpressionConfigurationSection"
                       type="CSF.Zpt.ExpressionEvaluators.CSharpExpressions.ExpressionConfigurationSection, CSF.Zpt.ExpressionEvaluators.CSharpExpressions" />
            </sectionGroup>
          </sectionGroup>
      </sectionGroup>
    </sectionGroup>
  </configSections>

  <CSF>
    <Zpt>
      <ExpressionEvaluators>
        <CSharpExpressions>
          <ExpressionConfigurationSection>
            <Assemblies>
              <Assembly Name="NAME" />
            </Assemblies>
            <Namespaces>
              <Namespace Name="NAMESPACE" Alias="ALIAS" />
            </Namespaces>
          </ExpressionConfigurationSection>
        </CSharpExpressions>
      </ExpressionEvaluators>
    </Zpt>
  </CSF>
</configuration>

Within the assembly references, the NAME placeholder refers to the full name of a referenced assembly. The assembly full-name is the result which would be obtained by interrogating Assembly.FullName for that assembly. For assemblies which are not installed in the Global Assembly Cache, the assembly must also be deployed into the application's "private bin" directory. The private bin directory is typically the same directory which contains the CSF.Zpt.dll assembly. It is often possible to use short-names (without the Version, Culture and PublicKeyToken information) for assemblies which are in the private bin directory. On the other hand, full names must be used for assemblies which are installed elsewhere (such as the GAC).

For namespace imports, the NAMESPACE placeholder is the name of the namespace (for example System.Linq). The Alias attribute is optional; when it is provided, the imported namespace will be assigned to the named alias. The code generated looks something like the following examples:

// Without an alias: <Namespace Name="My.Namespace" />
using My.Namespace;

// With an alias: <Namespace Name="My.Other.Namespace" Alias="other" />
using other = My.Other.Namespace;

 

CONFIGURING DIAGNOSTICS

ZPT-Sharp makes use of the .NET System.Diagnostics functionality to make diagnostic and logging information available, configured via the configuration file. This .NET functionality provides a highly rich and configurable API, an in-depth examination of which is well beyond the scope of this documentation. Refer to the appropriate .NET framework documentation for more information.

For reference, the TraceSource names used by ZPT-Sharp are as follows:

CSF.Zpt

CSF.Zpt.Cli

CSF.Zpt.Mvc

The following example configuration content illustrates a minimal logging set-up which will record messages to a file.

<configuration>
  <system.diagnostics>
    <sources>
      <source name="CSF.Zpt" switchName="defaultSwitch" switchType="System.Diagnostics.SourceSwitch">
        <listeners>
          <add name="myListener" 
               type="System.Diagnostics.TextWriterTraceListener" 
               initializeData="ZptSharp.log" />
          <remove name="Default" />
        </listeners>
      </source>
    </sources>
    <switches>
      <add name="defaultSwitch" value="Verbose"/>
    </switches>
  </system.diagnostics>
</configuration>

 

SEE ALSO

ZptBuilder.exe (1)

Documentation for the ZptBuilder application, which makes use of this configuration

Framework documentation for .NET XML configuration files

Describes the overall layout and syntax of this configuration file format. XML configuration files have a great deal of other functionality available, beyond that which is described here.

Framework documentation for the .NET System.Diagnostics namespace

Describes how to set-up and configure TraceListener instances. Listeners subscribe to the TraceSource instances exposed by the application code.