Zero-Touch の基礎知識についてはすでに説明されているため、このセクションでは、機能性とユーザの操作性の両方を向上させるために、Dynamo ノードをカスタマイズする利点を詳しく説明します。警告メッセージ、情報メッセージ、カスタム アイコンなどの機能を追加することで、より直感的で情報量が多く、視覚的に魅力のあるノードを作成できます。カスタマイズすることにより、ユーザが潜在的な問題を理解したり、ワークフローを最適化したりするのに役立つだけではなく、ノードの専門性を際立たせたわかりやすいノードにすることができます。
ノードのカスタマイズは、ソリューションが明確で信頼性が高く、特定のプロジェクト ニーズを満たすように調整されていることを確認するための優れた方法です。
Dynamo では、OnLogWarningMessage
メソッドは、警告メッセージを Dynamo のコンソールのログに直接記録する手段を提供します。これは、予期しない動作につながる可能性のある入力やパラメータに問題があるときに、開発者がユーザに警告できるため、特に Zero-Touch ノードにとって強力な機能です。このガイドでは、任意の Zero-Touch ノードに OnLogWarningMessage
を実装する方法について説明します。
OnLogWarningMessage
の実装手順OnLogWarningMessage
は DynamoServices
名前空間の一部であるため、まずプロジェクト ファイルに追加するところから始めます。
警告メッセージを追加する前に、メソッド内のロジックを検討します。
どのような条件で、不正確または予期しない結果が生じる可能性が生じるか。
メソッドが正しく機能するために必要な特定の入力値またはパラメータは存在するか。
確認する条件の例:
範囲外の値(例: if (inputValue < 0)
)。
null または空のコレクション(例: if (list == null || list.Count == 0)
)。
データ タイプの不一致(ファイルの種類がサポートされていない場合など)。
OnLogWarningMessage
を使用して警告をログに記録する問題を引き起こす可能性のある条件を検出する OnLogWarningMessage
呼び出しを実行します。条件が満たされた場合、ユーザに明確なガイダンスを提供する警告メッセージをログに記録します。
OnLogWarningMessage
の構文OnLogWarningMessage
の実装例実際の OnLogWarningMessage
の動作を示すために、ここで Zero-Touch ノードをビルドする際に遭遇する可能性のあるさまざまなシナリオを示します。
この例では、以前の「Zero-Touch ケース スタディ - グリッド ノード」で作成したカスタム ノードに基づいてビルドします。xCount
入力と yCount
入力に基づいて長方形のグリッドを生成する RectangularGrid
という名前のメソッドです。入力が無効かどうかをテストし、次に OnLogWarningMessage
を使用して警告をログに記録し、処理を停止する手順を説明します。
入力の検証に OnLogWarningMessage
を使用する
xCount
と yCount
に基づいてグリッドを生成する場合です。続行する前に、両方の値が正の整数であることを確認します。
この例の場合は、次のようになります。
条件: xCount
または yCount
が 0 以下の場合。
メッセージ: "Grid count values must be positive integers."
これにより、ユーザーがゼロまたは負の値を入力した場合に Dynamo に警告が表示され、必要な入力を理解しやすくなります。
ここで、Grids サンプル ノードの実装に進みます。
例 2: null または空のコレクションを確認する
点のリストが必要なメソッドであるにも関わらず、ユーザが空または null のリストを渡した場合は、OnLogWarningMessage
を使用して問題を通知できます。
この例の場合は、次のようになります。
条件: points
リストが null または含まれる点が 3 つ未満の場合。
メッセージ: "Point list cannot be null or have fewer than three points."
これは、ポリゴンを形成するには少なくとも 3 つの点を含む有効なリストを渡す必要があることをユーザに警告しています。
例 3: ファイル タイプの互換性を検証する
ファイル・パスを処理するノードでは、特定のファイル・タイプのみが許可されるようにしたい場合があります。サポートされていないファイル タイプが検出された場合は、警告をログに記録します。
この例の場合は、次のようになります。
条件: ファイル パスが「.csv」で終わらない場合。
メッセージ: "Only CSV files are supported."
これにより、CSV ファイルを確実に渡すようにユーザに警告し、互換性のないファイル形式に関連する問題を防ぐことができます。
OnLogInfoMessage
による情報メッセージを追加するDynamo では、DynamoServices
名前空間の OnLogInfoMessage
により、開発者は情報メッセージを Dynamo のコンソールに直接記録できます。これは、操作が成功したことの確認、進行状況の伝達、またはノード アクションに関する追加の分析情報の提供に役立ちます。このガイドでは、Zero-Touch ノードに OnLogInfoMessage
を追加してフィードバックを強化し、ユーザの操作性を向上させる方法を説明します。
OnLogInfoMessage
の実装手順OnLogInfoMessage
は DynamoServices
名前空間の一部であるため、まずプロジェクト ファイルに追加するところから始めます。
情報メッセージを追加する前に、メソッドの目的について検討します。
アクションが完了後に確認すると役立つ情報とは何か。
ユーザが知りたいと思うような重要な手順やマイルストーンがメソッド内に存在するか。
役立つ確認の例:
完了メッセージ(例: グリッドまたはモデルが完全に作成されたとき)。
処理されたデータの詳細(例:「10 項目が正常に処理されました」)。
実行の要約(例: プロセスで使用されたパラメータ)。
OnLogInfoMessage
を使用して情報メッセージをログに記録するメソッド内の意味のあるポイントに OnLogInfoMessage
呼び出しを実行します。主要な手順または完了が発生したら、何が起こったかをユーザに知らせるために情報メッセージをログに記録します。
OnLogInfoMessage
の構文OnLogInfoMessage
の実装例ここでは、Zero-Touch ノードで OnLogInfoMessage
を使用する際の異なるシナリオを示します。
この例では、以前の「Zero-Touch ケース スタディ - グリッド ノード」で作成したカスタム ノードに基づいてビルドします。xCount
入力と yCount
入力に基づいて長方形のグリッドを生成する RectangularGrid
という名前のメソッドです。入力が無効かどうかをテストし、ノードの実行が完了した後に、OnLogInfoMessage
を使用して情報を提供する方法について説明します。
入力の検証に OnLogInfoMessage
を使用する
xCount
と yCount
に基づいてグリッドを生成する場合です。グリッドを生成した後、グリッドの寸法を含む情報メッセージをログに記録して、グリッドの作成を確認します。
この例の場合は、次のようになります。
条件: グリッドの作成処理が完了している。
メッセージ: "Successfully created a grid with dimensions {xCount}x{yCount}."
このメッセージで、グリッドが指定どおりに作成されたことをユーザに通知し、ノードが想定どおりに機能したことを確認することができます。
ここで、Grids サンプル ノードの実装に進みます。
点のリストを処理するノードを作成するときに、正常に処理された点の数をログに記録したい場合があります。これは、大規模なデータセットに役立ちます。
この例の場合は、次のようになります。
条件: ループが完了した後、処理された項目の数を表示する。
メッセージ: "6 points were processed successfully."
このメッセージは、ユーザが処理の結果を理解し、すべての点が処理されたことを確認するのに役立ちます。
場合によっては、ノードがアクションを完了するために使用した入力パラメータを確認すると有効なことがあります。たとえば、ノードがデータをファイルにエクスポートする場合、ファイル名とパスをログに記録することで、正しいファイルが使用されたことをユーザに知らせることができます。
この例の場合は、次のようになります。
条件: エクスポート処理が正常に完了している。
メッセージ: "Data exported successfully to {filePath}."
このメッセージは、エクスポートが機能したことをユーザに知らせて正確なファイル パスを表示するため、ファイルの場所に関する混乱を避けることができます。
これまで、Dynamo では、パッケージ作成者がノードのドキュメントを提供する方法に制限がありました。カスタム ノードの作成者は、ノードのツールチップに表示する簡単な説明のみが許可されていたり、大量の注釈が付いたサンプル グラフを含むパッケージを出荷するように制限されていました。
Dynamo のシステムが改善され、パッケージ作成者はカスタム ノードに関してより適切で詳細なドキュメントを提供できるようになりました。この新しいアプローチでは、テキストのオーサリングに使いやすい Markdown 言語を使用し、Dynamo で Markdown を表示するためのドキュメント ブラウザのビュー拡張機能を利用します。Markdown を使用すると、パッケージ作成者はカスタム ノードをドキュメント化する際の可能性が広がります。
Markdown は、プレーンテキスト ドキュメントの書式設定に使用できる軽量のマークアップ言語です。Markdown が 2004 年に作成されて以来、その人気は高まり続け、現在では世界で最も人気のあるマークアップ言語の 1 つとなっています。
Markdown ファイルの作成を開始するのは簡単です。準備に必要なのはメモ帳などのシンプルなテキスト エディタのみです。ただし、メモ帳を使用するよりも簡単な Markdown の記述方法があります。Dillinger などのオンライン エディタを使用すると、変更しながらリアルタイムでその内容を確認できます。Markdown ファイルを編集するもう 1 つの一般的な方法は、Visual Studio Code などのコード エディタを使用することです。
Markdown は非常に柔軟性が高く、優れたドキュメントを簡単に作成するのに十分な機能を備えています。画像やビデオなどのメディア ファイルの追加や、さまざまな形式のコンテンツを含むテーブルの作成が可能です。もちろん、テキストに太字や斜体の書式を設定するシンプルな機能もあります。Markdown ドキュメントを記述する際は、これらすべて、およびさらに多くのことができますが、詳細については、基本的な Markdown 構文を説明しているこちらのガイドをご覧ください。
ノードにドキュメントを追加するのは簡単です。ドキュメントは、すべての種類のカスタム ノードに追加可能で、以下の内容に対応します。
すぐに使用できる Dynamo ノード
カスタム ノード(.dyf) - すぐに使用できるノードやその他のパッケージ ノードのコレクション。
カスタム C# パッケージ ノード(Zero-Touch とも呼ばれます。これらのカスタム ノードは、初期設定のままのノードと同様に見えます)
NodeModel ノード(ドロップ ダウンや選択ボタンなどの特殊な UI 機能を含むノード)
カスタム UI を持つ NodeModel ノード(ノード上のグラフィックスなど固有の UI 機能を含むノード)
Markdown ファイルを Dynamo 内に表示するには、次の手順に従います。
Dynamo では、ドキュメント ブラウザのビュー拡張機能を使用してノード ドキュメントを表示します。ノードのドキュメントを開くには、ノードを右クリックして[ヘルプ]を選択します。これによりドキュメント ブラウザが開き、そのノードに関連付けられている Markdown があれば表示されます。
ドキュメント ブラウザに表示されるドキュメントは 2 つの部分から構成されています。1 つ目は Node Info
セクションで、入力/出力、ノード カテゴリ、ノード名/名前空間、ノードの簡単な説明など、ノードから抽出された情報から自動生成されます。2 つ目には、ノードをドキュメント化するために提供される Markdown ファイルであるカスタム ノードのドキュメントが表示されます。
Dynamo のノードにドキュメント ファイルを追加するには、パッケージ フォルダに /doc
という名前の新しいフォルダを作成します。パッケージがロードされると、Dynamo によってこのフォルダがスキャンされ、すべてのドキュメントの Markdown ファイルが取得されます。
特定のノードに対して要求されたときに開くファイルを Dynamo が認識できるようにするには、Markdown ファイルに特定の形式で名前を付ける必要があります。Markdown ファイルには、ドキュメント化されたノードの名前空間に従って名前を付ける必要があります。ノードの名前空間が不明な場合は、ノード上で Help
を押して Node Info
セクションを開きます。ノード名の下に、選択したノードの完全な名前空間が表示されます。
この名前空間は、その特定のノードの Markdown ファイルの名前です。たとえば、上の画像の CustomNodeExample
の名前空間は TestPackage.TestCategory.CustomNodeExample
であるため、このノードの Markdown ファイルの名前は TestPackage.TestCategory.CustomNodeExample.md
になります。
ノード(同じ名前で入力が異なるノード)のオーバーロードがあるといった特殊なケースにおいては、ノードの名前空間の後に入力名を ()
で囲んで追加する必要があります。たとえば、組み込みノード Geometry.Translate
に複数のオーバーロードがあるとします。この場合、以下に示すノードの Markdown ファイルの名前は次のようになります。Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction).md
Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction,distance).md
ドキュメント ファイルを簡単に変更できるように、ドキュメント ブラウザには、開いているドキュメント ファイルに対するファイル ウォッチャーが実装されています。これにより、Markdown ファイルに変更を加え、その変更を Dynamo ですぐに確認できます。
新しいドキュメント ファイルの追加は、Dynamo が開いているときにも行うことができます。新しい Markdown ファイルを /doc
フォルダに追加し、ドキュメント化されたノードに対応する名前を付けるだけです。
Dynamo の Zero-Touch ノードのカスタム アイコンを使用すると、ノードを視覚的に区別し、ライブラリで認識しやすくなります。カスタムのアイコンを追加することで、ノードを他のノードよりも目立たせることができ、ユーザはリストでノードをすばやく識別できるようになります。
このガイドでは、Zero-Touch ノードにアイコンを追加する方法について説明します。
まず、Zero-Touch ノード用の Visual Studio クラス ライブラリ(.NET Framework)プロジェクトを作成します。プロジェクトがまだ作成されていない場合は、「スタートアップ」セクションを参照して、プロジェクトを作成するための手順ごとの説明を確認してください。
アイコンは既存のノードにのみ追加できるため、機能する Zero-Touch ノードが少なくとも 1 つあることを確認してください。ガイダンスについては、「Zero-Touch ケース スタディ - グリッド ノード」を参照してください。
カスタム アイコンを作成する手順は次のとおりです。
アイコンを設計する: 画像エディタを使用して、シンプルで視覚的にわかりやすいノードのアイコンを作成します。
画像の仕様:
小さいアイコン: 32 x 32 ピクセル(ライブラリのサイドバーとノード自体で使用)。
大きいアイコン: 128 x 128 ピクセル(ライブラリ内のノードにカーソルを合わせる際にノード プロパティで使用)。
ファイル命名規則:
ファイル名を正しいノードに関連付けるには、ファイル名が次の形式と一致している必要があります。
<ProjectName>.<ClassName>.<MethodName>.Small.png
(小さいアイコンの場合)。
<ProjectName>.<ClassName>.<MethodName>.Large.png
(大きいアイコンの場合)。
例: プロジェクトが ZeroTouchNodeIcons
、クラスが Grids
、メソッドが RectangularGrid
の場合、ファイル名は次のようになります。
ZeroTouchNodeIcons.Grids.RectangularGrid.Small.png
ZeroTouchNodeIcons.Grids.RectangularGrid.Large.png
ヒント: 専門性の高い外観にするには、すべてのアイコンで一貫した設計テーマを使用してください。
アイコンを .dll
に埋め込むには、リソース ファイルを作成します。
新しいリソース ファイルを追加する:
[ソリューション エクスプローラ]でプロジェクトを右クリックします。
**[追加] > [新規アイテム]**に移動し、[リソース ファイル]を選択します。
ファイル名を <ProjectName>Images.resx
にします。たとえば、ZeroTouchNodeIconsImages.resx
などです。
カスタム ツールのプロパティをクリアする:
[ソリューション エクスプローラ]でリソース ファイルを選択します。
[プロパティ]パネルで、ResXFileCodeGenerator
値を削除して Custom Tool
フィールドをクリアします。
注: [カスタム ツール]フィールドをクリアしないと、Visual Studio によってリソース名のピリオドがアンダースコアに変換されます。**ビルドする前に、リソース名にアンダースコアではなくクラス名を区切るピリオドが含まれていることを確認してください。
[リソース エディタを管理(旧式)]を使用してリソース ファイルを開きます。
Visual Studio 17.11 以降を使用している場合は、リソース ファイルを右クリックし、[開く]を選択し、[リソース エディタを管理(旧式)]を選択します。
17.11 より前のバージョンの Visual Studio を使用している場合は、リソース ファイルをダブル クリックして、リソース エディタで開きます(Visual Studio のバージョンではまだ旧式になっていません)。
![リソース エディタを管理(旧式)]でリソース ファイルを開く
画像を追加します。
イメージ ファイルをエディタにドラッグしてドロップするか、[既存のファイルを追加]オプションを使用します。
パーシスタンスを更新します。
リソース エディタ内から画像を選択し(ソリューション エクスプローラから画像を選択した場合は機能しません)、[プロパティ]パネルの[パーシスタンス]プロパティを Embedded in .resx
に変更します。これにより、画像が確実に .dll
に含まれるようになります。
プロジェクトがまだ SDK スタイルではない場合は、リソースの埋め込みに必要なため変換します。
Visual Studio の**[拡張機能] > [拡張機能の管理]**メニューから .NET Upgrade Assistant
拡張機能をインストールします。
[ソリューション エクスプローラ]でプロジェクトを右クリックし、[アップグレード] > [プロジェクトを SDK スタイルに変換]を選択します。
変換が完了するのを待ちます。
プロジェクトをロード解除します。
[ソリューション エクスプローラ]でプロジェクトを右クリックし、[プロジェクトをロード解除]を選択します。
.csproj
ファイルを編集します。
</ItemGroup>
と </Project>
の間に次の <Target>
要素を追加します。
ZeroTouchNodeIcons
のすべてのインスタンスをプロジェクト名に置き換えます。
プロジェクトを再ロードします。
ロードされていないプロジェクトを右クリックし、[プロジェクトを再ロード]を選択します。
プロジェクトをビルドします。
ビルド後のスクリプトを追加したら、Visual Studio でプロジェクトをビルドします。
出力ファイルを確認します。
.dll
と .customization.dll
が bin
フォルダにあることを確認します。
.dll
を Dynamo に追加します。
Dynamo では、[ライブラリを読み込む]ボタンを使用して、.dll を Dynamo に読み込みます。
カスタム ノードがそれぞれのアイコンとともに表示されるはずです。