Click or drag to resize

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.)

New Plugin Project

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…".

Manage 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.

Beta Note:
Check or select the option to include "Prereleases". At the time you get this file the package is available at nuget.org and the "Local Repository" from the screenshot is not required.
Select Nu Get Package
This process will add the required assembly references and template source files to your project.

After adding the package the added files are already configured to use the plugin-id where required.

The files that need attention are:

Plugin.cs

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.

PluginManifest.xml

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.

PluginTexts.tpk

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.

Offered as open source at http://www.newtonsoft.com/json under MIT license

SQLite Database

System.Data.SQLite.dll

A small lightweight SQL database.

Offered as public domain at https://system.data.sqlite.org/ under a Microsoft Public license (MS-PL)

Open XML SDK

DocumentFormat.OpenXml.dll

The SDK is required to create Microsoft Office documents.

© Microsoft Corporation

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.

Offered as open source project at https://github.com/ClosedXML/ClosedXML under MIT license