Per plugin-project setup |
To start with a new plugin you need to choose a plugin-id. This plugin-id is a unique technical identifier that is used in many different places. Those are:
The name of the plugin project
The root namespace of the plugin
The folder in which the plugin data resides when deploying the plugin
The namespace used for localization Ids
Therefore the best practice is to chose:
<CompanyName>.<PluginName>
After you have chosen the Id, open the New Project dialog and enter the following information:
Name of the project is your chosen Plugin-id
Target Framework is .NET Framework 4
Project Type is Class Library (use WPF Custom Control Library if you want to add own WPF resources like windows or resource dictionaries to your plugin.)
After the project was created you can remove the generated Class.cs file. Then right click on the projects root note to open the context menu to select the "Manage NuGet Packages…".
In the now open package manager dialog, that slightly differs between the different Visual Studio versions search for "articy" and install the package with Id ArticyDraft3.MacroDevKit or Title articy:draft Macro DevKit.
After adding the package the added files are already configured to use the plugin-id where required.
The files that need attention are:
This file contains the plugin's main class stub where you override the methods you need for your
plugin's features. Since this class is declared as private you may implement your methods in an
own partial file.
By convention this class must be called Plugin and needs to be derived from MacroPlugin
, to be found by the plugin loader.
Each plugin needs this file which contains some meta-data about the plugin and is consulted by the
loader to check and validate a plugin. Most of the tags are optional and for display purposes.
Looking at the added file will give you a hint.
The Name is required and is already populated with your plugin id. The Version should
contain an up to three part numeric version number. If missing 0.0 is assumed. The
MinimumArticyVersion is the minimum version of articy:draft that is allowed/required to use that
plugin. You can use up to four parts of the version number and it is compared to the version number
of the ArticyDraft.exe file.
The Properties section contains two properties that are used internally to decide if a plugin can be
used when working in single-user or multi-user environment.
If you want to create a plugin that is suited for multi-user, you need to properly claim and
unclaim partitions or you will get access denied exceptions when trying to change an object.
For single-user plugins it is always allowed to change objects.
You may add own custom properties to this section and query them from your plugin code using the
Manifest.Properties property of your plugin's main class.
This file may contain texts for different UI languages of your plugin and is the file format that
is used throughout articy:draft for its own texts.
You can copy those TextDefinition blocks and change the key accordingly. The Key must
contain at least one dot (".") to be valid.
If you save that file and have the MDK installer allowed to add the Visual Studio integration, the
custom build tool "BuildTextConsts" will be run. It will create a source code file that contains
constants in namespaces/classes that match your localization Id, which are placed into their own
Base-Namespace Lids.
Using this feature allows compile-time safe access to localization. For example: If your plugin is
named MyCompany.ArticyPlugin and you have the loca key Plugin.Name. then the full
qualified loca Id would be MyComany.ArticyPlugin.Plugin.Name. You can either use that Id as
string for a lookup or you can use the code-generated constant LIds.MyComany.ArticyPlugin.Plugin.Name
with full intellisense support.
If your plugin does not require own native assemblies/dlls you should set your platform target
to "AnyCPU". Doing so will allow 32 and 64 Bit users to use your plugin.
To ease packaging and debugging of your plugin you should set your "output path" to something
like bin\Debug\AnyCPU.
For more details please read the chapter Packaging / Deploying your plugin.
The references that were added from "NuGet package manager" reference core articy:draft assemblies
as well as common 3rd party assemblies that were already used from the articy:draft code. Those
assemblies are configured that they do not copy themselves to the output folder, because the plugin
will always use those that were already loaded from the articy:draft process.
Common 3rd Party assemblies are:
Name | Assembly | Description and Copyrights |
---|---|---|
JSON.net | NewtonSoft.Json.dll |
The most commonly free library to work with JSON files/objects. |
SQLite Database | System.Data.SQLite.dll |
A small lightweight SQL database. |
Open XML SDK | DocumentFormat.OpenXml.dll |
The SDK is required to create Microsoft Office documents. |
Closed XML | ClosedXML.dll |
A tool API to work with Microsoft Excel (xlsx) files. Greatly eases the work compared to
directly using the Open XML SDK directly. |