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 Importieren von Zero-Touch-Bibliotheken.

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 Vorgehensweisen zur Skripterstellung 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 Primer 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 Primer eine detaillierte exemplarische Vorgehensweise an.

• Python-Blöcke stellen eine Skripterstellungs-Schnittstelle im Arbeitsbereich für visuelle Programmierung dar, ähnlich wie Codeblöcke. Die Autodesk.DesignScript-Bibliotheken verwenden eine Punktnotation ähnlich der von DesignScript.

  Laden Sie ein Beispiel für einen Python-Block herunter (klicken Sie mit der rechten Maustaste und dann auf Speichern unter), oder sehen Sie sich im Primer eine detaillierte exemplarische Vorgehensweise an.

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 A-Forge-Beispiel 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 Dynamo-GitHub-Wiki 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 JSON-Konstruktor, da sie sonst nicht in Dynamo 2.0 geöffnet werden können.

Die API-Dokumentation von Dynamo deckt derzeit die Kernfunktionen ab: http://dynamods.github.io/DynamoAPI.

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.

Die DynamoRevit-Quelldateien werden auch im DynamoDS-GitHub gehostet, damit Entwickler Beiträge einbringen und Beta-Versionen erstellen können. Die Erstellung von DynamoRevit aus Quelldateien folgt im Allgemeinen dem gleichen Prozess wie bei Dynamo, mit Ausnahme einiger wichtiger Details:

• DynamoRevit referenziert Dynamo-Assemblys. Diese sollten daher mit entsprechenden NuGet-Paketen erstellt werden. DynamoRevit 2.x lässt sich beispielsweise nicht in Dynamo 1.3 laden.

• DynamoRevit ist für bestimmte Revit-Versionen spezifisch. Beispiel: Die Verzweigung DynamoRevit 2018 muss unter Revit 2018 ausgeführt werden.

In diesem Handbuch verwenden wir folgende Versionen:

• Revit 2023

• Den neuesten DynamoRevit-Build in der Verzweigung Revit2023

• Den neuesten Dynamo-Build

Um einen erfolgreichen Build zu gewährleisten, werden sowohl das Dynamo- als auch das DynamoRevit-Repository, die für diese exemplarische Vorgehensweise verwendet werden, geklont und erstellt.

Anmerkung: Die manuelle Erstellung von Dynamo vor DynamoRevit ist nur erforderlich, wenn Sie Dynamo 1.x und DynamoRevit 1.x erstellen. Neuere Versionen des DynamoRevit-Repositorys basieren auf dem NuGet-Paket-Manager für die zum Erstellen erforderlichen Dynamo-Abhängigkeiten. Auch wenn beim Build Dynamo Revit 2.x kein manueller Abruf von Dynamo erforderlich ist, benötigen Sie die dlls -Kerndateien dennoch an anderer Stelle, um das Dynamo Revit-addin auszuführen. Es lohnt sich also, Dynamo dennoch abzurufen und zu erstellen. Weitere Informationen finden Sie unten:

Suchen des DynamoRevit-Repositorys auf GitHub

Der Code für das DynamoRevit-Projekt befindet sich in einem separaten Repository auf GitHub, nicht in dem Repository, in dem sich der Dynamo-Kernquellcode befindet. Dieses Repository enthält die Quelldateien für Revit-spezifische Blöcke und das Revit-Zusatzmodul, das Dynamo lädt. Builds von DynamoRevit für verschiedene Versionen von Revit (z. B. 2016, 2017 oder 2018) sind im Repository als Verzweigungen angeordnet.

Die DynamoRevit-Quelldateien befinden sich hier: .

1. Klonen oder laden Sie das Repository herunter.

2. Die DynamoRevit-Verzweigungen referenzieren Revit-Versionen.

Klonen des Repositorys mithilfe von Git

Ähnlich wie beim Abrufen des Dynamo-Repositorys verwenden wir den Git-Befehl zum Klonen, um DynamoRevit zu klonen und die Verzweigung anzugeben, die unserer Revit-Version entspricht. Zunächst öffnen wir eine Befehlszeilenschnittstelle und legen das aktuelle Verzeichnis auf den Speicherort fest, an den wir die Dateien klonen möchten.

cd C:\Users\username\Documents\GitHub ändert das aktuelle Verzeichnis.

Ersetzen Sie username durch Ihren Benutzernamen.

Jetzt können wir das Repository in dieses Verzeichnis klonen. Wir müssen eine Verzweigung des Repositorys angeben. Wir können jedoch nach dem Klonen zu dieser Verzweigung wechseln.

git clone https://github.com/DynamoDS/DynamoRevit.git klont das Repository von einer Remote-URL und wechselt vorgabemäßig zur Hauptverzweigung.

Nachdem das Klonen des Repositorys abgeschlossen ist, ändern Sie das aktuelle Verzeichnis in den Repository-Ordner, und wechseln Sie zu der Verzweigung, die der installierten Version von Revit entspricht. In diesem Beispiel wird Revit RC2.13.1_Revit2023 verwendet. Alle Remote-Verzweigungen können auf der GitHub-Seite im Dropdown-Menü Branch angezeigt werden.

cd C:\Users\username\Documents\GitHub\DynamoRevit ändert das Verzeichnis in DynamoRevit. git checkout RC2.13.1_Revit2023 setzt die aktuelle Verzweigung auf RC2.13.1_Revit2023. git branch überprüft, in welcher Verzweigung wir uns befinden, und zeigt die anderen Verzweigungen an, die lokal verfügbar sind.

Die Verzweigung mit einem Sternchen ist die derzeit ausgecheckte Verzweigung. Die Verzweigung Revit2018 wird angezeigt, da wir diese zuvor ausgecheckt haben, sodass sie lokal verfügbar ist.

Es ist wichtig, die richtige Verzweigung des Repositorys zu wählen, um sicherzustellen, dass beim Erstellen des Projekts in Visual Studio Assemblys in der richtigen Version des Revit-Installationsverzeichnisses referenziert werden, insbesondere RevitAPI.dll und RevitAPIUI.dll.

Erstellen des Repositorys mit Visual Studio

1. Klicken Sie mit der rechten Maustaste auf restorepackages.bat, und wählen Sie Run as administrator.

Wenn die Pakete erfolgreich wiederhergestellt wurden, wird ein packages-Ordner mit den neuesten NuGet-Beta-Paketen zum Ordner src hinzugefügt.

1. Die neuesten Dynamo-NuGet-Beta-Pakete

Nachdem die Pakete wiederhergestellt wurden, öffnen Sie die Visual Studio-Projektmappendatei DynamoRevit.All.sln in src, und erstellen Sie die Projektmappe. Der Build kann AssemblySharedInfo.cs möglicherweise zunächst nicht finden. Wenn dies der Fall ist, kann dieses Problem durch erneutes Ausführen des Builds behoben werden.

1. Wählen Sie Build > Build Solution aus.

2. Überprüfen Sie im Ausgabefenster, ob die Erstellung erfolgreich war. Es sollte eine Meldung ähnlich der folgenden angezeigt werden: ===== Build: 13 succeeded, 0 failed, 0 up-to-date, 0 skipped =====.

Ausführen eines lokalen Builds von DynamoRevit in Revit

Erstellen Sie eine Dynamo.addin-Datei im Zusatzmodulordner von Revit, der sich unter C:\ProgramData\Autodesk\Revit\Addins\2023 befindet. Wir haben bereits eine Version von DynamoRevit installiert, daher bearbeiten wir einfach die vorhandene Datei, um auf den neuen Build zu verweisen.

• Geben Sie den Dateipfad von DynamoRevitDS.dll in <Assembly>...</Assembly> an.

Alternativ können wir auch festlegen, dass das Zusatzmodul die Versionsauswahl anstelle einer bestimmten Assembly lädt.

• Legen Sie den Dateipfad für <Assembly>...</Assembly> auf DynamoRevitVersionSelector.dll fest.

• <FullClassName>...</FullClassName> gibt an, welche Klasse aus der Assembly instanziiert werden soll, auf die mit dem oben angegebenen Assembly-Elementpfad verwiesen wurde. Diese Klasse wird als Einstiegspunkt für das Zusatzmodul verwendet.

Außerdem müssen wir die vorhandene Dynamo-Version entfernen, die im Lieferumfang von Revit enthalten ist. Wechseln Sie dazu zu C:\\Program Files\Autodesk\Revit 2023\AddIns , und entfernen Sie die beiden Ordner, die Dynamo enthalten: DynamoForRevit und DynamoPlayerForRevit. Sie können sie entweder löschen oder in einem separaten Ordner sichern, wenn Sie die Originalversion von Dynamo for Revit wiederherstellen müssen.

Der zweite Schritt besteht darin, einen Dateipfad für die Dynamo Core-Assemblys zur Datei Dynamo.config im Ordner bin von DynamoRevit hinzuzufügen. DynamoRevit lädt diese, wenn das Zusatzmodul in Revit geöffnet wird. In dieser Konfigurationsdatei können Sie Ihr DynamoRevit-Zusatzmodul auf verschiedene Versionen von Dynamo Core verweisen, um Änderungen sowohl in Core als auch in DynamoRevit zu entwickeln und zu testen.

Der Code sollte wie folgt aussehen:

• Fügen Sie den Verzeichnispfad des Ordners bin zu <add key/> hinzu.

Wir haben Dynamo direkt vor dieser exemplarischen Vorgehensweise geklont und erstellt, um sicherzustellen, dass Dynamo gut mit DynamoRevit funktioniert. Der Verzeichnispfad verweist auf diesen Build.

Wenn wir jetzt Revit öffnen, sollte sich auf der Registerkarte Verwalten ein Dynamo-Zusatzmodul befinden.

1. Wählen Sie Manage aus.

2. Klicken Sie auf das Symbol für das Dynamo-Zusatzmodul.

3. Eine Instanz von DynamoRevit.

Wenn ein Fehler-Dialogfeld mit fehlenden Assemblys angezeigt wird, ist es wahrscheinlich, dass ein Konflikt zwischen den von Ihnen erstellten Versionen von DynamoCore und den Versionen, die Sie zur Laufzeit laden, aufgetreten ist. Beispiel: DynamoRevit mit den neuesten 2.0-Beta-Paketen von DynamoCore funktioniert nicht, wenn Sie versuchen, die Anwendung mit Dynamo 1.3-DLL-Dateien zu starten. Stellen Sie sicher, dass beide Repositorys dieselbe Version aufweisen und DynamoRevit eine übereinstimmende Version der NutGet-Abhängigkeiten abruft. Diese werden in der Datei package.json des DynamoRevit-Repositorys definiert.

Debugging in DynamoRevit mithilfe von Visual Studio

Im vorherigen Abschnitt Erstellen von Dynamo aus Quelldateien haben wir das Debugging in Visual Studio kurz vorgestellt und beschrieben, wie Visual Studio an einen Prozess angehängt werden kann. Anhand einer Beispielausnahme im Block Wall.ByCurveAndHeight werden Sie durch das Anhängen an einen Prozess, das Festlegen von Haltepunkten, das Durchgehen durch Code und das Ermitteln der Quelle der Ausnahme mithilfe der Aufrufliste geführt. Diese Debugging-Werkzeuge gelten generell für .NET-Entwicklungsarbeitsabläufe. Daher ist es sinnvoll, sich außerhalb dieses Handbuchs eingehender mit diesen zu beschäftigen.

• Haltepunkte definieren im Quellcode Zeilen, an denen die Anwendung vor dem Ausführen angehalten wird. Wenn ein Block einen Absturz von DynamoRevit verursacht oder ein unerwartetes Ergebnis zurückgibt, können wir einen Haltepunkt zur Quelle des Blocks hinzufügen, um den Vorgang anzuhalten, den Code einzusehen und die Live-Werte der Variablen zu überprüfen, bis wir die Ursache des Problems gefunden haben.

