Create a new Delta Shell plugin

Exercise outline

The goal of this exercise is to show how a new plugin can be developed using the Delta Shell Application plugin NuGet package. The Delta Shell NuGet package will be used in order to make a quick start. The screenshots included in this whole tutorial may differ, depending on which version of Visual Studio is used. Most of the figures have been created using Visual Studio 2013, and some with Visual Studio 2015. The Community edition of Visual Studio can be used without any problem.

Create a new C# project

Start Visual Studio and create a new C# project (File | New | Project...) by configuring the project wizard as shown in the following image:

 

A new solution will be created with the structure shown in the following figure:

Remove the class added by default, named Class1.cs.

Add the Delta Shell application plugin package to the project using NuGet

A Visual Studio extension called NuGet will be used to add the Delta Shell application plugin package to the newly created project.

We must now indicate the location from which the NuGet manager should retrieve the Delta Shell application plugin package. This can be done, by opening the options of Visual studio (click TOOLS | Options) and then browsing to the section Package Sources in the settings for the NuGet Package Manager.

This package is automatically built on a TeamCity build server. We can retrieve it directly from that build server. If we decide to call this source, for example, TeamCityAuth, in the Package Sources, add a new source by using the + button with the following information :

It is also possible to use the package if it is locally saved in the computer, in a folder of your system. In this case, the source would be the folder in the computer in which the NuGet package files can be found. We can call this source Local Packages. For example, according to the figure below:

Once it has been set up where the NuGet package for Delta Shell application plugin can be found, this package needs to be installed in the solution that we have created at the beginning of this tutorial. In order to do this, open the NuGet package manager (right click the solution | Manage NuGet Packages for Solution...) and search for the Delta Shell application plugin package in the source that you want to use. For example, if you select tyhe source called TeamCityAuth, shown in a solid blue line in the left of the figure, Visual Studio will contact the build server specified above, and it will show the available packages in there:

Alternatively, if you want to use your local source, simply select the previously indicated feed source, Local packages in a dashed line in the figure above.

In other versions of Visual Studio, the interface can be slightly different, for example in VS 2015, the source of the packages can be found in a drop down menu on the NuGet Solution view (highlighted in orange):

In either case, proceed to install the Delta Shell Application plugin onto the solution.

In Visual Studio 2013, you will be asked to select the project into which you want to INSTALL the NuGet package. Select Deltashell.Plugins.VolumeModel :

If asked for confirmation, respond affirmatively to complete the installation of the packages. NuGet will now either contact the server and then download the Delta Shell framework package, or retrieve it from the local folder. Then, it will run the corresponding install scripts to configure your project for use as a Delta Shell plugin. This whole process may take a while.

After installing the package your project will look something like this :

Remove PostSharp from project

During the installation of the Delta Shell application plugin, you might be asked to install PostSharp. PostSharp needs a license and is mostly used for automatically adding code for property and collection changed events and event bubbling. In this tutorial we will not use this functionality. So, if asked, you can cancel the installation of PostSharp. As indicated in the figure above, another possibility is that you are indirectly requested to install PostSharp by Visual Studio by the file RequiresPostSharp.cs added to the solution.

In order to fully remove PostSharp from the solution, do the following :

1. Remove PostSharp reference and, if present, the file RequiresPostSharp.cs from the project (selected items in figure above).
2. Open packages.config and remove the reference to PostSharp. The exact syntax will depend on the version of the .NET framework you are working with, and the corresponding version of PostSharp available at the moment of following this tutorial. So the reference could be, for example:
   <package id="PostSharp" version="2.1.7.28" targetFramework="net40" />
   or
   <package id="PostSharp" version="3.1.75" targetFramework="net452" />
