Dynamo Application Integration Guide

Who Is This Document For?

This document is for application engineers interested in building an integration with Dynamo. It provides high level documentation of each of the pieces of the Dynamo architecture which deal with things like transaction management, element binding, and document interaction. Each component has reference example code. Most of these examples refer to the Dynamo for Revit repository, as it was the first application integration developed with Dynamo. But the examples can be easily extrapolated to work with other applications.

Sections

• Why Do a Dynamo Integration?
• Can My Application Integrate with Dynamo?
• Integration Components
  • Dynamo Model
  • Element Binder
  • Element Id Lifecycle Manager
  • Transaction Manager
• Scheduler Thread
• Element Updater
• Elements
• Geometry
• Units

Why Do a Dynamo Integration?

Integrating Dynamo with your application allows your users to experiment with your API using a visual programming language. By using a visual programming environment, you invite even those users who have never written source code to experiment with your API. As those users gain proficiency, and want to further extend Dynamo, they might want to try scripting in python or compiling their own "zero touch" node libraries using any .net language. Because the Dynamo Workspace is compiled to Design Script, users can also experiment with turning their nodes into code, enhancing their understanding of how code is generated from the visual programming interface.

Can My Application Integrate with Dynamo?

An application can integrate with Dynamo using the components described here-in if:

• It has a .net API. This is not a hard and fast rule as we also have a version of Dynamo that runs on the mono run-time as a service, and can therefore be called from any application on any platform. If you have a cross-platform application or web service that would like to use Dynamo as a Service, please contact @ikeough for more information.
• It provides notifications when elements are added, removed, or modified in the document.
• It exposes unique ids for elements. Unique ids are required to bind nodes in Dynamo to the elements which they create.
• It has persistent storage of elements. Dynamo can create, delete, and modify elements in the document, provided APIs exist to do so, but does not store elements for your application.
• (Optional) Allows rendering data created in Dynamo to be injected into the application's scene. This is useful for drawing transient geometry in context in your application.

Integration Components

Dynamo Model

The DynamoModel is the core component of any Dynamo application integration. A DynamoModel contains a collection of Workspaces and has an EngineController for executing those Workspaces using the Design Script Virtual Machine. The first thing your application integration will do is construct an instance of DynamoModel.

For an example of constructing a DynamoModel, see Dynamo for Revit's example.

Element Binder

Dynamo allows for two-way interaction between the visual programming environment and the application. For example, you can build functionality in your application integration which allows a user to select an element in the document, and have Dynamo "bind" that element to a node in the workspace. The element binder generates serializable Ids from your documents' elements, and manages the storage and retrieval of those ids during execution.

• These bound element ids are used by CallsiteData objects. CallsiteData instances are serialized to the .dyn file allowing re-loading of CallsiteData objects at startup. This allows Dynamo to re-bind to elements in your document.
• The element binder is used during construction and disposal of instances of element wrapper types.
• Between executions, Dynamo disposes of all references to wrapper types. You must use the element binder to maintain an association between an element and a call site between executions.

For an example, see Dynamo for Revit's ElementBinder class.

Element Id Lifecycle Manager

The ElementIdLifecycleManager class is a singleton which keeps track of elements in the model that have been deleted.

• The manager uses reference counting to ensure that an Element is not deleted from the document if other references to the element still exist.

For an example, see Dynamo for Revit's ElementIdLifeCycleManager class.

Transaction Manager

The TransactionManager class is a singleton which is responsible for opening and closing transactions in your application as necessary to support batch operations on the application’s API.

• Dynamo tries to minimize the number of transactions that are created during execution. To do this, the transaction manager opens a transaction at the start of execution and subsequent method calls during execution use that open transaction.
• Allows for the active transaction to be forced closed, and a new transaction started, if your API requires this.

For an example, see Dynamo for Revit's TransactionManager class.

Scheduler Thread

The ISchedulerThread interface provides the contract for classes which implement threading logic for Dynamo.

• When Dynamo is running in "stand alone" mode, the scheduler creates a thread to be used by an ISchedulerThread implementation. This allows for execution to be on a separate thread from the UI.
• When running in an application like Revit, where API calls are only permitted on the application's main thread, an ISchedulerThread implementation can be made to use that thread.

For an example ISchedulerThread implementation see Dynamo for Revit's RevitSchedulerThread class.

Element Updater

The element updater is a class which listens for document modification events from the application and raises corresponding events in Dynamo.

• Supports element addition, modification, and deletion.

For an example of an element updater, see the RevitServicesUpdaterclass.

Elements

The Element class is a wrapper for an underlying base class representing an object in your document.

• Element classes provide application-integration, like element binding, and transaction manager in the base class.
• Element classes wrap your APIs' constructors in static constructor methods.
  • Makes node names more "dynamo-like" (i.e. Point.ByCoordinates).
  • Adds error handling logic before the API constructor method is called to reduce fragility when called from the graph.
• Allows for auto-generation of node libraries which use the shared based class. For a proposal on auto-wrapping an API see https://github.com/DynamoDS/DynamoRevit/issues/975.

Geometry

The underlying geometry library for Dynamo, LibG, is an ASM-backed implementation of ProtoGeometry. In order to normalize geometry that is used in Dynamo, Dynamo converts geometry from your application's geometry library type into a ProtoGeometry equivalent. Your application must have APIs for building things like brep surfaces, and solids, or have an ability to ingest native ASM geometry.

For an example of a converter implementation which converts Revit geometry objects to Dynamo geometry, see the GeometryObjectConverter class.

Units

Dynamo is unit-less. Geometry will be created in whatever units your API provides. If you would like those units to be scaled, for instance, in the "UI" units, your application must provide an API which gets the unit type in the interface, and provides a conversion factor, so that the conversion can be done as data goes in, and come out of, Dynamo.

For an example of unit conversion, see the UnitConverter class.