• Code durchgehen: Hierbei wird die Quelle Zeile für Zeile durchlaufen. Wir können Funktionen nacheinander ausführen, einen Funktionsaufruf schrittweise ausführen oder die gerade ausgeführte Funktion verlassen.

• Die Aufrufliste zeigt die Funktion an, die derzeit von einem Prozess ausgeführt wird, im Vergleich zu den vorherigen Funktionsaufrufen, die diesen Funktionsaufruf veranlasst haben. Visual Studio verfügt über ein Aufruflistenfenster, um dies anzuzeigen. Wenn wir beispielsweise eine Ausnahme außerhalb des Quellcodes erreichen, können wir den Pfad zum aufrufenden Code in der Aufrufliste sehen.

Der Block Wall.ByCurveAndHeight gibt eine Ausnahme mit der folgenden Meldung aus, wenn er eine PolyCurve als Kurveneingabe erhält: To BSPlineCurve Not Implemented. Durch das Debugging können wir herausfinden, warum genau der Block diesen Geometrietyp nicht als Eingabe für den Kurvenparameter akzeptiert. In diesem Beispiel wird davon ausgegangen, dass DynamoRevit erfolgreich erstellt wurde und als Zusatzmodul für Revit ausgeführt werden kann.

1. Der Block Wall.ByCurveAndHeight löst eine Ausnahme aus.

Öffnen Sie zunächst die Projektmappendatei DynamoRevit.All.sln, starten Sie Revit, und starten Sie dann das DynamoRevit-Zusatzmodul. Hängen Sie anschließend im Fenster Attach to Process Visual Studio an den Revit-Prozess an.

Revit und DynamoRevit müssen ausgeführt werden, um als verfügbare Prozesse angezeigt zu werden.

1. Öffnen Sie das Fenster Attach to Process durch Auswahl von Debug > Attach to Process....

2. Legen Sie Transport auf Default fest.

3. Wählen Sie Revit.exe aus.

4. Wählen Sie Attach aus.

Wenn Visual Studio an Revit angehängt ist, öffnen Sie den Wall.ByCurveAndHeight-Quellcode in Wall.cs. Wir finden diesen im Projektmappen-Explorer unter Libraries > RevitNodes > Elements im Bereich Public static constructors der Datei. Legen Sie im Konstruktor des Wandtyps einen Haltepunkt fest, sodass bei Ausführung eines Blocks in Dynamo der Prozess unterbrochen wird und wir die Codezeilen einzeln durchgehen können. Normalerweise beginnen Dynamo-Konstruktoren vom Typ Zero-Touch mit By<parameters>.

1. Die Klassendatei mit dem Konstruktor für Wall.ByCurveAndHeight.

2. Legen Sie einen Haltepunkt fest, indem Sie entweder links neben die Zeilennummer klicken oder mit der rechten Maustaste auf die Codezeile klicken und Breakpoint > Insert Breakpoint auswählen.

Nachdem der Haltepunkt festgelegt wurde, muss der Prozess durch die Funktion Wall.ByCurveAndHeight laufen. Die Funktion kann in Dynamo erneut ausgeführt werden, indem erneut eine Verbindung mit einem der Anschlüsse hergestellt wird. Dadurch wird eine erneute Ausführung des Blocks erzwungen. Der Haltepunkt wird in Visual Studio erreicht.

1. Das Symbol für den Haltepunkt ändert sich, wenn er erreicht wird.

2. Das Fenster mit der Aufrufliste zeigt die als Nächstes angewendete Methode.

Überspringen Sie nun die einzelnen Zeilen im Konstruktor, bis die Ausnahme erreicht wird. Der gelb hervorgehobene Code ist die nächste auszuführende Anweisung.

1. Die Debugging-Werkzeuge für die Navigation im Code.

2. Drücken Sie Step Over, um den markierten Code auszuführen, und unterbrechen Sie dann die Ausführung, nachdem die Funktion zurückgegeben wurde.

3. Die nächste auszuführende Anweisung, angegeben durch die gelbe Hervorhebung und den Pfeil.

Wenn wir weiter durch die Funktion gehen, erreichen wir die Ausnahme, die im DynamoRevit-Fenster angezeigt wird. Im Fenster mit der Aufrufliste können wir sehen, dass die Ausnahme ursprünglich von einer Methode mit dem Namen Autodesk.Revit.CurveAPIUtils.CreateNurbsCurve ausgelöst wurde. Glücklicherweise wird die Ausnahme hier verarbeitet, sodass Dynamo nicht abgestürzt ist. Der Debugging-Prozess hat den Kontext für das Problem zugänglich gemacht, indem eine andere Methode im Quellcode ermittelt wurde.

1. Wenn wir in Walls.cs auf die Anweisung treffen, die die Ausnahme verursacht, gelangen wir durch den Debugging-Prozess so nah wie möglich an die Ursache des Problems im Benutzercode in ProtoToRevitCurve.cs.

2. Die Anweisung, die die Ausnahme in ProtoToRevitCurve.cs verursacht.

3. In der Aufrufliste sehen wir, dass die Ausnahme aus Nichtbenutzercode stammt.

4. Ein Popup-Fenster mit Informationen zur Ausnahme.

Dieser Vorgang kann auf alle Quelldateien angewendet werden, mit denen wir arbeiten. Wenn wir eine Bibliothek mit Zero-Touch-Blöcken für Dynamo Studio entwickeln, können wir die Quelle der Bibliothek öffnen und einen Dynamo-Prozess anhängen, um für die Blockbibliothek ein Debugging durchzuführen. Auch wenn alles perfekt funktioniert, ist das Debugging eine gute Möglichkeit, Code zu prüfen und herauszufinden, wie bestimmte Aspekte funktionieren.

Abrufen des neuesten Builds

Dieser Vorgang ist fast identisch mit dem Abrufen von Änderungen für Dynamo, mit der Ausnahme, dass wir sicherstellen müssen, dass wir uns in der richtigen Verzweigung befinden. Verwenden Sie den Befehl git branch im DynamoRevit-Repository, um zu sehen, welche Verzweigungen lokal verfügbar und welche derzeit ausgecheckt sind.

cd C:\Users\username\Documents\GitHub\DynamoRevit legt das aktuelle Verzeichnis auf das DynamoRevit-Repository fest. git branch überprüft, ob wir uns in der richtigen Verzweigung, RC2.13.1_Revit2023, befinden. git pull origin RC2.13.1_Revit2023 ruft Änderungen aus der Remote-Ursprungsverzweigung RC2.13.1_Revit2023 ab.

Der Ursprung verweist einfach auf die ursprüngliche URL, die wir geklont haben.

Wir sollten hier sorgsam darauf achten, in welcher Verzweigung wir uns gerade befinden und von welcher Verzweigung wir Daten abrufen, um zu vermeiden, dass Änderungen beispielsweise von RC2.13.1_Revit2023 in Revit2018 abgerufen werden.

Wie unter Erstellen von Dynamo aus Quelldateien erwähnt, können wir eine Pull-Anforderung erstellen, wenn wir bereit sind, eine Änderung an das DynamoRevit-Repository zu übermitteln. Dabei folgen wir den Richtlinien des Dynamo-Teams, die im Abschnitt zu Pull-Anforderungen beschrieben werden.

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.

Die Quelldateien von Dynamo werden auf GitHub gehostet, sodass jeder sie klonen und dazu beitragen kann. In diesem Kapitel erfahren Sie, wie Sie das Repository mithilfe von Git klonen, die Quelldateien mit Visual Studio kompilieren, einen lokalen Build ausführen und ein Debugging für diesen durchführen sowie neue Änderungen aus GitHub abrufen.

Suchen der Dynamo-Repositorys auf GitHub

GitHub ist ein Hosting-Dienst, der auf Git, einem Versionskontrollsystem zur Änderungsverfolgung und Koordination der Arbeit zwischen verschiedenen Personen, basiert. Git ist ein Werkzeug, mit dem wir die Quelldateien von Dynamo herunterladen und mit ein paar Befehlen auf dem neuesten Stand halten können. Mit dieser Methode vermeiden wir die unnötige und von Natur aus unübersichtliche Arbeit des Herunterladens und manuellen Ersetzens der Quelldateien bei jedem Update. Das Git-Versionskontrollsystem verfolgt alle Unterschiede zwischen einem lokalen und einem Remote-Code-Repository.

Die Quelldateien von Dynamo werden im DynamoDS-GitHub im folgenden Repository gehostet: https://github.com/DynamoDS/Dynamo.

Dynamo-Quelldateien

1. Klonen oder laden Sie das gesamte Repository herunter.

2. Zeigen Sie andere DynamoDS-Repositorys an.

3. Dynamo-Quelldateien

4. Git-spezifische Dateien

Abrufen des Dynamo-Repositorys mit Git

Bevor wir das Repository klonen können, müssen wir Git installieren. Befolgen Sie diese Kurzanleitung, um die Installationsschritte auszuführen und zu erfahren, wie Sie einen GitHub-Benutzernamen und eine -E-Mail-Adresse einrichten. In diesem Beispiel verwenden wir Git in der Befehlszeile. In diesem Handbuch wird davon ausgegangen, dass Sie Windows verwenden. Sie können Git jedoch auch unter Mac oder Linux verwenden, um die Dynamo-Quelle zu klonen.

Wir benötigen eine URL für das Dynamo-Repository, von dem geklont werden soll. Sie finden diese auf der Repository-Seite unter der Schaltfläche Clone or Download. Kopieren Sie die URL zum Einfügen in die Befehlszeile.

1. Wählen Sie Clone or Download aus.

2. Kopieren Sie die URL.

Wenn Git installiert ist, können wir das Dynamo-Repository klonen. Öffnen Sie zunächst die Eingabeaufforderung. Navigieren Sie dann unter Verwendung des Befehls zum Ändern des Verzeichnisses cd zu dem Ordner, in den die Quelldateien geklont werden sollen. In diesem Fall haben wir unter Documents einen Ordner mit dem Namen Github erstellt.

cd C:\Users\username\Documents\GitHub

Ersetzen Sie username durch Ihren Benutzernamen.

Im nächsten Schritt führen wir einen Git-Befehl aus, um das Dynamo-Repository an den angegebenen Speicherort zu klonen. Die URL im Befehl wird durch Klicken auf die Schaltfläche Clone or Download auf GitHub abgerufen. Führen Sie diesen Befehl im Befehlsterminal aus. Beachten Sie, dass dadurch die Hauptverzweigung für das Dynamo-Repository geklont wird, bei der es sich um den aktuellen Code für Dynamo handelt und der die neueste Version von Dynamo-Code enthält. Diese Verzweigung ändert sich täglich.

git clone https://github.com/DynamoDS/Dynamo.git

Wir wissen, dass Git funktioniert, wenn der Klonvorgang erfolgreich abgeschlossen wurde. Navigieren Sie im Datei-Explorer zu dem Verzeichnis, in das Sie die Quelldateien geklont haben, um sie anzuzeigen. Die Verzeichnisstruktur sollte der Hauptverzweigung des Dynamo-Repositorys auf GitHub entsprechen.

1. Dynamo-Quelldateien

2. Git-Dateien

Erstellen des Repositorys mit Visual Studio

Nachdem die Quelldateien nun auf den lokalen Computer geklont wurden, können wir eine ausführbare Datei für Dynamo erstellen. Dazu müssen wir die Visual Studio-IDE einrichten und sicherstellen, dass .NET Framework und DirectX installiert sind.

• Laden Sie die kostenlose, voll funktionsfähige IDE (Integrated Development Environment, integrierte Entwicklungsumgebung) Microsoft Visual Studio Community 2015 herunter, und installieren Sie sie (spätere Versionen funktionieren möglicherweise ebenfalls).

