In this example we'll create a custom search that finds issues with no release date.

First, open Visual Studio. You can use the free C# Express version if you like - that's what Comicster itself was written with!

Next, click "File|New Project..." and choose "Class Library" as your project type. In keeping with the naming conventions for Comicster extensions, we'll call our project Samples.Searches.ReleaseDate.

First thing you'll need to do in your newly-created project is add a reference to Comicster.Core.DLL. That'll give you access to the core set of Comicster classes, including the ISearch interface that we'll be implementing in this example.

Now rename your Class1.cs file to something more descriptive, like IssuesWithNoReleaseDate.cs. That will also rename the class itself.

Open up IssuesWithNoReleaseDate.cs and add the following lines to your list of "usings":

using Comicster;
using Comicster.Searches;

Now change your class' declaration so that it implements ISearch:

public class IssuesWithNoReleaseDate : ISearch
{
     public IEnumerable<Item> Execute(Collection collection)
    {
        throw new NotImplementedException();
    }

    public string Text
    {
        get { throw new NotImplementedException(); }
    }

}

Here I've used Visual Studio's shortcut to stub out the interface. You can see that ISearch only has one method and one property to implement.

The Text property is easy enough - it's the text you want displayed in Comicster's list of custom searches. Let's do that first:

public string Text
{
    get { return "Issues with no release date"; }
}

The Execute method is passed in the current collection, so for this example we can just add a simple Linq query and return the results:

public IEnumerable<Item> Execute(Collection collection)
{
    return collection.Owned.Issues.Concat(collection.Wanted.Issues)
        .Where(i => !i.ReleaseDate.HasValue);
}

Here we've concatenated the "owned" issues with the "wanted" issues so that we know we're searching the entire collection. We then filter the list on only issues with a release date.

The next step is to package up the assembly as a NuGet package so that Comicster can install it. Create a new file in the same folder as your project's solution file, and call it Samples.Searches.ReleaseDate.nuspec. That's the NuGet specification file that we'll use to package up our DLL. Here's what that file should look like:

<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
  <metadata>
    <id>Samples.Searches.ReleaseDate</id>
    <version>1.0</version>
    <authors>Your Name</authors>
    <owners>Your Name</owners>
    <projectUrl>http://example.com/your-web-site</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Finds issues with no release date.</description>
    <tags>search sample</tags>
  </metadata>

  <files>
    <file src="Samples.Searches.ReleaseDate\bin\Debug\Samples.Searches.ReleaseDate.dll" target="lib" />
  </files>
</package>

Noteice that the "tags" field should have the word "search" in it. You can use any other tags you like, but "search" is the special tag that tells Comicster that this package contains a custom search extension.

Now go ahead and use the NuGet Command-Line Tool to create your package. This is pretty easy; just run this command from a command prompt:

nuget pack samples.searches.releasedate.nuspec

That will create a new file called "Samples.Searches.ReleaseDate.1.0.nupkg", which is the package Comicster will install.

We now need a way to test our new package before we submit it to the online repository. Thankfully we've made that nice and easy. You'll need to create the following folders:

My Documents
    Comicster
        Packages

... then copy your .nupkg file into the "Packages" folder. Run Comicster, and click on "Tools|Extensions". If you've followed the instructions correctly, you'll see "Samples.Searches.ReleaseDate" in the list. Install it, and try out your new search!

TODO

• Provide a URL for Comicster.Core.DLL so that devs can obtain it

• Detail how to submit a plug-in

Both of these probably should belong in an article that lives "above" this one, detailing the creation and submission process of all extensions.