Home
Introduction and rules
User manual
How to use AWB
Discussion
Discuss AWB, report errors, and request features
User tasks
Request or help with AWB-able tasks
Technical
Technical documentation

AWB is able to load and use fully customised plugins. These plugins can process page text and extend the user interface, and are in the form of libraries (.dll files) which can be made in any .NET language such as C# or Visual Basic .NET. When AWB loads it automatically checks to see if there are any plugins in the folder it was executed from. Any plugins found are loaded and initialised without further intervention by the user.

WP:AWB/Plugins

List of plugins

Page Processing (IAWBPlugin)

CFD (categories for discussion)
IFD (images for deletion)
Kingbotk Plugin (adding/updating WikiProject talk page templates)
Delinker (a tool for easily removing URLs and hostnames usually used to help editors remove spam)
TheTemplator

Page Editing

CSVLoader (creating/updating articles using CSV/delimited-text files)

ListMaker ("search") Plugins (IListMakerPlugin)

Bing Search (Search Bing from within AWB)
NoLimits
Yahoo Search (Search Yahoo from within AWB) Discontinued.

General Plugins

TypoScan (the plugin supplies a list of 100 articles that need fixing, but no requirement to finish any or all of them)

Making a plugin

IAWBPlugin

These are "Page Processing" plugins.

C#

Firstly create a class library project in Visual Studio.
Now add a reference to the WikiFunctions.dll file that comes with AWB (right click the project in the "solution explorer" => click "add reference" => click the "browse" tab => locate the WikiFunctions.dll file). Also add a reference to System.Windows.Forms under the ".NET" tab.
Add using WikiFunctions; and using System.Windows.Forms; to the code.
Implement the interface IAWBPlugin in the WikiFunctions namespace so your code looks like this:

using System;
using System.Collections.Generic;
using System.Text;
using WikiFunctions;
using System.Windows.Forms;

namespace ExamplePlugin
{
    public class ExamplePlugin : WikiFunctions.Plugin.IAWBPlugin
    {
        
    }
}

5. In Visual Studio, hold the mouse over IAWBPlugin, right click, and select one of the 2 options under "Implement interface". This will build the required members for you. If you're using a text editor, you'll have to implement the members manually; if you're using another IDE, well, you should know what to do :)

using System;
using System.Collections.Generic;
using System.Text;
using WikiFunctions;
using System.Windows.Forms;

namespace ExamplePlugin
{
    public class ExamplePlugin : WikiFunctions.Plugin.IAWBPlugin
    {
        #region IAWBPlugin Members

        public void Initialise(IAutoWikiBrowser sender)
        {
            throw new Exception("The method or operation is not implemented.");
        }

        public string Name
        {
            get { throw new Exception("The method or operation is not implemented."); }
        }

        public string WikiName
        {
            get { throw new Exception("The method or operation is not implemented."); }
        }

        public string ProcessArticle(IAutoWikiBrowser sender, IProcessArticleEventArgs eventargs)
        {
            throw new Exception("The method or operation is not implemented.");
        }

        public void LoadSettings(object[] prefs)
        {
            throw new Exception("The method or operation is not implemented.");
        }

        public object[] SaveSettings()
        {
            throw new Exception("The method or operation is not implemented.");
        }

        public void Reset()
        {
            throw new Exception("The method or operation is not implemented.");
        }

        public void Nudge(out bool Cancel)
        {
            throw new Exception("The method or operation is not implemented.");
        }

        public void Nudged(int Nudges)
        {
            throw new Exception("The method or operation is not implemented.");
        }

        #endregion
    }
}

6. When AWB finds your plugin, it will create an instance of it, and call Initialise(). Your plugin will receive an IAutoWikiBrowser object using which you can interact with the application.

7. Add all processing code to the ProcessArticle method. The method receives a ProcessArticleEventArgs object, which contains all the info you need about the page and some writable members. Return the modified text as the exit value of ProcessArticle().

8. Replace the "throw new Exception("The method or operation is not implemented.");"

9. Compile the library (Note: the target framework may need to be changed to ".NET Framework 2.0" in your project properties to match AWB target framework 2.0 or AWB may fail to load the .dll).

10. Put the new .dll file in the AWB directory and load AWB up. Or, from v4.2, you can load plugins on the fly via the plugin menu option. There is a main menu option listing the plugins if they include/create a ToolStripMenuItem.

More complex example

The AWB project at SourceForge includes a CFD plugin which you can use to familiarise yourself with the techniques (see plugins directory).

Visual Basic

1. Firstly create a class library project in Visual Studio.

2. Double click on "My Project" in the solution explorer, select references, and add a reference as per step 2 above. You'll also need to add a reference to System.Windows.Forms.

3. Import the AWB namespaces in the same tab

4. Create a new class and type "Implements IAWBPlugin". Press Enter and Visual Studio will auto-generate the code required to implement the interface. The code will look something like this (AWB version 4, pre-release):