3. Remove all other references to PostSharp in the project:
   1. Unload the project (right click on project - Unload project)
   2. Edit project file (right click on project - Edit DeltaShell.Plugins.VolumeModel.csproj)

   3. Remove all lines indicating that PostSharp should be imported in the project. These lines are frequently located close to the end of the csproj file. For example:

      <Import Project="..\packages\PostSharp.2.1.7.28\tools\PostSharp.targets" Condition="Exists('..\packages\PostSharp.2.1.7.28\tools\PostSharp.targets')" />

      
      or

      <Import Project="..\packages\PostSharp.3.1.75\tools\PostSharp.targets" Condition="Exists('..\packages\PostSharp.3.1.75\tools\PostSharp.targets')" />
        <Target Name="EnsurePostSharpImported" BeforeTargets="BeforeBuild" Condition="'$(PostSharp30Imported)' == ''">
          <Error Condition="!Exists('..\packages\PostSharp.3.1.75\tools\PostSharp.targets')" Text="This project references NuGet package(s) that are missing on this computer. Enable NuGet Package Restore to download them.  For more information, see http://www.postsharp.net/links/nuget-restore." />
          <Error Condition="Exists('..\packages\PostSharp.3.1.75\tools\PostSharp.targets')" Text="The build restored NuGet packages. Build the project again to include these packages in the build. For more information, see http://www.postsharp.net/links/nuget-restore." />
        </Target>

      
      The exact lines to be removed will depend on the version of Visual Studio being used, and on the version of PostSharp that was incorporated to the project.

   4. Finally, load project back again.

Set startup project

The code being written during this tutorial cannot be directly invoked as start up program. The GUI of Delta Shell must be assigned as the start up executable file. This will on its turn call all plug ins in the framework, as well as the one we are developing in this tutorial. In order to change this setting, start by building the project. This action will copy DeltaShell to the bin folder next to your solution file (for example, D:\VolumeModel\bin)
Now open the project properties, and go to the debug page to change the startup program to the location of the executable file for the GUi of Delta Shell, for example D:\VolumeModel\bin\Debug\DeltaShell\DeltaShell.Gui.exe.

Select the radio button Start external program, and indicate the path to the executable file for the GUI of Delta Shell in the corresponding field.

Create an application plugin class

Add a new class named VolumeModelApplicationPlugin to the project. Use the code underneath in that file to describe the application part of the plugin:

using DelftTools.Shell.Core;
using Mono.Addins;

namespace DeltaShell.Plugins.VolumeModel
{
    [Extension(typeof(IPlugin))]
    public class VolumeModelApplicationPlugin : ApplicationPlugin
    {
        public override string Name
        {
            get { return "VolumeModelApplication"; }
        }
        public override string DisplayName
        {
            get { return "Volume model application"; }
        }
        public override string Description
        {
            get { return "Application plugin of the volume model application"; }
        }
        public override string Version
        {
            get { return "1.0"; }
        }
        public override string FileFormatVersion
        {
            get { return "1.0"; }
        }
    }
}

Create a GUI plugin class

Now, create a new class called VolumeModelGuiPlugin to the project and add the following code describing Gui part of the plugin:

using DelftTools.Shell.Core;
using DelftTools.Shell.Gui;
using Mono.Addins;
namespace DeltaShell.Plugins.VolumeModel
{
    [Extension(typeof(IPlugin))]
    public class VolumeModelGuiPlugin : GuiPlugin
    {
        public override string Name
        {
            get { return "VolumeModelApplicationUI"; }
        }
        public override string DisplayName
        {
            get { return "Volume model application (UI)"; }
        }
        public override string Description
        {
            get { return "Gui plugin of the volume model application"; }
        }
        public override string Version
        {
            get { return "1.0"; }
        }
        public override string FileFormatVersion
        {
            get { return "1.0"; }
        }
    }
}

To get the code above to work, we still need to add a reference to DelftTools.Shell.Gui in the project.

The dll referred to can be found inside the folder packages of the project. The exact location will depend on your system:

Exercise results

You should now be able to build the solution, and start up Delta Shell from Visual Studio. Once the application is up and running, open the Plugins window (File | Plugins ). Check that both the Volume model application plugin and the Volume model application (UI) plugin are visible in the overview of loaded plugins. This means they have been properly loaded into Delta Shell:

You can now start specifying the functionality of this new plugin.