Unabhängig vom Kenntnisstand ist die Dynamo-Plattform dafür konzipiert, dass alle Benutzer ihre Beiträge leisten können. Es gibt mehrere Entwicklungsoptionen, die auf unterschiedliche Fähigkeiten und Qualifikationen ausgerichtet sind und je nach Ziel alle ihre Stärken und Schwächen haben. Nachfolgend werden die verschiedenen Optionen und die Möglichkeiten zur Auswahl einer Option erläutert.

Drei Entwicklungsumgebungen: Visual Studio, Python Editor und Code Block DesignScript

Welche Optionen stehen zur Auswahl?

Die Entwicklungsoptionen für Dynamo lassen sich primär in zwei Kategorien einteilen: für Dynamo im Vergleich zu in Dynamo. Sie können sich die beiden Kategorien folgendermaßen vorstellen: In Dynamo impliziert Inhalte, die mit der Dynamo-IDE zur Verwendung in Dynamo erstellt werden, und für Dynamo impliziert die Verwendung externer Werkzeuge zur Erstellung von Inhalten, die zur Verwendung in Dynamo importiert werden. Obwohl sich dieses Handbuch auf die Entwicklung für Dynamo konzentriert, werden im Folgenden Ressourcen für alle Prozesse beschrieben.

Für Dynamo

Diese Blöcke gestatten die größtmögliche Anpassung. Viele Pakete werden mit dieser Methode erstellt. Sie ist erforderlich, um zur Quelle von Dynamo beizutragen. Der Prozess ihrer Erstellung wird in diesem Handbuch behandelt.

• Zero-Touch-Blöcke

• Von NodeModel abgeleitete Blöcke

• Erweiterungen

Der Primer enthält eine Anleitung zum .

Für die folgende Beschreibung wird Visual Studio als Entwicklungsumgebung für Zero-Touch- und NodeModel-Blöcke verwendet.

Visual Studio-Benutzeroberfläche mit einem Projekt, das wir entwickeln werden

In Dynamo

Diese Prozesse befinden sich zwar im Arbeitsbereich für visuelle Programmierung und sind relativ einfach durchzuführen. Es handelt sich jedoch bei allen um realisierbare Optionen zur Anpassung von Dynamo. Der Primer behandelt diese Prozesse ausführlich und bietet im Kapitel Tipps und Best Practices für die Skripterstellung.

• Codeblöcke stellen DesignScript in der visuellen Programmierumgebung bereit und ermöglichen so flexible Text-Skript- und Block-Arbeitsabläufe. Eine Funktion in einem Codeblock kann von jedem beliebigen Element im Arbeitsbereich aufgerufen werden.

  Laden Sie ein Codeblock-Beispiel herunter (klicken Sie mit der rechten Maustaste und dann auf Speichern unter), oder sehen Sie sich im eine detaillierte exemplarische Vorgehensweise an.

• Benutzerdefinierte Blöcke sind Container für Sammlungen von Blöcken oder sogar ganzen Diagrammen. Sie stellen eine effektive Methode dar, um häufig verwendete Routinen zu sammeln und sie mit der Community zu teilen.

  Laden Sie ein Beispiel für einen benutzerdefinierten Block herunter (klicken Sie mit der rechten Maustaste und dann auf Speichern unter), oder sehen Sie sich im

Die Entwicklung im Dynamo-Arbeitsbereich ist ein leistungsstarkes Werkzeug, um unmittelbar Feedback zu erhalten.

Entwickeln im Dynamo-Arbeitsbereich mit dem Python-Block

Welche Vor- und Nachteile haben die einzelnen Optionen?

Die Entwicklungsoptionen für Dynamo wurden speziell auf die Komplexität bei der Anpassung ausgelegt. Unabhängig davon, ob das Ziel darin besteht, ein rekursives Skript in Python zu schreiben oder eine vollständig angepasste Block-Benutzeroberfläche zu erstellen, gibt es Optionen zum Implementieren von Code, die nur das umfassen, was für den Einstieg erforderlich ist.

Codeblöcke, der Python-Block und benutzerdefinierte Blöcke in Dynamo

Mit diesen Optionen können Sie sehr einfach Code in der visuellen Programmierumgebung von Dynamo schreiben. Der Arbeitsbereich für visuelle Programmierung in Dynamo bietet Zugriff auf Python und DesignScript und umfasst die Möglichkeit, mehrere Blöcke in einem benutzerdefinierten Block zu enthalten.

Mit diesen Methoden haben wir folgende Möglichkeiten:

• Einstieg in das Schreiben mit Python oder DesignScript ohne oder mit geringem Einrichtungsaufwand

• Importieren von Python-Bibliotheken in Dynamo

• Gemeinsame Nutzung von Codeblöcken, Python-Blöcken und benutzerdefinierten Blöcken mit der Dynamo-Community im Rahmen eines Pakets

Zero-Touch-Blöcke

Unter Zero-Touch versteht man ein einfaches Verfahren zum Importieren von C#-Bibliotheken durch Zeigen und Klicken. Dynamo liest die öffentlichen Methoden einer .dll-Datei und konvertiert sie in Dynamo-Blöcke. Sie können Zero-Touch verwenden, um Ihre eigenen benutzerdefinierten Blöcke und Pakete zu entwickeln.

Mit dieser Methode haben wir folgende Möglichkeiten:

• Importieren von Bibliotheken, die nicht unbedingt für Dynamo entwickelt wurden, und automatisches Erstellen einer Suite mit neuen Blöcken, z. B. wie im im Primer beschrieben.

• Schreiben von C#-Methoden und einfache Nutzung der Methoden als Blöcke in Dynamo

• Gemeinsame Nutzung einer C#-Bibliothek als Blöcke mit der Dynamo-Community in einem Paket

Von NodeModel abgeleitete Blöcke

Diese Blöcke gehen ein Schritt tiefer in die Struktur von Dynamo. Sie basieren auf der NodeModel-Klasse und sind in C# geschrieben. Diese Methode bietet die größte Flexibilität und Leistung. Die meisten Aspekte des Blocks müssen jedoch explizit definiert werden, und Funktionen müssen in einer separaten Assembly ausgeführt werden.

Mit dieser Methode haben wir folgende Möglichkeiten:

• Erstellen einer vollständig anpassbaren Block-Benutzeroberfläche mit Schiebereglern, Bildern, Farben usw. (z. B. ColorRange-Block)

• Zugreifen und Bearbeiten von Vorgängen im Dynamo-Ansichtsbereich

• Anpassen der Vergitterung

• Laden als Paket in Dynamo

Wissenswertes über Dynamo-Versionierung und API-Änderungen (1.x → 2.x)

Da Dynamo regelmäßig aktualisiert wird, können Änderungen an Teilen der API vorgenommen werden, die von einem Paket verwendet wird. Die Nachverfolgung dieser Änderungen ist wichtig, um sicherzustellen, dass vorhandene Pakete weiterhin ordnungsgemäß funktionieren.

Änderungen an der API werden im nachverfolgt. Hier werden Änderungen an DynamoCore, Bibliotheken und Arbeitsbereichen behandelt.

Ein Beispiel für eine bevorstehende, signifikante Änderung ist der Wechsel von XML zum JSON-Dateiformat in Version 2.0. Von NodeModel abgeleitete Blöcke benötigen jetzt einen , da sie sonst nicht in Dynamo 2.0 geöffnet werden können.

Die API-Dokumentation von Dynamo deckt derzeit die Kernfunktionen ab: .

Berechtigung zum Verteilen von Binärdateien in einem Paket

Achten Sie auf DLL-Dateien, die in einem Paket enthalten sind, das in den Package Manager hochgeladen wird. Wenn der Autor des Pakets die DLL-Datei nicht erstellt hat, muss er über die Rechte zum Freigeben verfügen.

Wenn ein Paket Binärdateien enthält, müssen die Benutzer beim Herunterladen darüber informiert werden, dass das Paket Binärdateien enthält.

Überlegungen zur Leistung der Dynamo-Benutzeroberfläche

Zum Zeitpunkt der Erstellung dieses Dokuments verwendet Dynamo hauptsächlich WPF (Windows Presentation Foundation), um die Benutzeroberfläche zu rendern. WPF ist ein komplexes und leistungsstarkes XAML-/bindungsbasiertes System. Da Dynamo über eine komplexe Benutzeroberfläche verfügt, werden leicht Probleme mit der Benutzeroberfläche oder Speicherverluste verursacht bzw. die Diagrammausführung und Aktualisierungen der Benutzeroberfläche so zusammengefasst, dass die Leistung beeinträchtigt wird.

Weitere Informationen finden Sie auf der . Hier finden Sie Hilfestellung, um einige häufige Fallstricke bei Änderungen am Code von Dynamo zu vermeiden.

Einführung:

Dieser Abschnitt enthält Informationen zu Problemen, die möglicherweise beim Migrieren Ihrer Diagramme, Pakete und Bibliotheken in Dynamo 3.x auftreten können.

Dynamo 3.0 ist eine Hauptversion, und einige APIs wurden geändert oder entfernt. Die größte Änderung, die Sie als Entwickler oder Benutzer von Dynamo 3.x wahrscheinlich betreffen wird, ist der Umstieg auf .NET 8.

Dotnet/.NET ist die Laufzeitumgebung, die die C#-Sprache unterstützt, in der Dynamo geschrieben ist. Wir haben zusammen mit der restlichen Autodesk-Umgebung auf eine moderne Version dieser Laufzeitumgebung aktualisiert.

Weitere Informationen finden Sie in unserem Blog-Post.

Paketkompatibilität

Verwenden von Dynamo 2.x-Paketen in Dynamo 3.x

Da Dynamo 3.x jetzt unter der .NET 8-Laufzeitumgebung ausgeführt wird, kann die Funktionsweise von Paketen, die für Dynamo 2.x (mit .NET 48) erstellt wurden, in Dynamo 3.x nicht garantiert werden. Wenn Sie versuchen, ein Paket in Dynamo 3.x herunterzuladen, das mit einer Dynamo-Version unter 3.0 veröffentlicht wurde, erhalten Sie eine Warnung, dass das Paket aus einer älteren Version von Dynamo stammt.

Das bedeutet nicht, dass das Paket nicht funktioniert. Es ist lediglich eine Warnung davor, dass Kompatibilitätsprobleme auftreten können. Im Allgemeinen ist es empfehlenswert, zu überprüfen, ob eine neuere Version speziell für Dynamo 3.x erstellt wurde.

Möglicherweise wird diese Art von Warnung auch in den Dynamo-Protokolldateien zur Paketladedauer angezeigt. Wenn alles ordnungsgemäß funktioniert, können Sie dies ignorieren.

Verwenden von Dynamo 3.x-Paketen in Dynamo 2.x

Es ist sehr unwahrscheinlich, dass ein für Dynamo 3.x (mit .NET 8) erstelltes Paket mit Dynamo 2.x kompatibel ist. Außerdem wird eine Warnung angezeigt, wenn Sie Pakete herunterladen, die für neuere Versionen von Dynamo erstellt wurden, während Sie eine ältere Version verwenden.

Erweiterungen als Pakete

Überblick

Dynamo-Erweiterungen können wie normale Dynamo-Blockbibliotheken im Package Manager bereitgestellt werden. Wenn ein installiertes Paket eine Ansichtserweiterung enthält, wird die Erweiterung zur Laufzeit geladen, wenn Dynamo geladen wird. Sie können in der Dynamo-Konsole überprüfen, ob die Erweiterung ordnungsgemäß geladen wurde.

Paketstruktur

Die Struktur eines Erweiterungspakets ist dieselbe wie die eines normalen Pakets und enthält Folgendes:

Wenn Sie die Erweiterung bereits erstellt haben, verfügen Sie (mindestens) über eine .NET-Assembly und eine Manifestdatei. Die Assembly sollte eine Klasse enthalten, die IViewExtension oder IExtension implementiert. Die XML-Manifestdatei teilt Dynamo mit, welche Klasse instanziiert werden soll, um die Erweiterung zu starten. Damit der Package Manager die Erweiterung ordnungsgemäß findet, muss die Manifestdatei genau dem Assembly-Speicherort und dem -Namen entsprechen.

Platzieren Sie alle Assembly-Dateien im Ordner bin und die Manifestdatei im Ordner extra. In diesem Ordner können auch weitere Objekte platziert werden.

Beispiel für .XML-Manifestdatei:

Hochladen

Sobald Sie einen Ordner mit den oben aufgeführten Unterverzeichnissen erstellt haben, können Sie mit dem Übertragen (Hochladen) in den Package Manager beginnen. Beachten Sie, dass Sie derzeit keine Pakete aus Dynamo Sandbox publizieren können. Dies bedeutet, dass Sie Dynamo Revit verwenden müssen. Navigieren Sie in Dynamo Revit zu Pakete => Neues Paket publizieren. Dadurch wird der Benutzer aufgefordert, sich bei seinem Konto bei Autodesk Account anzumelden, mit dem er das Paket verknüpfen möchte.

An dieser Stelle sollten Sie sich im normalen Fenster zum Publizieren des Pakets befinden, in dem Sie alle erforderlichen Felder für Ihr Paket/Ihre Erweiterung ausfüllen. Es gibt einen sehr wichtigen zusätzlichen Schritt, bei dem Sie sicherstellen müssen, dass keine der Assembly-Dateien als Blockbibliothek markiert ist. Klicken Sie dazu mit der rechten Maustaste auf die importierten Dateien (den oben erstellten Paketordner). Ein Kontextmenü wird angezeigt, in dem Sie diese Option aktivieren (oder deaktivieren) können. Alle Erweiterungs-Assemblys sollten deaktiviert werden.

Vor dem öffentlichen Publizieren sollten Sie immer lokal publizieren, um sicherzustellen, dass alles wie erwartet funktioniert. Nachdem Sie sich dahingehend vergewissert haben, können Sie durch Auswahl von Publizieren die Publizierung starten.

Abrufen

Um zu überprüfen, ob das Paket erfolgreich hochgeladen wurde, können Sie es anhand des im Publizierungsschritt angegebenen Namens und der Schlüsselwörter suchen. Beachten Sie zum Schluss noch, dass die Erweiterungen einen Neustart von Dynamo erfordern, bevor sie funktionieren. In der Regel erfordern diese Erweiterungen Parameter, die beim Starten von Dynamo angegeben werden.

Einige allgemeine Informationen zu Interop-Typen

Was sind COM-Typen? – https://learn.microsoft.com/de-de/windows/win32/com/the-component-object-model

Die Standardmethode zur Verwendung von COM-Typen in C# besteht darin, die primären Interop-Assemblys (im Wesentlichen eine große Sammlung von APIs) mit dem Paket zu referenzieren und zu liefern.

Eine Alternative dazu besteht darin, die PIA (primäre Interop-Assemblys) in die verwaltete Assembly einzubetten. Dies umfasst im Grunde nur die Typen und Elemente, die tatsächlich von einer verwalteten Assembly verwendet werden. Dieser Ansatz weist jedoch noch einige andere Probleme auf, wie z. B. die Typäquivalenz.

Dieser Post beschreibt das Problem ziemlich gut:

So verwaltet Dynamo die Typäquivalenz

Dynamo delegiert Typäquivalenzen an die .NET-Runtime (dotnet). Ein Beispiel hierfür wäre, dass zwei Typen mit demselben Namen und Namensbereich, die aus unterschiedlichen Assemblys stammen, nicht als äquivalent angesehen werden und Dynamo beim Laden der in Konflikt stehenden Assemblys einen Fehler ausgibt. Bei Interop-Typen überprüft Dynamo mithilfe der , ob die Interop-Typen äquivalent sind.

So vermeiden Sie Konflikte zwischen eingebetteten Interop-Typen

Einige Pakete wurden bereits mit eingebetteten Interop-Typen erstellt (z. B. CivilConnection). Das Laden von zwei Paketen mit eingebetteten Interop-Assemblys, die nicht als äquivalent angesehen werden (unterschiedliche Versionen, wie definiert), führt zu einem package load error. Aus diesem Grund empfehlen wir Paketautoren, die dynamische Bindung (auch späte Bindung genannt) für Interop-Typen zu verwenden (die Lösung wird auch beschrieben).

Sie können sich dieses Beispiel ansehen:

Bei geöffnetem und gestartetem Visual Studio-Projekt werden Sie durch die Erstellung eines benutzerdefinierten Blocks geführt, mit dem ein rechteckiges Zellenraster erstellt wird. Auch wenn wir für die Erstellung mehrere Standardblöcke verwenden könnten, ist dies ein nützliches Werkzeug, das sich problemlos in einen Zero-Touch-Block integrieren lässt. Im Gegensatz zu Rasterlinien können Zellen um ihre Mittelpunkte skaliert, nach Eckscheitelpunkten abgefragt oder in Flächen integriert werden.

In diesem Beispiel werden einige der Funktionen und Konzepte behandelt, die Sie beim Erstellen eines Zero-Touch-Blocks beachten sollten. Nachdem wir den benutzerdefinierten Block erstellt und zu Dynamo hinzugefügt haben, informieren Sie sich auf der Seite Weitere Schritte mit Zero-Touch im Detail über die vorgegebenen Eingabewerte, das Zurückgeben mehrerer Werte, die Dokumentation, die Objekte, die Verwendung von Dynamo-Geometrietypen und Migrationen.