Public Class Plugin1
    Implements WikiFunctions.Plugin.IAWBPlugin


    Public Sub Initialise(ByVal MainForm As WikiFunctions.Plugin.IAutoWikiBrowser) _
    Implements WikiFunctions.Plugin.IAWBPlugin.Initialise

    End Sub

    Public Sub LoadSettings(ByVal Prefs() As Object) Implements WikiFunctions.Plugin.IAWBPlugin.LoadSettings

    End Sub

    Public ReadOnly Property Name() As String Implements WikiFunctions.Plugin.IAWBPlugin.Name
        Get

        End Get
    End Property

    Public Sub Nudge(ByRef Cancel As Boolean) Implements WikiFunctions.Plugin.IAWBPlugin.Nudge

    End Sub

    Public Sub Nudged(ByVal Nudges As Integer) Implements WikiFunctions.Plugin.IAWBPlugin.Nudged

    End Sub

    Public Function ProcessArticle(ByVal sender As WikiFunctions.Plugin.IAutoWikiBrowser, _
    ByVal eventargs As WikiFunctions.Plugin.ProcessArticleEventArgs) As String _
    Implements WikiFunctions.Plugin.IAWBPlugin.ProcessArticle

    End Function

    Public Sub Reset() Implements WikiFunctions.Plugin.IAWBPlugin.Reset

    End Sub

    Public Function SaveSettings() As Object() Implements WikiFunctions.Plugin.IAWBPlugin.SaveSettings

    End Function
End Class

5. Follow steps 6-9 above.

Settings

When AWB loads and saves settings, it calls each loaded plugin. Plugins are not obliged to do anything, but users of complex plugins will surely appreciate being able to save their preferences.

Plugin authors have at least 4 ways of saving their settings, by returning an array of:

Simple, serializable types such as Strings.
AWBSettings.PrefsKeyPair objects
Custom public classes with each field marked as Serializable
An XML block converted to a String. (This is what the Kingbotk plugin uses).

Notes

The Name property is the name of the plugin. This property must return a "unique" value so please choose something a little more inventive than "plugin" :)
The Initialise method is called once when the plugin is loaded. The IAutoWikiBrowser object passed to it can be stored and used to reference the web browser and other components, for adding buttons to the plugin menu and context menu, for trapping events, etc.
The ProcessArticleEventArgs.EditSummary property is used to add a customised-per-edit note to the edit summary. ProcessArticleEventArgs.Skip can be set to true to skip the page without saving. ProcessArticleEventArgs.AWBLogItem is a log listener that plugins can write to, to add info to the AWB Logging tab.
The WikiFunctions namespace provides some useful stuff
The System.Text.RegularExpressions provides all the regular expression functionality which is always critical for text manipulation
Multiple plugin classes per library and multiple libraries both work.

Uses

Advanced regular expressions and text handling
Conditionally prepend or append templates or edit existing instances in the same AWB run
Access certain AWB controls

IAutoWikiBrowser

The IAutoWikiBrowser object gives your plugin access to the user interface and much of the internals of AWB in a managed way. It's essential to get to grips to this object if you want to write a really compelling plugin for 3rd party use.

Please bear in mind that often new features and controls get added to AWB but not to IAutoWikiBrowser. If there's something missing, and if it's a reasonable for it to be in the interface, all you have to do is ask.

IListMakerPlugin

These are ListMaker/"Search" plugins.

Example

There is a working Bing example search plugin in the AWB SVN. Sources

Debugging your plugin

There is no specific support in AWB to assist with the debugging process which inevitably occurs during any software development cycle. Normal techniques such as displaying message boxes or writing data to an external file apply. How to do source-level debugging depends on your particular development environment.

Under Visual C# Express

In this environment, you should have all of the AWB sources (see above), and add your plugin project to the solution. This is because your plugin is implemented as a Class Library and Visual C# Express does not allow a project of that type to be started directly. Set AutoWikiBrowser as the StartUp Project and start debugging your plugin. You should bear in mind that Visual C# Express does not allow for a solution to include projects in different languages, so you cannot write your plugin using VB if you wish to debug it in this way.

Workaround

You can manually edit the .csproj.user as a workaround to debug your plugin in Visual C# Express without compiling AutoWikiBrowser.exe. This should also allow you to debug VB plugins.

1. In your plugin's source directory (where your MyPlugin.csproj is), look for a file named like MyPlugin.csproj.user. Edit this file or create it if it doesn't exist.

2. Replace the content of that file with the following text. Modify StartProgram to match your AutoWikiBrowser.exe location and save it.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <StartAction>Program</StartAction>
    <StartProgram>D:\src\awb\AWB\AWB\bin\Release\AutoWikiBrowser.exe</StartProgram>
  </PropertyGroup>
</Project>

3. Open your plugin project in Visual C# Express and Start Debugging. This should run AutoWikiBrowser.

4. Load your plugin DLL in AWB. You should now be debugging your plugin.

For VB projects, the above should be identical except you'll be looking for MyPlugin.vbproj.user.

Under Visual Studio

The professional version of Visual Studio allows the independent debugging of a Class Library (which is what your plugin is). The steps to follow are:

compile your plugin
run AWB in the normal way
With your plugin project selected as the StartUp Project, choose Debug→Attach to Process... and select the running autowikibrowser process
load your plugin into AWB

The debugger will now operate on your plugin within AWB.

Wikipedia:AutoWikiBrowser/Plugins