How To Implement A Generic Template Engine For SharePoint 2010 Using DotLiquid

*** NEW! My blog moved to my homepage at http://www.parago.de! ***

During the process of creating a complex SharePoint application you often need to send mails and create text files based on SharePoint data elements like SPListItem or SPWeb. Mail templates for instance mostly contain specific list item data. It would be helpful sometimes if the text generation itself is template-driven.

This article shows how to implement a generic template manager based on the free DotLiquid templating system with SharePoint specific extensions. This allows you for example to iterate through all SharePoint lists available within a SiteCollection and render only details for lists which contain Task in their title:

<p>All task lists for the current web '{{SP.Web.Title}}' and site '{{SP.Site.Url}}'
  <ul>
    {% for list in SP.Lists %}
      {% if list.Title contains 'Task' %} 
        <li><i>{{list.Title}}</i> with ID '{{Slist.ID|upcase}}' (<i>(Created: 
                                                     {{list.Created|sp_format_date}})</i></li>
      {% endif %}
    {% endfor %}
  </ul>
</p>
<p>All lists for current web '{{SP.Site.RootWeb.Title}}' created by the 'splists' tag
  <ul>{% splists '<li>{0}</li>' %}</ul>
</p>

The screenshot below shows the result of the rendered template sample:

TemplateEngine

Of course the technique implemented in this article can also be used in conjunction with other technologies or applications, it’s not only SharePoint related.

DotLiquid Template Engine

The DotLiquid template engine is a C# port of the Ruby’s Liquid templating system and is available for .NET 3.5 and above. DotLiquid is open source and can be downloaded at dotliquidmarkup.org. The software is also available as NuGet package for Visual Studio.

The templating system includes features like variable, text replacement, conditional evaluation and loop statements that are similar to common programming languages. The language elements consists of tags and filter constructs.

The engine can also be easily extended by implementing and adding custom filters and/or tags. This article actually shows how to extend the DotLiquid and implement SharePoint specific parts.

The following sample shows a Liquid template file:

<p>{{ user.name | upcase }} has to do:</p>

<ul>
{% for item in user.tasks -%}
  <li>{{ item.name }}</li>
{% endfor -%}
</ul>

Output markup is surrounded by curly brackets {{…}} and tag markup by {%…%}. Output markup can take filter definitions like upcase. Filters are simple static methods, where the first parameter is always the output of the left side of the filter and the return value of the filter will be the new left value when the next filter is run. When there are no more filters, the template will receive the resulting string.

There are a big number of standard filters available to use, but later on we will implement a custom filter method for SharePoint. The result of the above rendered template looks like:

<p>TIM JONES has to do:</p>

<ul>
  <li>Documentation</li>
  <li>Code comments</li>
</ul>

To pass variables and render the template you first need to parse the template and the then just call the Render method with the variable values:

string templateCode = @"<ul>
{% for item in user.tasks -%}
  <li>{{ item.name }}</li>
{% endfor -%}
</ul>";

Template template = Template.Parse(templateCode);

string result = template.Render(Hash.FromAnonymousObject(new {
                                    user = new User
                                    {
                                      Name = "Tim Jones",
                                      Tasks = new List<Task> {
                                        new Task { Name = "Documentation" },
                                        new Task { Name = "Code comments" }
                                      }
                                    }}));

public class User : Drop
{
	public string Name { get; set; }
	public List<Task> Tasks { get; set; }
}

public class Task : Drop
{
	public string Name { get; set;	 }
}

The User and Task classes inherit from the Drop class. This is an important class in DotLiquid. The next sections explains the class in more detail. It is out of scope of this article to discuss all the features for DotLiquid in detail. For more information please see the homepage of DotLiquid (dotliquidmarkup.org) or the website of the original creator of the Liquid template language at liquidmarkup.org. You will find there a lot of manuals and sample code.

Template Manager

The TemplateManager class is a wrapper over the DotLiquid template engine and provides SharePoint support. The class allows to cache parsed templates, to register tags and filters and render them using a top-level custom Drop class named SharePointDrop:

internal class TemplateManager
{
  public Dictionary<string, Template> Templates { get; protected set; }

  public TemplateManager()
  {
    Templates = new Dictionary<string, Template>();
  }

  public void AddTemplate(string name, string template)
  {
    if(string.IsNullOrEmpty(name))
      throw new ArgumentNullException("name");
    if(string.IsNullOrEmpty(template))
      throw new ArgumentNullException("template");

    if(Templates.ContainsKey(name))
      Templates[name] = Template.Parse(template);
    else
      Templates.Add(name, Template.Parse(template));
  }

  public void RegisterTag<T>(string tagName) where T : Tag, new()
  {
    Template.RegisterTag<T>(tagName);
  }

  public void RegisterFilter(Type type)
  {
    Template.RegisterFilter(type);
  }

  public string Render(string nameOrTemplate, IDictionary<string, object> values)
  {
    Template template;

    if(Templates.ContainsKey(nameOrTemplate))
      template = Templates[nameOrTemplate];
    else
      template = Template.Parse(nameOrTemplate);

    SharePointDrop sp = new SharePointDrop();

    if(values != null)
    {
      foreach(KeyValuePair<string, object> kvp in values)
        sp.AddValue(kvp.Key, kvp.Value);
    }

    return template.Render(new RenderParameters { LocalVariables = 
             Hash.FromAnonymousObject(new { SP = sp }), RethrowErrors = true });
  }
}

The Render method is using the SharePointDrop class to support objects like SPListItem or SPListCollection. The Drop class as key concept of DotLiquid must be explained in detail. The DotLiquid template engine is focusing on making templates safe. A Drop is a class which allows you to export DOM like objects. DotLiquid, by default, only accepts a limited number of types as parameters to the Render method. These data types include the .NET primitive types (integer, float, string, etc.), and some collection types including IDictionary, IList and IIndexable (a custom DotLiquid interface).

If DotLiquid would support arbitrary types, then it could result in properties or methods being unintentionally exposed to template authors. To prevent this, DotLiquid templating system uses Drop classes that use an opt-in approach to exposing object data.

The code following shows the SharePointDrop implementation:

internal class SharePointDrop : Drop
{
  Dictionary<string, object> _values;

  public SharePointDrop()
  {
    _values = new Dictionary<string, object>();

    if(SPContext.Current != null)
      _values.Add("Site", SPContext.Current.Site);
    if(SPContext.Current != null)
      _values.Add("Web", SPContext.Current.Web);
    if(SPContext.Current != null)
      _values.Add("User", SPContext.Current.Web.CurrentUser);

    _values.Add("Date", DateTime.Now);
    _values.Add("DateISO8601",
                   SPUtility.CreateISO8601DateTimeFromSystemDateTime(DateTime.Now));

    // TODO: Add more default values
  }

  public void AddValue(string name, object value)
  {
    if(string.IsNullOrEmpty(name))
      throw new ArgumentNullException("name");

    if(_values.ContainsKey(name))
      _values[name] = value;
    else
      _values.Add(name, value);
  }

  public override object BeforeMethod(string method)
  {
    if(!string.IsNullOrEmpty(method) && _values.ContainsKey(method))
      return DropHelper.MayConvertToDrop(_values[method]);

    return null;
  }
}

The SharePointDrop class main objective is to solve the problem of casting unsupported data types like SPListItem or SPListItemCollection and other SharePoint related types. Therefore the class is overriding the BeforeMethod method of the Drop class to analyse the requested variable value. If the variable is available in the value context the method will try to cast the data type to a known Drop type by calling the MayConvertToDrop method of the DropHelper class:

public static object MayConvertToDrop(object value)
{
  if(value != null)
  {
    // TODO: Add your own drop implementations here

    if(value is SPList)
      return new SPPropertyDrop(value);
    if(value is SPListCollection)
      return ConvertDropableList<SPPropertyDrop, SPList>(value as ICollection);
    if(value is SPListItem)
      return new SPListItemDrop(value as SPListItem);
    if(value is SPListItemCollection)
      return ConvertDropableList<SPListItemDrop, SPListItem>(value as ICollection);
    if(value is SPWeb)
      return new SPPropertyDrop(value);
    if(value is SPSite)
      return new SPPropertyDrop(value);
    if(value is SPUser)
      return new SPPropertyDrop(value);
    if(value is Uri)
      return ((Uri)value).ToString();
    if(value is Guid)
      return ((Guid)value).ToString("B");
  }

  return value;
}

The SPListItemDrop class for instance is returning the value of the requested field:

internal class SPListItemDrop : SPDropBase
{
  public SPListItem ListItem { get { return DropableObject as SPListItem; } }

  public SPListItemDrop()
  {
  }

  public SPListItemDrop(SPListItem listItem)
  {
    DropableObject = listItem;
  }

  public override object BeforeMethod(string method)
  {
    if(!string.IsNullOrEmpty(method))
    {
      StringBuilder sb = new StringBuilder();
      string name = method + "\n";

      for(int i = 0; i < name.Length; i++)
      {
        if(name[i] == '\n')
          continue;
        if(name[i] == '_')
        {
          if(name[i + 1] != '_')
            sb.Append(' ');
          else
          {
            i++;
            sb.Append('_');
          }
        }
        else
          sb.Append(name[i]);
      }

      name = sb.ToString();

      if(ListItem.Fields.ContainsField(name))
        return DropHelper.MayConvertToDrop(ListItem[name]);
    }

    return null;
  }
}

The method parameter (field name of the SPListItem) of the BeforeMethod method can contain underscores which are replaced by spaces. So, field names with spaces like Start Date of the Task item must be defined in the template as {{task.Start_Date}}.

The SPPropertyDrop class, also part of the solution of this article, is a generic Drop implementation which exposes all properties of an object and may cast them if needed into an Drop objects again. For implementation details see the source code.

Filters and Tags

The solution is also providing a custom filter and tag implementation. The filter called sp_format_date (see template above) is implemented by the method SPFormatDate and is calling the FormatDate method of the class SPUtility form the SharePoint API:

internal static class SPFilters
{
  public static object SPFormatDate(object input)
  {
    DateTime dt = DateTime.MinValue;

    if(input is string)
    {
      try
      {
        dt = SPUtility.ParseDate(SPContext.Current.Web, input as string, 
               SPDateFormat.DateOnly, false);
      }
      catch { }
    }
    else if(input is DateTime)
      dt = (DateTime)input;

    if(dt != DateTime.MinValue && dt != DateTime.MaxValue && SPContext.Current != null)
      return SPUtility.FormatDate(SPContext.Current.Web, (DateTime)input, 
               SPDateFormat.DateOnly);

    return input;
  }
}

The custom tag named splists is returning a formatted list of all SPList object names of the current web (see template above):

internal class SPListsTag : Tag
{
  string _format;

  public override void Initialize(string tagName, string markup, List<string> tokens)
  {
    base.Initialize(tagName, markup, tokens);

    if(string.IsNullOrEmpty(markup))
      _format = "{0}";
    else
      _format = markup.Trim().Trim("\"".ToCharArray()).Trim("'".ToCharArray());
  }

  public override void Render(Context context, StreamWriter result)
  {
    base.Render(context, result);

    if(SPContext.Current != null && !string.IsNullOrEmpty(_format))
    {
      foreach(SPList list in SPContext.Current.Web.Lists)
        result.Write(string.Format(_format, list.Title));
    }
  }
}

Download Source Code | Download Article (PDF)

Advertisements

How To Implement A Modern Progress Dialog For WPF Applications

*** NEW! My blog moved to my homepage at http://www.parago.de! ***

Developing a Windows Presentation Foundation (WPF) application requires sometimes to execute an asynchronous task with long-running execution steps, e.g. calling a web service. If those steps are triggered by user interactions, you want show a progress dialog to block the user interface and display detail step information. In some cases you also want to allow the user to stop the long-running task by clicking a Cancel button.

The following screenshots show some samples of progress dialogs implemented in this blog entry:

image

image

image

image

This article will show how to implement such progress dialogs in WPF with C#. All of the above dialogs can be used with one implementation. The solution will also show how to hide the close button of a window, which is officially not supported by WPF.

The code snippet below shows how to use and display such a progress dialog:

ProgressDialogResult result = ProgressDialog.Execute(this, "Loading data...", () => {

  // TODO: Do your work here!

});

if(result.OperationFailed)
  MessageBox.Show("ProgressDialog failed.");
else
  MessageBox.Show("ProgressDialog successfully executed.");

The ProcessDialog class provides a number of static Execute methods (overrides) to easily setup a long-running task with a dialog window. The first parameter always defines the parent window in order to center the process dialog relative to the parent window. The second parameter is the text message displayed in all dialogs. The third parameter is the asynchronous method itself.

The fourth parameter allows to pass additional settings. Those dialog settings, represented by an instance of the ProcessDialogSettings class, define if the dialog shows a sub label, has a Cancel button or displays the progress bar itself in percentage or indeterminate. Predefined settings are also defined as static properties.

Using lambda expressions in C#, it is very comfortable to start a long-running task and displaying the dialog. You can also communicate with the progress dialog to report messages to the user by calling the Report method of the ProgressDialog class:

ProgressDialogResult result = ProgressDialog.Execute(this, "Loading data...", (bw) => {

  ProgressDialog.Report(bw, "Connecting to the server...");

  // TODO: Connect to the server

  ProgressDialog.Report(bw, "Reading metadata...");

  // TODO: Reading metadata

}, ProgressDialogSettings.WithSubLabel);

The two samples above did not show a Cancel button. The next code shows a progress dialog with a Cancel button including code to check if the long-running code must be cancelled:

int millisecondsTimeout = 1500;

ProgressDialogResult result = ProgressDialog.Execute(this, "Loading data", (bw, we) => {

  for(int i = 1; i <= 5; i++)
  {
    if(ProgressDialog.ReportWithCancellationCheck(bw, we, "Executing step {0}/5...", i))
      return;

    Thread.Sleep(millisecondsTimeout);
  }

  // So this check in order to avoid default processing after the Cancel button has been
  // pressed. This call will set the Cancelled flag on the result structure.
  ProgressDialog.CheckForPendingCancellation(bw, we);

}, ProgressDialogSettings.WithSubLabelAndCancel);

if(result.Cancelled)
  MessageBox.Show("ProgressDialog cancelled.");
else if(result.OperationFailed)
  MessageBox.Show("ProgressDialog failed.");
else
  MessageBox.Show("ProgressDialog successfully executed.");

Calling the ReportWithCancellationCheck method will check for a pending cancellation request (from the UI) and will may set the Cancel property of the DoWorkEventArgs class passed from the underlying BackgroundWorker object to True. Otherwise the method will display the message and continue processing.

The Exceute method of the ProgressDialog class will return an instance of the ProgressDialogResult class that returns the status of the execution. Thrown exceptions in the task method will be stored in the Error property if the OperationFailed property is set to True. For more samples see the Visual Studio 2010 solution you can download from my homepage.

The ProgressDialog window contains the main application logic. The above described static Execute methods will internally call the ExecuteInternal method to create an instance of the ProgressDialog window passing and setting all necessary values. Then the Execute method with the asynchronous method as parameter is called:

internal static ProgressDialogResult ExecuteInternal(Window owner, string label,
  object operation, ProgressDialogSettings settings)
{
  ProgressDialog dialog = new ProgressDialog(settings);
  dialog.Owner = owner;

  if(!string.IsNullOrEmpty(label))
    dialog.Label = label;

  return dialog.Execute(operation);
}

The operation method can be a delegate of the following type:

· Action

· Action<BackgroundWorker>

· Action<BackgroundWorker, DoWorkEventArgs>

· Func<object>

· Func<BackgroundWorker, object>

· Func<BackgroundWorker, DoWorkEventArgs, object>

The Func types can return a value that will be used to set the Result property of the ProgressDialogResult class.

The Excute method is implemented as follows:

internal ProgressDialogResult Execute(object operation)
{
  if(operation == null)
    throw new ArgumentNullException("operation");

  ProgressDialogResult result = null;

  _isBusy = true;

  _worker = new BackgroundWorker();
  _worker.WorkerReportsProgress = true;
  _worker.WorkerSupportsCancellation = true;

  _worker.DoWork +=
    (s, e) => {
      if(operation is Action)
        ((Action)operation)();
      else if(operation is Action<BackgroundWorker>)
        ((Action<BackgroundWorker>)operation)(s as BackgroundWorker);
      else if(operation is Action<BackgroundWorker, DoWorkEventArgs>)
        ((Action<BackgroundWorker, DoWorkEventArgs>)operation)(s as BackgroundWorker, e);
      else if(operation is Func<object>)
        e.Result = ((Func<object>)operation)();
      else if(operation is Func<BackgroundWorker, object>)
        e.Result = ((Func<BackgroundWorker, object>)operation)(s as BackgroundWorker);
      else if(operation is Func<BackgroundWorker, DoWorkEventArgs, object>)
        e.Result = ((Func<BackgroundWorker, DoWorkEventArgs, object>)operation)(s as BackgroundWorker, e);
      else
        throw new InvalidOperationException("Operation type is not supoorted");
    };

  _worker.RunWorkerCompleted +=
    (s, e) => {
      result = new ProgressDialogResult(e);
      Dispatcher.BeginInvoke(DispatcherPriority.Send, (SendOrPostCallback)delegate {
        _isBusy = false;
        Close();
      }, null);
    };

  _worker.ProgressChanged +=
    (s, e) => {
      if(!_worker.CancellationPending)
      {
        SubLabel = (e.UserState as string) ?? string.Empty;
        ProgressBar.Value = e.ProgressPercentage;
      }
    };

  _worker.RunWorkerAsync();

  ShowDialog();

  return result;
}

The ProgressDialog class is using internally a BackgroundWorker object to handle the asynchronous execution of the task or operation method.

For more details of the implementation see the source code.

Download Source Code

Download Article (PDF)

UPDATE:

I wrote a second edition of the progress dialog which is using a ProgressDialogContext class to access BackgroundWorker and the DoWorkEventArgs. Also, all Report methods moved to the context class. So, you can basically use the static ProgressDialog.Current property within the asynchronous method and its sub methods to report to the progress dialog. This usefully if you call a chain of methods in which you have to report messages to the dialog and may need to cancel the process.

Download Source Code with ProgresDialogContext class

How To Implement A Custom SharePoint 2010 Logging Service For ULS And Windows Event Log

Prior to Microsoft SharePoint 2010 there was no official documented way to programmatically use the built-in ULS service (Unified Logging Service) to log own custom messages. There are still solutions available on the internet that can be used, but SharePoint 2010 now supports full-blown logging service support.

To log a message to the SharePoint log files just call the WriteTrace method of the SPDiagnosticsService class:

SPDiagnosticsService.Local.WriteTrace(0, new SPDiagnosticsCategory("My Category", TraceSeverity.Medium, EventSeverity.Information), TraceSeverity.Medium, "My log message");

The problem with this technique is that the log entry does not contain any category information, instead SharePoint uses the value "Unknown":

image

Of course, that does not matter if someone develops small solutions. Developing custom solutions you may want to implement an own logging service with custom categories and UI integration within the Central Administration (CA) of SharePoint 2010.

This article shows how to develop a custom logging service that integrates with the Diagnostic Logging UI of the Central Administration:

image

Custom Logging Service

A custom logging service must inherit from the SPDiagnosticsServiceBase class. This is the base class for diagnostic services in SharePoint and it offers the option to log messages to log files via ULS and to the Windows Event Log. By overriding the ProvideAreas method the service provides information about diagnostic areas, categories and logging levels. A diagnostic area is a logical container of one or more categories.

The sample service defines one diagnostic area and one category (used by application pages) for this area:

[Guid("D64DEDE4-3D1D-42CC-AF40-DB09F0DFA309")] 
public class LoggingService : SPDiagnosticsServiceBase
{
  public static class Categories
  {
    public static string ApplicationPages = "Application Pages";
  }

  public static LoggingService Local
  {
    get { return SPFarm.Local.Services.GetValue(DefaultName); }
  }

  public static string DefaultName
  {
    get { return "Parago Logging Service"; }
  }

  public static string AreaName
  {
    get { return "Parago"; }
  }

  protected override IEnumerable ProvideAreas()
  {
    List areas = new List
    {
      new SPDiagnosticsArea(AreaName, 0, 0, false, new List
      {
        new SPDiagnosticsCategory(Categories.ApplicationPages, null, TraceSeverity.Medium, 
              EventSeverity.Information, 0, 0, false, true)
      })
    };

    return areas;
  }

  // . . .

}

The area name as well as the category names will be also shown in the Diagnostic Logging UI of the CA. It is also possible to define a resource DLL to localize the names.

The service will offer the two static methods WriteTrace and WriteEvent. WriteTrace writes the log message to the SharePoint log files, usually saved in the SharePoint folder C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\LOGS.

The WriteEvent writes the log message to the Windows Event Log. The event source is called like the AreaName and later on created within the FeatureReceiver:

[Guid("D64DEDE4-3D1D-42CC-AF40-DB09F0DFA309")] 
public class LoggingService : SPDiagnosticsServiceBase
{

  ...

  public static void WriteTrace(string categoryName, TraceSeverity traceSeverity, 
    string message)
  {
    if(string.IsNullOrEmpty(message))
      return;

    try
    {
      LoggingService service = Local;

      if(service != null)
      {
        SPDiagnosticsCategory category = service.Areas[AreaName].Categories[categoryName];
        service.WriteTrace(1, category, traceSeverity, message);
      }
    }
    catch { }
  }

  public static void WriteEvent(string categoryName, EventSeverity eventSeverity, 
    string message)
  {
    if(string.IsNullOrEmpty(message))
      return;

    try
    {
      LoggingService service = Local;

      if(service != null)
      {
        SPDiagnosticsCategory category = service.Areas[AreaName].Categories[categoryName];
        service.WriteEvent(1, category, eventSeverity, message);
      }
    }
    catch { }
  }
}

The usage of the new custom logging service is quite simple:

 

// ULS Logging
LoggingService.WriteTrace(LoggingService.Categories.ApplicationPages, 
  TraceSeverity.Medium, "...");

// Windows Event Log
LoggingService.WriteEvent(LoggingService.Categories.ApplicationPages, 
  EventSeverity.Information, "...");

Next, we need to register it with SharePoint.

Service Registration

The custom logging service must be registered with SharePoint 2010 to show up in the Diagnostic Logging UI of the CA. The event sources also must be created on each server of the SharePoint farm. These two registration steps can be bundle within the FeatureActivated override method of the FeatureReceiver.

[Guid("50CA5F69-381F-4C2A-BE6C-F28219AFF20C")]
public class FeatureEventReceiver : SPFeatureReceiver
{
  const string EventLogApplicationRegistryKeyPath = 
    @"SYSTEM\CurrentControlSet\services\eventlog\Application";

  public override void FeatureActivated(SPFeatureReceiverProperties properties)
  {
    RegisterLoggingService(properties);
  } 

  public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
  {
    UnRegisterLoggingService(properties);
  }

  static void RegisterLoggingService(SPFeatureReceiverProperties properties)
  {
    SPFarm farm = properties.Definition.Farm;

    if(farm != null)
    {
      LoggingService service = LoggingService.Local;

      if(service == null)
      {
        service = new LoggingService();
        service.Update();

        if(service.Status != SPObjectStatus.Online)
          service.Provision();
      }

      foreach(SPServer server in farm.Servers)
      {
        RegistryKey baseKey = RegistryKey.OpenRemoteBaseKey(RegistryHive.LocalMachine, 
                                server.Address);

        if(baseKey != null)
        {
          RegistryKey eventLogKey = baseKey.OpenSubKey(EventLogApplicationRegistryKeyPath,  
                                      true);

          if(eventLogKey != null)
          {
            RegistryKey loggingServiceKey = eventLogKey.OpenSubKey(LoggingService.AreaName);

            if(loggingServiceKey == null)
            {
              loggingServiceKey = eventLogKey.CreateSubKey(LoggingService.AreaName, 
                                   RegistryKeyPermissionCheck.ReadWriteSubTree);
              loggingServiceKey.SetValue("EventMessageFile", 
                @"C:\Windows\Microsoft.NET\Framework\v2.0.50727\EventLogMessages.dll", 
                RegistryValueKind.String);
            }
          }
        }
      }
    }
  }

  static void UnRegisterLoggingService(SPFeatureReceiverProperties properties)
  {
    SPFarm farm = properties.Definition.Farm;

    if(farm != null)
    {
      LoggingService service = LoggingService.Local;

      if(service != null)
        service.Delete();

      foreach(SPServer server in farm.Servers)
      {
        RegistryKey baseKey = RegistryKey.OpenRemoteBaseKey(RegistryHive.LocalMachine, 
                                server.Address);

        if(baseKey != null)
        {
          RegistryKey eventLogKey = baseKey.OpenSubKey(EventLogApplicationRegistryKeyPath, 
                                      true);

          if(eventLogKey != null)
          {
            RegistryKey loggingServiceKey = eventLogKey.OpenSubKey(LoggingService.AreaName);

            if(loggingServiceKey != null)
              eventLogKey.DeleteSubKey(LoggingService.AreaName);
          }
        }
      }
    }
  }
}

The FeatureActivated override is calling the RegisterLoggingService helper method to register with the SharePoint system if the service is not already available. Since one of the base classes of LoggingService is the SPService class which provides an Update and Provision method, we can register the new service farm-wide.

The second step is to create a new Windows Event Log source. Therefore we have to go through the collection of SharePoint farm servers and remotely add the new source by generating registry entries on each server.

To unregister we redo the registration steps by overriding FeatureDeactivating method of the FeatureReceiver class. The UnRegisterLoggingService method then deletes the service and removes all registry keys on all servers in the SharePoint farm.

The sample solution also created an application page to test the logging service. The source code is available as download.

image

Enter a test message and press the Log button. The message will be logged to the Windows Event Log:

And to the SharePoint log files:

image

That’s it.

Download Source Code | Download PDF Version

How To Access SAP Business Data From Silverlight 4 ClientsUsing WCF RIA Services

The introduction of Microsoft’s WCF RIA Services for Silverlight 4 simplified very much the development process of N-tier business applications using Silverlight and ASP.NET. By using this new technology we can also easy access and integrate SAP business data in Silverlight clients.

This article shows how to provide a SAP domain service as web service that will be consumed by a Silverlight client. The sample application will allow the user to query customer data. The service uses LINQ to SAP from Theobald Software to connect to a SAP R/3 system.

Project Setup

The first step in setting up a new Silverlight 4 project with WCF RIA Services is to create a solution using the Visual Studio template Silverlight Navigation Application:



Visual Studio 2010 is then asking you to create an additional web application, which hosts the Silverlight application. It’s important to select the checkbox Enable WCF RIA Services (see screenshot below):


After clicking the Ok button, Visual Studio generates a solution with two projects, one Silverlight 4 project and one ASP.NET project. In the next section we are creating the SAP data access layer using the LINQ to SAP designer.

LINQ to SAP

The LINQ to SAP provider and its Visual Studio 2010 designer offers a very handy way to design SAP interfaces visually. The designer will generate the code for the SAP data access layer automatically, similar to LINQ to SQL. The LINQ provider is part of the .NET library ERPConnect.net from Theobald Software. The company offers a demo version for download on its homepage.

The next step is to create the needed LINQ to SAP file by opening the Add New Item dialog:


LINQ to SAP is internally called LINQ to ERP.

Clicking the Add button will create a new ERP file and opens the LINQ designer. Now, drag the Function object from the toolbox and drop it onto the designer surface. If you have not entered the SAP connection data so far, you are now asked to do so:


Enter the connection data for your SAP R/3 system and then click the Ok button. Next, search for and select the SAP function module named SD_RFC_CUSTOMER_GET. The function module provides a list of customer data.

The RFC Function modules dialog opens and let you define the necessary parameters:


In the above function dialog, change the method name to GetCustomers and mark the Pass checkbox for the NAME1 parameter in the Exports tab. Also set the variable name to namePattern. On the Tables tab mark the Return checkbox for the table parameter CUSTOMER_T and set the table and structure name to CustomerTable and CustomerRow:


After clicking the Ok button and saving the ERP file, the LINQ designer will generate a SAPContext class which contains a method called GetCustomers with an input parameter named namePattern. This method executes a search for SAP customer data allowing the user to enter a wildcard pattern. The method returns a table of customer data:


On the LINQ designer level (click on the free part of the LINQ designer surface) the property Create Object Outside Of Context Class must be set to True:


Now, we finally add a Customer class which we use in our SAP domain service later on. This class and its values will be transmitted to the Silverlight client by the WCF RIA Services. It’s important to set the Key attribute on the identifier fields for WCF RIA Services, otherwise the project will not compile:


That’s it! We now have our SAP data access layer ready to use and can start adding the domain service in the next section.

SAP Domain Service

The next step is to add the SAP domain service to our web project. A domain service is a specialized WCF service and is one of the core constructs of WCF RIA Services. The service exposes operations that can be called from the client generated code. On the client side we use the domain context to access the domain service on the server side.

Add a new Domain Service Class and name it SAPService:


In the upcoming dialog create an empty domain service class by just clicking the Ok button:


Next, we add the service operation GetCustomers to the SAP service with a name pattern parameter. The operation then returns a list of Customer objects. The Query attribute limits the result set to 200 entries.

The operation uses the visually designed SAP data access logic to retrieve the SAP customer data. First of all, an instance of the SAPContext class will be created using a connection string (see sample in code). For more details regarding the SAP connection string see the ERPConnect.net manual.

The LINQ to SAP context class contains the GetCustomers method which we will call using the given namePattern parameter. Next, the operation creates an instance of the Customer class for each customer record returned by SAP.

The license code for the ERPConnect.net library is set in the constructor of our domain service class.


That’s all we need on the server side.

In the next section we are implementing the Silverlight client.

Silverlight Client

The implementation of the client side is straightforward. The home view contains a DataGrid control to display the list of customer data as well as a search area with TextBox and Button controls to allow users to enter name search pattern.

The click event handler of the load button, called OnLoadButtonClick, will execute the SAP service. The boilerplate code to access the web service was generated by WCF RIA Services in the subfolder Generated_Code in the Silverlight project.

First of all, an instance of the SAPContext will be created. Then we load the query GetCustomersQuery and execute the service operation on the server side using WCF RIA Services. If the domain service returns an error, the callback anonymous method will mark the error as handled and display the error message.

If the execution of the service operation succeeded the result set gets displayed in the DataGrid control.


The next screenshot shows the final result:


That’s it.

Summary

This article has shown how easy SAP customer data can be integrate within Silverlight clients using tools like WCF RIA Services and LINQ to SAP. It is quite simple to extend the SAP service to integrate all kind of operations.

Download Source Code

New article about integrating SAP data into SharePoint 2010

I wrote a new article about SharePoint 2010, SAP and BCS (Business Connectivity Services). I have published this article and a demo project with source code on Codeproject:

How To Integrate SAP Business Data Into SharePoint 2010 Using Business Connectivity Services And LINQ to SAP

A PDF version of the article can be downloaded from my Homepage.

Feel free to send me your feedback.

New article about implementing a SharePoint entity repository

I wrote a new article about SharePoint on CodeProject.com (How To Implement A Generic Entity List Repository And Business Logic For SharePoint 2010 Using The T4 Templating Engine).

This article describes how to implement a generic, extensible entity list repository and business logic for SharePoint 2010 using the T4 templating engine (Text Template Transformation Toolkit).

The article is also available as PDF file at the Parago website.

Feel free to send me your feedback.