Per plugin project setup

To start development of a new MDK plugin, you need to choose a plugin-id. This plugin-id is a unique technical identifier that is used in different places:

  • as name of the plugin project

  • as root C#-namespace for your plugin code

  • as part of the output folder name to where the plugin is deployed

  • as namespace for localization Ids

We recommend a plugin-id following this schema:
<CompanyName>.<PluginName>

The easiest way to set up a new MDK plugin project is to use the DevKit Tools plugin within articy:draft X.

Create Mdk Plugin Menu
Create Mdk Plugin
Provide the plugin-id as "Name of plugin" and the project path where the MDK plugin project should be created.

This generator creates a Visual Studio project pre-configured for the development of a articy:draft X MDK plugin. This includes adding the required Articy.MDK NuGet package.

After opening the project via Visual Studio, please consider reviewing the following files:

Plugin.cs

This file contains the plugin's main class stub. There, you override the methods you need for your plugin's features.
For your plugin to work, it needs to be named Plugin and it needs to extend MacroPlugin.

PluginManifest.xml

Each plugin project needs this file to function. It contains 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 only.

  • Name: required tag, which is already populated with your plugin id

  • Version: contains the plugin's version number; if missing '0.0.0'' is assumed; note that the version must not exceed three digits

  • MinimumArticyVersion: the minimum version of articy:draft that is allowed/required to use that plugin; it is compared to the version number of the ArticyDraft.exe file

  • Properties section: contains two properties that are used to determine if a plugin can be used in single-user and/or multi-user environments.

Note that 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 class.

PluginTexts.tpk

This custom file is only relevant if you plan to deploy your plugin in different languages. It already contains entries for the keys Plugin.DisplayName and Plugin.ContextName to illustrate how to provide values for different languages. Note that the Key value must contain at least one dot (".") to be valid.
For your convenience, you should consider using the free Visual Studio extensions "LocaTools" we offer in order to automatically generate C# constants for your entries in the TPK file. Learn more about this here. 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, the fully qualified "loca identifier" would be "MyComany.ArticyPlugin.Plugin.Name". You can either use that string literal for a lookup, or you can use the generated constant LIds.MyComany.ArticyPlugin.Plugin.Name with full intellisense support.

3rd-party libraries

The NuGet packages also add references to required compile-time/reference assemblies of 3rd-party libaries. Please do not add/package your own copies of them, because they may clash with the ones we ship.

Name

Assembly

Description and Copyrights

JSON.net

Newtonsoft.Json.dll

The most commonly used JSON library.
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

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