Dalsze kroki z Zero-Touch
Po omówieniu tworzenia projektu Zero-Touch możemy teraz lepiej zapoznać się z zagadnieniami dotyczącymi tworzenia węzła, analizując przykład ZeroTouchEssentials w witrynie dodatku Dynamo w serwisie Github.
Wiele węzłów standardowych dodatku Dynamo to w zasadzie węzły Zero-Touch, takie jak większość węzłów Math, Color i DateTime powyżej.
Aby rozpocząć, pobierz projekt ZeroTouchEssentials stąd: https://github.com/DynamoDS/ZeroTouchEssentials
W programie Visual Studio otwórz plik rozwiązania ZeroTouchEssentials.sln
i skompiluj to rozwiązanie.
Plik
ZeroTouchEssentials.cs
zawiera wszystkie metody, które zaimportujemy do dodatku Dynamo.
Otwórz dodatek Dynamo i zaimportuj plik ZeroTouchEssentials.dll
, aby pobrać węzły, do których odwołujemy się w kolejnych przykładach.
Przykłady kodu są ściągane z pliku ZeroTouchEssentials.cs i na ogół są z nim zgodne. Dokumentację XML usunięto, aby były one zwięzłe. Każdy przykład kodu spowoduje utworzenie węzła pokazanego na ilustracji powyżej.
Domyślna wartość wejściowa
Dodatek Dynamo obsługuje definiowanie wartości domyślnych dla portów wejściowych w węźle. Te wartości domyślne zostają dostarczone do węzła, jeśli porty nie mają połączeń. Wartości domyślne są wyrażane za pomocą mechanizmu języka C# do określania argumentów opcjonalnych omówionego w Podręczniku programowania C#. Wartości domyślne określa się w następujący sposób:
Ustaw domyślną wartość parametrów metody:
inputNumber = 2.0
Po umieszczeniu kursora na porcie wejściowym węzła zostanie wyświetlona wartość domyślna
Zwracanie wielu wartości
Zwracanie wielu wartości jest nieco bardziej złożone niż tworzenie wielu danych wejściowych. Aby to zrobić, należy użyć słownika. Pozycje słownika stają się portami po stronie wyjściowej węzła. Wiele portów wartości zwracanych tworzy się w następujący sposób:
Dodaj instrukcję
using System.Collections.Generic;
, aby użyć słownika:Dictionary<>
.Dodaj instrukcję
using Autodesk.DesignScript.Runtime;
, aby użyć atrybutuMultiReturn
. Jest to odwołanie do pliku „DynamoServices.dll” z pakietu NuGet dodatku DynamoServices.Dodaj do metody atrybut
[MultiReturn(new[] { "string1", "string2", ... more strings here })]
. Te ciągi odwołują się do kluczy w słowniku i staną się one nazwami portów wyjściowych.Zwróć słownik
Dictionary<>
z funkcji z kluczami odpowiadającymi nazwom parametrów w atrybucie:return new Dictionary<string, object>
Zobacz przykład kodu w pliku ZeroTouchEssentials.cs
Węzeł zwracający wiele pozycji danych wyjściowych.
Zwróć uwagę, że teraz istnieją dwa porty wyjściowe o nazwach zgodnych z ciągami wprowadzonymi dla kluczy słownika.
Dokumentacja, etykiety narzędzi i wyszukiwanie
Do najlepszych rozwiązań należy dodawanie do węzłów dodatku Dynamo dokumentacji opisującej funkcję węzła, jego dane wejściowe i wyjściowe, tagi wyszukiwania itp. Robi się to za pomocą tagów dokumentacji XML. Dokumentację XML tworzy się w następujący sposób:
Każdy tekst komentarza poprzedzony trzema ukośnikami jest traktowany jako należący do dokumentacji
Na przykład:
/// Documentation text and XML goes here
Po trzech ukośnikach utwórz tagi XML powyżej metod, które dodatek Dynamo odczyta podczas importowania pliku .dll
Na przykład:
/// <summary>...</summary>
Włącz dokumentację XML w programie Visual Studio, wybierając opcję
Project > Project Properties > Build
i zaznaczając opcjęXML documentation file
Program Visual Studio wygeneruje plik XML w określonej lokalizacji
Typy tagów są następujące:
Tag
/// <summary>...</summary>
określa dokumentację główną węzła i jego zawartość będzie wyświetlana jako etykieta narzędzi nad węzłem na pasku po lewej stronie paska wyszukiwaniaTag
/// <param name="inputName">...</param>
tworzy dokumentację dla określonych parametrów wejściowychTag
/// <returns>...</returns>
tworzy dokumentację dla parametru wyjściowegoTag
/// <returns name = "outputName">...</returns>
tworzy dokumentację dla wielu parametrów wyjściowychTag
/// <search>...</search>
dopasowuje węzeł do wyników wyszukiwania na podstawie listy rozdzielonej przecinkami. Jeśli na przykład tworzymy węzeł, który dzieli siatkę, możemy dodać takie oznaczenia, jak „mesh” (siatka), „subdivision” (podpodział) i „catmull-clark”.
Poniżej przedstawiono przykładowy węzeł z opisami danych wejściowych i wyjściowych oraz podsumowanie, które będzie wyświetlane w bibliotece.
Zobacz przykład kodu w pliku ZeroTouchEssentials.cs
Należy zwrócić uwagę, że kod dla tego węzła przykładowego zawiera:
Podsumowanie węzła
Opis danych wejściowych
Opis danych wyjściowych
Obiekty
W dodatku Dynamo nie ma słowa kluczowego new
, dlatego obiekty należy konstruować przy użyciu statycznych metod konstrukcji. Obiekty konstruuje się w następujący sposób:
Ustaw konstruktor jako wewnętrzny,
internal ZeroTouchEssentials()
, chyba że jest to niezgodne z wymaganiamiSkonstruuj obiekt za pomocą metody statycznej, na przykład
public static ZeroTouchEssentials ByTwoDoubles(a, b)
Uwaga: w dodatku Dynamo używa się prefiksu „By”, aby wskazać, że metoda statyczna jest konstruktorem. Chociaż jest to opcjonalne, używanie prefiksu „By” ułatwia zapewnienie zgodności tworzonej biblioteki z istniejącym stylem dodatku Dynamo.
Zobacz przykład kodu w pliku ZeroTouchEssentials.cs
Po zaimportowaniu biblioteki DLL przykładu ZeroTouchEssentials w bibliotece będzie znajdował się węzeł ZeroTouchEssentials. Ten obiekt można utworzyć za pomocą węzła ByTwoDoubles
.
Używanie typów geometrii dodatku Dynamo
W bibliotekach Dynamo można używać własnych typów geometrii dodatku Dynamo jako danych wejściowych i tworzyć nową geometrię jako dane wyjściowe. Typy geometrii tworzy się w następujący sposób:
Utwórz odwołanie do pliku „ProtoGeometry.dll” w projekcie, umieszczając instrukcję
using Autodesk.DesignScript.Geometry;
u góry pliku z kodem C# i dodając do projektu pakiet NuGet ZeroTouchLibrary.Ważne: zadbaj o zarządzanie zasobami geometrii, które nie są zwracane z funkcji — zobacz sekcję Instrukcje Dispose/using poniżej.
Uwaga: obiekty geometrii dodatku Dynamo są używane tak samo jak wszystkie inne obiekty przekazywane do funkcji.
Zobacz przykład kodu w pliku ZeroTouchEssentials.cs
Węzeł, który pobiera długość krzywej i podwaja ją.
Ten węzeł przyjmuje jako dane wejściowe typ geometrii Curve (krzywa).
Instrukcje Dispose/using
Zasobami geometrii, które nie są zwracane z funkcji, należy zarządzać ręcznie, chyba że jest używany dodatek Dynamo w wersji 2.5 lub nowszej. W dodatku Dynamo 2.5 i wersjach późniejszych zasoby geometrii są obsługiwane wewnętrznie przez system, jednak w przypadku złożonego przypadku zastosowania geometrii może być konieczne ręczne usunięcie geometrii lub zmniejszenie pamięci w określonym z góry czasie. Silnik dodatku Dynamo obsługuje wszystkie zasoby geometrii zwracane z funkcji. Niezwrócone zasoby geometrii można obsłużyć ręcznie w następujący sposób:
Za pomocą instrukcji using:
Instrukcję using opisano tutaj
Aby dowiedzieć się więcej na temat nowych funkcji zwiększających stabilność wprowadzonych w dodatku Dynamo 2.5, zobacz Ulepszenia stabilności geometrii w dodatku Dynamo.
Za pomocą ręcznych wywołań metody Dispose:
Migracje
Wraz z opublikowaniem nowszej wersji biblioteki nazwy węzłów mogą ulec zmianie. Zmiany nazw można określić w pliku migracji, tak aby wykresy opracowane na podstawie poprzednich wersji biblioteki nadal działały poprawnie po aktualizacji. Migracje implementuje się w następujący sposób:
Utwórz plik
.xml
w tym samym folderze, w którym znajduje się plik.dll
, w następującym formacie: „Nazwa_podstawowego_pliku_DLL”.Migrations.xmlW pliku
.xml
utwórz pojedynczy element<migrations>...</migrations>
W tym elemencie migrations utwórz elementy
<priorNameHint>...</priorNameHint>
dla każdej zmiany nazwyDla każdej zmiany nazwy dodaj element
<oldName>...</oldName>
i element<newName>...</newName>
Kliknij prawym przyciskiem myszy i wybierz polecenie
Add > New Item
Wybierz opcję
XML File
W przypadku tego projektu należy nadać plikowi migracji nazwę
ZeroTouchEssentials.Migrations.xml
Ten kod przykładowy informuje dodatek Dynamo, że każdy węzeł o nazwie GetClosestPoint
ma teraz nazwę ClosestPointTo
.
Zobacz przykład kodu w pliku ProtoGeometry.Migrations.xml
Typy ogólne
W projekcie Zero-Touch nie jest obecnie obsługiwane używanie typów ogólnych. Mogą one być używane, ale nie w kodzie, który jest bezpośrednio importowany, gdy nie ustawiono typu. Metod, właściwości lub klas, które są ogólne i nie mają ustawionego typu, nie można uwidocznić.
W poniższym przykładzie węzeł Zero-Touch typu T
nie zostanie zaimportowany. Jeśli pozostała część biblioteki zostanie zaimportowana do dodatku Dynamo, pojawią się wyjątki wynikające z brakujących typów.
Użycie typu ogólnego z typem ustawionym w tym przykładzie spowoduje zaimportowanie do dodatku Dynamo.
Last updated