Weitere Schritte mit Zero-Touch
Last updated
Last updated
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.
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
Der Vorgabewert wird angezeigt, wenn Sie den Mauszeiger über den Eingabeanschluss des Blocks bewegen.
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>
.
Weitere Informationen finden Sie in diesem Codebeispiel in ZeroTouchEssentials.cs.
Ein Block, der mehrere Ausgaben zurückgibt.
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.
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 > Output
auswählen und Documentation file
aktivieren.
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.
Weitere Informationen finden Sie in diesem Codebeispiel in ZeroTouchEssentials.cs.
Beachten Sie, dass der Code für diesen Beispielblock Folgendes enthält:
Eine Blockzusammenfassung
Eine Eingabebeschreibung
Eine Ausgabebeschreibung
Blockbeschreibungen erläutern kurz die Funktion und die Ausgabe eines Blocks. In Dynamo werden sie an zwei Stellen angezeigt:
In der QuickInfo des Blocks
Im Dokumentationsbrowser
Befolgen Sie diese Richtlinien, um beim Schreiben oder Aktualisieren von Blockbeschreibungen Konsistenz zu gewährleisten und Zeit zu sparen.
Überblick
Beschreibungen sollten aus ein bis zwei Sätzen bestehen. Wenn Sie weitere Informationen benötigen, fügen Sie diese im Dokumentationsbrowser unter Im Detail ein.
Groß- und Kleinschreibung (Großschreibung des ersten Wortes eines Satzes und von Eigennamen). Kein Punkt am Ende.
Die Sprache sollte so klar und einfach wie möglich sein. Definieren Sie Akronyme bei der ersten Erwähnung, es sei denn, sie sind auch unter Laien allgemein bekannt.
Legen Sie immer Wert auf Klarheit, auch wenn das bedeutet, von diesen Richtlinien abzuweichen.
Richtlinien
Beginnen Sie die Beschreibung mit einem Verb in der dritten Person.
Beispiel: Ermittelt, ob sich ein Geometrieobjekt mit einem anderen schneidet.
Beginnen Sie nicht mit einem Verb in der zweiten Person oder mit einem Substantiv.
Beispiel: Ermitteln, ob sich ein Geometrieobjekt mit einem anderen schneidet
Verwenden Sie "Gibt zurück" oder "Erstellt" bzw. ein anderes beschreibendes Verb anstelle von "Holt".
Beispiel: Gibt eine NURBS-Darstellung einer Fläche zurück.
Verwenden Sie nicht "Holen" oder "Holt". Dieses Verb ist wenig spezifisch und kann sehr unterschiedlich übersetzt werden.
Beispiel: Holt eine NURBS-Darstellung der Fläche.
Wenn Sie sich auf Eingaben beziehen, verwenden Sie "angegeben" oder "eingegeben" anstelle von "festgelegt" oder anderen Begriffen. Lassen Sie "angegeben" oder "eingegeben" nach Möglichkeit weg, um die Beschreibung zu vereinfachen und die Wortzahl zu reduzieren.
Beispiel: Löscht die angegebene Datei.
Beispiel: Projiziert eine Kurve entlang der angegebenen Projektionsrichtung auf die angegebene Basisgeometrie.
Sie können "festgelegt" verwenden, wenn Sie sich nicht direkt auf eine Eingabe beziehen.
Beispiel: Schreibt Textinhalte in eine Datei, die durch den angegebenen Pfad festgelegt wird.
Um die Konsistenz zu gewährleisten, sollten Sie bei Eingaben weder "festgelegt" noch einen anderen Begriff außer "angegeben" oder "eingegeben" verwenden. Mischen Sie "angegeben" und "eingegeben" nicht in derselben Beschreibung, es sei denn, dies ist aus Gründen der Übersichtlichkeit erforderlich.
Beispiel: Löscht die festgelegte Datei.
Beispiel: Projiziert eine eingegebene Kurve entlang einer angegebenen Projektionsrichtung auf eine festgelegte Basisgeometrie.
Verwenden Sie "ein" oder "eine", wenn Sie sich zum ersten Mal auf eine Eingabe beziehen. Verwenden Sie aus Gründen der Übersichtlichkeit ggf. "der/die/das ein-/angegebene" anstelle von "ein" oder "eine".
Beispiel: Sweept eine Kurve entlang der Pfadkurve.
Verwenden Sie nicht "dies(e/r)", wenn Sie sich zum ersten Mal auf eine Eingabe beziehen.
Beispiel: Sweept diese Kurve entlang der Pfadkurve.
Wenn Sie sich zum ersten Mal auf eine Ausgabe oder ein anderes Substantiv beziehen, das das Ziel der Blockoperation ist, verwenden Sie "ein" oder "eine". Verwenden Sie "der/die/das" nur, wenn Sie den Artikel zusammen mit "eingegeben" oder "angegeben" verwenden.
Beispiel: Kopiert eine Datei.
Beispiel: Kopiert die angegebene Datei.
Wenn Sie sich zum ersten Mal auf eine Ausgabe oder ein anderes Substantiv beziehen, das das Ziel der Blockoperation ist, verwenden Sie nicht "der/die/das" allein.
Beispiel: Kopiert die Datei.
Schreiben Sie das erste Wort eines Satzes und alle Eigennamen, Substantive und Wörter, die im Allgemeinen groß geschrieben werden, groß.
Beispiel: Gibt den Schnittpunkt zweier Begrenzungsrahmen zurück.
Schreiben Sie gängige Geometrieobjekte und Konzepte nur groß, wenn dies aus Gründen der Übersichtlichkeit erforderlich ist.
Beispiel: Skaliert ungleichmäßig um die angegebene Ebene.
Schreiben Sie Boolesch groß. Schreiben Sie True und False groß, wenn Sie sich auf die Ausgabe von Booleschen Werten beziehen.
Beispiel: Gibt True zurück, wenn die beiden Werte unterschiedlich sind.
Beispiel: Wandelt eine Zeichenfolge basierend auf einem Booleschen Parameter in Groß- oder Kleinbuchstaben um.
Boolesche Werte dürfen nicht klein geschrieben werden. Schreiben Sie True und False nicht klein, wenn Sie sich auf die Ausgabe von Booleschen Werten beziehen.
Beispiel: Gibt true zurück, wenn die beiden Werte unterschiedlich sind.
Beispiel: Wandelt eine Zeichenfolge basierend auf einem booleschen Parameter in Groß- oder Kleinbuchstaben um.
Blockwarnungen und -fehler machen den Benutzer auf ein Problem mit dem Diagramm aufmerksam. Sie informieren den Benutzer über Probleme, die die normale Ausführung des Diagramms beeinträchtigen, indem ein Symbol und ein erweiterter Text-Beschriftungsblock über dem Block angezeigt werden. Blockfehler und -warnungen können unterschiedliche Schweregrade aufweisen: Einige Diagramme können mit Warnungen dennoch ausgeführt werden, während bei anderen die erwarteten Ergebnisse blockiert werden. In allen Fällen sind Blockfehler und -warnungen wichtige Werkzeuge, um den Benutzer über Probleme mit dem Diagramm auf dem Laufenden zu halten.
Richtlinien zur Gewährleistung der Konsistenz und zur Zeitersparnis beim Schreiben oder Aktualisieren von Blockwarn- und -fehlermeldungen finden Sie auf der Wiki-Seite Inhaltsmuster: Blockwarnungen und -fehler.
Dynamo verfügt nicht über das Schlüsselwort new
, sodass Objekte unter Verwendung statischer Konstruktionsmethoden erstellt werden müssen. Objekte werden wie folgt konstruiert:
Legen Sie den Konstruktor als intern (internal ZeroTouchEssentials()
) fest, sofern nicht anders erforderlich.
Konstruieren Sie das Objekt mit einer statischen Methode wie public static ZeroTouchEssentials ByTwoDoubles(a, b)
.
Anmerkung: Dynamo verwendet das Präfix Von, um anzugeben, dass eine statische Methode ein Konstruktor ist. Diese Option ist zwar optional, doch die Verwendung von Von hilft Ihnen dabei, die Bibliothek besser in den vorhandenen Dynamo-Stil einzupassen.
Weitere Informationen finden Sie in diesem Codebeispiel in 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.
Dynamo-Bibliotheken können native Dynamo-Geometrietypen als Eingaben verwenden und neue Geometrie als Ausgaben erstellen. Geometrietypen werden wie folgt erstellt:
Referenzieren Sie ProtoGeometry.dll im Projekt, indem Sie using Autodesk.DesignScript.Geometry;
oben in der C#-Datei einfügen und das ZeroTouchLibrary-NuGet-Paket zum Projekt hinzufügen.
Wichtig: Verwalten Sie die Geometrieressourcen, die nicht von Ihren Funktionen zurückgegeben werden, wie im Abschnitt Verwerfen/Verwenden von Anweisungen weiter unten beschrieben.
Anmerkung: Dynamo-Geometrieobjekte werden wie alle anderen übergebenen Objekte für Funktionen verwendet.
Weitere Informationen finden Sie in diesem Codebeispiel in ZeroTouchEssentials.cs.
Ein Block, der die Länge einer Kurve abruft und diese verdoppelt.
Dieser Block akzeptiert einen Kurvengeometrietyp als Eingabe.
Geometrieressourcen, die nicht aus Funktionen zurückgegeben werden, müssen manuell verwaltet werden, es sei denn, Sie verwenden die Dynamo-Version 2.5 oder höher. In Dynamo 2.5 und späteren Versionen werden Geometrieressourcen intern vom System verwaltet. Sie müssen Geometrie jedoch möglicherweise weiterhin manuell entfernen, wenn es sich um einen komplexen Anwendungsfall handelt oder wenn Sie zu einem festgelegten Zeitpunkt Speicherplatz reduzieren müssen. Die Dynamo-Engine verarbeitet alle Geometrieressourcen, die aus Funktionen zurückgegeben werden. Nicht zurückgegebene Geometrieressourcen können wie folgt manuell verarbeitet werden:
Mit einer using-Anweisung:
Die using-Anweisung ist 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:
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.
Klicken Sie mit der rechten Maustaste, und wählen Sie
Add > New Item
aus.Wählen Sie
XML File
.Für dieses Projekt geben wir der Migrationsdatei den Namen
ZeroTouchEssentials.Migrations.xml
.
Dieser Beispielcode weist Dynamo an, dass alle Blöcke mit dem Namen GetClosestPoint
jetzt den Namen ClosestPointTo
erhalten.
Weitere Informationen finden Sie in diesem Codebeispiel in ProtoGeometry.Migrations.xml.
Zero-Touch unterstützt derzeit keine Generika. Sie können verwendet werden, jedoch nicht in dem Code, der direkt importiert wird, wenn der Typ nicht festgelegt ist. Methoden, Eigenschaften oder Klassen, die generisch sind und nicht über einen festgelegten Typ verfügen, können nicht verfügbar gemacht werden.
Im folgenden Beispiel wird ein Zero-Touch-Block des Typs T
nicht importiert. Wenn die restliche Bibliothek in Dynamo importiert wird, fehlen Typausnahmen.
Wenn Sie in diesem Beispiel einen generischen Typ mit dem festgelegtem Typ verwenden, wird dieser in Dynamo importiert.