# SDK

The **SDK for UDiTH Builder** allows you to create custom plugins that are executed by **UDiTH Builder**.
With these plugins, you can create new attributes and graphics, or read, update, and delete existing ones.

## Working with SDK for UDiTH Builder

### Creating plugins

To develop a custom plugin, you first need to reference the `UDiTHBuilderPlugin.dll` file in your plugin project. Your custom plugin class must implement the `IPluginVersion1` interface and its `BeforeExport` method. This method is then called by UDiTH Builder.

The `PreExportHook` object that is passed as a parameter to `BeforeExport` is the single entry point. It contains various accessors and methods that allow you to create or modify attributes and graphics dynamically. See the API documentation below for details.

## Prerequisites for debugging

If you want to debug your custom plugin, you must adjust both the **Start Action** and the **Build Events** of your project:

### Start action

Enter the path to your `UDiTH Builder` executable file, for example `%ProgramFiles%\CAXperts\UDiTH Builder\UDiTH Builder.exe`.

### Build events

Under **Post-Build Events**, enter the following:

`COPY /Y "$(TargetPath)" "%AppData%\CAXperts\UDiTH Builder\Plugins"`

This is required because UniversalPlantViewer Builder executes every DLL found in the `%AppData%\CAXperts\UDiTH Builder\Plugins` directory.

### Dependencies

If your plugin requires third-party dependencies or other DLL files, you must place them inside a `libs` folder next to your custom plugin DLL files.

![](./media/Builder2_image32.png)

### Running your plugins

Once you have deployed your custom plugin DLLs to the folder in which the SDK looks for plugins, `%AppData%\CAXperts\UDiTH Builder\Plugins`, you can select the plugins to be executed in **Settings -> Plugins**:

![](./media/Builder2_image28.png)

### API

The various accessors described below can be accessed through the `PreExportHook` object that is passed as a parameter to the `BeforeExport` method. The `BeforeExport` method is the single entry point for a custom plugin. A plugin class must implement the `IPluginVersion1` interface and its `BeforeExport` method. This method is then called by the SDK in UDiTH Builder.

#### BuilderContext

The builder context is used for writing log information to the UDiTH Builder output file.

#### void Log
(string message)

Writes a message to the UDiTH Builder output file. Requires a `string` message parameter and returns `void`.

#### void LogError
(string message, Exception e)

Writes a message and an exception to the UDiTH Builder output file. Requires a `string` message and an `Exception` object as parameters and returns `void`.

#### void CancelExecution()

Throws a new `CanceledExecutionException`.

#### void CancelExecution
(string message)

Throws a new `CanceledExecutionException` with the specified message. Requires a `string` message parameter.

#### BuilderElementAccessor

This accessor contains methods for accessing elements and session objects.

#### IEnumerable\<ISession\> Sessions { get; }

This property returns the available session objects as an `IEnumerable<ISession>`.

#### IEnumerable\<IElement\> IterateElements()

Iterates over all elements and returns an `IEnumerable<IElement>`.

#### IElement GetElement
(Guid uid)

Accesses a single element by its `uid`. Requires the `uid` as a parameter and returns either the matching element or `null` if no element is found.

#### IElement CreateElement
(Guid uid, ISession session)

Creates a new builder element. Requires a `uid` and a session object as parameters and returns the newly created element.

#### void DeleteElement
(Guid uid, ISession session)

Completely deletes an existing element, including all its attributes and graphics. Requires the `uid` and the session object of the element as parameters and returns `void`.

#### BuilderAttributeAccessor

Contains various methods for interacting with attributes.

#### IEnumerable\<string\> IterateAttributes()

Iterates over all attribute keys and returns an `IEnumerable<string>`.

#### IEnumerable\<IElement\> FindElementsByAttributes
(string conditionQuery)

Finds all elements that match a given condition. Requires the query condition string as a parameter and returns an `IEnumerable<IElement>`. The query condition has the form `Name=Value`. Several conditions can be combined with an `&` character.

#### void RenameAttribute
(string originalName, string newName)

Changes an attribute key for all elements. Requires the old and new attribute keys as parameters and returns `void`.

#### void DeleteAttribute
(string name)

Completely removes an attribute. Requires the attribute name as a parameter and returns `void`.

#### IDictionary\<string, string\> GetAttributes
(IElement element, HashSet\<string\> attributes = null)

Gets all attributes for a specific element. Requires the element as a parameter and returns a dictionary of attributes. Optionally, a `HashSet<string>` containing the attribute keys to extract can be passed as a second parameter.

#### void AddAttribute
(IElement element, string name, string value)

Adds a new attribute to an existing element. Requires the element, the attribute name, and the attribute value. Returns `void`.

#### void UpdateAttribute
(IElement element, string name, string value)

Updates an existing attribute of an element. Requires the element, the attribute name, and the attribute value. Returns `void`.

#### void RenameAttribute
(IElement element, string oldName, string newName)