• Laden Sie Microsoft .NET Framework 4.5 oder höher herunter, und installieren Sie die Software.

• Installieren Sie Microsoft DirectX aus dem lokalen Dynamo-Repository (Dynamo\tools\install\Extra\DirectX\DXSETUP.exe).

.NET und DirectX sind möglicherweise bereits installiert.

Sobald die Installation abgeschlossen ist, können wir Visual Studio starten und die Projektmappe Dynamo.All.sln unter Dynamo\src öffnen.

1. Wählen Sie File > Open > Project/Solution aus.

2. Navigieren Sie zum Dynamo-Repository, und öffnen Sie den Ordner src.

3. Wählen Sie die Projektmappendatei Dynamo.All.sln aus.

4. Wählen Sie Open aus.

Bevor wir die Projektmappe erstellen können, müssen einige Einstellungen angegeben werden. Zunächst sollten wir eine Debugversion von Dynamo erstellen, damit Visual Studio während des Debugging weitere Informationen sammeln kann, um uns bei der Entwicklung zu unterstützen. Außerdem sollten wir AnyCPU als Ziel verwenden.

Diese werden zu Ordnern im Ordner bin.

1. In diesem Beispiel haben wir Debug als Projektmappenkonfiguration gewählt.

2. Setzen Sie die Projektmappenplattform auf Any CPU.

Wenn das Projekt geöffnet ist, können wir die Projektmappe erstellen. Durch diesen Vorgang wird eine DynamoSandbox.exe-Datei erstellt, die ausgeführt werden kann.

Durch das Erstellen des Projekts werden NuGet-Abhängigkeiten wiederhergestellt.

1. Wählen Sie Build > Build Solution aus.

2. Stellen Sie im Ausgabefenster sicher, dass der Build erfolgreich war. Er sollte in etwa wie folgt lauten: ==== Build: 69 succeeded, 0 failed, 0 up-to-date, 0 skipped ====

Ausführen eines lokalen Builds

Wenn Dynamo erfolgreich erstellt wurde, wird im Dynamo-Repository ein Ordner namens bin mit der Datei DynamoSandbox.exe erstellt. In unserem Fall verwenden wir die Option Debug für die Erstellung, sodass sich die ausführbare Datei unter bin\AnyCPU\Debug befindet. Durch Ausführen dieser Datei wird ein lokaler Build von Dynamo geöffnet.

1. Die ausführbare DynamoSandbox-Datei, die wir gerade erstellt haben. Führen Sie diese Datei aus, um Dynamo zu starten.

Damit sind wir fast bereit, um mit der Entwicklung für Dynamo zu beginnen.

Anweisungen zum Erstellen von Dynamo für andere Plattformen (z. B. Linux oder OS X) finden Sie auf dieser Wiki-Seite.

Debuggen eines lokalen Builds mithilfe von Visual Studio

Beim Debuggen werden Fehler oder Probleme identifiziert, isoliert und behoben. Nachdem Dynamo erfolgreich aus den Quelldateien erstellt wurde, können wir verschiedene Werkzeuge in Visual Studio verwenden, um das Debugging für eine laufende Anwendung, z. B. das DynamoRevit-Zusatzmodul, durchzuführen. Wir können den Quellcode analysieren, um die Ursache eines Problems zu finden, oder den derzeit ausgeführten Code überwachen. Eine ausführlichere Beschreibung des Debugging und der Navigation durch Code in Visual Studio finden Sie in den Visual Studio-Dokumenten.

Für die eigenständige Dynamo-Anwendung DynamoSandbox werden zwei Optionen für das Debugging behandelt:

• Erstellen und Starten von Dynamo direkt über Visual Studio

• Anhängen von Visual Studio an einen laufenden Dynamo-Prozess

Durch Starten von Dynamo über Visual Studio wird die Projektmappe ggf. für jede Debugging-Sitzung neu erstellt. Wenn wir also Änderungen an den Quelldateien vorgenommen haben, werden diese beim Debuggen berücksichtigt. Lassen Sie die Projektmappe Dynamo.All.sln geöffnet, wählen Sie Debug, AnyCPU und DynamoSandbox aus den Dropdown-Menüs aus, und klicken Sie dann auf Start. Dadurch wird Dynamo erstellt, ein neuer Prozess (DynamoSandbox.exe) gestartet und der Visual Studio-Debugger an diesen angehängt.

Erstellen und starten Sie die Anwendung direkt über Visual Studio.

1. Legen Sie die Konfiguration auf Debug fest.

2. Legen Sie die Plattform auf Any CPU fest.

3. Legen Sie das Startprojekt auf DynamoSandbox fest.

4. Klicken Sie auf Start, um den Debugging-Vorgang zu starten.

Alternativ können wir das Debugging auch für einen bereits ausgeführten Dynamo-Prozess durchführen, um ein Problem mit einem bestimmten geöffneten Diagramm oder Paket zu beheben. Zu diesem Zweck öffnen wir die Quelldateien des Projekts in Visual Studio und hängen sie mithilfe des Debug-Menüelements Attach to Process an einen laufenden Dynamo-Prozess an.

Anhängen eines laufenden Prozesses an Visual Studio

1. Wählen Sie Debug > Attach to Process... aus.

2. Wählen Sie DynamoSandbox.exe.

3. Wählen Sie Attach aus.

In beiden Fällen hängen wir den Debugger an einen Prozess an, für den wir das Debugging ausführen möchten. Wir können vor oder nach dem Starten des Debuggers Haltepunkte im Code festlegen, die unmittelbar vor dem Ausführen dieser Codezeile eine Unterbrechung des Vorgangs bewirken. Wenn beim Debuggen eine nicht abgefangene Ausnahme ausgelöst wird, springt Visual Studio im Quellcode an die Stelle, an der diese aufgetreten ist. Dies ist eine effiziente Methode, um einfache Abstürze und nicht behandelte Ausnahmen zu finden und den Ausführungsablauf einer Anwendung zu verstehen.

Beim Debuggen von DynamoSandbox legen wir im Konstruktor des Blocks Color.ByARGB einen Haltepunkt fest, der bewirkt, dass der Dynamo-Prozess angehalten wird, wenn der Block instanziiert wird. Wenn dieser Block eine Ausnahme ausgelöst hat oder zu einem Absturz von Dynamo führte, können wir die einzelnen Zeilen im Konstruktor durchgehen, um zu ermitteln, wo das Problem aufgetreten ist.

1. Der Haltepunkt

2. Die Aufrufliste, die die derzeit ausgeführte Funktion und frühere Funktionsaufrufe anzeigt.

Im nächsten Abschnitt, Erstellen von DynamoRevit aus Quelldateien, wird ein spezifisches Debugging-Beispiel vorgestellt. Außerdem wird erläutert, wie Sie Haltepunkte festlegen, Code durchgehen und die Aufrufliste lesen.

Abrufen des aktuellen Builds

Da die Dynamo-Quelldateien auf GitHub gehostet werden, lassen sich lokale Quelldateien am einfachsten auf dem aktuellen Stand halten, indem Sie Änderungen mithilfe von Git-Befehlen abrufen.

Legen Sie mithilfe der Befehlszeile das aktuelle Verzeichnis auf das Dynamo-Repository fest:

cd C:\Users\username\Documents\GitHub\Dynamo

Ersetzen Sie "username" durch Ihren Benutzernamen.

Verwenden Sie den folgenden Befehl, um die neuesten Änderungen abzurufen:

git pull origin master

1. Hier sehen wir, dass das lokale Repository mit Änderungen aus dem Remote-Repository aktualisiert wurde.

Zusätzlich zum Abrufen von Aktualisierungen gibt es vier weitere Git-Arbeitsabläufe, mit denen Sie sich vertraut machen sollten.

• Fork: Spalten Sie das Dynamo-Repository auf, um eine vom Original separate Kopie zu erstellen. Hier vorgenommene Änderungen wirken sich nicht auf das ursprüngliche Repository aus. Aktualisierungen können mit Pull-Anforderungen abgerufen oder übermittelt werden. Fork ist kein Git-Befehl, sondern ein Arbeitsablauf, der von GitHub hinzugefügt wird. Das Fork-Pull-Anforderungsmodell ist einer der häufigsten Arbeitsabläufe für Online-Beiträge zu Open-Source-Projekten. Sie sollten sich näher damit beschäftigen, wenn Sie zu Dynamo beitragen möchten.

• Verzweigung: Experimentieren Sie, oder arbeiten Sie an neuen Funktionen, unabhängig von den anderen Vorgängen in Verzweigungen. Dies erleichtert das Senden von Pull-Anforderungen.

• Führen Sie häufig Commits aus, nachdem Sie einen Arbeitsschritt abgeschlossen haben bzw. nach Änderungen, die möglicherweise rückgängig gemacht werden sollen. Ein Commit zeichnet Änderungen im Repository auf und wird angezeigt, wenn eine Pull-Anforderung an das Dynamo-Haupt-Repository gestellt wird.

• Erstellen Sie Pull-Anforderungen, wenn Änderungen bereit sind, offiziell im Dynamo-Haupt-Repository vorgeschlagen zu werden.

Das Dynamo-Team verfügt über spezielle Anweisungen zum Erstellen von Pull-Anforderungen. Weitere Informationen finden Sie im Abschnitt zu Pull-Anforderungen in dieser Dokumentation.

Eine Referenzliste der Git-Befehle finden Sie auf dieser Dokumentationsseite.

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.

Ein Zero-Touch-Block, der eine Python-Skriptzeichenfolge ausführt

Python-Modul

Dieser Block ist von einer Instanz des IronPython-Skriptmoduls abhängig. Dazu müssen wir einige zusätzliche Assemblys referenzieren. Führen Sie die folgenden Schritte aus, um eine grundlegende Vorlage in Visual Studio einzurichten:

• Erstellen Sie ein neues Visual Studio-Klassenprojekt.

• Fügen Sie eine Referenz zur Datei IronPython.dll hinzu, die sich im Ordner C:\Program Files (x86)\IronPython 2.7\IronPython.dll befindet.

• Fügen Sie eine Referenz zur Datei Microsoft.Scripting.dll hinzu, die sich im Ordner C:\Program Files (x86)\IronPython 2.7\Platforms\Net40\Microsoft.Scripting.dll befindet.

• Berücksichtigen Sie die using-Anweisungen IronPython.Hosting und Microsoft.Scripting.Hosting in Ihrer Klasse.

• Fügen Sie einen privaten, leeren Konstruktor hinzu, um zu verhindern, dass mit dem Paket ein zusätzlicher Block zur Dynamo-Bibliothek hinzugefügt wird.

• Erstellen Sie eine neue Methode, die eine einzelne Zeichenfolge als Eingabeparameter akzeptiert.

• Bei dieser Methode wird ein neues Python-Modul instanziiert und ein leerer Skriptbereich erstellt. Sie können sich diesen Bereich als globale Variablen innerhalb einer Instanz des Python-Interpreters vorstellen.

• Rufen Sie anschließend Execute im Modul auf, das die Eingabezeichenfolge und den Bereich als Parameter übergibt.

• Rufen Sie abschließend die Ergebnisse des Skripts ab, und geben Sie sie zurück, indem Sie GetVariable für den Bereich aufrufen und den Namen der Variablen aus dem Python-Skript übergeben, das den Wert enthält, den Sie zurückgeben möchten. (Weitere Informationen finden Sie im folgenden Beispiel.)

Der folgende Code stellt ein Beispiel für den oben genannten Schritt dar. Beim Erstellen der Projektmappe wird eine neue .dll-Datei im Ordner bin des Projekts erstellt. Diese .dll-Datei kann jetzt als Teil eines Pakets oder durch Navigieren zu File < Import Library... in Dynamo importiert werden.

