Creating a New Custom Module

To start, launch Visual Studio and pick the option to Create a New Project. Select the project template for Class Library (.NET Framework). Pick the name and location for your project. For our example we are going to name it "MyCaseConverter". The selected project framework should be .NET Framework 4.6.1 or newer 4.x version. Rename the default empty "Class1.cs" to something useful. For our example we are going to rename it to "CaseConverter.cs".

The first step to making this a JobServer module is to add the interface references by going to Manage NuGet Packages for the project. Select the Browse tab and search for JobServer.NET. You will see it listed as XCENT.JobServer.Plugin. Just select that and click the Install option in the NuGet manger window.

((TODO: add screen snapshot showing XCENT.JobServer.Plugin in NuGet manager window))

Once installed, add using statements for XCENT.JobServer.Abstract and XCENT.JobServer.Plugin to your CaseConverter class. Then modify the declaration for the CaseConverter class so that it derives from ModuleBase. Once you do that, you will need to add the following lines to the class.

    public override string Description { get { return "My Case Converter"; } }
    public override string InfoURL { get { return string.Empty; } }
     
    [ParamDef(Caption: "A list of files to convert", ModuleParameterDirection: ModuleParameterDirection.In, IsRequired: true)]
    public List<string> FileSource { get; set; }
    
    public CaseConverter() : base("MyCaseConverter", "MyCustomModules", "MyCaseConverter", null) {
        //
    }
    
    public override ModuleRunResult OnRun() {
        return new ModuleRunResult() { Outcome = ExecutionOutcome.Success };
    }

This is the minimum you need to frame out your first custom module. When you use the installer for JobServer.NET, one of the installation options is to install a template for Visual Studio. If you choose to install the template for Visual Studio, you can save some of the steps above as it will create this overall structure for you on new JobServer plugin projects. Note, plugins refer to the (API) interface for both custom Modules and Triggers. However, the current release is only supporting custom modules at the current time.

As you may have already observed, there is no code in here yet to do anything useful. If you built this and installed it as is, it would show up in JobServer and would appear to put on the act of doing something, but it really is getting a whole bunch of nothing done so far. So, what is the basic structure we have here setup to do? This is going to be a module that takes a single input parameter and is going to expect that to be a single file or list of files that the module is going to process. To do something useful, we just add some code to the OnRun method. So, we will inject the following code into the top of this method. This code simply renames all the files it is provided to all lowercase filenames.

In the above code, notice that the constructor for the class passes a few important parameters back to ModuleBase. The first one is the name that your module will show up in the JobServer.NET user interface as. The second is the category for your module. In current versions of JobServer, this shows up as a prefix on your module name, and this one would show up as [MyCustomModules] MyCaseConverter. The category should be used to make sure your module names are unique and do not conflict with any others. We recommend that for any real modules you create, use your organization name, or org name and department as a way to both name and organize your own modules.

    try {
        foreach (string file in FileSource) {
            if (File.Exists(file)) {
                FileInfo fi = new FileInfo(file);
                if (fi.Name != fi.Name.ToLower()) {
                    this.SetMessage("Processing file:" + fi.Name);
                    string newname = Path.Combine(fi.DirectoryName, fi.Name.ToLower());
                    File.Move(file, newname);
                }
            }
        }
    }
    catch (Exception ex) {
        this.WriteLogEntry(LogEntryLevel.Error, "Exception in module", ex.ToString());
        return new ModuleRunResult() { Outcome = ExecutionOutcome.Failure };
    }

We now see a simple implementation of processing the input files and returning a valid status based on success or failure of the processing. This should now build correctly and if so, provides you with a DLL that can be installed as a custom module.