Ausführen von Python-Skripts in Zero-Touch-Blöcken (C#)

Wenn wir mit dem Schreiben von Skripts in Python vertraut sind und mehr Funktionen aus den Dynamo-Python-Standardblöcken herausholen möchten, können wir mit Zero-Touch eigene Blöcke erstellen. Beginnen wir mit einem einfachen Beispiel, in dem ein Python-Skript als Zeichenfolge an einen Zero-Touch-Block übergeben werden kann, in dem das Skript ausgeführt und ein Ergebnis zurückgegeben wird. Diese Fallstudie baut auf den exemplarischen Vorgehensweisen und Beispielen im Abschnitt Erste Schritte auf. Wenn Sie mit der Erstellung von Zero-Touch-Blöcken noch nicht vertraut sind, finden Sie dort weitere Informationen.

Das gewünschte Layout für Ihr Paket hängt von den Blocktypen ab, die Sie in das Paket aufnehmen. Vom Blockmodell abgeleitete Blöcke, ZeroTouch-Blöcke und benutzerdefinierte Blöcke weisen alle einen leicht unterschiedlichen Prozess zum Definieren der Kategorisierung auf. Sie können diese Blocktypen innerhalb desselben Pakets mischen und anpassen. Dies erfordert jedoch eine Kombination der unten beschriebenen Strategien.

NodeModel

NodeModel-Bibliotheken sind vorgabemäßig basierend auf der Klassenstruktur organisiert.

Der Block befindet sich in Add-Ons unter:

Sie können die Kategorie auch überschreiben, indem Sie das NodeCategory-Attribut für die Klasse oder im Konstruktor verwenden, wie unten gezeigt.

Der Block befindet sich nun in Add-Ons unter:

ZeroTouch

ZeroTouch-Bibliotheken sind vorgabemäßig ebenfalls basierend auf der Klassenstruktur organisiert.

Der Block befindet sich in Add-Ons unter:

Sie können den Speicherort der Klassenstruktur auch mithilfe einer XML-Datei für die Dynamo-Anpassung überschreiben.

• Die XML-Datei muss entsprechend benannt und im Ordner extra des Pakets enthalten sein.

  • PackageName_DynamoCustomization.xml

CustomNodes

Benutzerdefinierte Blöcke werden während der Blockerstellung auf Grundlage des angegebenen Category Name organisiert (mithilfe des neuen Dialogfelds Benutzerdefinierter Block).

WARNUNG! Die Verwendung der Punktnotation in Blocknamen oder -kategorien führt zu zusätzlichen verschachtelten Unterkategorien. . dient als Trennzeichen, um die zusätzliche Hierarchie festzulegen. Dies ist ein neues Verhalten in der Bibliothek für Dynamo 2.0.

Der Kategoriename kann später in der DYF-Datei (XML oder JSON) aktualisiert werden

Strategien für die Paketblock-Migration

Wenn ein Paketautor beschließt, zuvor vorhandene Blöcke in einer neuen Version umzubenennen, sollte er eine Möglichkeit zum Migrieren von Diagrammen bereitstellen, die Blöcke mit den alten Namen enthalten. Dies kann auf folgende Weise erreicht werden...

ZeroTouch-Blöcke verwenden eine Namespace.Migrations.XML-Datei, die sich im Ordner bin der Pakete befindet, z. B.:

MyZeroTouchLib.MyNodes.SayHello bis MyZeroTouchLib.MyNodes.SayHelloRENAMED

Von NodeModel abgeleitete Blöcke verwenden das AlsoKnownAs-Attribut für die Klasse, z. B.:

SampleLibraryUI.Examples.DropDownExample bis SampleLibraryUI.Examples.DropDownExampleRENAMED

Bevor wir mit der Entwicklung beginnen, ist es wichtig, ein solides Fundament für ein neues Projekt zu schaffen. Die Dynamo-Entwickler-Community verfügt über mehrere Projektvorlagen, die sich hervorragend als Ausgangspunkt eignen. Ein umfassendes Verständnis, wie Sie ein Projekt von Grund auf neu beginnen, ist jedoch noch wertvoller. Der Aufbau eines Projekts von Grund auf ermöglicht ein tieferes Verständnis des Entwicklungsprozesses.

Erstellen eines Visual Studio-Projekts

Visual Studio ist eine leistungsstarke IDE, in der wir ein Projekt erstellen, Referenzen hinzufügen, .dll-Dateien generieren und debuggen können. Beim Erstellen eines neuen Projekts erstellt Visual Studio außerdem eine Projektmappe, eine Struktur zum Organisieren von Projekten. In einer einzelnen Projektmappe können mehrere Projekte enthalten sein, die zusammen erstellt werden können. Um einen Zero-Touch-Block zu erstellen, müssen wir ein neues Visual Studio-Projekt starten, in im wir eine C#-Klassenbibliothek schreiben und eine

Wenn Sie Assemblys entwickeln, die als Paket für Dynamo publiziert werden sollen, kann das Projekt so konfiguriert werden, dass alle erforderlichen Objekte gruppiert und in einer paketkompatiblen Verzeichnisstruktur abgelegt werden. Dadurch kann das Projekt schnell als Paket getestet werden und die Benutzererfahrung simuliert werden.

So erstellen Sie Pakete direkt im Paketordner

Es gibt zwei Methoden zum Erstellen eines Pakets in Visual Studio:

• Hinzufügen von Postbuildereignissen über das Dialogfeld Projekteinstellungen, die XCopy- oder Python-Skripts zum Kopieren der erforderlichen Dateien verwenden

-o, -O, --OpenFilePath: Weisen Sie Dynamo an, eine Befehlsdatei zu öffnen und die enthaltenen Befehle unter diesem Pfad auszuführen. Diese Option wird nur unterstützt, wenn die Ausführung über DynamoSandbox erfolgt.

-c, -C, --CommandFilePath: Weisen Sie Dynamo an, eine Befehlsdatei zu öffnen und die enthaltenen Befehle unter diesem Pfad auszuführen. Diese Option wird nur unterstützt, wenn die Ausführung über DynamoSandbox erfolgt.

-v, -V, --Verbose: Weisen Sie Dynamo an, alle vom Programm durchgeführten Auswertungen in einer XML-Datei im angegebenen Pfad auszugeben.

-g, -G, --Geometry: Weisen Sie Dynamo an, die Geometrie aller Auswertungen in einer JSON-Datei unter diesem Pfad auszugeben.

-h, -H, --help: Rufen Sie die Hilfe ab.

-i, -I, --Import: Weisen Sie Dynamo an, eine Assembly als Blockbibliothek zu importieren. Dieses Argument sollte ein Dateipfad zu einer einzelnen .dll sein. Wenn Sie mehrere .dlls importieren möchten, listen Sie diese durch ein Leerzeichen getrennt auf: -i 'assembly1.dll' 'assembly2.dll'.

--GeometryPath: Relativer oder absoluter Pfad zu einem Verzeichnis, das ASM-Dateien enthält. Wenn bereitgestellt, wird auf der Festplatte nicht nach der ASM-Datei gesucht, sondern diese wird direkt aus diesem Pfad geladen.

-k, -K, --KeepAlive: Im Keepalive-Modus können Sie den Dynamo-Prozess so lange ausführen, bis er durch eine geladene Erweiterung beendet wird.

--HostName: Identifizieren Sie die mit dem Host verknüpfte Dynamo-Variante.

-s, -S, --SessionId: Identifizieren Sie die Sitzungs-ID von Dynamo-Host-Analysen.

-p, -P, --ParentId: Identifizieren Sie die übergeordnete ID von Dynamo-Host-Analysen.

-x, -X, --ConvertFile: Wird dies in Kombination mit dem Flag -O verwendet, wird eine .dyn-Datei aus dem angegebenen Pfad geöffnet und in .json konvertiert. Die Datei hat die Erweiterung .json und befindet sich im selben Verzeichnis wie die ursprüngliche Datei.

-n, -N, --NoConsole: Verlassen Sie sich nicht auf das Konsolenfenster, um im Keepalive-Modus mit der CLI zu interagieren.

-u, -U, --UserData: Geben Sie den Benutzerdatenordner an, der von PathResolver mit der CLI verwendet werden soll.

--CommonData: Geben Sie den gemeinsamen Datenordner an, der von PathResolver mit der CLI verwendet werden soll.

--DisableAnalytics: Deaktiviert Analysen in Dynamo für die Dauer des Prozesses.

--CERLocation: Geben Sie das Werkzeug für den Absturzfehlerbericht an, das sich auf der Festplatte befindet.

--ServiceMode: Geben Sie den Startvorgang für den Servicemodus an.

Warum?

Aus unterschiedlichen Gründen kann es erforderlich sein, Dynamo über die Befehlszeile zu steuern. Dazu zählen die folgenden:

• Automatisieren vieler Dynamo-Läufe

• Testen von Dynamo-Diagrammen (bei Verwendung von DynamoSandbox siehe auch unter -c)

• Ausführen einer Sequenz von Dynamo-Diagrammen in einer bestimmten Reihenfolge

• Schreiben von Stapeldateien für mehrere Befehlszeilenausführungen

Was?

Die Befehlszeilenschnittstelle (DynamoCLI) ist eine Ergänzung zu DynamoSandbox. Es handelt sich um ein DOS/TERMINAL-Befehlszeilen-Dienstprogramm, mit dem Dynamo komfortabel über Befehlszeilenargumente ausgeführt werden kann. In der ersten Implementierung kann das Programm nicht eigenständig ausgeführt werden, sondern muss in dem Ordner ausgeführt werden, in dem sich die Dynamo-Binärdateien befinden, da es von denselben DLL-Kerndateien wie Sandbox abhängt. Es funktioniert nicht mit anderen Builds von Dynamo.

Es gibt vier Möglichkeiten zum Ausführen der CLI: über eine DOS-Eingabeaufforderung, über DOS-Stapeldateien und als Windows-Desktop-Verknüpfung, deren Pfad so geändert wird, dass er die angegebenen Befehlszeilen-Flags enthält. Die Spezifikation für die DOS-Datei kann vollständig qualifiziert oder relativ sein, und zugeordnete Laufwerke und URL-Syntax werden ebenfalls unterstützt. Sie kann auch mit Mono erstellt und unter Linux oder Mac vom Terminal aus ausgeführt werden.

Das Dienstprogramm unterstützt Dynamo-Pakete, Sie können jedoch keine benutzerdefinierten Blöcke (dyf), sondern nur eigenständige Diagramme (dyn) laden.

In vorläufigen Tests unterstützt das CLI-Dienstprogramm lokalisierte Versionen von Windows, und Sie können filespec-Argumente mit ASCII-Großbuchstaben angeben.

Auf die CLI kann über die Anwendung DynamoCLI.exe zugegriffen werden. Diese Anwendung ermöglicht es Benutzern oder einer anderen Anwendung, mit dem Dynamo-Auswertungsmodell zu interagieren, indem DynamoCLI.exe mit einer Befehlszeichenfolge aufgerufen wird. Dies kann in etwa wie folgt aussehen:

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn"

Mit diesem Befehl wird Dynamo angewiesen, die angegebene Datei unter "C:\BeliebigeDynamoDatei.Dyn" zu öffnen, ohne eine Benutzeroberfläche anzuzeigen, und sie dann auszuführen. Dynamo wird beendet, wenn die Ausführung des Diagramms abgeschlossen ist.

Neu in Version 2.1: Anwendung DynamoWPFCLI.exe. Diese Anwendung unterstützt all das, was auch die Anwendung DynamoCLI.exe unterstützt, weist aber zusätzlich die Option Geometrie (-g) auf. Die Anwendung DynamoWPFCLI.exe ist nur für Windows verfügbar.

Wichtige Anmerkungen

• Die bevorzugte Methode für die Interaktion mit DynamoCLI erfolgt über eine Schnittstelle für Eingabeaufforderungen.

• Derzeit müssen Sie DynamoCLI vom Installationsverzeichnis im Ordner [Dynamo-Version] aus ausführen. Die CLI benötigt Zugriff auf dieselben DLL-Dateien wie Dynamo und sollte daher nicht verschoben werden.

• Sie sollten Diagramme ausführen können, die derzeit in Dynamo geöffnet sind. Dies kann jedoch zu unbeabsichtigten Nebeneffekten führen.

• Alle Dateipfade sind vollständig DOS-konform; relative und vollständig qualifizierte Pfade sollten daher funktionieren. Stellen Sie jedoch sicher, dass Sie Ihre Pfade in Anführungszeichen setzen:

wie

-o: Sie können Dynamo mit Verweis auf eine DYN-Datei im Headless-Modus öffnen, in dem das Diagramm ausgeführt wird.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn"

-v kann verwendet werden, wenn Dynamo im Headless-Modus ausgeführt wird (wenn Sie -o zum Öffnen eines Datei verwendet haben). Dieses Flag wiederholt alle Blöcke im Diagramm und gibt ihre Ausgabewerte in einer einfachen XML-Datei aus. Da das Flag --ServiceMode Dynamo dazu zwingen kann, mehrere Diagrammauswertungen auszuführen, enthält die Ausgabedatei Werte für jede auftretende Auswertung.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -p "C:\aFileWithPresetsInIt.dyn" --ServiceMode "all" -v "C:\output.xml"

Die XML-Ausgabedatei hat folgende Form:

-g kann verwendet werden, wenn Dynamo im Headless-Modus ausgeführt wird (wenn Sie -o zum Öffnen einer Datei verwendet haben). Dieses Flag generiert das Diagramm und gibt dann die resultierende Geometrie in einer JSON-Datei aus.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoWPFCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -g "C:\geometry.json"

Die JSON-Geometriedatei hat folgende Form:

Noch offen – In Bearbeitung

-h: Verwenden Sie diese Option, um eine Liste der möglichen Optionen abzurufen.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -h

Das Flag -i kann mehrmals verwendet werden, um mehrere Assemblys zu importieren, die zum Ausführen des zu öffnenden Diagramms erforderlich sind.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -i"a.dll" -i"aSecond.dll"

Das Flag -l kann verwendet werden, um Dynamo unter einer anderen Gebietsschema-Einstellung auszuführen. In der Regel wirkt sich die Gebietsschema-Einstellung jedoch nicht auf die Diagrammergebnisse aus.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -o "C:\someReallyCoolDynamoFile.Dyn" -l "de-DE"

Das Flag --GeometryPath kann verwendet werden, um DynamoSandbox oder die CLI auf einen bestimmten Satz von ASM-Binärdateien zu verweisen. Verwenden Sie es wie

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoSandbox.exe --GeometryPath "\pathToGeometryBinaries\"

oder

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoSandbox.exe --GeometryPath "\pathToGeometryBinaries\"

Mit dem Flag -k können Sie den Dynamo-Prozess so lange ausführen, bis er durch eine geladene Erweiterung beendet wird.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -k

Das Flag --HostName kann verwendet werden, um die mit dem Host verknüpfte Dynamo-Variante zu identifizieren.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe --HostName "DynamoFormIt"

oder

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoSandbox.exe --HostName "DynamoFormIt"

Das Flag -s kann verwendet werden, um die Sitzungs-ID von Dynamo-Host-Analysen zu ermitteln.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -s [HostSessionId]

Das Flag -p kann verwendet werden, um die übergeordnete ID von Dynamo-Host-Analysen zu ermitteln.

C:\Program Files\Dynamo\Dynamo Core\[Dynamo Version]\DynamoCLI.exe -p "RVT&2022&MUI64&22.0.2.392"

Publizieren eines Pakets

Pakete sind eine einfache Möglichkeit, Blöcke zu speichern und gemeinsam mit der Dynamo-Community zu nutzen. Ein Paket kann alle möglichen Elemente enthalten, von benutzerdefinierten Blöcken, die im Dynamo-Arbeitsbereich erstellt wurden, bis hin zu von NodeModel abgeleiteten Blöcken. Pakete werden mit dem Package Manager publiziert und installiert. Zusätzlich zu dieser Seite enthält der Primer eine allgemeine Anleitung für Pakete.

Was ist ein Package Manager?

Der Dynamo Package Manager ist eine Softwareregistrierung (ähnlich wie npm), auf die Sie über Dynamo oder über einen Webbrowser zugreifen können. Der Package Manager umfasst das Installieren, Publizieren, Aktualisieren und Anzeigen von Paketen. Wie npm verwaltet er verschiedene Versionen von Paketen. Außerdem können Sie so die Abhängigkeiten Ihres Projekts verwalten.

Suchen Sie im Browser nach Paketen, und zeigen Sie Statistiken an: .

• In Dynamo umfasst der Package Manager das Installieren, Publizieren und Aktualisieren von Paketen.

1. Online-Suche nach Paketen: Packages > Search for a Package...

2. Anzeigen/Bearbeiten von installierten Paketen: Packages > Manage Packages...

3. Publizieren eines neuen Pakets: Packages > Publish New Package...

Pakete werden in Dynamo über den Package Manager publiziert. Es wird empfohlen, lokal zu publizieren, das Paket zu testen und dann online zu publizieren, um das Paket gemeinsam mit der Community zu nutzen. Anhand der NodeModel-Fallstudie werden die erforderlichen Schritte zum Publizieren des RectangularGrid-Blocks als Paket lokal und dann online beschrieben.

Starten Sie Dynamo, und wählen Sie Packages > Publish New Package..., um das Fenster Publish a Package zu öffnen.

1. Wählen Sie Add file..., um nach Dateien zu suchen, die dem Paket hinzugefügt werden sollen.

2. Wählen Sie die beiden .dll-Dateien aus der NodeModel-Fallstudie aus.

3. Wählen Sie Ok aus.

Geben Sie dem Paket einen Namen, eine Beschreibung und eine Versionsbezeichnung, wenn die Dateien dem Paketinhalt hinzugefügt wurden. Beim Publizieren eines Pakets mit Dynamo wird automatisch eine pkg.json-Datei erstellt.

Ein Paket, das bereit für die Publizierung ist

1. Geben Sie die erforderlichen Informationen für Name, Beschreibung und Version ein.

2. Publizieren Sie das Paket, indem Sie auf Lokal publizieren klicken und den Dynamo-Paketordner AppData\Roaming\Dynamo\Dynamo Core\1.3\packages auswählen, damit der Block in Core verfügbar ist. Publizieren Sie immer lokal, bis das Paket so weit ist, dass es freigegeben werden kann.

Nach dem Publizieren eines Pakets sind die Blöcke in der Dynamo-Bibliothek unter der Kategorie CustomNodeModel verfügbar.

1. Das soeben in der Dynamo-Bibliothek erstellte Paket.

Wenn das Paket online publiziert werden kann, öffnen Sie den Package Manager, wählen Sie Publish und dann Publish Online.

1. Um zu sehen, wie Dynamo das Paket formatiert hat, klicken Sie auf die drei vertikalen Punkte rechts neben CustomNodeModel und wählen Stammverzeichnis anzeigen.

2. Wählen Sie im Fenster zum Publizieren von Dynamo-Paketen Publish und dann Publish Online aus.

3. Um ein Paket zu löschen, wählen Sie Delete.

Wie aktualisiere ich ein Paket?

Das Aktualisieren eines Pakets ist ein ähnlicher Vorgang wie das Publizieren. Öffnen Sie den Package Manager, wählen Sie Publish Version... für das Paket aus, das aktualisiert werden muss, und geben Sie eine höhere Version ein.

1. Wählen Sie Publish Version, um ein vorhandenes Paket mit neuen Dateien im Stammverzeichnis zu aktualisieren, und wählen Sie dann, ob es lokal oder online publiziert werden soll.

Web-Client des Package Manager

Mit dem Web-Client des Package Manager können Benutzer nach Paketdaten suchen und diese anzeigen, einschließlich Versionierung, Download-Statistiken und anderen relevanten Informationen. Darüber hinaus können sich Paketautoren anmelden, um ihre Paketdetails, wie z. B. Kompatibilitätsinformationen, direkt über den Web-Client zu aktualisieren.

Weitere Informationen zu diesen Funktionen finden Sie im folgenden Blog-Post: .

Der Web-Client des Package Manager ist über folgenden Link verfügbar:

Aktualisieren von Paketdetails

Autoren können ihre Paketbeschreibung, den Website-Link und den Repository-Link bearbeiten, indem sie die folgenden Schritte ausführen:

1. Wählen Sie unter Meine Pakete das Paket aus, und klicken Sie auf Paketdetails bearbeiten.

2. Fügen Sie die Links für die Website und das Repository mithilfe der entsprechenden Felder hinzu, oder ändern Sie sie.

3. Aktualisieren Sie bei Bedarf die Paketbeschreibung.

Anmerkung: Die Aktualisierung im Package Manager in Dynamo kann bis zu 15 Minuten dauern, da Server-Updates einige Zeit in Anspruch nehmen. Wir arbeiten daran, um diese Zeit zu reduzieren.

Bearbeiten von Kompatibilitätsinformationen für publizierte Paketversionen

Kompatibilitätsinformationen können rückwirkend für zuvor publizierte Paketversionen aktualisiert werden. Führen Sie die folgenden Schritte aus:

Schritt 1:

1. Klicken Sie auf die Paketversion, die Sie aktualisieren möchten.

2. Die Liste Abhängig von wird automatisch mit den Paketen gefüllt, von denen Ihr Paket abhängt.

3. Klicken Sie auf das Stiftsymbol neben Kompatibilität, um den Arbeitsablauf Kompatibilitätsinformationen bearbeiten zu öffnen.

Schritt 2:

Folgen Sie dem Flussdiagramm unten, und prüfen Sie die folgende Tabelle, um zu ermitteln, welche Option für Ihr Paket am besten geeignet ist.

Sehen wir uns einige Szenarien anhand von Beispielen an:

Beispielpaket Nr. 1 – Civil Connection: Dieses Paket verfügt über API-Abhängigkeiten in Bezug auf Revit und Civil 3D und enthält keine Sammlung von Kernblöcken (z. B. Geometriefunktionen, mathematische Funktionen und/oder Listenverwaltung). In diesem Fall wäre Option 1 die ideale Option. Das Paket wird in Revit und Civil 3D als kompatibel angezeigt, die dem Versionsbereich und/oder der Liste der einzelnen Versionen entsprechen.

Beispielpaket Nr. 2 – Rhythm: Dieses Paket ist eine Sammlung aus Revit-spezifischen Blöcken sowie Core-Blöcken. In diesem Fall weist das Paket Host-Abhängigkeiten auf. Es enthält aber auch Core-Blöcke, die in Dynamo Core verwendet werden können. In diesem Fall wäre die ideale Option Option 2. Das Paket wird in der Revit- und Dynamo Core-Umgebung (auch als Dynamo Sandbox bezeichnet) als kompatibel angezeigt, die dem Versionsbereich und/oder der Liste der einzelnen Versionen entspricht.

Beispielpaket Nr. 3 – Mesh Toolkit: Dieses Paket ist ein Dynamo Core-Paket, bei dem es sich um eine Sammlung von Geometrieblöcken ohne Host-Abhängigkeiten handelt. In diesem Fall wäre die ideale Option Option 3. Das Paket wird in Dynamo und allen Host-Umgebungen als kompatibel angezeigt, die dem Versionsbereich und/oder der Liste der einzelnen Versionen entsprechen.

Je nach ausgewählter Option werden Dynamo- und/oder Host-spezifische Felder eingeblendet, wie in der folgenden Abbildung gezeigt.

Verwenden von Methoden in GeometryPrimitiveConverter.cs

Die Klasse in der Codebibliothek von DynamoRevit bietet verschiedene Methoden zum Konvertieren zwischen geometrischen Typen in Revit und Dynamo. Diese Methoden sind nützlich beim Arbeiten mit Geometrie in Dynamo-Skripten, die mit Revit-Modellen interagieren.

Wenn wir wissen, wie wir ein Zero-Touch-Projekt erstellen, können wir uns die Details zum Erstellen eines Blocks anhand des Beispiels ZeroTouchEssentials im Dynamo-GitHub genauer ansehen.

Viele der Standardblöcke von Dynamo sind im Wesentlichen Zero-Touch-Blöcke, wie die meisten der oben genannten Mathematik-, Farb- und DateTime-Blöcke.

Laden Sie zunächst hier das Projekt ZeroTouchEssentials herunter: https://github.com/DynamoDS/ZeroTouchEssentials

Öffnen Sie in Visual Studio die Projektmappendatei ZeroTouchEssentials.sln, und erstellen Sie die Projektmappe.

Die Datei ZeroTouchEssentials.cs enthält alle Methoden, die wir in Dynamo importieren.

Öffnen Sie Dynamo, und importieren Sie die Datei ZeroTouchEssentials.dll, um die Blöcke abzurufen, die in den folgenden Beispielen referenziert werden.

Die Codebeispiele werden aus abgerufen und entsprechen im Allgemeinen dieser Datei. Die XML-Dokumentation wurde entfernt, um sie kurz zu halten, und bei jedem Codebeispiel wird der Block in der Abbildung darüber erstellt.

Vorgegebene Eingabewerte

Dynamo unterstützt die Definition von Vorgabewerten für Eingabeanschlüsse auf einem Block. Diese Vorgabewerte werden für den Block bereitgestellt, wenn die Anschlüsse keine Verbindungen haben. Vorgaben werden mithilfe des C#-Mechanismus zum Angeben optionaler Argumente im ausgedrückt. Die Vorgaben werden wie folgt angegeben:

• Stellen Sie die Methodenparameter auf einen Vorgabewert ein: inputNumber = 2.0

1. Der Vorgabewert wird angezeigt, wenn Sie den Mauszeiger über den Eingabeanschluss des Blocks bewegen.

Zurückgeben mehrerer Werte

Das Zurückgeben mehrerer Werte ist etwas komplexer als die Erstellung mehrerer Eingaben, daher müssen sie mithilfe eines Wörterbuchs zurückgegeben werden. Die Einträge im Wörterbuch werden auf der Ausgabeseite des Blocks zu Anschlüssen. Mehrere Rückgabe-Anschlüsse werden auf folgende Weise erstellt:

• Fügen Sie using System.Collections.Generic; hinzu, um Dictionary<> zu verwenden.

• Fügen Sie using Autodesk.DesignScript.Runtime; hinzu, um das Attribut MultiReturn zu verwenden. Dieses referenziert DynamoServices.dll aus dem DynamoServices-NuGet-Paket.

Weitere Informationen finden Sie in diesem Codebeispiel in .

Ein Block, der mehrere Ausgaben zurückgibt.

1. Beachten Sie, dass nun zwei Ausgabeanschlüsse vorhanden sind, die entsprechend den Zeichenfolgen benannt sind, die wir für die Wörterbuchschlüssel eingegeben haben.

Dokumentation, QuickInfos und Suche

Es wird empfohlen, Dynamo-Blöcken Dokumentation hinzuzufügen, die die Funktion, Eingaben, Ausgaben, Suchbegriffe usw. des Blocks beschreibt. Dies erfolgt über XML-Dokumentations-Tags. XML-Dokumentation wird wie folgt erstellt:

• Jeder Kommentartext, dem drei Schrägstriche vorangestellt sind, wird als Dokumentation betrachtet.

  • Beispiel: /// Documentation text and XML goes here

• Erstellen Sie nach den drei Schrägstrichen XML-Tags über Methoden, die Dynamo beim Importieren der DLL-Datei liest.

1. Visual Studio generiert eine XML-Datei am angegebenen Speicherort.

Folgende Tag-Typen stehen zur Verfügung:

• /// <summary>...</summary> ist die Hauptdokumentation für Ihren Block und wird als QuickInfo über dem Block in der linken Suchleiste angezeigt.

• /// <param name="inputName">...</param> erstellt Dokumentation für bestimmte Eingabeparameter.

• /// <returns>...</returns> erstellt Dokumentation für einen Ausgabeparameter.

Im Folgenden sehen Sie einen Beispielblock mit Eingabe- und Ausgabebeschreibungen sowie eine Zusammenfassung, die in der Bibliothek angezeigt wird.

Weitere Informationen finden Sie in diesem Codebeispiel in .

Beachten Sie, dass der Code für diesen Beispielblock Folgendes enthält:

1. Eine Blockzusammenfassung

2. Eine Eingabebeschreibung

3. Eine Ausgabebeschreibung

Optimale Verfahren für Dynamo-Blockbeschreibungen

Blockbeschreibungen erläutern kurz die Funktion und die Ausgabe eines Blocks. In Dynamo werden sie an zwei Stellen angezeigt:

• In der QuickInfo des Blocks

• Im Dokumentationsbrowser

Befolgen Sie diese Richtlinien, um beim Schreiben oder Aktualisieren von Blockbeschreibungen Konsistenz zu gewährleisten und Zeit zu sparen.

Überblick

Beschreibungen sollten aus ein bis zwei Sätzen bestehen. Wenn Sie weitere Informationen benötigen, fügen Sie diese im Dokumentationsbrowser unter Im Detail ein.

Groß- und Kleinschreibung (Großschreibung des ersten Wortes eines Satzes und von Eigennamen). Kein Punkt am Ende.

Die Sprache sollte so klar und einfach wie möglich sein. Definieren Sie Akronyme bei der ersten Erwähnung, es sei denn, sie sind auch unter Laien allgemein bekannt.

Legen Sie immer Wert auf Klarheit, auch wenn das bedeutet, von diesen Richtlinien abzuweichen.

Richtlinien

Warnungen und Fehler in Dynamo-Blöcken

Blockwarnungen und -fehler machen den Benutzer auf ein Problem mit dem Diagramm aufmerksam. Sie informieren den Benutzer über Probleme, die die normale Ausführung des Diagramms beeinträchtigen, indem ein Symbol und ein erweiterter Text-Beschriftungsblock über dem Block angezeigt werden. Blockfehler und -warnungen können unterschiedliche Schweregrade aufweisen: Einige Diagramme können mit Warnungen dennoch ausgeführt werden, während bei anderen die erwarteten Ergebnisse blockiert werden. In allen Fällen sind Blockfehler und -warnungen wichtige Werkzeuge, um den Benutzer über Probleme mit dem Diagramm auf dem Laufenden zu halten.

Richtlinien zur Gewährleistung der Konsistenz und zur Zeitersparnis beim Schreiben oder Aktualisieren von Blockwarn- und -fehlermeldungen finden Sie auf der Wiki-Seite .

Objekte

Dynamo verfügt nicht über das Schlüsselwort new, sodass Objekte unter Verwendung statischer Konstruktionsmethoden erstellt werden müssen. Objekte werden wie folgt konstruiert:

• Legen Sie den Konstruktor als intern (internal ZeroTouchEssentials()) fest, sofern nicht anders erforderlich.

• Konstruieren Sie das Objekt mit einer statischen Methode wie public static ZeroTouchEssentials ByTwoDoubles(a, b).

Anmerkung: Dynamo verwendet das Präfix Von, um anzugeben, dass eine statische Methode ein Konstruktor ist. Diese Option ist zwar optional, doch die Verwendung von Von hilft Ihnen dabei, die Bibliothek besser in den vorhandenen Dynamo-Stil einzupassen.

Weitere Informationen finden Sie in diesem Codebeispiel in .

Nachdem die DLL-Datei ZeroTouchEssentials importiert wurde, befindet sich ein ZeroTouchEssentials-Block in der Bibliothek. Dieses Objekt kann mithilfe des Blocks ByTwoDoubles erstellt werden.

Verwenden von Dynamo-Geometrietypen

Dynamo-Bibliotheken können native Dynamo-Geometrietypen als Eingaben verwenden und neue Geometrie als Ausgaben erstellen. Geometrietypen werden wie folgt erstellt:

• Referenzieren Sie ProtoGeometry.dll im Projekt, indem Sie using Autodesk.DesignScript.Geometry; oben in der C#-Datei einfügen und das ZeroTouchLibrary-NuGet-Paket zum Projekt hinzufügen.

• Wichtig: Verwalten Sie die Geometrieressourcen, die nicht von Ihren Funktionen zurückgegeben werden, wie im Abschnitt Verwerfen/Verwenden von Anweisungen weiter unten beschrieben.

Anmerkung: Dynamo-Geometrieobjekte werden wie alle anderen übergebenen Objekte für Funktionen verwendet.

Weitere Informationen finden Sie in diesem Codebeispiel in .

Ein Block, der die Länge einer Kurve abruft und diese verdoppelt.

1. Dieser Block akzeptiert einen Kurvengeometrietyp als Eingabe.

Verwerfen/Verwenden von Anweisungen

Geometrieressourcen, die nicht aus Funktionen zurückgegeben werden, müssen manuell verwaltet werden, es sei denn, Sie verwenden die Dynamo-Version 2.5 oder höher. In Dynamo 2.5 und späteren Versionen werden Geometrieressourcen intern vom System verwaltet. Sie müssen Geometrie jedoch möglicherweise weiterhin manuell entfernen, wenn es sich um einen komplexen Anwendungsfall handelt oder wenn Sie zu einem festgelegten Zeitpunkt Speicherplatz reduzieren müssen. Die Dynamo-Engine verarbeitet alle Geometrieressourcen, die aus Funktionen zurückgegeben werden. Nicht zurückgegebene Geometrieressourcen können wie folgt manuell verarbeitet werden:

• Mit einer using-Anweisung:

  Die using-Anweisung ist dokumentiert.

  Weitere Informationen zu den neuen Stabilitätsfunktionen ab Dynamo 2.5 finden Sie im Artikel zu .

• Mit manuellen Dispose-Aufrufen:

Migrationen

Beim Publizieren einer neueren Version einer Bibliothek können sich Blocknamen ändern. Namensänderungen können in einer Migrationsdatei angegeben werden, sodass in früheren Versionen einer Bibliothek erstellte Diagramme auch nach einer Aktualisierung ordnungsgemäß funktionieren. Migrationen werden wie folgt durchgeführt:

• Erstellen Sie eine .xml-Datei im selben Ordner wie die .dll-Datei mit folgendem Format: "BaseDLLName".Migrations.xml.

• Erstellen Sie in der .xml-Datei ein einzelnes <migrations>...</migrations>-Element.

1. Klicken Sie mit der rechten Maustaste, und wählen Sie Add > New Item aus.

2. Wählen Sie XML File.

3. Für dieses Projekt geben wir der Migrationsdatei den Namen ZeroTouchEssentials.Migrations.xml.

Dieser Beispielcode weist Dynamo an, dass alle Blöcke mit dem Namen GetClosestPoint jetzt den Namen ClosestPointTo erhalten.

Weitere Informationen finden Sie in diesem Codebeispiel in .

Generika

Zero-Touch unterstützt derzeit keine Generika. Sie können verwendet werden, jedoch nicht in dem Code, der direkt importiert wird, wenn der Typ nicht festgelegt ist. Methoden, Eigenschaften oder Klassen, die generisch sind und nicht über einen festgelegten Typ verfügen, können nicht verfügbar gemacht werden.

Im folgenden Beispiel wird ein Zero-Touch-Block des Typs T nicht importiert. Wenn die restliche Bibliothek in Dynamo importiert wird, fehlen Typausnahmen.

Wenn Sie in diesem Beispiel einen generischen Typ mit dem festgelegtem Typ verwenden, wird dieser in Dynamo importiert.

Einführung:

Dynamo 2.0 ist eine Hauptversion, und einige APIs wurden geändert oder entfernt. Eine der größten Änderungen, die sich auf Block- und Paket-Autoren auswirken wird, ist der Wechsel zum JSON-Dateiformat.

Generell werden Zero-Touch-Block-Autoren wenig bis gar keine Arbeit damit haben, ihre Pakete in der Version 2.0 zu verwenden.

Benutzeroberflächen-Blöcke und Blöcke, die direkt aus NodeModel abgeleitet werden, erfordern mehr Arbeit, damit sie in der Version 2.x ausgeführt werden können.

Erweiterungsautoren müssen möglicherweise auch einige Änderungen vornehmen, je nachdem, wie viele der Dynamo Core-APIs sie in ihren Erweiterungen verwenden.

Allgemeine Paket-Regeln:

• Bündeln Sie Dynamo- oder Dynamo Revit-DLL-Dateien nicht zusammen mit Ihrem Paket. Diese DLL-Dateien sind bereits von Dynamo geladen worden. Wenn Sie eine andere Version bündeln, als der Benutzer geladen hat (d. h., Sie verteilen zum Beispiel Dynamo Core 1.3, der Benutzer führt Ihr Paket jedoch unter Dynamo 2.0 aus), treten mysteriöse Laufzeitfehler auf. Dazu gehören DLL-Dateien wie DynamoCore.dll, DynamoServices.dll, DSCodeNodes.dll, ProtoGeometry.dll.

• Bündeln und verteilen Sie newtonsoft.json.net nach Möglichkeit nicht zusammen mit Ihrem Paket. Diese DLL-Datei ist ebenfalls bereits von Dynamo 2.x geladen. Das gleiche Problem wie oben kann auftreten.

Häufige Probleme:

1. Beim Öffnen eines Diagramms haben einige Blöcke mehrere Anschlüsse mit demselben Namen, das Diagramm sah beim Speichern jedoch einwandfrei aus. Dieses Problem kann mehrere Ursachen haben.

Die häufigste Fehlerursache ist, dass der Block mit einem Konstruktor erstellt wurde, der die Anschlüsse neu erstellt hat. Stattdessen hätte ein Konstruktor verwendet werden müssen, der die Anschlüsse geladen hat. Diese Konstruktoren sind gewöhnlich mit [JsonConstructor] gekennzeichnet. Beispiele finden Sie unten.

Dies kann folgende Ursachen haben:

• Es gab einfach keinen passenden [JsonConstructor], oder der Datei wurden Inports und Outports aus der JSON-DYN-Datei nicht übergeben.

• Es wurden zwei Versionen von JSON.net gleichzeitig in denselben Prozess geladen, was einen .NET-Laufzeitfehler verursachte, sodass das Attribut [JsonConstructor] nicht ordnungsgemäß verwendet werden konnte, um den Konstruktor zu markieren.

1. Beim Laden des Diagramms fehlen Blöcke vollständig, und es treten Fehler in der Konsole auf.

• Dies kann auftreten, wenn die Deserialisierung aus irgendeinem Grund fehlgeschlagen ist. Es empfiehlt sich, nur die benötigten Eigenschaften zu serialisieren. Wir können [JsonIgnore] für komplexe Eigenschaften verwenden, die Sie nicht laden oder speichern müssen, um sie zu ignorieren. Eigenschaften wie function pointer, delegate, action, oder event usw. Diese sollten nicht serialisiert werden, da sie in der Regel nicht deserialisiert werden können und einen Laufzeitfehler verursachen.

Aktualisierung im Detail:

Benutzerdefinierte Blöcke 1.3 - > 2.0

Bekannte Probleme:

• Ein gleicher benutzerdefinierter Blockname und Kategoriename auf derselben Ebene in library.js führt zu unerwartetem Verhalten. : Vermeiden Sie die Verwendung derselben Namen für Kategorie und Blöcke.

• Kommentare werden in Blockkommentare anstatt in Zeilenkommentare umgewandelt.

• Kurze Typnamen werden durch vollständige Namen ersetzt. Wenn Sie beispielsweise beim erneuten Laden des benutzerdefinierten Blocks keinen Typ angegeben haben, wird var[]..[] angezeigt, da dies der Vorgabetyp ist.

Zero-Touch-Blöcke 1.3 -> 2.0

• In Dynamo 2.0 wurden Listen- und Wörterbuchtypen getrennt, und die Syntax zum Erstellen von Listen und Wörterbüchern wurde geändert. Listen werden mit [] initialisiert, während Wörterbücher {} verwenden. Wenn Sie zuvor das Attribut DefaultArgument verwendet haben, um Parameter auf den Zero-Touch-Blöcken zu markieren, und die Listensyntax verwendet haben, um eine bestimmte Liste wie someFunc([DefaultArgument("{0,1,2}")]) als Vorgabe zu verwenden, ist dies nicht mehr gültig. Sie müssen dann das DesignScript-Snippet ändern, um die neue Initialisierungssyntax für Listen zu verwenden.

• Wie oben erwähnt, sollten Sie Dynamo-DLL-Dateien nicht mit Ihren Paketen verteilen (DynamoCore

NodeModel-Blöcke 1.3 -> 2.0

NodeModel-Blöcke erfordern die meiste Arbeit bei der Aktualisierung auf Dynamo 2.x. Auf höherer Ebene müssen Sie Konstruktoren implementieren, die nur zum Laden der Blöcke aus JSON verwendet werden, zusätzlich zu den regulären NodeModel-Konstruktoren, die zum Instanziieren neuer Instanzen der Blocktypen verwendet werden. Um zwischen diesen zu unterscheiden, markieren Sie die Konstruktoren für die Ladezeit mit [JsonConstructor], einem Attribut von newtonsoft.Json.net.

Die Namen der Parameter im Konstruktor sollten im Allgemeinen mit den Namen der JSON-Eigenschaften übereinstimmen. Diese Zuordnung wird jedoch komplizierter, wenn Sie die Namen überschreiben, die mithilfe von [JsonProperty]-Attributen serialisiert werden.

JSON-Konstruktoren

Die häufigste Änderung, die beim Aktualisieren von Blöcken erforderlich ist, die von der NodeModel-Basisklasse (oder anderen Dynamo Core-Basisklassen, z. B. DSDropDownBase) abgeleitet wurden, ist die Notwendigkeit, Ihrer Klasse einen JSON-Konstruktor hinzuzufügen.

Die Initialisierung eines neuen Blocks, der in Dynamo erstellt wurde (z. B. über die Bibliothek), ist weiterhin durch den ursprünglichen parameterlosen Konstruktor möglich. Der JSON-Konstruktor ist erforderlich, um einen Block zu initialisieren, der aus einer gespeicherten DYN- oder DYF-Datei deserialisiert (geladen) wird.

Der JSON-Konstruktor unterscheidet sich vom Basiskonstruktor dadurch, dass er über PortModel-Parameter für inPorts und outPorts verfügt, die von der JSON-Ladelogik bereitgestellt werden. Der Aufruf zum Registrieren der Anschlüsse für den Block ist hier nicht erforderlich, da die Daten in der DYN-Datei vorhanden sind. Ein JSON-Konstruktor sieht beispielsweise wie folgt aus:

using Newtonsoft.Json; //New dependency for Json

………

[JsonConstructor] //Attribute required to identity the Json constructor

//Minimum constructor implementation. Note that the base method invocation must also be present.

FooNode(IEnumerable<PortModel> inPorts, IEnumerable<PortModel> outPorts) : base(inPorts, outPorts) { }

Diese Syntax :base(Inports,outPorts){} ruft den nodeModel-Basiskonstruktor auf und übergibt die deserialisierten Anschlüsse an diesen.

Spezielle Logik im Klassenkonstruktor, die die Initialisierung bestimmter Daten umfasst, die in die DYN-Datei serialisiert werden (z. B. Festlegen der Anschlussregistrierung, Vergitterungsstrategie usw.), muss in diesem Konstruktor nicht wiederholt werden, da diese Werte aus dem JSON-Konstruktor gelesen werden können.

Dies ist der Hauptunterschied zwischen dem JSON-Konstruktor und Nicht-JSON-Konstruktoren für Ihre NodeModels. JSON-Konstruktoren werden beim Laden aus einer Datei aufgerufen und erhalten geladene Daten. Andere Benutzerlogik muss jedoch im JSON-Konstruktor dupliziert werden (z. B. Initialisieren von Ereignis-Steuerprogrammen für den Block oder Anhängen).

Beispiele finden Sie hier im DynamoSamples-Repository -> , oder .

Öffentliche Eigenschaften und Serialisierung

Bisher konnte ein Entwickler bestimmte Modelldaten über die SerializeCore- und DeserializeCore-Methode in das XML-Dokument serialisieren und deserialisieren. Diese Methoden sind weiterhin in der API vorhanden, werden jedoch in einer zukünftigen Version von Dynamo nicht mehr unterstützt (ein Beispiel finden Sie ). Mit der JSON.NET-Implementierung können jetzt public-Eigenschaften in der von NodeModel abgeleiteten Klasse direkt in die DYN-Datei serialisiert werden. JSON.Net stellt mehrere Attribute bereit, mit denen die Serialisierung der Eigenschaft gesteuert wird.

Dieses Beispiel mit der Angabe eines PropertyName finden Sie im Dynamo-Repository.

[JsonProperty(PropertyName = "InputValue")]

public DSColor DsColor {...

Konverter:

Anmerkung Wenn Sie eine eigene JSON.net-Konverterklasse erstellen, verfügt Dynamo derzeit über keinen Mechanismus, mit dem Sie diese in die Lade- und Speichermethoden einlesen können. Daher kann die Klasse auch dann nicht verwendet werden, wenn Sie sie mit dem [JsonConverter]-Attribut markieren. Sie können den Konverter stattdessen direkt in Ihrem Setter oder Getter aufrufen. //ZU ERLEDIGEN: Bestätigung dieser Einschränkung erforderlich. Alle Nachweise sind willkommen.

Ein Beispiel, in dem eine Serialisierungsmethode zum Konvertieren der Eigenschaft in eine Zeichenfolge angegeben ist, finden Sie im Dynamo-Repository.

[JsonProperty("MeasurementType"), JsonConverter(typeof(StringEnumConverter))]

public ConversionMetricUnit SelectedMetricConversion{...

Ignorieren von Eigenschaften

Für public-Eigenschaften, die nicht für die Serialisierung vorgesehen sind, muss das Attribut [JsonIgnore] hinzugefügt werden. Wenn die Blöcke in der DYN-Datei gespeichert werden, wird dadurch sichergestellt, dass diese Daten vom Serialisierungsmechanismus ignoriert werden. Beim erneuten Öffnen des Diagramms treten dann keine unerwarteten Auswirkungen auf. Ein Beispiel dafür finden Sie im Dynamo-Repository.

Rückgängig/Wiederholen

Wie bereits erwähnt, wurden in der Vergangenheit die Methoden SerializeCore und DeserializeCore verwendet, um Blöcke zu speichern und in die XML-DYN-Datei zu laden. Außerdem wurden sie und werden weiterhin auch zum Speichern und Laden des Blockstatus zum Rückgängigmachen und Wiederherstellen verwendet. Wenn Sie komplexe Funktionen zum Rückgängigmachen und Wiederherstellen für den NodeModel-Benutzeroberflächen-Block implementieren möchten, müssen Sie diese Methoden implementieren und in das XML-Dokumentobjekt serialisieren, das als Parameter für diese Methoden bereitgestellt wird. Dies sollte ein selten auftretender Anwendungsfall sein, mit Ausnahme von komplexen Benutzeroberflächen-Blöcken.

APIs für Ein- und Ausgabeanschlüsse

Ein häufiges Vorkommen in NodeModel-Blöcken, die von 2.0-API-Änderungen betroffen sind, ist die Anschlussregistrierung im Blockkonstruktor. Wenn Sie sich die Beispiele im Dynamo- oder DynamoSamples-Repository ansehen, werden Sie bisher die Verwendung der Methode InPortData.Add() oder OutPortData.Add() gefunden haben. In der Dynamo-API wurden die öffentlichen InPortData- und OutPortData-Eigenschaften bisher als veraltet markiert. In Version 2.0 wurden diese Eigenschaften entfernt. Entwickler sollten jetzt die Methoden InPorts.Add() und OutPorts.Add() verwenden. Darüber hinaus haben diese beiden Add()-Methoden leicht unterschiedliche Signaturen:

InPortData.Add(new PortData("Port Name", "Port Description")); //Old version valid in 1.3 but now deprecated

im Vergleich zu

InPorts.Add(new PortModel(PortType.Input, this, new PortData("Port Name", "Port Description"))); //Recommended 2.0

Beispiele für konvertierten Code finden Sie hier im Dynamo-Repository -> oder .

Der andere häufige Anwendungsfall, der von den 2.0-API-Änderungen betroffen ist, bezieht sich auf die Methoden, die häufig in der Methode BuildAst() verwendet werden, um das Blockverhalten basierend auf dem Vorhandensein oder Fehlen von Anschlussverbindungen zu bestimmen. Zuvor wurde HasConnectedInput(index) verwendet, um einen verbundenen Anschlussstatus zu validieren. Entwickler sollten nun die Eigenschaft InPorts[0].IsConnected verwenden, um den Anschlussverbindungsstatus zu überprüfen. Ein Beispiel hierfür finden Sie in im Dynamo-Repository.

Beispiele:

Gehen wir nun die Schritte für die Aktualisierung eines 1.3-Benutzeroberflächen-Blocks auf Dynamo 2.x durch.

Damit die nodeModel-Klasse in der Version 2.0 ordnungsgemäß geladen und gespeichert wird, müssen wir einfach nur einen jsonConstructor hinzufügen, der das Laden der Anschlüsse handhabt. Wir übergeben die Anschlüsse einfach an den Basiskonstruktor, und diese Implementierung ist leer.

Anmerkung: Rufen Sie RegisterPorts() oder eine Variante davon nicht in Ihrem JsonConstructor auf. Dadurch werden die Eingabe- und Ausgabeparameterattribute in Ihrer Blockklasse zum Erstellen neuer Anschlüsse verwendet. Dies ist nicht erwünscht, da die geladenen Anschlüsse verwendet werden sollen, die an den Konstruktor übergeben werden.

In diesem Beispiel wird der JSON-Konstruktor mit dem minimalsten Ladeaufwand hinzugefügt. Was passiert aber, wenn wir komplexere Konstruktionslogik ausführen müssen, wie z. B. die Einrichtung einiger Listener für die Ereignisbehandlung im Konstruktor? Das nächste aus dem entnommene Beispiel ist oben im JsonConstructors Section dieses Dokuments verknüpft.

Im Folgenden wird ein komplexerer Konstruktor für einen Benutzeroberflächen-Block dargestellt:

Wenn wir einen JSON-Konstruktor hinzufügen, um diesen Block aus einer Datei zu laden, müssen wir einen Teil dieser Logik neu erstellen. Beachten Sie jedoch, dass wir den Code, mit dem Anschlüsse erstellt, Vergitterungen festgelegt oder die Vorgabewerte für Eigenschaften angegeben werden, die aus der Datei geladen werden können, nicht berücksichtigen.

Beachten Sie, dass andere öffentliche Eigenschaften, die in JSON serialisiert wurden, wie ButtonText und WindowText, nicht als explizite Parameter zum Konstruktor hinzugefügt werden müssen. Sie werden automatisch von JSON.net mit den Settern für diese Eigenschaften festgelegt.

Erweiterungen sind ein leistungsstarkes Entwicklungswerkzeug im Dynamo-Ökosystem. Sie ermöglichen Entwicklern, benutzerdefinierte Funktionen basierend auf Dynamo-Interaktionen und -Logik zu steuern. Erweiterungen können in zwei Hauptkategorien unterteilt werden: Erweiterungen und Ansichtserweiterungen. Wie die Namen schon sagen, können Sie mit dem Ansichtserweiterungs-Framework die Dynamo-Benutzeroberfläche durch Registrieren benutzerdefinierter Menüelemente erweitern. Normale Erweiterungen funktionieren auf ähnliche Weise, nur ohne Benutzeroberfläche. Wir können beispielsweise eine Erweiterung erstellen, die bestimmte Informationen in der Dynamo-Konsole protokolliert. Dieses Szenario erfordert keine angepasste Benutzeroberfläche und kann daher auch mit einer Erweiterung durchgeführt werden.

Fallstudie für Erweiterungen

Im Anschluss an das Beispiel SampleViewExtension aus dem DynamoSamples-GitHub-Repository gehen wir die Schritte zum Erstellen eines einfachen, modusunabhängigen Fensters durch, in dem die aktiven Blöcke im Diagramm in Echtzeit angezeigt werden. Für eine Ansichtserweiterung müssen wir eine Benutzeroberfläche für das Fenster erstellen und Werte an ein Ansichtsmodell binden.

Auf NodeModel basierende Blöcke bieten erheblich mehr Flexibilität und Leistung als Zero-Touch-Blöcke. In diesem Beispiel wird der Zero-Touch-Rasterblock weiter optimiert. Dazu wird ein integrierter Schieberegler hinzugefügt, mit dem die Größe des Rechtecks zufällig festgelegt wird.

Der Schieberegler skaliert die Zellen relativ zu ihrer Größe, sodass der Benutzer keinen Schieberegler mit dem richtigen Bereich zur Verfügung stellen muss.

Model-View-Viewmodel-Muster

In diesem Abschnitt werden, ein Grundwissen über ZeroTouch vorausgesetzt, die Vorteile der Anpassung von Dynamo-Blöcken erläutert, um sowohl die Funktionalität als auch das Benutzererlebnis zu verbessern. Durch Hinzufügen von Elementen wie Warnmeldungen, Informationsmeldungen und benutzerdefinierten Symbolen können Sie Blöcke erstellen, die intuitiver, informativer und visuell ansprechender sind. Diese Anpassungen helfen den Benutzern nicht nur, potenzielle Probleme zu verstehen oder ihre Arbeitsabläufe zu optimieren, sondern stellen Ihre Blöcke auch als professionelle und benutzerfreundliche Werkzeuge in den Vordergrund.

Das Anpassen von Blöcken ist eine hervorragende Möglichkeit, um sicherzustellen, dass Ihre Lösungen klar, zuverlässig und auf die spezifischen Projektanforderungen zugeschnitten sind.

Erstellen von benutzerdefinierten Warnmeldungen mit OnLogWarningMessage

In Dynamo bietet die Methode OnLogWarningMessage eine Möglichkeit, Warnmeldungen direkt in der Konsole von Dynamo zu protokollieren. Dies ist eine leistungsstarke Funktion, insbesondere für Zero-Touch-Blöcke, da Entwickler Benutzer benachrichtigen können, wenn Probleme mit Eingaben oder Parametern auftreten, die zu unerwartetem Verhalten führen könnten. In dieser Anleitung erfahren Sie, wie Sie OnLogWarningMessage in einem beliebigen Zero-Touch-Block implementieren.

Implementierungsschritte für OnLogWarningMessage

Schritt 1: Importieren des erforderlichen Namensbereichs

OnLogWarningMessage ist Teil des DynamoServices-Namensbereichs. Fügen Sie dies daher zunächst Ihrer Projektdatei hinzu.

Schritt 2: Ermitteln, wann Warnungen protokolliert werden sollen

Bevor Sie eine Warnmeldung hinzufügen, beachten Sie die Logik in Ihrer Methode:

• Welche Bedingungen können zu falschen oder unerwarteten Ergebnissen führen?

• Gibt es bestimmte Eingabewerte oder Parameter, die für eine ordnungsgemäße Funktionsweise der Methode erforderlich sind?

Beispiele für zu überprüfende Bedingungen:

• Werte außerhalb des Bereichs (z. B. if (inputValue < 0))

• Null oder leere Sammlungen (z. B. if (list == null || list.Count == 0))

• Nicht übereinstimmende Datentypen (z. B., wenn ein Dateityp nicht unterstützt wird)

Schritt 3: Verwenden von OnLogWarningMessage, um die Warnung zu protokollieren

Platzieren Sie OnLogWarningMessage-Aufrufe dort, wo Sie Bedingungen erkennen, die Probleme verursachen könnten. Wenn die Bedingung erfüllt ist, protokollieren Sie eine Warnmeldung mit klaren Anweisungen für den Benutzer.

Syntax für OnLogWarningMessage

Implementierungsbeispiele für OnLogWarningMessage

Um OnLogWarningMessage in der Praxis zu demonstrieren, sehen Sie hier verschiedene Szenarien, die beim Erstellen eines Zero-Touch-Blocks auftreten können.

Beispiel 1: Überprüfen numerischer Eingaben

In diesem Beispiel verwenden wir den benutzerdefinierten Block, der im vorherigen Abschnitt Zero-Touch-Fallstudie - Rasterblock erstellt wurde, eine Methode mit der Bezeichnung RectangularGrid, die basierend auf xCount- und yCount-Eingaben ein Raster aus Rechtecken generiert. Wir gehen die Tests durch, wenn eine Eingabe ungültig ist, und verwenden dann OnLogWarningMessage, um eine Warnung zu protokollieren und die Verarbeitung zu stoppen.

Verwenden von OnLogWarningMessage für die Eingabevalidierung

Für die Erstellung eines Rasters basierend auf xCount und yCount. Stellen Sie sicher, dass es sich bei beiden Werten um positive Ganzzahlen handelt, bevor Sie fortfahren.

In diesem Beispiel:

• Bedingung: Wenn entweder xCount oder yCount kleiner oder gleich null ist

• Meldung: "Grid count values must be positive integers."

Dadurch wird die Warnung in Dynamo angezeigt, wenn ein Benutzer null oder negative Werte eingibt. Dies erleichtert das Verständnis der erwarteten Eingabe.

Nun können wir die Warnung in den Beispielblock Grids implementieren:

Beispiel 2: Prüfung auf keine oder leere Sammlungen

Wenn Ihre Methode eine Liste von Punkten erfordert, ein Benutzer jedoch eine leere oder Nullliste übergibt, können Sie OnLogWarningMessage verwenden, um ihn über das Problem zu informieren.

In diesem Beispiel:

• Bedingung: Wenn die points-Liste null ist oder weniger als drei Punkte enthält

• Meldung: "Point list cannot be null or have fewer than three points."

Dadurch werden Benutzer gewarnt, dass sie eine gültige Liste mit mindestens drei Punkten übergeben müssen, um ein Polygon zu bilden.

**Beispiel 3: Überprüfen der Dateitypkompatibilität **

Bei einem Block, der Dateipfade verarbeitet, sollten Sie sicherstellen, dass nur bestimmte Dateitypen zulässig sind. Wenn ein nicht unterstützter Dateityp erkannt wird, protokollieren Sie eine Warnung.

In diesem Beispiel:

• Bedingung: Wenn der Dateipfad nicht auf .csv endet

• Meldung: "Only CSV files are supported."

Dadurch werden Benutzer darauf aufmerksam gemacht, sicherzustellen, dass sie eine CSV-Datei übermitteln, um Probleme im Zusammenhang mit inkompatiblen Dateiformaten zu vermeiden.

Hinzufügen von Informationsmeldungen mit OnLogInfoMessage

In Dynamo ermöglicht es OnLogInfoMessage aus dem DynamoServices-Namensbereich Entwicklern, Informationsmeldungen direkt in der Konsole von Dynamo zu protokollieren. Dies ist hilfreich, um erfolgreiche Vorgänge zu bestätigen, den Fortschritt zu kommunizieren oder zusätzliche Einblicke in Blockaktionen zu erhalten. In dieser Anleitung erfahren Sie, wie Sie OnLogInfoMessage in einen beliebigen Zero-Touch-Block einfügen, um Feedback und Benutzerfreundlichkeit zu verbessern.

Implementierungsschritte für OnLogInfoMessage

Schritt 1: Importieren des erforderlichen Namensbereichs

OnLogInfoMessage ist Teil des DynamoServices-Namensbereichs. Fügen Sie dies daher zunächst Ihrer Projektdatei hinzu.

Schritt 2: Ermitteln, wann Informationen protokolliert werden sollen

Bevor Sie eine Informationsmeldung hinzufügen, denken Sie über den Zweck Ihrer Methode nach:

• Welche Informationen sollten nach Abschluss eines Vorgangs sinnvollerweise bestätigt werden?

• Gibt es wichtige Schritte oder Meilensteine innerhalb der Methode, über die die Benutzer möglicherweise informiert werden sollten?

Beispiele für nützliche Bestätigungen:

• Abschlussmeldungen (z. B., wenn ein Raster oder Modell vollständig erstellt wurde)

• Details zu verarbeiteten Daten (z. B. 10 Elemente erfolgreich verarbeitet)

• Zusammenfassung der Ausführung (z. B. im Prozess verwendete Parameter)

Schritt 3: Verwenden von OnLogInfoMessage zum Protokollieren von Informationsmeldungen

Platzieren Sie OnLogInfoMessage-Aufrufe an wichtigen Punkten in Ihrer Methode. Wenn ein wichtiger Schritt oder Abschluss erfolgt, protokollieren Sie eine Informationsmeldung, um den Benutzer über den Vorfall zu informieren.

Syntax für OnLogInfoMessage

Implementierungsbeispiele für OnLogInfoMessage

Im Folgenden finden Sie verschiedene Szenarien, um die Verwendung von OnLogInfoMessage in Ihren Zero-Touch-Blöcken zu veranschaulichen.

Beispiel 1: Überprüfen numerischer Eingaben

In diesem Beispiel verwenden wir den benutzerdefinierten Block, der im vorherigen Abschnitt Zero-Touch-Fallstudie - Rasterblock erstellt wurde, eine Methode mit der Bezeichnung RectangularGrid, die basierend auf xCount- und yCount-Eingaben ein Raster aus Rechtecken generiert. Wir werden die Tests durchgehen, wenn eine Eingabe ungültig ist, und dann OnLogInfoMessage verwenden, um Informationen bereitzustellen, nachdem der Block fertig ausgeführt wurde.

Verwenden von OnLogInfoMessage für die Eingabevalidierung

Für die Erstellung eines Rasters basierend auf xCount und yCount. Nach dem Erstellen des Rasters können Sie dessen Erstellung bestätigen, indem Sie eine Informationsmeldung mit den Bemaßungen des Rasters protokollieren.

In diesem Beispiel:

• Bedingung: Die Rastererstellung ist abgeschlossen.

• Meldung: "Successfully created a grid with dimensions {xCount}x{yCount}."

Diese Meldung informiert Benutzer darüber, dass das Raster wie angegeben erstellt wurde, und hilft ihnen zu bestätigen, dass der Block wie erwartet funktionierte.

Nun können wir die Warnung in den Beispielblock Grids implementieren:

Beispiel 2: Bereitstellen von Informationen zur Datenanzahl

Wenn Sie einen Block erstellen, der eine Liste von Punkten verarbeitet, können Sie protokollieren, wie viele Punkte erfolgreich verarbeitet wurden. Dies kann für große Datensätze nützlich sein.

In diesem Beispiel:

• Bedingung: Nach Abschluss der Schleife, die Anzahl der verarbeiteten Elemente wird angezeigt.

• Meldung: "6 points were processed successfully."

Diese Meldung hilft Benutzern, das Ergebnis der Verarbeitung nachzuvollziehen und zu bestätigen, dass alle Punkte verarbeitet wurden.

Beispiel 3: Zusammenfassung der verwendeten Parameter

In einigen Fällen ist es hilfreich, die Eingabeparameter zu bestätigen, die ein Block zum Abschließen einer Aktion verwendet hat. Wenn Ihr Block beispielsweise Daten in eine Datei exportiert, können Sie durch das Protokollieren des Dateinamens und -pfads Benutzern die Sicherheit geben, dass die richtige Datei verwendet wurde.

In diesem Beispiel:

• Bedingung: Der Exportvorgang wurde erfolgreich abgeschlossen.

• Meldung: "Data exported successfully to {filePath}."

Mit dieser Meldung wird den Benutzern bestätigt, dass der Export erfolgreich war, und der genaue Dateipfad wird angezeigt, um Verwirrung über die Dateispeicherorte zu vermeiden.

Erstellen und Hinzufügen von benutzerdefinierter Dokumentation zu Blöcken

Dokumentation für benutzerdefinierte Blöcke

In der Vergangenheit gab es in Dynamo Einschränkungen bei der Art und Weise, wie Paketautoren die Dokumentation für ihre Blöcke bereitstellen konnten. Autoren von benutzerdefinierten Blöcken konnten nur kurze Beschreibungen in der QuickInfo des Blocks angeben oder das Paket mit ausführlich kommentierten Beispieldiagrammen versenden.

Eine neue Möglichkeit

Dynamo bietet jetzt ein verbessertes System für Paketautoren, mit dem eine optimierte und mehr beschreibende Dokumentation für Ihre benutzerdefinierten Blöcke bereitgestellt werden kann. Bei diesem neuen Ansatz werden die benutzerfreundliche Markdown-Sprache für die Texterstellung und die Ansichtserweiterung des Dokumentationsbrowsers zur Anzeige von Markdown in Dynamo verwendet. Die Verwendung von Markdown bietet Paketautoren eine Vielzahl neuer Möglichkeiten beim Dokumentieren ihrer benutzerdefinierten Blöcke.

Was ist Markdown?

Markdown ist eine einfache Auszeichnungssprache, die Sie zum Formatieren von Klartextdokumenten verwenden können. Seit Markdown im Jahr 2004 ins Leben gerufen wurde, hat ihre Popularität stetig zugenommen, sodass sie heute eine der beliebtesten Auszeichnungssprachen der Welt ist.

Erste Schritte mit Markdown

Es ist ganz einfach, Markdown-Dateien zu erstellen. Alles, was Sie brauchen, ist ein einfacher Texteditor, wie den Windows-Editor, und schon kann es losgehen. Es gibt jedoch noch einfachere Möglichkeiten, Markdown-Code zu schreiben, als den Editor zu verwenden. Es gibt mehrere Online-Editoren, wie z. B. , mit denen Sie Ihre Änderungen in Echtzeit sehen können, während Sie sie vornehmen. Eine weitere beliebte Methode zum Bearbeiten von Markdown-Dateien ist die Verwendung eines Code-Editors wie .

Was kann Markdown?

Markdown ist sehr flexibel und sollte genügend Funktionen bieten, um auf einfache Weise eine gute Dokumentation zu erstellen. Dazu gehören: Hinzufügen von Mediendateien wie Bildern oder Videos, Erstellen von Tabellen mit verschiedenen Inhaltsformen und natürlich einfache Textformatierungsfunktionen wie fett oder kursiv. All dies und noch viel mehr ist beim Schreiben von Markdown-Dokumenten möglich. Weitere Informationen finden Sie in dieser Anleitung, in der die erklärt wird.

Hinzufügen erweiterter Dokumentation zu Ihren Blöcken

Das Hinzufügen von Dokumentation zu Ihren Blöcken ist einfach. Die Dokumentation kann zu allen Varianten benutzerdefinierter Blöcke hinzugefügt werden, dazu gehören:

• Vordefinierte Dynamo-Blöcke

• Benutzerdefinierte Blöcke (.dyf): Sammlungen von vordefinierten und/oder anderen Paketblöcken.

• Benutzerdefinierte C#-Paketblöcke (auch als ZeroTouch bezeichnet). Diese benutzerdefinierten Blöcke sehen wie die vordefinierten Blöcke aus.

• NodeModel-Blöcke (Blöcke, die spezielle Benutzeroberflächen-Elemente wie Dropdown-Menüs oder Auswahlschaltflächen enthalten)

Führen Sie die folgenden Schritte aus, damit Ihre Markdown-Dateien in Dynamo angezeigt werden.

Öffnen von Dokumentationsdateien in Dynamo

Dynamo verwendet die Ansichtserweiterung des Dokumentationsbrowsers, um die Dokumentation für Blöcke anzuzeigen. Um die Dokumentation eines Blocks zu öffnen, klicken Sie mit der rechten Maustaste auf den Block und wählen Hilfe. Dadurch wird der Dokumentationsbrowser geöffnet, und der mit diesem Block verknüpften Markdown-Code wird angezeigt, sofern vorhanden.

Die im Dokumentationsbrowser angezeigte Dokumentation besteht aus zwei Teilen. Der erste Teil ist der Abschnitt Node Info. Dieser wird automatisch aus den aus dem Block extrahierten Informationen generiert, wie z. B. Eingaben/Ausgaben, Blockkategorie, Blockname/Namensbereich und Kurzbeschreibung des Blocks. Im zweiten Teil wird die Dokumentation für benutzerdefinierte Blöcke angezeigt. Dabei handelt es sich um die Markdown-Datei, die zur Dokumentation des Blocks bereitgestellt wird.

doc-Ordner für Pakete

Um Dokumentationsdateien zu Ihren Blöcken in Dynamo hinzuzufügen, erstellen Sie in Ihrem Paketverzeichnis einen neuen Ordner mit dem Namen /doc. Wenn das Paket geladen ist, durchsucht Dynamo dieses Verzeichnis und ruft alle darin enthaltenen Markdown-Dokumentationsdateien ab.

Benennen von Markdown-Dateien

Um sicherzustellen, dass Dynamo weiß, welche Datei geöffnet werden soll, wenn diese für einen bestimmten Block angefordert wird, muss die Benennung der Markdown-Datei in einem bestimmten Format erfolgen. Die Markdown-Datei sollte entsprechend dem Namensbereich des Blocks benannt werden, den sie dokumentiert. Wenn Sie sich beim Namensbereich des Blocks nicht sicher sind, sehen Sie sich den Abschnitt Node Info an, nachdem Sie Help im Block gedrückt haben. Unter dem Blocknamen sehen Sie den vollständigen Namensbereich des ausgewählten Blocks.

Dieser Namensbereich sollte der Name der Markdown-Datei für diesen bestimmten Block sein. Der Namensbereich von CustomNodeExample aus den obigen Abbildungen lautet beispielsweise TestPackage.TestCategory.CustomNodeExample. Daher sollte die Markdown-Datei für diesen Block den Namen TestPackage.TestCategory.CustomNodeExample.md erhalten.

In besonderen Fällen, in denen Überlastungen Ihrer Blöcke (Blöcke mit demselben Namen, aber unterschiedlichen Eingaben) vorhanden sind, müssen Sie die Eingabenamen in () nach dem Blocknamensbereich hinzufügen. Der integrierte Block Geometry.Translate weist beispielsweise mehrere Überlastungen auf. In diesem Fall würden wir die Markdown-Dateien für die Blöcke unten wie folgt benennen: Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction).md Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction,distance).md

Ändern von Markdown-Dateien, während sie in Dynamo geöffnet sind

Um das Ändern von Dokumentationsdateien zu erleichtern, implementiert der Dokumentationsbrowser einen Dateibeobachter für die geöffnete Dokumentationsdatei. Dadurch können Sie Änderungen an der Markdown-Datei vornehmen, und die Änderungen werden sofort in Dynamo angezeigt.

Das Hinzufügen neuer Dokumentationsdateien ist auch möglich, während Dynamo geöffnet ist. Fügen Sie dem Ordner /doc einfach eine neue Markdown-Datei mit einem Namen hinzu, der dem dokumentierten Block entspricht.

Hinzufügen von benutzerdefinierten Symbolen zu Zero-Touch-Blöcken

Überblick

Durch benutzerdefinierte Symbole für Zero-Touch-Blöcke in Dynamo werden Ihre Blöcke optisch unterscheidbar und sind in der Bibliothek leichter zu erkennen. Durch Hinzufügen maßgeschneiderter Symbole können Sie Ihre Blöcke von den anderen besser unterscheidbar machen, sodass Benutzer sie in einer Liste schnell ermitteln können.

In dieser Anleitung erfahren Sie, wie Sie Symbole zu Ihren Zero-Touch-Blöcken hinzufügen.

Schritte zum Hinzufügen von benutzerdefinierten Blocksymbolen

Schritt 1: Einrichten des Projekts

Erstellen Sie zunächst ein Visual Studio-Klassenbibliotheksprojekt (.NET Framework) für Ihre Zero Touch-Blöcke. Wenn Sie noch kein Projekt haben, finden Sie im Abschnitt Erste Schritte eine Schritt-für-Schritt-Anleitung zum Erstellen eines Projekts.

Stellen Sie sicher, dass Sie mindestens einen funktionalen Zero-Touch-Block haben, da Symbole nur zu vorhandenen Blöcken hinzugefügt werden können. Weitere Informationen finden Sie unter Zero-Touch-Fallstudie - Rasterblock.

Schritt 2: Erstellen Ihrer Symbolbilder

So erstellen Sie benutzerdefinierte Symbole

1. Entwerfen Sie Ihre Symbole: Verwenden Sie einen Bildeditor, um einfache, visuell klare Symbole für Ihre Blöcke zu erstellen.

2. Bildspezifikationen:

   • Kleines Symbol: 32 x 32 Pixel (wird in der Seitenleiste der Bibliothek und auf dem Block selbst verwendet).

   • Großes Symbol

Beispiel: Wenn das Projekt ZeroTouchNodeIcons, Ihre Klasse Grids und Ihre Methode RectangularGrid lauten, werden die Dateien wie folgt benannt:

• ZeroTouchNodeIcons.Grids.RectangularGrid.Small.png

• ZeroTouchNodeIcons.Grids.RectangularGrid.Large.png

Tipp: Verwenden Sie für alle Ihre Symbole einen einheitlichen Designstil, um ein professionelles Aussehen zu erzielen.

Schritt 3: Hinzufügen einer Ressourcendatei zum Projekt

Erstellen Sie eine Ressourcendatei, um Ihre Symbole in die .dll einzubetten:

1. Fügen Sie eine neue Ressourcendatei hinzu:

• Klicken Sie im Solution Explorer mit der rechten Maustaste auf das Projekt.

• Wechseln Sie zu Add > New Item und wählen Sie Resources File aus.

• Geben Sie der Datei den Namen <ProjectName>Images.resx. Beispielsweise ZeroTouchNodeIconsImages.resx.

1. Deaktivieren Sie die benutzerdefinierte Werkzeugeigenschaft:

   • Wählen Sie die Ressourcendatei im Solution Explorer aus.

   • Löschen Sie in der Gruppe Properties das Feld Custom Tool, indem Sie den Wert ResXFileCodeGenerator entfernen.

ANMERKUNG: Wenn Sie das Feld Custom Tool nicht bereinigen, konvertiert Visual Studio Punkte in Ihren Ressourcennamen in Unterstriche. Vergewissern Sie sich vor der Erstellung, dass die Ressourcennamen anstelle von Unterstrichen Punkte als Trennzeichen für Klassennamen enthalten.

Schritt 4: Fügen Sie Ihre Bilder als Ressourcen hinzu

1. Doppelklicken Sie auf die erstellte Ressourcendatei:

   • Fügen Sie jeweils ein Bild mit der Schaltfläche + hinzu.

   • Setzen Sie den Ressourcentyp auf File.

   • Navigieren Sie zum Speicherort der Bilddatei, und fügen Sie die großen und kleinen

ANMERKUNG: Sie müssen Ihre Bilder nicht in einem Ressourcenordner oder Unterordnern Large und Small organisieren. Diese Methode hat sich jedoch bewährt.

Schritt 5: Konvertieren des Projekts in den SDK-Stil (für ältere Projekte)

Wenn Ihr Projekt noch nicht im SDK-Stil vorliegt (erforderlich zum Einbetten von Ressourcen), konvertieren Sie es:

1. Installieren Sie die .NET Upgrade Assistant-Erweiterung über das Menü Extensions > Manage Extensions in Visual Studio.

1. Klicken Sie im Solution Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Upgrade > Convert project to SDK-style aus.

1. Warten Sie, bis die Konvertierung abgeschlossen ist.

Schritt 6: Hinzufügen eines After-Build-Skripts zum Einbetten von Ressourcen

1. Beenden Sie das Projekt:

   • Klicken Sie im Solution Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Unload Project aus.

1. Bearbeiten Sie die Datei .csproj:

   • Fügen Sie das folgende <Target>-Element zwischen </ItemGroup> und </Project> hinzu:

1. Ersetzen Sie alle Instanzen von ZeroTouchNodeIcons durch Ihren Projektnamen.

2. Laden Sie das Projekt neu:

   • Klicken Sie mit der rechten Maustaste auf das beendete Projekt, und wählen Sie Reload Project.

Schritt 7: Erstellen und Laden Ihrer .dll in Dynamo

1. Erstellen Sie das Projekt:

   • Nachdem Sie das After-Build-Skript hinzugefügt haben, erstellen Sie Ihr Projekt in Visual Studio.

1. Suchen Sie nach Ausgabedateien:

   • Stellen Sie sicher, dass sich .dll und .customization.dll im Ordner bin befinden.

2. Fügen Sie die .dll zu Dynamo hinzu:

1. Ihre benutzerdefinierten Blöcke sollten nun mit den entsprechenden Symbolen angezeigt werden.