using IronPython.Hosting;
using Microsoft.Scripting.Hosting;

namespace PythonLibrary
{
    public class PythonZT
    {
        // Unless a constructor is provided, Dynamo will automatically create one and add it to the library
        // To avoid this, create a private constructor
        private PythonZT() { }

        // The method that executes the Python string
        public static string executePyString(string pyString)
        {
            ScriptEngine engine = Python.CreateEngine();
            ScriptScope scope = engine.CreateScope();
            engine.Execute(pyString, scope);
            // Return the value of the 'output' variable from the Python script below
            var output = scope.GetVariable("output");
            return (output);
        }
    }
}

Das Python-Skript gibt die Variable output zurück, d. h., wir benötigen eine output-Variable im Python-Skript. Verwenden Sie dieses Beispielskript, um den Block in Dynamo zu testen. Wenn Sie den Python-Block schon einmal in Dynamo verwendet haben, sollte Ihnen die folgende Darstellung bekannt sein. Weitere Informationen finden Sie im Primer-Abschnitt zu Python.

import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *

cube = Cuboid.ByLengths(10,10,10);
volume = cube.Volume
output = str(volume)

Mehrere Ausgaben

Eine Einschränkung der Python-Standardblöcke besteht darin, dass sie nur einen einzigen Ausgabeanschluss haben. Wenn wir also mehrere Objekte zurückgeben möchten, müssen wir eine Liste erstellen und jedes Objekt abrufen. Wenn wir das obige Beispiel ändern, um ein Wörterbuch zurückzugeben, können wir beliebig viele Ausgabeanschlüsse hinzufügen. Weitere Informationen zu Wörterbüchern finden Sie im Abschnitt Zurückgeben mehrerer Werte unter Weitere Schritte mit Zero-Touch.

Mit diesem Block können wir sowohl das Volumen des Quaders als auch seinen Schwerpunkt zurückgeben.

Wir ändern das vorherige Beispiel mit den folgenden Schritten:

• Fügen Sie im NuGet-Paket-Manager eine Referenz auf DynamoServices.dll hinzu.

• Schließen Sie zusätzlich zu den vorherigen Assemblys System.Collections.Generic und Autodesk.DesignScript.Runtime mit ein.

• Ändern Sie den Rückgabetyp für die Methode, um ein Wörterbuch mit unseren Ausgaben zurückzugeben.

• Jede Ausgabe muss einzeln aus dem Bereich abgerufen werden. (Richten Sie ggf. eine einfache Schleife für größere Ausgabesätze ein.)

using IronPython.Hosting;
using Microsoft.Scripting.Hosting;
using System.Collections.Generic;
using Autodesk.DesignScript.Runtime;

namespace PythonLibrary
{
    public class PythonZT
    {
        private PythonZT() { }

        [MultiReturn(new[] { "output1", "output2" })]
        public static Dictionary<string, object> executePyString(string pyString)
        {
            ScriptEngine engine = Python.CreateEngine();
            ScriptScope scope = engine.CreateScope();
            engine.Execute(pyString, scope);
            // Return the value of 'output1' from script
            var output1 = scope.GetVariable("output1");
            // Return the value of 'output2' from script
            var output2 = scope.GetVariable("output2");
            // Define the names of outputs and the objects to return
            return new Dictionary<string, object> {
                { "output1", (output1) },
                { "output2", (output2) }
            };
        }
    }
}

Außerdem wurde dem Beispiel-Python-Skript eine zusätzliche Ausgabevariable (output2) hinzugefügt. Beachten Sie, dass diese Variablen alle gültigen Python-Namenskonventionen verwenden können. Der Name Output wurde in diesem Beispiel einzig aus Gründen der Übersichtlichkeit verwendet.

import clr
clr.AddReference('ProtoGeometry')
from Autodesk.DesignScript.Geometry import *

cube = Cuboid.ByLengths(10,10,10);
centroid = Cuboid.Centroid(cube);
volume = cube.Volume
output1 = str(volume)
output2 = str(centroid)

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 ZeroTouchEssentials.cs 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 C#-Programmierhandbuch ausgedrückt. Die Vorgaben werden wie folgt angegeben:

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

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        // Set the method parameter to a default value
        public static double MultiplyByTwo(double inputNumber = 2.0) 
        {
            return 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.

• Fügen Sie der Methode das Attribut [MultiReturn(new[] { "string1", "string2", ... more strings here })] hinzu. Die Zeichenfolgen verweisen auf Schlüssel im Wörterbuch und werden zu den Namen der Ausgabeanschlüsse.

• Geben Sie ein Dictionary<> mit Schlüsseln aus der Funktion zurück, die den Parameternamen im Attribut entsprechen: return new Dictionary<string, object>.

using System.Collections.Generic;
using Autodesk.DesignScript.Runtime;

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        [MultiReturn(new[] { "add", "mult" })]
        public static Dictionary<string, object> ReturnMultiExample(double a, double b)
        {
            return new Dictionary<string, object>

                { "add", (a + b) },
                { "mult", (a * b) }
            };
        }
    }
}

Weitere Informationen finden Sie in diesem Codebeispiel in ZeroTouchEssentials.cs.

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.

  • Beispiel: /// <summary>...</summary>

• Aktivieren Sie die XML-Dokumentation in Visual Studio, indem Sie Project > Project Properties > Build auswählen und XML documentation file aktivieren.

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.

• /// <returns name = "outputName">...</returns> erstellt Dokumentation für mehrere Ausgabeparameter.

• /// <search>...</search> gleicht Ihren Block mit Suchergebnissen basierend auf einer durch Kommas getrennten Liste ab. Wenn wir beispielsweise einen Block erstellen, der ein Netz unterteilt, möchten wir möglicherweise Tags wie Netz, Unterteilung und Catmull-Clark hinzufügen.

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

using Autodesk.DesignScript.Geometry;

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        /// <summary>
        /// This method demonstrates how to use a native geometry object from Dynamo
        /// in a custom method
        /// </summary>
        /// <param name="curve">Input Curve. This can be of any type deriving from Curve, such as NurbsCurve, Arc, Circle, etc</param>
        /// <returns>The twice the length of the Curve </returns>
        /// <search>example,curve</search>
        public static double DoubleLength(Curve curve)
        {
            return curve.Length * 2.0;
        }
    }
}

Weitere Informationen finden Sie in diesem Codebeispiel in ZeroTouchEssentials.cs.

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

1. Eine Blockzusammenfassung

2. Eine Eingabebeschreibung

3. Eine Ausgabebeschreibung

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.

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        private double _a;
        private double _b;

        // Make the constructor internal
        internal ZeroTouchEssentials(double a, double b)
        {
            _a = a;
            _b = b;
        }

        // The static method that Dynamo will convert into a Create node
        public static ZeroTouchEssentials ByTwoDoubles(double a, double b)
        {
            return new ZeroTouchEssentials(a, b);
        }
    }
}

Weitere Informationen finden Sie in diesem Codebeispiel in ZeroTouchEssentials.cs.

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.

using Autodesk.DesignScript.Geometry;

namespace ZeroTouchEssentials
{
    public class ZeroTouchEssentials
    {
        // "Autodesk.DesignScript.Geometry.Curve" is specifying the type of geometry input, 
        // just as you would specify a double, string, or integer 
        public static double DoubleLength(Autodesk.DesignScript.Geometry.Curve curve)
        {
            return curve.Length * 2.0;
        }
    }
}

Weitere Informationen finden Sie in diesem Codebeispiel in ZeroTouchEssentials.cs.

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:

  Copy

  using (Point p1 = Point.ByCoordinates(0, 0, 0))
  {
    using (Point p2 = Point.ByCoordinates(10, 10, 0))
    {
        return Line.ByStartPointEndPoint(p1, p2);
    }
  }

  Die using-Anweisung ist hier dokumentiert.

  Weitere Informationen zu den neuen Stabilitätsfunktionen ab Dynamo 2.5 finden Sie im Artikel zu Verbesserungen der Stabilität der Dynamo-Geometrie.

• Mit manuellen Dispose-Aufrufen:

  Copy

  Point p1 = Point.ByCoordinates(0, 0, 0);
  Point p2 = Point.ByCoordinates(10, 10, 0);
  Line l = Line.ByStartPointEndPoint(p1, p2);
  p1.Dispose();
  p2.Dispose();
  return l;

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.

• Erstellen Sie im migrations-Element für jede Namensänderung <priorNameHint>...</priorNameHint>-Elemente.

• Geben Sie für jede Namensänderung ein <oldName>...</oldName>- und ein <newName>...</newName>-Element an.

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.

<?xml version="1.0"?>
<migrations>
  <priorNameHint>
    <oldName>Autodesk.DesignScript.Geometry.Geometry.GetClosestPoint</oldName>
    <newName>Autodesk.DesignScript.Geometry.Geometry.ClosestPointTo</newName>
  </priorNameHint>
</migrations>

Weitere Informationen finden Sie in diesem Codebeispiel in ProtoGeometry.Migrations.xml.

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.

public class SomeGenericClass<T>
{
    public SomeGenericClass()
    {
        Console.WriteLine(typeof(T).ToString());
    }  
}

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

public class SomeWrapper
{
    public object wrapped;
    public SomeWrapper(SomeGenericClass<double> someConstrainedType)
    {
        Console.WriteLine(this.wrapped.GetType().ToString());
    }
}

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.

Benutzerdefinierter, rechteckiger Rasterblock

Um mit dem Erstellen des Rasterblocks zu beginnen, erstellen Sie ein neues Visual Studio-Klassenbibliotheksprojekt. Eine ausführliche exemplarische Vorgehensweise zum Einrichten eines Projekts finden Sie auf der Seite Erste Schritte.

1. Wählen Sie Class Library für den Projekttyp.

2. Geben Sie dem Projekt den Namen CustomNodes.

Da wir Geometrie erstellen, müssen wir das entsprechende NuGet-Paket referenzieren. Installieren Sie das ZeroTouchLibrary-Paket über den NuGet-Paket-Manager. Dieses Paket ist für die Anweisung using Autodesk.DesignScript.Geometry; erforderlich.

1. Suchen Sie nach dem ZeroTouchLibrary-Paket.

2. Wir verwenden diesen Block im aktuellen Build von Dynamo Studio (Version 1.3). Wählen Sie die Paketversion aus, die dieser Version entspricht.

3. Beachten Sie, dass wir auch die Klassendatei in Grids.cs umbenannt haben.

Als Nächstes müssen wir einen Namensbereich und eine Klasse einrichten, in denen die Methode RectangularGrid gespeichert wird. Der Block wird in Dynamo entsprechend den Methoden- und Klassennamen benannt. Wir müssen diesen Vorgang noch nicht in Visual Studio kopieren.

using Autodesk.DesignScript.Geometry;
using System.Collections.Generic;

namespace CustomNodes
{
    public class Grids
    {
        public static List<Rectangle> RectangularGrid(int xCount, int yCount)
        {
        //The method for creating a rectangular grid will live in here
        }
    }
}

Autodesk.DesignScript.Geometry; referenziert die Datei ProtoGeometry.dll im ZeroTouchLibrary-Paket. System.Collections.Generic ist zum Erstellen von Listen erforderlich.

Jetzt können wir die Methode zum Zeichnen der Rechtecke hinzufügen. Die Klassendatei sollte der folgenden Abbildung entsprechen und kann in Visual Studio kopiert werden.

using Autodesk.DesignScript.Geometry;
using System.Collections.Generic;

namespace CustomNodes
{
    public class Grids
    {
        public static List<Rectangle> RectangularGrid(int xCount, int yCount)
        {
            double x = 0;
            double y = 0;

            var pList = new List<Rectangle>();

            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    x++;
                    Point pt = Point.ByCoordinates(x, y);
                    Vector vec = Vector.ZAxis();
                    Plane bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, 1, 1);
                    pList.Add(rect);
                }
            }
            return pList;
        }
    }
}

