oleg-shilo / notepadpluspluspluginpack.net

.Net package to install into visual studio to make plugins for Notepad++

NppPlugin .NET package for VS2015 and beyond...

What is this? Its a simple template for very fast and easy building plugins for Notepad++ in C#/.Net

This is a fork of UFO's plugin package updated for VS2015

Getting started

1. Download a release
2. Place the visual studio project template (the NppPlugin.zip) in the visual studio path (typically "My Documents\Visual Studio 2015\Templates\ProjectTemplates\Visual C#\")
3. Ensure you have installed Visual C++ from the visual studio installer otherwise your project wont build
   
4. Create a new project inside Visual studio using file -> new -> project -> visual C# -> Notepad++ project
5. Build (building will copy the dll to the Notepad++/plugins folder)
6. Start Notepad++ and activate your plugin from the plugins menu

Upgrading to a newer version

• Upgrading the pluging package

  • replacing the NppPluginXXXX.zip from your visual studio (typically "My Documents\Visual Studio 2015\Templates\ProjectTemplates\Visual C#\") with a newer version

• Upgrading plugings using the plugin pack.

  • Delete the folder PluginInfrastructure and copy over that folder from a newer version of NppPluginXXXX.zip
  • Open visual studio
    • Click "show all files" in the "solution explorer"
    • Select the new files, Right-click and choose "include in project"

Plugins using this pluginpack

• https://github.com/kbilsted/NppPluginGuidHelper
• https://github.com/zkirkland/FirstUpper
• https://github.com/kbilsted/NppPluginCutNCopyLine
• https://github.com/kbilsted/NppPluginRebaseAssister
• https://github.com/nea/MarkdownViewerPlusPlus
• https://github.com/AnnaVel/RtfHelper

If your plugin is not on the list, please make a PR with a link to it.. :-)

How to start coding plugins

First read the the demo-plugin code. It is actively being maintaned - see https://github.com/kbilsted/NotepadPlusPlusPluginPack.Net/tree/master/Demo%20Plugin it is a spin-off of Don Ho's http://download.tuxfamily.org/nppplugins/NppPluginDemo/NppPluginDemo.zip

Overall plugin architecture

Plugins can interact with Notepad++ or the underlying Scintilla engine. The plugin pack provides two classes to make this interaction easier. This is NotepadPlusPlusGateway and ScintillaGateWay which are thin layers making interaction more pleasant (and testable!).

If you are interested in low-level access you can use the Win32 api also included in the plugin pack.

The architecture of the plugin is.

               +-----------+ +-----------+
               | Scintilla | | Notepad++ |
               +-----------+ +-----------+
                    ^             ^
                    |             |
           +--------+--------+----+------------+                   
           |                 |                 |
 +------------------+ +----------------+ +-----------+ 
 | ScintillaGateway | | NotepadGateway | | Win32     |
 +------------------+ +----------------+ +-----------+ 
      ^                     ^                ^        
      |                     |                |        
      +-----------------+---+----------------+                   
                        |              
                   +-----------+ 
                   | Plugin    |
                   +-----------+ 

How to debug plugins

• start notepad++
• in Visualstudio: debug -> attach to process... -> notepad++.exe

you can now set breakpoints and step-execute. (currently not working in v6.9.2 notepad-plus-plus/notepad-plus-plus#1964)

• you can make this process easier by setting the "start action" in the project -> properties -> debug to start notepad++.exe - then you can simply build and hit F5.

Working with dependencies

To use external dependencies such as libraries in your plugin you can proceed in two ways:

• clone the dependency sources into your plugin project (e.g. as a shared project)
• add the dependency as reference (i.e. via NuGet) and merge it into the plugin .dll via ILMerge (preferred)

Shared Projects

One possibility is to include dependencies by adding the required source code into a new Shared Project in the plugin-development solution.

Assuming you are using Visual Studio to add a Shared Project to your solution (New Project -> Shared Project) and copy the required sources into that project. Double-check that the Shared Project is part of your main plugin-project references. If not, add the reference. You are now ready to use the included sources in your plugin and they will be compiled into the final plugin .dll.

Note: Do not include properties etc. from other dependencies when copying the sources, as the main project defines the e.g. assembly information.

References

The prefered way to use dependencies is via References, in the best-case through NuGet.

Via NuGet you are able to add packages to your project, certain versions etc. through a global repository. Package information is stored in your project and other developers can gather the same, correct versions through the global repository without committing masses of data.

To use included references in your compiled plugin you need to merge these into the .dll as Notepad++ is not fond of locating non-plugin .dll's in its folder. ILMerge was developed for the purpose of merging managed libraries. It can be installed via NuGet and used manually.

The best way is to install MSBuild.ILMerge.Task via NuGet in your plugin project. It will include ILMerge as dependency and attach itself to your Visual Studio build process. By that, with every build you compile a merged plugin .dll including all your custom references to use. ILMerge will add configuration files to your project: ILMerge.props and ILMergeOrder.txt. Refer to the official homepage for more information about the configuration possibilities.

Note: To use ILMerge in your plugin you have to change the Target Framework of your plugin project to at least .NET Framework 4.0 (CP). ILMerge can work with .NET 3.5 and below, but requires additional configuration and adaptation. If you do not required the extreme backwards compatibility, upgrade the .NET Framework target as quick and easy solution.

Versioning

Until we reach v1.0 expect a bit of chaos and breaking changes.

From v1.0 and onwards we will turn over to semantic versioning

Credits

• For the main work on the plugin package
  • A Guy called "Ufo" - merging in v0.5 http://sourceforge.net/projects/sourcecookifier/files/other%20plugins/NppPlugin.NET.v0.5.zip/download and v0.7 https://bitbucket.org/uph0/npppluginnet
• The DllExport technique:
  • Dark Daskin: http://www.codeproject.com/KB/dotnet/DllExporter.aspx
  • Robert Giesecke: http://sites.google.com/site/robertgiesecke/Home/uploads/csharpprojecttemplateforunmanagedexports https://www.nuget.org/packages/UnmanagedExports

Requirements:

• works with .NET Runtime 3.5 and above (can easily be reduced to .Net runtime 2.0 if needed)
• UNICODE plugins only.

About me

I blog at http://firstclassthoughts.co.uk/ on code readability and quality