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 should be created with the structure shown in the following figure:
The default class added, named Class1.cs, must be removed.
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.
General information about NuGet can be found at http://docs.nuget.org/.
Information on how to install NuGet as a Visual Studio extension can be found at http://docs.nuget.org/docs/start-here/installing-nuget.
As of Visual Studio 2013, NuGet is installed by default. However, you have to make sure that it is updated to the latest version by checking the Extension and Updates window (click TOOLS | Extensions and Updates... | Updates | Visual Studio Gallery). If a previous version is used, installing the Delta Shell application plugin package might result in the following error:
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 :
Name | TeamCityAuth |
Source | http://build.deltares.nl/httpAuth/app/nuget/v1/FeedService.svc/ |
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:
Name | Local Packages |
Source | D:\localNuGet |
Once it has been set up where the NuGet package for Delta Shell application pluginm 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 Shel Application plugin onto the solutiion.
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 :
- Remove PostSharp reference and, if present, the file RequiresPostSharp.cs from the project (selected items in figure above).
- 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" /> - Remove all other references to PostSharp in the project:
- Unload the project (right click on project - Unload project)
- Edit project file (right click on project - Edit DeltaShell.Plugins.VolumeModel.csproj)
Remove (near the end of the csproj) all references to PostSharp. 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<DontImportPostSharp>True</DontImportPostSharp> ... <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 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.- Finally, load project back again.
Set startup project
Start building the project. This will copy DeltaShell to the bin folder next to your solution file (D:\VolumeModel\bin)
Now open the project properties and go to the debug page and change set the startup program to : D:\VolumeModel\bin\Debug\DeltaShell\DeltaShell.Gui.exe
Create an application plugin class
Add a class named VolumeModelApplicationPlugin to the project and add the following code describing 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"; } } } }
Created a GUI plugin class
Create a class named 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 need to add a reference to DelftTools.Shell.Gui in the project.
The dll referred to can be found in the folder packages of the project:
Set local copy of reference to False
Important: Once the reference has been added, set the Copy Local property of the DelftTools.Shell.Gui reference to False. The DeltaShell framework will have already copied it to the bin, so we do not need to copy the DelftTools.Shell.Gui.dll to our plugin folder.
Exercise results
Run the application and 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: