How do I...Write a configurable extension in .Net?

Creating an Extension Library

1.  Open VS.NET and select File->New->Project. From the New Project Dialog Box, choose the Windows Class Library template project and name it ConfigurableExtService.

2.  To access the Deki Wiki extension framework, select Project->Reference and add a reference to the assemblies below.  These binaries can be found within the bin directory of your Deki Wiki web root (Deki Wiki VM:  /var/www/deki-hayes/bin).

• log4net.dll
• mindtouch.deki.ext.dll
• mindtouch.dream.dll
• SgmlReaderDll.dll

3.  Create a new class containing the code below.  The DreamServiceConfig attribute is used to declare each configuration value used by the service.  This example takes three string configuration values (db-name, db-user, and db-password) and one integer value (db-timeout).

using System;
using System.Collections;
using MindTouch.Dream;
using MindTouch.Deki;

namespace ConfigurableExtService {

    [DreamService("Configurable Extension Service",
                  "Copyright (c) 2007 MindTouch, Inc.",
                  SID = new string[] { "http://services.mindtouch.com/deki/draft/2007/06/configurable" }
    )]
    [DekiExtLibrary(Namespace = "samples", Description = "Samples Library")]
    [DreamServiceConfig("db-name", "string", "Database name")]
    [DreamServiceConfig("db-user", "string", "Database user")]
    [DreamServiceConfig("db-password", "string", "Database password")]
    [DreamServiceConfig("db-timeout", "int", "Database timeout")]
    public class ConfigurableExtService : DekiExtService {

    }
}

Reading Configuration Values

Add the following function into your library to read the db-name, db-user, db-password, and db-timeout.   This code uses the Config property, which is inherited from DekiExtService, to read each configuration value.  The "??" operator specifies a default when no value is found:

[DekiExtFunction(Description = "Function that reads configuration values")]
public XDoc ShowConfig() {
    XDoc result = new XDoc("html").Start("body").Start("ul");
    result.Elem("li", String.Format("Database name:  {0}", Config["db-name"].AsText ?? "default db-name"));
    result.Elem("li", String.Format("Database user:  {0}", Config["db-user"].AsText ?? "default db-user"));
    result.Elem("li", String.Format("Database password:  {0}", Config["db-password"].AsText ?? "default db-password"));
    result.Elem("li", String.Format("Database timeout:  {0}", Config["db-timeout"].AsInt ?? 1000));    
    return result.End().End();
}

Testing the Extension

1.  Compile and copy the ConfigurableExtService.dll assembly into the bin/services directory of your Deki Wiki web root (Deki Wiki VM:  /var/www/deki-hayes/bin/services).  Deki Wiki will automatically load new extension libraries from this location.

2.  Restart Deki Wiki (Deki Wiki VM:  /etc/init.d/dekihost restart).

3.  Register the service by opening your wiki and selecting Tools->Control Panel->Service Management (administrator access is required).  Add a new Local service with SID=http://services.mindtouch.com/deki/d...6/configurable.  Also add these configuration values:

• db-name=mydatabase
  
• db-user=myusername
  
• db-password=mypassword
• db-timeout=100
  

Figure 1

 4.  At this point, you are ready to invoke the extension.  Create a new page and add the text below to invoke the configuration sample:

{{samples.showconfig()}} 

Output when the page is saved:

• Database name: mydatabase
• Database user: myusername
• Database password: mypassword
• Database timeout: 100