Wenn das Projekt ähnlich aussieht wie hier gezeigt, versuchen Sie, die .dll-Datei zu erstellen.

1. Wählen Sie Build > Projektmappe erstellen.

Prüfen Sie, ob im Ordner bin des Projekts eine .dll-Datei enthalten ist. Wenn der Build erfolgreich war, können wir die .dll-Datei zu Dynamo hinzufügen.

1. Der benutzerdefinierte Block RectangularGrids in der Dynamo-Bibliothek

2. Der benutzerdefinierte Block im Ansichtsbereich

3. Die Schaltfläche Hinzufügen zum Hinzufügen der .dll-Datei zu Dynamo

Benutzerdefinierte Blockänderungen

Im obigen Beispiel haben wir einen recht einfachen Block erstellt, der außerhalb der Methode RectangularGrids nicht viel mehr definiert hat. Es ist jedoch eventuell empfehlenswert, QuickInfos für Eingabeanschlüsse zu erstellen oder dem Block eine Zusammenfassung hinzuzufügen, wie bei den Dynamo-Standardblöcken. Das Hinzufügen dieser Elemente zu benutzerdefinierten Blöcken erleichtert deren Verwendung, insbesondere dann, wenn ein Benutzer in der Bibliothek nach ihnen suchen möchte.

1. Ein Vorgabe-Eingabewert

2. Eine QuickInfo für die xCount-Eingabe

Der Block RectangularGrid benötigt einige dieser grundlegenden Funktionen. Im folgenden Code wurden Beschreibungen der Eingabe- und Ausgabeanschlüsse, eine Zusammenfassung und vorgabemäßige Eingabewerte hinzugefügt.

using Autodesk.DesignScript.Geometry;
using System.Collections.Generic;

namespace CustomNodes
{
    public class Grids
    {
        /// <summary>
        /// This method creates a rectangular grid from an X and Y count.
        /// </summary>
        /// <param name="xCount">Number of grid cells in the X direction</param>
        /// <param name="yCount">Number of grid cells in the Y direction</param>
        /// <returns>A list of rectangles</returns>
        /// <search>grid, rectangle</search>
        public static List<Rectangle> RectangularGrid(int xCount = 10, int yCount = 10)
        {
            double x = 0;
            double y = 0;

            var pList = new List<Rectangle>();

            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    x++;
                    Point pt = Point.ByCoordinates(x, y);
                    Vector vec = Vector.ZAxis();
                    Plane bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, 1, 1);
                    pList.Add(rect);
                    Point cPt = rect.Center();
                }
            }
            return pList;
        }
    }
}

• Legen Sie Vorgabewerte für die Eingaben fest, indem Sie den Methodenparametern Werte zuweisen: RectangularGrid(int xCount = 10, int yCount = 10)

• Erstellen Sie QuickInfos für Ein- und Ausgabe, Suchbegriffe und eine Zusammenfassung mit XML-Dokumentation, der /// vorangestellt ist.

Um QuickInfos hinzuzufügen, benötigen wir eine XML-Datei im Projektverzeichnis. Eine .xml-Datei kann automatisch von Visual Studio generiert werden, indem Sie die Option aktivieren.

1. Aktivieren Sie hier die XML-Dokumentationsdatei, und geben Sie einen Dateipfad an. Dadurch wird eine XML-Datei erstellt.

Das ist alles. Wir haben einen neuen Block mit mehreren Standardelementen erstellt. Im folgenden Kapitel zu den Zero-Touch-Grundlagen wird ausführlicher auf die Zero-Touch-Blockentwicklung und die zu beachtenden Aspekte eingegangen.

Welchen Zweck verfolgt dieses Handbuch?

In diesem Handbuch erfahren Sie, wie Sie die verschiedenen C#-Entwicklungsmöglichkeiten für Dynamo verwenden - vom Erstellen von Zero-Touch-Blöcken bis hin zum Erstellen von Erweiterungen.

Dynamo-Quelldateien auf GitHub

Welche zusätzlichen Entwicklerressourcen stellen wir zur Verfügung?

Dynamo: Laden Sie die neuesten stabilen und täglichen Builds von Dynamo herunter.

https://dynamobuilds.com/

Dynamo-GitHub: Dynamo ist ein Open-Source-Entwicklungsprojekt auf GitHub.

https://github.com/DynamoDS/Dynamo

Dynamo-GitHub-Wiki: Dies ist die primäre Ressource für die Entwicklerdokumentation.

https://github.com/DynamoDS/Dynamo/wiki

Namenskonventionen für Blöcke: Hier werden Standards und Richtlinien für die Benennung von Kategorien, Blöcken sowie Eingabe- und Ausgabeanschlüssen in Dynamo bereitgestellt.

https://github.com/DynamoDS/Dynamo/wiki/Naming-Standards

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

https://dynamods.github.io/DynamoAPI/

DynamoBIM: Die beste Quelle für zusätzliche Informationen, Lerninhalte und Foren ist die DynamoBIM-Website.

https://dynamobim.org

Dynamo-Wörterbuch: Eine durchsuchbare Datenbank mit allen Dynamo-Blöcken.

https://dictionary.dynamobim.com/

Leitfaden für die DesignScript-Sprache: Ein PDF-Leitfaden zum Schreiben in DesignScript.

PDF

Wie kann ich Änderungen an diesem Handbuch vorschlagen?

Sie können jederzeit Vorschläge für diese Dokumentation machen. Diese können direkt über GitHub durch Erstellen einer Änderungsanfrage übermittelt werden.

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 .dll-Datei erstellen.

Fenster Neues Projekt in Visual Studio

1. Öffnen Sie zunächst Visual Studio, und erstellen Sie ein neues Projekt: File > New > Project

2. Wählen Sie die Projektvorlage Class Library.

3. Geben Sie dem Projekt einen Namen (wir haben das Projekt MyCustomNode genannt).

4. Legen Sie den Dateipfad für das Projekt fest. In diesem Beispiel belassen wir den Vorgabespeicherort.

5. Wählen Sie Ok aus.

Visual Studio erstellt und öffnet automatisch eine C#-Datei. Sie sollten einen angemessenen Namen vergeben, den Arbeitsbereich einrichten und den Vorgabecode durch diese Multiplikationsmethode ersetzen:

 namespace MyCustomNode
 {
     public class SampleFunctions
     {
         public static double MultiplyByTwo(double inputNumber)
         {
             return inputNumber * 2.0;
         }
     }
 }

1. Öffnen Sie den Projektmappen-Explorer und die Ausgabefenster über View.

2. Benennen Sie die Datei Class1.cs im Projektmappen-Explorer auf der rechten Seite in SampleFunctions.cs um.

3. Fügen Sie den oben genannten Code für die Multiplikationsfunktion hinzu. Die Details dazu, wie Dynamo Ihre C#-Klassen liest, werden wir später behandeln.

4. Projektmappen-Explorer: Hiermit erhalten Sie Zugriff auf alle Elemente in Ihrem Projekt.

5. Ausgabefenster: Dieses wird später benötigt, um zu sehen, ob der Build erfolgreich war.

Der nächste Schritt besteht darin, das Projekt zu erstellen. Zuvor müssen wir jedoch einige Einstellungen überprüfen. Stellen Sie zunächst sicher, dass Any CPU oder x64 als Plattformziel ausgewählt und Prefer 32-bit in den Projekteigenschaften deaktiviert ist.

1. Öffnen Sie die Projekteigenschaften, indem Sie Project > "ProjectName" Properties auswählen.

2. Wählen Sie die Seite Build aus.

3. Wählen Sie im Dropdown-Menü die Option Any CPU oder x64 aus.

4. Stellen Sie sicher, dass Prefer 32-bit deaktiviert ist.

Jetzt können wir das Projekt erstellen, um eine .dll-Datei zu generieren. Wählen Sie dazu entweder Build Solution aus dem Menü Build aus, oder verwenden Sie den Kurzbefehl CTRL+SHIFT+B.

1. Wählen Sie Build > Build Solution aus.

2. Sie können feststellen, ob Ihr Projekt erfolgreich erstellt wurde, indem Sie das Ausgabefenster überprüfen.

Wenn das Projekt erfolgreich erstellt wurde, wird im Ordner bin des Projekts eine .dll-Datei mit dem Namen MyCustomNode angezeigt. In diesem Beispiel haben wir die Visual Studio-Vorgabe für den Projektdateipfad c:\users\username\documents\visual studio 2015\Projects beibehalten. Sehen wir uns nun die Dateistruktur des Projekts an.

1. Der Ordner bin enthält die in Visual Studio erstellte .dll-Datei.

2. Die Visual Studio-Projektdatei

3. Die Klassendatei

4. Da unsere Projektmappen-Konfiguration auf Debug festgelegt wurde, wird die .dll-Datei unter bin\Debug erstellt.

Jetzt können wir Dynamo öffnen und die .dll-Datei importieren. Navigieren Sie mit der Funktion Hinzufügen zum bin-Speicherort des Projekts, und wählen Sie die zu öffnende .dll-Datei aus.

1. Wählen Sie die Schaltfläche Hinzufügen, um eine .dll-Datei zu importieren.

2. Navigieren Sie zum Projektspeicherort. Das Projekt befindet sich unter dem Vorgabedateipfad von Visual Studio: C:\Users\username\Documents\Visual Studio 2015\Projects\MyCustomNode.

3. Wählen Sie die zu importierende Datei MyCustomNode.dll aus.

4. Klicken Sie auf Open, um die .dll-Datei zu laden.

Wenn eine Kategorie mit dem Namen MyCustomNode in der Bibliothek erstellt wird, wurde die DLL-Datei erfolgreich importiert. Dynamo hat jedoch zwei Blöcke erstellt, obwohl wir einen einzelnen Block erhalten wollten. Im nächsten Abschnitt werden wir erläutern, warum dies geschieht und wie Dynamo DLL-Dateien liest.

1. MyCustomNode in der Dynamo-Bibliothek. Die Bibliothekskategorie wird durch den Namen der .dll-Datei bestimmt.

2. SampleFunctions.MultiplyByTwo im Ansichtsbereich.

So liest Dynamo Klassen und Methoden

Wenn Dynamo eine DLL-Datei lädt, werden alle öffentlichen statischen Methoden als Blöcke angezeigt. Konstruktoren, Methoden und Eigenschaften werden in Erstellungs-, Aktions- und Abfrageblöcke umgewandelt. In unserem Multiplikationsbeispiel wird die Methode MultiplyByTwo() zu einem Aktionsblock in Dynamo. Dies liegt daran, dass der Block basierend auf der zugehörigen Methode und Klasse benannt wurde.

1. Die Eingabe erhält basierend auf dem Parameternamen der Methode den Namen inputNumber.

2. Die Ausgabe erhält vorgabemäßig den Namen double, da es sich hierbei um den zurückgegebenen Datentyp handelt.

3. Der Block erhält den Namen SampleFunctions.MultiplyByTwo, da dies die Klassen- und Methodennamen sind.

Im obigen Beispiel wurde der zusätzliche Erstellungsblock SampleFunctions erzeugt, da wir nicht explizit einen Konstruktor bereitgestellt haben, und daher automatisch einer erstellt wurde. Dies kann durch Erstellen eines leeren privaten Konstruktors in der Klasse SampleFunctions vermieden werden.

namespace MyCustomNode
{
    public class SampleFunctions
    {
        //The empty private constructor.
        //This will be not imported into Dynamo.
        private SampleFunctions() { }

        //The public multiplication method. 
        //This will be imported into Dynamo.
        public static double MultiplyByTwo(double inputNumber)
        {
            return inputNumber * 2.0;
        }
    }
}

