Advanced Dynamo Node Customization
With a foundation knowledge of ZeroTouch already established. this section delves into the advantages of customizing Dynamo nodes to enhance both functionality and user experience. By adding features such as warning messages, informational messages, and custom icons, you can create nodes that are more intuitive, informative, and visually engaging. These customizations not only help users understand potential issues or optimize their workflows but also make your nodes stand out as professional and user-friendly tools.
Customizing nodes is an excellent way to ensure your solutions are clear, reliable, and tailored to meet specific project needs.
Generating Custom Warning Messages Using OnLogWarningMessage
In Dynamo, the OnLogWarningMessage
method provides a way to log warning messages directly to Dynamo's console. This is a powerful feature, especially for Zero Touch nodes, as it allows developers to alert users when there are issues with inputs or parameters that could lead to unexpected behavior. This guide will teach you how to implement OnLogWarningMessage
in any Zero Touch node.
Implementation Steps for OnLogWarningMessage
OnLogWarningMessage
Step 1: Import the Required Namespace
OnLogWarningMessage
is part of the DynamoServices
namespace, so begin by adding this to your project file.
Step 2: Identify When to Log Warnings
Before adding a warning message, consider the logic in your method:
What conditions might cause incorrect or unexpected results?
Are there specific input values or parameters that the method requires to function correctly?
Examples of conditions to check:
Out-of-range values (e.g.,
if (inputValue < 0)
).Null or empty collections (e.g.,
if (list == null || list.Count == 0)
).Data type mismatches (e.g., if a file type is unsupported).
Step 3: Use OnLogWarningMessage
to Log the Warning
OnLogWarningMessage
to Log the WarningPlace OnLogWarningMessage
calls where you detect conditions that could cause issues. When the condition is met, log a warning message that provides clear guidance to the user.
Syntax for OnLogWarningMessage
OnLogWarningMessage
Example Implementations of OnLogWarningMessage
OnLogWarningMessage
To demonstrate OnLogWarningMessage
in action, here are different scenarios you might encounter when building a Zero Touch node.
Example 1: Validating Numeric Inputs
In this example, we'll build upon the custom node created in the previous "Zero-Touch Case Study - Grid Node"; A Method named RectangularGrid
that generates a grid of rectangles based on xCount
and yCount
inputs. We will walk through testing If an input is invalid, and then using OnLogWarningMessage
to log a warning and stop processing.
Using OnLogWarningMessage
for Input Validation
When generating a grid based on xCount
and yCount
. You want to ensure both values are positive integers before proceeding.
In this example:
Condition: If either
xCount
oryCount
is less than or equal to zero.Message:
"Grid count values must be positive integers."
This will show the warning in Dynamo if a user enters zero or negative values, helping them understand the expected input.
Now we know what this looks like, we can implement it into the Grids example node:
Example 2: Checking for Null or Empty Collections
If your method requires a list of points but a user passes an empty or null list, you can use OnLogWarningMessage
to inform them about the issue.
In this example:
Condition: If the
points
list is null or contains fewer than three points.Message:
"Point list cannot be null or have fewer than three points."
This warns users that they need to pass a valid list with at least three points to form a polygon.
Example 3: Verifying File Type Compatibility
For a node that processes file paths, you may want to ensure that only certain file types are allowed. If an unsupported file type is detected, log a warning.
In this example:
Condition: If the file path doesn't end with ".csv".
Message:
"Only CSV files are supported."
This warns users to ensure they are passing a CSV file, helping prevent issues related to incompatible file formats.
Adding Informational Messages with OnLogInfoMessage
OnLogInfoMessage
In Dynamo, OnLogInfoMessage
from the DynamoServices
namespace lets developers log informational messages directly to Dynamo's console. This is helpful for confirming successful operations, communicating progress, or providing additional insights about node actions. This guide will teach you how to add OnLogInfoMessage
in any Zero Touch node to enhance feedback and improve user experience.
Implementation Steps for OnLogInfoMessage
OnLogInfoMessage
Step 1: Import the Required Namespace
OnLogInfoMessage
is part of the DynamoServices
namespace, so begin by adding this to your project file.
Step 2: Identify When to Log Information
Before adding an info message, think about the purpose of your method:
What information would be useful to confirm after an action is completed?
Are there key steps or milestones within the method that users might want to know about?
Examples of useful confirmations:
Completion messages (e.g., when a grid or model is fully created).
Details of processed data (e.g., "10 items processed successfully").
Execution summaries (e.g., parameters used in the process).
Step 3: Use OnLogInfoMessage
to Log Informational Messages
OnLogInfoMessage
to Log Informational MessagesPlace OnLogInfoMessage
calls at meaningful points in your method. When a key step or completion occurs, log an informational message to update the user on what happened.
Syntax for OnLogInfoMessage
OnLogInfoMessage
Example Implementations of OnLogInfoMessage
OnLogInfoMessage
Here are different scenarios to demonstrate using OnLogInfoMessage
in your Zero Touch nodes.
Example 1: Validating Numeric Inputs
In this example, we'll build upon the custom node created in the previous "Zero-Touch Case Study - Grid Node"; A Method named RectangularGrid
that generates a grid of rectangles based on xCount
and yCount
inputs. We will walk through testing If an input is invalid, and then using OnLogInfoMessage
to provide info after the node has completed its run.
Using OnLogInfoMessage
for Input Validation
When generating a grid based on xCount
and yCount
. After generating the grid, you want to confirm its creation by logging an informational message with the grid's dimensions.
In this example:
Condition: The grid creation process has completed.
Message:
"Successfully created a grid with dimensions {xCount}x{yCount}."
This message will inform users that the grid was created as specified, helping them confirm that the node worked as expected.
Now we know what this looks like, we can implement it into the Grids example node:
Example 2: Providing Data Count Information
If you're creating a node that processes a list of points, you might want to log how many points were processed successfully. This can be useful for large datasets.
In this example:
Condition: After the loop completes, showing the count of processed items.
Message:
"6 points were processed successfully."
This message will help users understand the result of the processing and confirm that all points were processed.
Example 3: Summarizing Parameters Used
In some cases, it's useful to confirm the input parameters a node used to complete an action. For example, if your node exports data to a file, logging the file name and path can reassure users that the correct file was used.
In this example:
Condition: The export process completes successfully.
Message:
"Data exported successfully to {filePath}."
This message confirms to users that the export worked and shows the exact file path, helping avoid confusion over file locations.
Creating and Adding Custom Documentation to Nodes
Custom node documentation
Historically, there has been limitations in Dynamo for how package authors could provide documentation for their nodes. Custom Node authors have been restricted to only allowing a short description that displays in the tooltip of the node, or to ship your package with heavily annotated sample graphs.
A new way
Dynamo now offers an improved system for package authors to provide better and more explanatory documentation for your custom nodes. This new approach utilizes the user-friendly Markdown language for text authoring and the Documentation Browser view extension to display the Markdown in Dynamo. Using Markdown gives package authors a wide array of new possibilities when documenting their custom nodes.
What is Markdown?
Markdown is a lightweight markup language that you can use to format plaintext text documents. Since Markdown was created in 2004 it's popularity has only increased and is now one of the most popular markup languages in the world.
Getting started with Markdown
It's easy to start making Markdown files - all you need is a simple text editor, like Notepad, and you're good to go. However, there are easier ways to write Markdown than using Notepad. There are several online editors, such as Dillinger, that let you see your changes in real-time as you make them. Another popular way of editing Markdown files is using a code editor like Visual studio code.
What can Markdown do?
Markdown is very flexible and should provide enough functionality to easily create good documentation - this includes; adding media files like images or videos, creating tables with different forms of content, and of course simple text formatting features like making text bold or italic. All of this and so much more is possible when writing Markdown documents, for more information have a look at this guide which explains the basic Markdown syntax.
Adding extended documentation to your nodes
Adding documentation to your nodes is easy. Documentation can be added to all flavors of custom nodes, covering:
Out of the Box Dynamo Nodes
Custom Nodes (.dyf) - Collections of out of the box and/or other package nodes.
Custom C# Package Nodes (Also known as Zerotouch. These custom nodes look like the out-of-the-box nodes)
NodeModel Nodes (Nodes that contain special UI features such as drop downs or selection buttons)
NodeModel Nodes with Custom UI (Nodes that contain unique UI features such as graphics on the node)
Follow these few steps to get your Markdown files to show inside Dynamo.
Opening documentation files in Dynamo
Dynamo uses the Documentation Browser view extension to display nodes documentation. To open a nodes documentation, right click on the node and select help. This will open up the Documentation Browser and display the Markdown associated with that node, if there is any provided.
The documentation displayed in the Documentation Browser is made up of two parts. The first is the Node Info
section, this is auto generated from the information extracted from the node, such as the inputs/outputs, node category, node name/namespace and the nodes short description. Second part show the custom nodes documentation, which is the Markdown file that is provided to document the node.
Package doc folder
To add documentation files to your nodes in Dynamo, create a new folder in your package directory called /doc
. When your package is loaded, Dynamo will scan this directory and get all of the documentation Markdown files in it.
Naming Markdown files
To make sure Dynamo knows which file to open when requested for a specific node, the naming of the Markdown file needs to be in a specific format. Your Markdown file should be named according to the node it documents' namespace. If you are unsure about the namespace of the node, look at the Node Info
section when you press Help
on the node and under the node name you will see the full namespace of the selected node.
This namespace should be the name of your Markdown file for that particular node. For example the namespace of CustomNodeExample
from above images, is TestPackage.TestCategory.CustomNodeExample
therefore the Markdown file for this node should be named TestPackage.TestCategory.CustomNodeExample.md
In special cases where you have overloads of your nodes (nodes with same name, but different inputs), you will have to add the input names in ()
after the node namespace. For example the built-in node Geometry.Translate
has multiple overloads. In this case we would name the Markdown files for below nodes as follows: Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction).md
Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction,distance).md
Modifying Markdown files while open in Dynamo
To make it easy to modify documentation files, the Documentation Browser implements a File Watcher on the open documentation file. This enables you to make changes to your Markdown file and you will see the changes in Dynamo instantly.
Adding new documentation files can also be done whilst Dynamo is open. Simply add a new Markdown file to the /doc
folder, with a name that corresponds to the node it documents.
Adding Custom Icons to Zero Touch Nodes
Overview
Custom icons for Zero Touch nodes in Dynamo make your nodes visually distinctive and easier to recognize in the Library. By adding bespoke icons, you can make your nodes stand out from the rest, allowing users to quickly identify them in a list.
This guide will show you how to add icons to your Zero Touch nodes.
Steps to Add Custom Node Icons
Step 1: Set Up Your Project
To begin, create a Visual Studio Class Library (.NET Framework) project for your Zero Touch nodes. If you don't already have a project, refer to the Getting Started section for step-by-step instructions on creating one.
Make sure you have at least one functional Zero Touch node, as icons can only be added to existing nodes. For guidance, see the Zero Touch Case Study - Grid Node.
Step 2: Create Your Icon Images
To create custom icons:
Design Your Icons: Use an image editor to create simple, visually clear icons for your nodes.
Image Specifications:
Small Icon: 32x32 pixels (used in the Library's sidebar and on the node itself).
Large Icon: 128x128 pixels (used in the node properties when hovering over the node in the library).
File Naming Convention:
The file names must match the format below to associate them with the correct node:
<ProjectName>.<ClassName>.<MethodName>.Small.png
(for the small icon).<ProjectName>.<ClassName>.<MethodName>.Large.png
(for the large icon).
Example: If your project is ZeroTouchNodeIcons
, your class is Grids
, and your method is RectangularGrid
, the files would be named:
ZeroTouchNodeIcons.Grids.RectangularGrid.Small.png
ZeroTouchNodeIcons.Grids.RectangularGrid.Large.png
Tip: Stick to a consistent design theme across all your icons for a professional look.
Step 3: Add a Resources File to Your Project
To embed your icons into the .dll
, create a resources file:
Add a New Resources File:
Right-click your project in the Solution Explorer.
Go to Add > New Item and select Resources File.
Name the file
<ProjectName>Images.resx
. For example,ZeroTouchNodeIconsImages.resx
.
Clear the Custom Tool Property:
Select the resources file in the Solution Explorer.
In the Properties panel, clear the
Custom Tool
field by removing theResXFileCodeGenerator
value.
NOTE: Failing to clear the "Custom Tool" field will result in Visual Studio converting periods to underscores in your resource names. Please verify before Building that your resource names have periods separating class names rather than underscores.
Step 4: Add Your Images as Resources
Open the resources file using the Managed Resources Editor (Legacy):
If using Visual Studio 17.11 or later, right-click the resources file, choose Open With, and select Managed Resources Editor (Legacy).
If using a Visual Studio version previous to 17.11, double click on the resources file to open with the Resources Editor (which in your version of Visual Studio has not been made legacy yet).
Add your images:
Drag and drop your image files into the editor or use the Add Existing File option.
Update persistence:
Select the images from within the Resources Editor (this will not work if you select them from the Solution Explorer), change the Persistence property in the Properties panel to
Embedded in .resx
. This ensures the images are included in your.dll
.
Step 5: Convert Your Project to SDK-Style
If your project is not already SDK-style (required for embedding resources), convert it:
Install the
.NET Upgrade Assistant
extension from Visual Studio's Extensions > Manage Extensions menu.
Right-click the project in the Solution Explorer and select Upgrade > Convert project to SDK-style.
Wait for the conversion to complete.
Step 6: Add an After-Build Script to Embed Resources
Unload the project:
Right-click the project in the Solution Explorer and select Unload Project.
Edit the
.csproj
file:Add the following
<Target>
element between</ItemGroup>
and</Project>
:
Replace all instances of
ZeroTouchNodeIcons
with your project name.Reload the project:
Right-click the unloaded project and select Reload Project.
Step 7: Build and Load Your .dll into Dynamo
Build the project:
After adding the After-Build script, build your project in Visual Studio.
Check for output files:
Ensure your
.dll
and the.customization.dll
are in thebin
folder.
Add the
.dll
to Dynamo:In Dynamo, use the Import Library button to import your .dll into Dynamo.
Your custom nodes should now appear with their respective icons.
Last updated