Renames an existing attribute of an element. Requires the element, the old attribute name, and the new attribute name. Returns `void`.

#### void DeleteAttribute
(IElement element, string name)

Removes an existing attribute from an element. Requires the element and the attribute name as parameters. Returns `void`.

#### BuilderGraphicAccessor

Contains various methods for getting, creating, and modifying graphics.

#### ISessionTransformation GetSessionTransformation
(ISession session)

Returns the transformation information for the corresponding session object. Requires the session object as an input parameter.

#### IEnumerable\<string\> GetAspects()

Accesses all available aspects and returns an `IEnumerable<string>`.

#### void CreateAspect
(string aspectName)

Creates a new aspect. Requires the new aspect name as a parameter and returns `void`.

#### void DeleteAspect
(string aspectName)

Deletes an existing aspect. Requires the aspect name as input and returns `void`.

#### IEnumerable\<IGraphicElement\> GetGraphics
(IElement element)

Gets all graphic objects of an element. Requires the element as an input parameter and returns an `IEnumerable<IGraphicElement>`.

#### IGraphicElement CreateGraphic
(IElement element, string aspectName, IEnumerable\<string\> primitives)

Creates a new graphic. Requires the element, the aspect name, and the primitives. Returns the newly created graphic element.

#### IEnumerable\<string\> GetPrimitives
(IGraphicElement graphicElement)

Accesses the primitives of a graphic element and returns an `IEnumerable<string>`.

#### void SetPrimitives
(IGraphicElement graphicElement, IEnumerable\<string\> primitives)

Sets the primitives for a graphic element. Requires the graphic element and the new primitives as parameters. Returns `void`.

#### void SetColor
(IGraphicElement graphicElement, Color colour)

Changes the colour of a graphic element. Requires the graphic element and the new colour as parameters. Returns `void`.

#### BuilderLinkAccessor

Used to attach links to elements.

#### ILink CreateLink
(string url, Color colour, string name = null, LinkType type = LinkType.Default)

Creates a new link. Use the returned identifier to register elements to the link.

#### void AddRelation
(ILink link, IElement element)

Registers an element to the link.

#### BuilderDocumentAccessor

Contains methods for registering and linking documents with elements.

#### IDocument CreatePdf
(byte\[\] fileContent, string name, string treePath)

Registers a new PDF file, which is then written to the general output location.

#### void AddRelation
(IDocument document, IElement element)

Links an element to a created document.

#### BuilderIntelliPidElementAccessor

This accessor contains methods for accessing IntelliPid elements and session objects.

#### IEnumerable\<ISession\> Sessions { get; }

This property returns the available session objects as an `IEnumerable<ISession>`.

#### IEnumerable\<IIntelliPidElement\> IterateElements()

Iterates over all elements and returns an `IEnumerable<IIntelliPidElement>`.

#### IIntelliPidElement GetElement
(Guid uid)

Accesses a single element by its `uid`. Requires the `uid` as a parameter and returns either the matching element or `null` if no element is found.

#### BuilderIntelliPidAttributeAccessor

Contains various methods for interacting with IntelliPid attributes.

#### IEnumerable\<string\> IterateAttributes()

Iterates over all IntelliPid attribute keys and returns an `IEnumerable<string>`.

#### IEnumerable\<IIntelliPidElement\> FindElementsByAttributes
(string conditionQuery)

Finds all IntelliPid elements that match a given condition. Requires the query condition string as a parameter and returns an `IEnumerable<IIntelliPidElement>`. The query condition has the form `Name=Value`. Several conditions can be combined with an `&` character.

#### void RenameAttribute
(string originalName, string newName)

Changes an IntelliPid attribute key for all IntelliPid elements. Requires the old and new attribute keys as parameters and returns `void`.

#### void DeleteAttribute
(string name)

Completely removes an IntelliPid attribute. Requires the attribute name as a parameter and returns `void`.

#### IDictionary\<string, string\> GetAttributes
(IIntelliPidElement element, HashSet\<string\> attributes = null)

Gets all IntelliPid attributes for a specific IntelliPid element. Requires the IntelliPid element as a parameter and returns a dictionary of attributes. Optionally, a `HashSet<string>` containing the attribute keys to extract can be passed as a second parameter.

#### void AddAttribute
(IIntelliPidElement element, string name, string value)

Adds a new attribute to an existing IntelliPid element. Requires the IntelliPid element, the attribute name, and the value. Returns `void`.

#### void UpdateAttribute
(IIntelliPidElement element, string name, string value)

Updates an existing attribute of an IntelliPid element. Requires the IntelliPid element, the attribute name, and the value. Returns `void`.

#### void RenameAttribute
(IIntelliPidElement element, string oldName, string newName)

Renames an existing attribute of an IntelliPid element. Requires the IntelliPid element, the old attribute name, and the new attribute name. Returns `void`.

#### void DeleteAttribute
(IIntelliPidElement element, string name)

Removes an existing attribute from an IntelliPid element. Requires the element and the attribute name as parameters. Returns `void`.