1. Dynamo hat unsere Methode als Erstellungsblock importiert.

Hinzufügen von Dynamo-NuGet-Paketreferenzen

Der Block für die Multiplikation ist sehr einfach, und es sind keine Referenzen auf Dynamo erforderlich. Wenn wir beispielsweise auf eine Dynamo-Funktion zum Erstellen von Geometrie zugreifen möchten, müssen wir die Dynamo-NuGet-Pakete referenzieren.

• ZeroTouchLibrary: Paket zum Erstellen von Zero-Touch-Blockbibliotheken für Dynamo mit den folgenden Bibliotheken: DynamoUnits.dll, ProtoGeometry.dll.

• WpfUILibrary: Paket zum Erstellen von Blockbibliotheken für Dynamo mit angepasster Benutzeroberfläche in WPF, die die folgenden Bibliotheken enthält: DynamoCoreWpf.dll, CoreNodeModels.dll, CoreNodeModelWpf.dll.

• DynamoServices: DynamoServices-Bibliothek für Dynamo.

• Core: Komponenten- und System-Testinfrastruktur für Dynamo, die die folgenden Bibliotheken enthält: DSIronPython.dll, DynamoApplications.dll, DynamoCore.dll, DynamoInstallDetective.dll, DynamoShapeManager.dll, DynamoUtilities.dll, ProtoCore.dll, VMDataBridge.Bridge.dll.

• Tests: Komponenten- und System-Testinfrastruktur für Dynamo, die die folgenden Bibliotheken enthält: DynamoCoreTests.dll, SystemTestServices.dll, TestServices.dll.

• DynamoCoreNodes: Paket zum Erstellen von Core-Blöcken für Dynamo, das die folgenden Bibliotheken enthält: Analysis.dll, GeometryColor.dll, DSCoreNodes.dll.

Um diese Pakete in einem Visual Studio-Projekt zu referenzieren, laden Sie das Paket entweder von NuGet unter den oben genannten Links herunter und referenzieren die DLL-Dateien manuell, oder verwenden Sie den NuGet-Paket-Manager in Visual Studio. Zunächst gehen wir die Schritte zum Installieren mit NuGet in Visual Studio durch.

1. Öffnen Sie den NuGet-Paket-Manager, indem Sie Tools > NuGet Package Manager > Manage NuGet Packages for Solution... auswählen.

Dies ist der NuGet-Paket-Manager. In diesem Fenster wird angezeigt, welche Pakete für das Projekt installiert wurden, und der Benutzer kann nach anderen Paketen suchen. Wenn eine neue Version des DynamoServices-Pakets veröffentlicht wird, können Pakete von hier aus aktualisiert oder auf eine frühere Version zurückgesetzt werden.

1. Wählen Sie Durchsuchen, und suchen Sie nach DynamoVisualProgramming, um die Dynamo-Pakete aufzurufen.

2. Die Dynamo-Pakete. Wenn Sie eines auswählen, werden die aktuelle Version und eine Beschreibung des Inhalts angezeigt.

3. Wählen Sie die gewünschte Paketversion aus, und klicken Sie auf Installieren. Dadurch wird ein Paket für das spezifische Projekt installiert, an dem Sie gerade arbeiten. Da wir die neueste stabile Version von Dynamo, Version 1.3, verwenden, wählen Sie die entsprechende Paketversion aus.

Um ein aus dem Browser heruntergeladenes Paket manuell hinzuzufügen, öffnen Sie den Verweis-Manager im Projektmappen-Explorer und suchen nach dem Paket.

1. Klicken Sie mit der rechten Maustaste auf References, und wählen Sie Add Reference aus.

2. Wählen Sie Browse aus, um zum Paketspeicherort zu navigieren.

Nachdem Visual Studio ordnungsgemäß konfiguriert wurde und wir erfolgreich eine .dll-Datei zu Dynamo hinzugefügt haben, verfügen wir über eine solide Grundlage für die nun folgenden Konzepte. Dies ist nur der Anfang. Bleiben Sie daher weiter dabei, um mehr über das Erstellen eines benutzerdefinierten Blocks zu erfahren.

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 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

Der Web-Client des Package Manager wird ausschließlich zum Suchen und Anzeigen von Paketdaten wie z. B. Versionierung und Download-Statistiken verwendet.

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.

• Bündeln und verteilen Sie CEFSharp 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.

• Im Allgemeinen sollten Sie die Freigabe von Abhängigkeiten für Dynamo oder Revit vermeiden, wenn Sie die Version dieser Abhängigkeit steuern müssen.

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.

• Die Datei DynamoServices.dll mit einer anderen Version als die aktuelle Dynamo-Version wurde mit dem Paket gebündelt. Dadurch kann ein .NET-Laufzeitfehler beim Ermitteln des Attributs [MultiReturn] auftreten, sodass die mit verschiedenen Attributen markierten Zero-Touch-Blöcke diese nicht anwenden können. Sie werden möglicherweise feststellen, dass ein Block eine einzelne Wörterbuchausgabe anstelle mehrerer Anschlüsse zurückgibt.

2) 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:

• 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, DynamoServices usw.).

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.

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).

Öffentliche Eigenschaften und Serialisierung

[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.

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

public ConversionMetricUnit SelectedMetricConversion{...

Ignorieren von Eigenschaften

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:

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.

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.

Dynamo basiert auf der Kreativität und dem Engagement der Community. Das Dynamo-Team empfiehlt allen Beitragenden, Möglichkeiten zu erkunden, Ideen zu testen und die Community um Feedback zu bitten. Innovationen werden sehr gern gesehen. Änderungen werden jedoch nur dann aufgenommen, wenn sie die Verwendung von Dynamo erleichtern und die in diesem Dokument definierten Kriterien erfüllen. Änderungen, die nur im kleinen Rahmen Vorteile bringen, werden nicht eingeführt.

Erwartungen bei Pull-Anforderungen

Das Dynamo-Team erwartet, dass bei Pull-Anforderungen einige Richtlinien befolgt werden:

• Halten Sie unsere und ein.

• Führen Sie beim Hinzufügen neuer Funktionen Komponententests durch.

• Fügen Sie beim Beheben eines Fehlers einen Komponententest hinzu, aus dem hervorgeht, wie das aktuelle Verhalten unterbrochen wird.

• Konzentrieren Sie sich bei der Diskussion auf ein Problem. Erstellen Sie ein neues Problemthema, wenn ein neues oder verwandtes Thema aufkommt.

Einige Richtlinien dazu, was Sie nicht tun sollten:

• Überraschen Sie uns nicht mit großen Pull-Anforderungen. Übermitteln Sie stattdessen eine Anfrage, und beginnen Sie eine Diskussion, damit wir uns auf eine Richtung einigen können, bevor Sie viel Zeit investieren.

• Führen Sie für Code, den Sie nicht geschrieben haben, kein Commit aus. Wenn Sie Code finden, der Ihrer Meinung nach gut für Dynamo geeignet wäre, übermitteln Sie eine Anfrage und beginnen eine Diskussion, bevor Sie fortfahren.

• Übermitteln Sie keine Pull-Anforderungen, mit denen lizenzbezogene Dateien oder Header geändert werden. Wenn Sie der Meinung sind, dass es ein Problem mit diesen gibt, übermitteln Sie eine Anfrage. Wir nehmen uns der Angelegenheit gerne an.

• Nehmen Sie keine API-Erweiterungen vor, ohne eine Anfrage zu übermitteln und das Thema zunächst mit uns zu besprechen.

Ausfüllen der Vorlage für Pull-Anforderungen

Verwenden Sie beim Senden einer Pull-Anforderung die . Bevor Sie Ihre Pull-Anforderung einreichen, stellen Sie sicher, dass der Zweck klar beschrieben ist und alle folgenden Aussagen als Zutreffend bestätigt werden können:

• Die Codebasis ist nach dieser Pull-Anforderung in einem besseren Zustand als zuvor.

• Die Dokumentation entspricht den .

• Der Umfang der Tests für diese Pull-Anforderung ist angemessen.

• Für den Benutzer sichtbare Zeichenfolgen, sofern vorhanden, wurden in *.resx-Dateien extrahiert.

• Alle Tests mit Self-Service-CI sind erfolgreich.

• Snapshots von Änderungen an der Benutzeroberfläche, sofern vorhanden, liegen vor.

• Änderungen an der API folgen der und sind im Dokument für dokumentiert.

Das Dynamo-Team weist Ihrer Pull-Anforderung einen geeigneten Prüfer zu.

Überprüfungsprozess für Pull-Anforderungen

Nachdem eine Pull-Anforderung übermittelt wurde, werden Sie möglicherweise während des Überprüfungsprozesses weiter mit einbezogen. Beachten Sie die folgenden Überprüfungskriterien:

• Das Dynamo-Team kommt einmal im Monat zusammen, um Pull-Anforderungen zu prüfen. Es werden zunächst die ältesten, dann die neueren Anforderungen geprüft.

• Wenn eine überprüfte Pull-Anforderung Änderungen durch den Eigentümer erfordert, hat der Eigentümer der Pull-Anforderung 30 Tage Zeit, um zu antworten. Wenn bei der Pull-Anforderung bis zur nächsten Sitzung keine Aktivität stattgefunden hat, wird sie entweder vom Team geschlossen oder, je nach Nützlichkeit, von einem Mitglied des Teams übernommen.

• Für Pull-Anforderungen sollte die vorgegebene Vorlage für Pull-Anforderungen von Dynamo verwendet werden.

• Pull-Anforderungen, bei denen die Vorlage für Pull-Anforderungen von Dynamo nicht vollständig ausgefüllt ist bzw. bei denen nicht alle Richtlinien erfüllt werden, werden nicht überprüft.

Cherrypicking bei Dynamo Revit-Commits

Da es auf dem Markt viele Versionen von Revit gibt, müssen Sie Ihre Änderungen möglicherweise in bestimmte Verzweigungen von DynamoRevit-Versionen integrieren, damit die neuen Funktionen in anderen Versionen von Revit aufgegriffen werden können. Während des Überprüfungsprozesses sind die Beitragenden dafür verantwortlich, die überprüften Commits nach Angabe des Dynamo-Teams in die spezifischen anderen DynamoRevit-Verzweigungen zu integrieren.

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.

Wenn Sie nach Beispielen für die Entwicklung für Dynamo suchen, sehen Sie sich die folgenden Ressourcen an:

Beispiel-Repositorys

Diese Beispiele sind Visual Studio-Vorlagen, mit denen Sie Ihr eigenes Projekt starten können:

• : Vorlage für ZeroTouch-Basisblöcke

  • Zurückgeben mehrerer Ausgaben:

  • Verwenden eines nativen Geometrieobjekts aus Dynamo:

  • Beispieleigenschaft (Abfrageblock):

• : Vorlagen für NodeModel-Basisblöcke und Ansichtsanpassung

  • NodeModel-Basisvorlage:

    • Definieren von Blockattributen (Eingabe-/Ausgabenamen, Beschreibungen, Typen):

    • Zurückgeben von Null-Blöcken, wenn keine Eingaben vorhanden sind:

    • Erstellen eines Funktionsaufrufs:

  • Basisvorlage zur NodeModel-Ansichtsanpassung: , , ,

    • Benachrichtigen der Benutzeroberfläche, dass ein Element aktualisiert werden muss:

    • Anpassen von NodeModel:

    • Definieren von Schiebereglerattributen:

    • Bestimmen der Interaktionslogik für den Schieberegler:

• : Vorlagen für ZeroTouch, angepasste Benutzeroberfläche, Tests und Ansichtserweiterungen

  • • Erstellen eines angepassten Benutzeroberflächen-Basisblocks:

    • Erstellen eines Dropdown-Menüs:

  • • Systemtests:

    • ZeroTouch-Tests:

  • :

    • Zero-Touch-Beispielblöcke, einschließlich eines Blocks, der IGraphicItem implementiert, um das Geometrie-Rendering zu beeinflussen:

    • Zero-Touch-Beispielblöcke zum Einfärben von Geometrie mit IRenderPackage:

  • : Eine IViewExtension-Implementierung, die ein modusunabhängiges Fenster anzeigt, wenn auf MenuItem geklickt wird

• : Vorlagen für die erweiterte Dynamo-Paketentwicklung mit NodeModel

  • Beispiele für Grundfunktionen:

  • Geometrie-Beispiele:

  • Beispiele für die Benutzeroberfläche:

Fallbeispiele

Drittentwickler haben wichtige und interessante Beiträge für die Plattform geleistet, von denen viele auch Open-Source-Beiträge sind. Die folgenden Projekte sind außergewöhnliche Beispiele für das, was mit Dynamo ausgeführt werden kann.

Ladybug ist eine Python-Bibliothek zum Laden, Analysieren und Ändern von EnergyPlus Weather-Dateien (epw).

Honeybee ist eine Python-Bibliothek zum Erstellen, Ausführen und Visualisieren der Ergebnisse von Tageslichtanalysen (RADIANCE) und Energieanalysen (EnergyPlus/OpenStudio).

Bumblebee ist ein Plugin für die Interoperabilität mit Excel und Dynamo (GPL).

Clockwork ist eine Sammlung benutzerdefinierter Blöcke für Revit-bezogene Aktivitäten sowie für andere Zwecke, wie Listenverwaltung, mathematische Operationen, Zeichenfolgenoperationen, geometrische Operationen (hauptsächlich Begrenzungsrahmen, Netze, Ebenen, Punkte, Oberflächen, UVs und Vektoren) und die Unterteilung von Oberflächen.

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

Allgemein gehören zur Erstellung einer Model-View-Beziehung in Dynamo zwei Aspekte:

• Eine NodeModel-Klasse zum Einrichten der Kernlogik des Blocks (Modell)

• Eine INodeViewCustomization-Klasse zum Anpassen der Anzeige von NodeModel (Ansicht)

NodeModel-Objekte verfügen bereits über eine verknüpfte View-Model-Beziehung (NodeViewModel). Daher können wir uns auf das Modell und die Ansicht für eine angepasste Benutzeroberfläche konzentrieren.

So implementieren Sie NodeModel

NodeModel-Blöcke unterscheiden sich in einigen wichtigen Punkten von Zero-Touch-Blöcken, die in diesem Beispiel behandelt werden. Bevor wir uns mit der Anpassung der Benutzeroberfläche befassen, erstellen wir zunächst die NodeModel-Logik.

1. Erstellen der Projektstruktur:

Ein NodeModel-Block kann nur Funktionen aufrufen. Daher müssen wir den Block NodeModel und die Funktionen in verschiedene Bibliotheken unterteilen. Die Standardmethode hierfür besteht für Dynamo-Pakete darin, für jedes Paket ein separates Projekt zu erstellen. Beginnen Sie mit dem Erstellen einer neuen Projektmappe, die die Projekte enthält.

1. Wählen Sie File > New > Project aus.

2. Wählen Sie Other Project Types aus, um die Option Projektmappe aufzurufen.

3. Wählen Sie Blank Solution aus.

4. Geben Sie der Projektmappe den Namen CustomNodeModel.

5. Wählen Sie Ok aus.

Erstellen Sie in der Projektmappe zwei C#-Klassenbibliotheksprojekte: eines für Funktionen und eines zur Implementierung der NodeModel-Schnittstelle.

1. Klicken Sie mit der rechten Maustaste auf die Projektmappe, und wählen Sie Add > New Project.

2. Wählen Sie die Klassenbibliothek.

3. Vergeben Sie den Namen CustomNodeModel.

4. Klicken Sie auf Ok.

5. Wiederholen Sie den Vorgang, um ein weiteres Projekt mit dem Namen CustomNodeModelFunctions hinzuzufügen.

Als Nächstes müssen wir die automatisch erstellten Klassenbibliotheken umbenennen und dem Projekt CustomNodeModel eine der Bibliotheken hinzufügen. Die GridNodeModel-Klasse implementiert die abstrakte NodeModel-Klasse, GridNodeView wird zum Anpassen der Ansicht verwendet, und GridFunction enthält alle Funktionen, die aufgerufen werden müssen.

1. Fügen Sie eine weitere Klasse hinzu, indem Sie mit der rechten Maustaste auf das Projekt CustomNodeModel klicken, Add > New Item... auswählen und Class wählen.

2. Im Projekt CustomNodeModel benötigen wir die Klassen GridNodeModel.cs und GridNodeView.cs.

3. Für das Projekt CustomNodeModelFunction benötigen wir eine GridFunctions.cs-Klasse.

Bevor wir den Klassen Code hinzufügen, fügen wir die erforderlichen Pakete für dieses Projekt hinzu. CustomNodeModel benötigt ZeroTouchLibrary und WpfUILibrary, CustomNodeModelFunction benötigt nur ZeroTouchLibrary. WpfUILibrary wird später bei der Anpassung der Benutzeroberfläche verwendet, und ZeroTouchLibrary wird zum Erstellen von Geometrie verwendet. Pakete können einzeln für Projekte hinzugefügt werden. Da diese Pakete Abhängigkeiten aufweisen, werden Core und DynamoServices automatisch installiert.

1. Klicken Sie mit der rechten Maustaste auf ein Projekt, und wählen Sie Manage NuGet Packages.

2. Installieren Sie nur die für dieses Projekt erforderlichen Pakete.

Visual Studio kopiert die NuGet-Pakete, die im Build-Verzeichnis referenziert werden. Dies kann auf False gesetzt werden, damit keine unnötigen Dateien im Paket vorhanden sind.

1. Wählen Sie Dynamo-NuGet-Pakete aus.

2. Legen Sie Copy Local auf False fest.

2. Übernehmen der NodeModel-Klasse

Wie bereits erwähnt, ist der wichtigste Aspekt, der einen NodeModel-Block von einem ZeroTouch-Block unterscheidet, die Implementierung der NodeModel-Klasse. Ein NodeModel-Block benötigt mehrere Funktionen aus dieser Klasse. Fügen Sie nach dem Klassennamen :NodeModel hinzu, um sie abzurufen.

Kopieren Sie den folgenden Code in GridNodeModel.cs.

Dies unterscheidet sich von Zero-Touch-Blöcken. Sehen wir uns die einzelnen Aspekte an.

• Geben Sie die Blockattribute wie Name, Kategorie, InPort-/OutPort-Namen, InPort-/OutPort-Typen und Beschreibungen an.

• public class GridNodeModel : NodeModel ist eine Klasse, die die NodeModel-Klasse von Dynamo.Graph.Nodes übernimmt.

• public GridNodeModel() { RegisterAllPorts(); } ist ein Konstruktor, der die Ein- und Ausgaben des Blocks registriert.

• BuildOutputAst() gibt einen AST (Abstract Syntax Tree, abstrakter Syntaxbaum) zurück, die erforderliche Struktur für die Rückgabe von Daten aus einem NodeModel-Block.

• AstFactory.BuildFunctionCall() ruft die Funktion RectangularGrid von GridFunctions.cs auf.

• new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid) gibt die Funktion und ihre Parameter an.

• new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue }); ordnet die Blockeingaben den Funktionsparametern zu.

• AstFactory.BuildNullNode() erstellt einen Null-Block, wenn die Eingabeanschlüsse nicht verbunden sind. Dadurch wird vermieden, dass eine Warnung für den Block angezeigt wird.

• RaisePropertyChanged("SliderValue") benachrichtigt die Benutzeroberfläche, wenn sich der Schiebereglerwert ändert.

• var sliderValue = AstFactory.BuildDoubleNode(SliderValue) erstellt einen Block im AST, der den Schiebereglerwert darstellt.

• Ändern Sie eine Eingabe für die Variable sliderValue in der functionCall-Variablen new List<AssociativeNode> { inputAstNodes[0], sliderValue });.

3. Aufrufen einer Funktion

Das Projekt CustomNodeModelFunction wird in einer anderen Assembly als CustomNodeModel erstellt, sodass es aufgerufen werden kann.

Kopieren Sie den folgenden Code in GridFunction.cs.

Diese Funktionsklasse ist der Zero-Touch-Rasterfallstudie sehr ähnlich, mit einem Unterschied:

• [IsVisibleInDynamoLibrary(false)] verhindert, dass Dynamo die folgende Methode und Klasse "sieht", da die Funktion bereits von CustomNodeModel aufgerufen wird.

Genauso wie wir Referenzen für NuGet-Pakete hinzugefügt haben, muss CustomNodeModel auf CustomNodeModelFunction verweisen, um die Funktion aufzurufen.

Die using-Anweisung für CustomNodeModel ist inaktiv, bis wir die Funktion referenzieren.

1. Klicken Sie mit der rechten Maustaste auf CustomNodeModel, und wählen Sie Add > Reference aus.

2. Wählen Sie Projects > Solution.

3. Aktivieren Sie CustomNodeModelFunction.

4. Klicken Sie auf Ok.

4. Anpassen der Ansicht

Um einen Schieberegler zu erstellen, müssen wir die Benutzeroberfläche durch Implementierung der INodeViewCustomization-Schnittstelle anpassen.

Kopieren Sie den folgenden Code in GridNodeView.cs:

• public class CustomNodeModelView : INodeViewCustomization<GridNodeModel> definiert die Funktionen, die zum Anpassen der Benutzeroberfläche erforderlich sind.

Nachdem die Struktur des Projekts eingerichtet wurde, verwenden Sie die Entwurfsumgebung von Visual Studio, um ein Benutzersteuerelement zu erstellen und dessen Parameter in einer .xaml-Datei zu definieren. Fügen Sie im Werkzeugkasten einen Schieberegler zu <Grid>...</Grid> hinzu.

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

2. Wählen Sie WPF aus.

3. Geben Sie dem Benutzersteuerelement den Namen Slider.

4. Klicken Sie auf Add.

Kopieren Sie den folgenden Code in Slider.xaml:

• Die Parameter des Schiebereglers werden in der .xaml-Datei definiert. Minimum- und Maximum-Attribute definieren den numerischen Bereich dieses Schiebereglers.

• In <Grid>...</Grid> können wir verschiedene Benutzersteuerelemente aus dem Visual Studio-Werkzeugkasten platzieren.

Beim Erstellen der Datei Slider.xaml hat Visual Studio automatisch eine C#-Datei mit dem Namen Slider.xaml.cs erstellt, die den Schieberegler initialisiert. Ändern Sie den Namensbereich in dieser Datei.

• Der Namensbereich sollte CustomNodeModel.CustomNodeModel lauten.

In GridNodeModel.cs wird die Berechnungslogik des Schiebereglers definiert.

5. Konfigurieren als Paket

Bevor wir das Projekt erstellen, fügen wir im letzten Schritt eine pkg.json-Datei hinzu, damit Dynamo das Paket lesen kann.

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

2. Wählen Sie Web aus.

3. Wählen Sie JSON File aus.

4. Geben Sie der Datei den Namen pkg.json.

5. Klicken Sie auf Add.

• Kopieren Sie den folgenden Code in pkg.json:

• "name": Bestimmt den Namen des Pakets und dessen Gruppe in der Dynamo-Bibliothek.

• "keywords": Geben Sie Suchbegriffe für die Suche in der Dynamo-Bibliothek an.

• "node_libraries": [] Die mit dem Paket verknüpften Bibliotheken.

  Der letzte Schritt besteht darin, die Projektmappe zu erstellen und als Dynamo-Paket zu publizieren. Im Kapitel Paketbereitstellung finden Sie Informationen zum Erstellen eines lokalen Pakets vor der Online-Publizierung und zum Erstellen eines Pakets direkt in Visual Studio.

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.

1. Das Fenster der Ansichtserweiterung, das nach dem Beispiel SampleViewExtension im GitHub-Repository entwickelt wurde.

Wir erstellen das Beispiel zwar von Grund auf. Sie können aber auch das DynamoSamples-Repository herunterladen und erstellen, um es als Referenz zu verwenden.

Diese exemplarische Vorgehensweise referenziert speziell das Projekt mit dem Namen SampleViewExtension, das unter DynamoSamples/src/ zu finden ist.

So implementieren Sie eine Ansichtserweiterung

Eine Ansichtserweiterung besteht aus drei wesentlichen Teilen:

• Einer Assembly, die eine Klasse enthält, die IViewExtension implementiert, sowie einer Klasse, die ein Ansichtsmodell erstellt

• Einer .xml-Datei, die Dynamo mitteilt, wo zur Laufzeit nach dieser Assembly gesucht werden soll, und dem Typ der Erweiterung

• Einer .xaml-Datei, die Daten an die grafische Darstellung bindet und die Darstellung des Fensters bestimmt

1. Erstellen der Projektstruktur

Erstellen Sie zunächst ein neues Class Library-Projekt mit dem Namen SampleViewExtension.

1. Erstellen Sie ein neues Projekt, indem Sie File > New > Project auswählen.

2. Wählen Sie Class Library aus.

3. Geben Sie dem Projekt den Namen SampleViewExtension.

4. Wählen Sie Ok aus.

In diesem Projekt benötigen wir zwei Klassen. Eine Klasse, die IViewExtension, und eine andere, die NotificationObject. implementiert. IViewExtension enthält alle Informationen darüber, wie die Erweiterung bereitgestellt, geladen, referenziert und verworfen wird. NotificationObject informiert über Änderungen in Dynamo und IDisposable. Bei einer Änderung wird die Anzahl entsprechend aktualisiert.

1. Eine Klassendatei mit dem Namen SampleViewExtension.cs, die IViewExtension implementiert.

2. Eine Klassendatei mit dem Namen SampleWindowViewMode.cs, die NotificationObject implementiert.

Um IViewExtension verwenden zu können, benötigen wir das NuGet-Paket WpfUILibrary. Bei der Installation dieses Pakets werden automatisch die Pakete Core, Services und ZeroTouchLibrary installiert.

1. Wählen Sie WpfUILibrary aus.

2. Wählen Sie Install aus, um alle abhängigen Pakete zu installieren.

2. Implementieren der IViewExtension-Klasse

In der IViewExtension-Klasse legen wir fest, was geschieht, wenn Dynamo gestartet, die Erweiterung geladen und Dynamo beendet wird. Fügen Sie in der Klassendatei SampleViewExtension.cs den folgenden Code hinzu:

Die SampleViewExtension-Klasse erstellt ein anklickbares Menüelement, um das Fenster zu öffnen, und verbindet es mit dem Ansichtsmodell und dem Ansichtsfenster.

• public class SampleViewExtension : IViewExtension SampleViewExtension übernimmt Daten von der IViewExtension-Schnittstelle und stellt alles bereit, was wir zur Erstellung des Menüelements benötigen.

• sampleMenuItem = new MenuItem { Header = "Show View Extension Sample Window" }; erstellt ein MenuItem und fügt es dem Menü View hinzu.

1. Menüelement

• sampleMenuItem.Click += (sender, args) löst ein Ereignis aus, das ein neues Fenster öffnet, wenn auf das Menüelement geklickt wird.

• MainGrid = { DataContext = viewModel } legt den Datenkontext für das Hauptraster im Fenster fest, wobei auf Main Grid in der zu erstellenden Datei .xaml verwiesen wird.

• Owner = p.DynamoWindow legt den Eigentümer des Popup-Fensters auf Dynamo fest. Das bedeutet, dass das neue Fenster von Dynamo abhängig ist. Aktionen wie das Minimieren, Maximieren und Wiederherstellen von Dynamo bewirken daher, dass das neue Fenster dasselbe Verhalten aufweist.

• window.Show(); zeigt das Fenster an, für das die zusätzlichen Fenstereigenschaften festgelegt wurden.

3. Implementieren des Ansichtsmodells

Nachdem wir einige der grundlegenden Parameter des Fensters festgelegt haben, fügen wir die Logik für die Reaktion auf verschiedene Dynamo-bezogene Ereignisse hinzu und weisen die Benutzeroberfläche an, basierend auf diesen Ereignissen zu aktualisieren. Kopieren Sie den folgenden Code in die Klassendatei SampleWindowViewModel.cs:

Diese Implementierung der Ansichtsmodellklasse überwacht CurrentWorkspaceModel und löst ein Ereignis aus, wenn ein Block zum Arbeitsbereich hinzugefügt oder aus diesem entfernt wird. Dadurch wird eine Eigenschaftsänderung ausgelöst, die die Benutzeroberfläche oder gebundenen Elemente darüber informiert, dass die Daten geändert wurden und aktualisiert werden müssen. Der ActiveNodeTypes-Getter wird aufgerufen, der intern eine zusätzliche Hilfsfunktion getNodeTypes() aufruft. Diese Funktion durchläuft alle aktiven Blöcke im Ansichtsbereich, füllt eine Zeichenfolge mit den Namen dieser Blöcke aus und gibt diese Zeichenfolge an die Bindung in der XAML-Datei zurück, die im Popup-Fenster angezeigt werden soll.

Nachdem wir die Kernlogik der Erweiterung definiert haben, legen wir nun die Darstellungsdetails des Fensters mit einer .xaml-Datei fest. Wir benötigen lediglich ein einfaches Fenster, in dem die Zeichenfolge über die ActiveNodeTypes-Eigenschaftenbindung in TextBlock Text angezeigt wird.

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

2. Wählen Sie die Vorlage des Benutzersteuerelements aus, die wir später zum Erstellen eines Fensters ändern werden.

3. Geben Sie der neuen Datei den Namen SampleWindow.xaml.

4. Wählen Sie Add aus.

Im .xaml-Code des Fensters müssen wir SelectedNodesText an einen Textblock binden. Fügen Sie den folgenden Code zu SampleWindow.xaml hinzu:

• Text="{Binding ActiveNodeTypes}" bindet den Eigenschaftswert von ActiveNodeTypes in SampleWindowViewModel.cs an den Wert TextBlock Text im Fenster.

Als Nächstes initialisieren wir das Beispielfenster in der XAML-C#-Sicherungsdatei SampleWindow.xaml.cs. Fügen Sie den folgenden Code zu SampleWindow.xaml hinzu:

Die Ansichtserweiterung kann jetzt erstellt und zu Dynamo hinzugefügt werden. Dynamo benötigt eine xml-Datei, um die .dll-Ausgabedatei als Erweiterung zu registrieren.

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

2. Wählen Sie die XML-Datei aus.

3. Geben Sie der Datei den Namen SampleViewExtension_ViewExtensionDefinition.xml.

4. Wählen Sie Add aus.

• Der Dateiname entspricht dem Dynamo-Standard zum Referenzieren einer Erweiterungs-Assembly wie folgt: "extensionName"_ViewExtensionDefinition.xml

Fügen Sie in der xml-Datei den folgenden Code hinzu, um Dynamo anzuweisen, wo nach der Erweiterungs-Assembly gesucht werden soll:

• In diesem Beispiel haben wir die Assembly im Vorgabeprojektordner von Visual Studio erstellt. Ersetzen Sie das Ziel <AssemblyPath>...</AssemblyPath> durch den Speicherort der Assembly.

Der letzte Schritt besteht darin, die Datei SampleViewExtension_ViewExtensionDefinition.xml in den Ordner der Ansichtserweiterungen von Dynamo zu kopieren, der sich im Dynamo Core-Installationsverzeichnis C:\Program Files\Dynamo\Dynamo Core\1.3\viewExtensions befindet. Beachten Sie, dass separate Ordner für extensions und viewExtensions existieren. Wenn Sie die xml-Datei in den falschen Ordner verschieben, wird sie zur Laufzeit möglicherweise nicht ordnungsgemäß geladen.

1. Die .xml-Datei, die wir in den Dynamo-Ordner mit den Ansichtserweiterungen kopiert haben.

Dies ist eine grundlegende Einführung in Ansichtserweiterungen. Eine detailliertere Fallstudie finden Sie im DynaShape-Paket, einem Open-Source-Projekt auf GitHub. Das Paket verwendet eine Ansichtserweiterung, die die Live-Bearbeitung in der Dynamo-Modellansicht ermöglicht.

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

• Verwenden des Build-Ziels AfterBuild in der .csproj-Datei, um Aufgaben zum Kopieren von Dateien und Verzeichnissen zu erstellen

AfterBuild ist die bevorzugte Methode für diese Operationstypen (und die in diesem Handbuch beschriebenen), da sie nicht auf dem Kopieren von Dateien beruht, die möglicherweise nicht auf dem Build-Computer verfügbar sind.

Kopieren von Paketdateien mit der AfterBuild-Methode

Richten Sie die Verzeichnisstruktur im Repository so ein, dass die Quelldateien von den Paketdateien getrennt sind. Platzieren Sie das Visual Studio-Projekt und alle zugehörigen Dateien in einem neuen src-Ordner, und arbeiten Sie dabei mit der Fallstudie CustomNodeModel. Sie speichern alle vom Projekt generierten Pakete in diesem Ordner. Die Ordnerstruktur sollte nun wie folgt aussehen:

1. Verschieben Sie die Projektdateien in den neuen src-Ordner.

Wir müssen sicherstellen, dass das Ziel der Datei CustomNodeModel.csproj hinzugefügt wurde (nicht einer anderen Projektdatei) und dass das Projekt keine vorhandenen Postbuild-Einstellungen aufweist.

1. Platzieren Sie das AfterBuild-Ziel vor dem </Project>-End-Tag.

Im Abschnitt <ItemGroup> sind eine Reihe von Variablen definiert, die bestimmte Dateitypen darstellen. Die Variable Dll stellt beispielsweise alle Dateien im Ausgabeverzeichnis mit der Erweiterung .dll dar.

Die Aufgabe Copy besteht darin, alle .dll-Dateien in ein Verzeichnis zu kopieren, insbesondere den Paketordner, in dem die Erstellung erfolgt.

Dynamo-Pakete verfügen in der Regel über einen dyf- und einen extra-Ordner für benutzerdefinierte Dynamo-Blöcke und andere Objekte, z. B. Bilder. Um diese Ordner zu erstellen, müssen wir eine MakeDir-Aufgabe verwenden. Diese Aufgabe erstellt einen Ordner, wenn er noch nicht vorhanden ist. Sie können diesem Ordner manuell Dateien hinzufügen.

Wenn Sie das Projekt erstellen, sollte der Projektordner jetzt einen packages-Ordner neben dem zuvor erstellten src-Ordner enthalten. Im packages-Verzeichnis befindet sich ein Ordner, der alle für das Paket erforderlichen Elemente enthält. Außerdem müssen wir die Datei pkg.json in den Paketordner kopieren, damit Dynamo erkennt, dass das Paket geladen werden soll.

1. Der neue Paketordner, den das AfterBuild-Ziel erstellt hat.

2. Der vorhandene src-Ordner mit dem Projekt.

3. Die Ordner dyf und extra, die aus dem AfterBuild-Ziel erstellt wurden.

4. Kopieren Sie die Datei pkg.json manuell.

Jetzt können Sie das Paket mithilfe des Paket-Managers von Dynamo publizieren oder es direkt in das Paketverzeichnis von Dynamo kopieren: <user>\AppData\Roaming\Dynamo\1.3\packages.