Mamy już działający projekt programu Visual Studio, więc teraz omówimy tworzenie węzła niestandardowego, który tworzy prostokątną siatkę komórek. Mimo że można ją utworzyć za pomocą kilku węzłów standardowych, jest to przydatne narzędzie, które można łatwo umieścić w węźle Zero-Touch. Inaczej niż w przypadku linii siatki komórki można skalować względem punktów środkowych, można sprawdzać ich wierzchołki narożnikowe i można wbudowywać je w powierzchnie.

W tym przykładzie omówiono kilka funkcji i pojęć, które należy uwzględnić podczas tworzenia węzła Zero-Touch. Po utworzeniu węzła niestandardowego i dodaniu go do dodatku Dynamo należy przejrzeć stronę „Dalsze kroki z Zero-Touch”, aby uzyskać więcej informacji na temat domyślnych wartości wejściowych, zwracania wielu wartości, dokumentacji, obiektów, używania typów geometrii dodatku Dynamo i migracji.

Węzeł niestandardowy siatki prostokątnej

Aby rozpocząć kompilowanie węzła siatki, utwórz nowy projekt biblioteki klas programu Visual Studio. Na stronie „Pierwsze kroki” można znaleźć szczegółowe omówienie sposobu konfigurowania projektu.

1. Jako typ projektu wybierz Class Library

2. Nadaj projektowi nazwę CustomNodes

Ponieważ będziemy tworzyć geometrię, musimy odwołać się do odpowiedniego pakietu NuGet. Zainstaluj pakiet ZeroTouchLibrary za pomocą Menedżera pakietów Nuget. Ten pakiet jest niezbędny dla instrukcji using Autodesk.DesignScript.Geometry;.

1. Odszukaj pakiet ZeroTouchLibrary

2. Użyjemy tego węzła w bieżącej kompilacji programu Dynamo Studio, czyli 1.3. Wybierz wersję pakietu zgodną z tą wersją.

3. Zwróć uwagę, że zmieniliśmy również nazwę pliku klasy na Grids.cs

Następnie należy ustanowić przestrzeń nazw i klasę, w których będzie istnieć metoda RectangularGrid. Węzeł zostanie nazwany w dodatku Dynamo zgodnie z nazwami metody i klasy. Nie musimy tego jeszcze kopiować do programu Visual Studio.

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

Część Autodesk.DesignScript.Geometry; odwołuje się do pliku ProtoGeometry.dll w pakiecie ZeroTouchLibrary System.Collections.Generic, który jest niezbędny do tworzenia list

Teraz możemy dodać metodę rysowania prostokątów. Plik klasy powinien wyglądać następująco i można go skopiować do programu Visual Studio.

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

Jeśli projekt wygląda podobnie do tego, spróbuj skompilować plik .dll.

1. Wybierz polecenie Build (Kompiluj) > Build Solution (Kompiluj rozwiązanie)

Sprawdź, czy w folderze bin projektu znajduje się plik .dll. Jeśli kompilacja się powiodła, można dodać plik .dll do dodatku Dynamo.

1. Węzeł niestandardowy RectangularGrids w bibliotece Dynamo

2. Węzeł niestandardowy w obszarze rysunku

3. Przycisk Add (Dodaj) umożliwiający dodanie pliku .dll do dodatku Dynamo

Modyfikacje węzłów niestandardowych

W powyższym przykładzie utworzyliśmy dość prosty węzeł, który nie definiował wiele więcej oprócz metody RectangularGrids. Jednak może być konieczne utworzenie etykiet narzędzi dla portów wejściowych lub nadanie węzłowi podsumowania, jak w przypadku standardowych węzłów Dynamo. Dodanie tych elementów do węzłów niestandardowych ułatwia korzystanie z nich, zwłaszcza jeśli użytkownik chce wyszukiwać je w bibliotece.

1. Domyślna wartość wejściowa

2. Etykieta narzędzia dla danych wejściowych xCount

Węzeł RectangularGrid wymaga niektórych z tych podstawowych funkcji. W poniższym kodzie dodaliśmy opisy portów wejściowych i wyjściowych, podsumowanie oraz domyślne wartości wejściowe.

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

• Nadaj wartości domyślne danym wejściowym, przypisując wartości parametrom metody: RectangularGrid(int xCount = 10, int yCount = 10)

• Utwórz etykiety narzędzi dla portów wejściowych i wyjściowych, słowa kluczowe wyszukiwania i podsumowanie za pomocą dokumentacji XML poprzedzonej znakiem ///.

Aby dodać etykiety narzędzi, potrzebujemy pliku xml w katalogu projektu. Plik .xml może zostać automatycznie wygenerowany przez program Visual Studio.

1. Włącz plik dokumentacji XML tutaj i określ ścieżkę pliku. Spowoduje to wygenerowanie pliku XML.

Gotowe! Utworzyliśmy nowy węzeł z kilkoma standardowymi elementami. W kolejnym rozdziale dotyczącym podstaw Zero-Touch podano więcej szczegółów na temat opracowywania węzłów Zero-Touch i problemów, o których należy pamiętać.

Jaki jest cel tego przewodnika?

Celem tego przewodnika jest zapewnienie pomocy w poruszaniu się po zakresie możliwości programowania za pomocą języka C# w dodatku Dynamo: od tworzenia węzłów Zero-Touch po kompilowanie rozszerzeń.

Źródło dodatku Dynamo w serwisie GitHub

Jakie dodatkowe zasoby dla programistów udostępniamy?

Dynamo: pobierz najnowsze stabilne i codzienne kompilacje dodatku Dynamo

https://dynamobuilds.com/

Dynamo GitHub: Dynamo to projekt typu open source w serwisie GitHub.

https://github.com/DynamoDS/Dynamo

Witryna wiki w serwisie Github dla dodatku Dynamo: to podstawowy zasób dokumentacji dla programistów.

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

Standardy nazewnictwa węzłów: standardy i wskazówki dotyczące nazewnictwa kategorii, węzłów oraz portów wejściowych i wyjściowych w dodatku Dynamo.

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

Podręcznik dotyczący języka/interfejsu API dodatku Dynamo: dokumentacja interfejsu API dodatku Dynamo obejmuje obecnie podstawowe funkcje

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

DynamoBIM: najlepsze źródło dodatkowych informacji, treści edukacyjnych oraz forów to witryna DynamoBIM.

https://dynamobim.org

Słownik dodatku Dynamo: baza danych wszystkich węzłów dodatku Dynamo z funkcją wyszukiwania

https://dictionary.dynamobim.com/

Podręcznik języka DesignScript: podręcznik dotyczący języka DesignScript w formacie PDF

PDF

Jak można zasugerować zmiany w tym przewodniku?

Do tej dokumentacji można zgłaszać sugestie. Można je przekazywać bezpośrednio w serwisie Github, tworząc żądania zmian.

Źródło dodatku Dynamo jest hostowane w serwisie Github, w którym każdy może je klonować i współtworzyć. W tym rozdziale omówimy sposób klonowania repozytorium za pomocą narzędzia git, kompilowania plików źródłowych za pomocą programu Visual Studio, uruchamiania i debugowania kompilacji lokalnej oraz ściągania (pull) nowych zmian z serwisu Github.

Znajdowanie repozytorium dodatku Dynamo w serwisie Github

Github to usługa hostingu oparta na narzędziu git, systemie kontroli wersji umożliwiającym śledzenie zmian i koordynowanie pracy wielu osób. Git to narzędzie, za pomocą którego można pobierać pliki źródłowe dodatku Dynamo i aktualizować je przy użyciu kilku poleceń. Stosowanie tej metody pozwala uniknąć niepotrzebnego i nieuporządkowanego pobierania i ręcznego zastępowania plików źródłowych przy każdej aktualizacji. System kontroli wersji git śledzi wszelkie różnice między lokalnym i zdalnym repozytorium kodu.

Źródło dodatku Dynamo jest hostowane w witrynie DynamoDS w serwisie GitHub w tym repozytorium: https://github.com/DynamoDS/Dynamo

Pliki źródłowe dodatku Dynamo.

1. Klonowanie lub pobieranie całego repozytorium

2. Wyświetlanie innych repozytoriów DynamoDS

3. Pliki źródłowe dodatku Dynamo

4. Pliki charakterystyczne narzędzia git

Ściąganie (pull) repozytorium dodatku Dynamo za pomocą narzędzia git

Zanim będzie można sklonować repozytorium, należy zainstalować narzędzie git. Postępuj zgodnie z tym krótkim przewodnikiem, aby zapoznać się z krokami instalacji oraz konfigurowania nazwy użytkownika i adresu e-mail w serwisie GitHub. W tym przykładzie użyjemy narzędzia git w wierszu polecenia. W tym podręczniku przyjęto, że jest używany system Windows, ale narzędzia git można też używać w systemie Mac lub Linux, aby sklonować źródło dodatku Dynamo.

Do sklonowania potrzebny jest adres URL repozytorium dodatku Dynamo. Można go znaleźć za pomocą przycisku „Clone or download” (Klonuj lub pobierz) na stronie repozytorium. Skopiuj adres URL, aby wkleić go do wiersza polecenia.

1. Wybierz przycisk „Clone or download” (Klonuj lub pobierz)

2. Skopiuj adres URL

Po zainstalowaniu narzędzia git można sklonować repozytorium dodatku Dynamo. Rozpocznij od otwarcia wiersza polecenia. Następnie za pomocą polecenia do zmiany katalogu, cd, przejdź do folderu, do którego mają zostać sklonowane pliki źródłowe. W tym przypadku utworzyliśmy folder o nazwie Github w folderze Documents.

cd C:\Users\username\Documents\GitHub

Zastąp ciąg „username” swoją nazwą użytkownika

W następnym kroku uruchomimy polecenie git, aby sklonować repozytorium dodatku Dynamo do określonego położenia. Adres URL do użycia w tym poleceniu można uzyskać, klikając przycisk „Clone or download” (Klonuj lub pobierz) w serwisie GitHub. Uruchom to polecenie w terminalu poleceń. Uwaga: spowoduje to sklonowanie gałęzi głównej repozytorium dodatku Dynamo, która jest najczęściej aktualizowanym kodem dodatku Dynamo i zawiera najnowszą wersję kodu dodatku Dynamo. Ta gałąź zmienia się codziennie.

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

Jeśli operacja klonowania zakończyła się pomyślnie, oznacza to, że narzędzie git działa. W eksploratorze plików przejdź do katalogu, do którego sklonowano pliki źródłowe. Struktura katalogu powinna wyglądać tak samo jak gałąź główna repozytorium dodatku Dynamo w serwisie Github.

1. Pliki źródłowe dodatku Dynamo

2. Pliki git

Kompilowanie repozytorium za pomocą programu Visual Studio

Po sklonowaniu plików źródłowych na komputer lokalny można utworzyć plik wykonywalny dla dodatku Dynamo. W tym celu należy skonfigurować środowisko IDE programu Visual Studio oraz upewnić się, że zainstalowano programy .NET Framework i DirectX.

• Pobierz i zainstaluj oprogramowanie Microsoft Visual Studio Community 2015 — bezpłatne i w pełni funkcjonalne środowisko IDE (czyli zintegrowane środowisko programistyczne — mogą się również sprawdzić nowsze wersje)

• Pobierz i zainstaluj program Microsoft .NET Framework 4.5 lub nowszy

• Zainstaluj program Microsoft DirectX z lokalnego repozytorium dodatku Dynamo (Dynamo\tools\install\Extra\DirectX\DXSETUP.exe)

Programy .NET i DirectX mogą być już zainstalowane.

Po zakończeniu instalacji można uruchomić program Visual Studio i otworzyć rozwiązanie Dynamo.All.sln znajdujące się w folderze Dynamo\src.

1. Wybierz opcję File > Open > Project/Solution

2. Przejdź do repozytorium dodatku Dynamo i otwórz folder src

3. Wybierz plik rozwiązania Dynamo.All.sln

4. Wybierz opcję Open

Przed skompilowaniem rozwiązania należy określić kilka ustawień. Najpierw należy skompilować wersję dodatku Dynamo do debugowania, aby zebrać w programie Visual Studio więcej informacji w ramach debugowania na potrzeby programowania. Jako platformy docelowej należy użyć AnyCPU.

Staną się one folderami w folderze bin

1. W tym przykładzie jako konfigurację rozwiązania wybraliśmy opcję Debug

2. Jako platformę rozwiązania ustaw Any CPU

Przy otwartym projekcie możemy skompilować rozwiązanie. W tym procesie zostanie utworzony plik DynamoSandbox.exe, który można uruchomić.

Skompilowanie projektu spowoduje przywrócenie zależności NuGet.

1. Wybierz opcję Build > Build Solution

2. Sprawdź, czy kompilacja została zakończona pomyślnie w oknie danych wyjściowych. Komunikat powinien przypominać następujący: ==== Build: 69 succeeded, 0 failed, 0 up-to-date, 0 skipped ====

Uruchamianie kompilacji lokalnej

Jeśli dodatek Dynamo zostanie skompilowany pomyślnie, w repozytorium dodatku Dynamo zostanie utworzony folder bin z plikiem DynamoSandbox.exe. W tym przypadku tworzymy plik wykonywalny za pomocą opcji Debug, dlatego znajduje się on w folderze bin\AnyCPU\Debug. Uruchomienie tego pliku spowoduje otwarcie kompilacji lokalnej dodatku Dynamo.

1. Nowo skompilowany plik wykonywalny DynamoSandbox. Uruchom ten plik, aby uruchomić dodatek Dynamo.

Wszystko jest już prawie gotowe do rozpoczęcia pracy nad dodatkiem Dynamo.

Instrukcje dotyczące kompilowania dodatku Dynamo dla innych platform (np. Linux lub OS X) można znaleźć na tej stronie wiki.

Debugowanie kompilacji lokalnej za pomocą programu Visual Studio

Debugowanie to proces identyfikowania, izolowania i usuwania błędów lub problemów. Po pomyślnym skompilowaniu dodatku Dynamo ze źródła można za pomocą kilku narzędzi w programie Visual Studio debugować uruchomioną aplikację, na przykład dodatek DynamoRevit. Można przeanalizować kod źródłowy aplikacji, aby znaleźć źródło problemu, lub obserwować wykonywanie kodu na bieżąco. Aby uzyskać bardziej szczegółowe wyjaśnienia dotyczące debugowania i nawigowania po kodzie w programie Visual Studio, zapoznaj się z dokumentacją programu Visual Studio w witrynie Docs.

W przypadku autonomicznej aplikacji Dynamo, DynamoSandbox, omówimy dwie opcje debugowania:

• Kompilowanie i uruchamianie dodatku Dynamo bezpośrednio z programu Visual Studio

• Dołączanie programu Visual Studio do uruchomionego procesu dodatku Dynamo

W przypadku uruchamiania dodatku Dynamo z programu Visual Studio rozwiązanie jest ponownie kompilowane dla każdej sesji debugowania, jeśli jest to wymagane. Jeśli więc wprowadzono zmiany w źródle, zostają one uwzględnione podczas debugowania. Przy otwartym rozwiązaniu Dynamo.All.sln wybierz z menu rozwijanego opcje Debug, AnyCPU i DynamoSandbox, a następnie kliknij opcję Start. Spowoduje to skompilowanie dodatku Dynamo i uruchomienie nowego procesu (DynamoSandbox.exe), a następnie dołączenie do niego debugera programu Visual Studio.

Kompilowanie i uruchamianie aplikacji bezpośrednio z programu Visual Studio

1. Ustaw konfigurację na Debug

2. Ustaw platformę na Any CPU

3. Ustaw projekt startowy na DynamoSandbox

4. Kliknij opcję Start, aby rozpocząć proces debugowania

Można również debugować proces dodatku Dynamo, który jest już uruchomiony, aby rozwiązać problem z określonym otwartym wykresem lub pakietem. W tym celu należy otworzyć pliki źródłowe projektu w programie Visual Studio i dołączyć program do uruchomionego procesu dodatku Dynamo za pomocą elementu menu debugowania Attach to Process.

Dołączanie uruchomionego procesu do programu Visual Studio

1. Wybierz opcję Debug > Attach to Process...

2. Wybierz opcję DynamoSandbox.exe

3. Wybierz opcję Attach

W obu sytuacjach dołączamy debuger do procesu, który chcemy debugować. Przed lub po uruchomieniu debugera możemy ustawić punkty przerwania w kodzie, co spowoduje wstrzymanie procesu bezpośrednio przed wykonaniem danego wiersza kodu. Jeśli podczas debugowania zostanie zgłoszony nieprzechwycony wyjątek, program Visual Studio przeskoczy do miejsca, w którym ten wyjątek wystąpił w kodzie źródłowym. Jest to efektywna metoda wyszukiwania prostych awarii oraz nieobsługiwanych wyjątków i analizowania procesu wykonywania aplikacji.

Podczas debugowania aplikacji DynamoSandbox ustawiamy punkt przerwania w konstruktorze węzła Colour.ByARGB, który powoduje wstrzymanie procesu dodatku Dynamo po utworzeniu wystąpienia węzła. Jeśli ten węzeł zgłaszał wyjątek lub powodował awarię dodatku Dynamo, można krokowo wykonywać poszczególne wiersze w konstruktorze, aby sprawdzić, gdzie wystąpił problem.

1. Punkt przerwania

2. Stos wywołań ze wskazaniem obecnie wykonywanej funkcji i poprzednimi wywołaniami funkcji.

W następnej sekcji Kompilowanie dodatku DynamoRevit ze źródła omówimy konkretny przykład debugowania i wyjaśnimy, jak ustawiać punkty przerwania, krokowo wykonywać kod i odczytywać stos wywołań.

Ściąganie (pull) najnowszej kompilacji

Ponieważ źródło dodatku Dynamo znajduje się w serwisie Github, najprostszym sposobem zaktualizowania lokalnych plików źródłowych jest ściągnięcie (pull) zmian za pomocą poleceń git.

Za pomocą tego wiersza polecenia ustaw repozytorium dodatku Dynamo jako katalog bieżący:

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

Zastąp ciąg "username" swoją nazwą użytkownika

Za pomocą następującego polecenia ściągnij najnowsze zmiany:

git pull origin master

1. Widać tutaj, że repozytorium lokalne zostało zaktualizowane o zmiany wprowadzone zdalnie.

Oprócz ściągania (pull) aktualizacji dostępne są cztery inne ważne procesy robocze, które warto znać.

• Rozwidlanie (fork) repozytorium dodatku Dynamo umożliwiające utworzenie kopii oddzielnej od oryginału. Żadne zmiany wprowadzone w tym miejscu nie wpływają na repozytorium oryginalne, a aktualizacje można pobierać (fetch) lub przesyłać za pomocą próśb o ściągnięcie (pull). Rozwidlenie (fork) nie jest poleceniem narzędzia git, lecz procesem roboczym dodanym w serwisie GitHub — model używania rozwidlenia (fork) i prośby o ściągnięcie (pull) jest jednym z najpopularniejszych procesów roboczych wykorzystywanych przy współtworzeniu projektów open source w trybie online. Osoby chcące współtworzyć dodatek Dynamo powinny się z nim zapoznać.

• Gałąź (branch) — pracuj nad eksperymentami lub nowymi elementami odizolowanymi od innych prac w gałęziach. Ułatwia to wysyłanie próśb o ściągnięcie (pull).

• Często wykonuj zatwierdzenia (commit), szczególnie po ukończeniu jednostek pracy i po wprowadzeniu zmian mogących wymagać cofnięcia. Zatwierdzenie (commit) powoduje zarejestrowanie zmian w repozytorium i będzie widoczne podczas wysyłania prośby o ściągnięcie (pull) do repozytorium głównego dodatku Dynamo.

• Twórz prośby o ściągnięcie (pull), gdy zmiany są gotowe do oficjalnego zaproponowania ich w repozytorium głównym dodatku Dynamo.

Zespół dodatku Dynamo utworzył szczegółowe instrukcje dotyczące tworzenia próśb o ściągnięcie (pull). Szczegółowe informacje na temat tego, co należy uwzględnić, można znaleźć w sekcji „Prośby o ściągnięcie (pull)” w tej dokumentacji.

Na tej stronie dokumentacji podano listę referencyjną poleceń narzędzia git.

Przed rozpoczęciem prac nad rozwiązaniem należy opracować solidne podstawy dla nowego projektu. W społeczności programistów dodatku Dynamo dostępnych jest kilka szablonów projektów, które doskonale nadają się do rozpoczęcia pracy, ale jeszcze cenniejsza jest umiejętność rozpoczynania projektu od podstaw. Tworzenie projektu od podstaw pozwala lepiej zrozumieć proces opracowywania rozwiązania.

Tworzenie projektu programu Visual Studio

Program Visual Studio to zaawansowane środowisko IDE, w którym można tworzyć projekty, dodawać odwołania, kompilować biblioteki .dlls i debugować. Podczas tworzenia nowego projektu program Visual Studio tworzy również rozwiązanie, czyli strukturę organizacyjną projektów. W jednym rozwiązaniu może istnieć wiele projektów i można je kompilować razem. Aby utworzyć węzeł ZeroTouch, należy rozpocząć nowy projekt programu Visual Studio, w którym zostanie napisana biblioteka klas języka C# i zostanie skompilowany plik .dll.

Okno nowego projektu w programie Visual Studio

1. Zacznij od otwarcia programu Visual Studio i utworzenia nowego projektu: File > New > Project

2. Wybierz szablon projektu Class Library

3. Nadaj projektowi nazwę (w tym przypadku nazwaliśmy projekt MyCustomNode)

4. Ustaw ścieżkę pliku dla projektu. W tym przykładzie pozostawimy go w położeniu domyślnym

5. Wybierz przycisk Ok

Program Visual Studio automatycznie utworzy i otworzy plik w języku C#. Należy nadać mu odpowiednią nazwę, skonfigurować obszar roboczy i zastąpić kod domyślny tą metodą mnożenia.

1. Otwórz Eksplorator rozwiązań i okna danych wyjściowych z poziomu obszaru View.

2. W Eksploratorze rozwiązań po prawej stronie zmień nazwę pliku Class1.cs na SampleFunctions.cs.

3. Dodaj powyższy kod dla funkcji mnożenia. Szczegóły dotyczące tego, jak dodatek Dynamo będzie odczytywał klasy w języku C#, zostaną omówione później.

4. Eksplorator rozwiązań: umożliwia dostęp do wszystkich elementów w projekcie.

5. Okno danych wyjściowych: będzie potrzebne później, aby sprawdzić, czy kompilacja się powiodła.

Następnym krokiem jest skompilowanie projektu, ale wcześniej należy sprawdzić kilka ustawień. Najpierw upewnij się, że jako platformę docelową wybrano Any CPU lub x64 i że opcja Prefer 32-bit nie jest zaznaczona we właściwościach projektu.

1. Otwórz właściwości projektu, wybierając opcję Project > "ProjectName" Properties

2. Wybierz stronę Build

3. Wybierz z menu rozwijanego opcję Any CPU lub x64

4. Upewnij się, że opcja Prefer 32-bit nie jest zaznaczona

Teraz możemy skompilować projekt, aby utworzyć plik .dll. Aby to zrobić, wybierz opcję Build Solution z menu Build lub użyj skrótu CTRL+SHIFT+B.

1. Wybierz opcję Build > Build Solution

2. Aby ustalić, czy projekt został pomyślnie skompilowany, należy sprawdzić okno danych wyjściowych

Jeśli projekt został pomyślnie skompilowany, w folderze projektu bin będzie znajdować się plik .dll o nazwie MyCustomNode. W tym przykładzie pozostawiliśmy ścieżkę pliku projektu jako domyślną w programie Visual Studio: c:\users\username\documents\visual studio 2015\Projects. Przyjrzyjmy się strukturze plików projektu.

1. Folder bin zawiera plik .dll skompilowany w programie Visual Studio.

2. Plik projektu programu Visual Studio.

3. Plik klasy.

4. Ponieważ jako konfigurację rozwiązania ustawiono Debug, plik .dll zostanie utworzony w folderze bin\Debug.

Teraz możemy otworzyć dodatek Dynamo i zaimportować plik .dll. Za pomocą funkcji dodawania przejdź do położenia projektu bin i wybierz plik .dll, który chcesz otworzyć.

1. Wybierz przycisk Add (Dodaj), aby zaimportować plik .dll

2. Przejdź do położenia projektu. Projekt znajduje się w domyślnej ścieżce pliku programu Visual Studio: C:\Users\username\Documents\Visual Studio 2015\Projects\MyCustomNode

3. Wybierz plik MyCustomNode.dll do zaimportowania

4. Kliknij przycisk Open, aby wczytać plik .dll

Jeśli w bibliotece o nazwie MyCustomNode została utworzona kategoria, plik .dll został zaimportowany pomyślnie. Dodatek Dynamo utworzył jednak dwa węzły z tego, co powinno być jednym węzłem. W następnej sekcji wyjaśnimy, dlaczego tak się dzieje i jak dodatek Dynamo odczytuje plik .dll.

1. Węzeł MyCustomNode w bibliotece dodatku Dynamo. Kategoria biblioteki jest określana przez nazwę pliku .dll.

2. Węzeł SampleFunctions.MultiplyByTwo w obszarze rysunku.

Jak dodatek Dynamo odczytuje klasy i metody

Gdy dodatek Dynamo wczytuje plik .dll, wszystkie publiczne metody statyczne zostają uwidocznione jako węzły. Konstruktory, metody i właściwości zostają przekształcone w węzły odpowiednio Create (tworzenia), Action (operacji) i Query (zapytań). W tym przykładzie z mnożeniem metoda MultiplyByTwo() staje się węzłem operacji w dodatku Dynamo. Dzieje się tak, ponieważ węzeł został nazwany na podstawie metody i klasy.

1. Nazwa danych wejściowych to inputNumber na podstawie nazwy parametru metody.

2. Nazwa danych wyjściowych to domyślnie double, ponieważ jest to zwracany typ danych.

3. Węzeł ma nazwę SampleFunctions.MultiplyByTwo, ponieważ takie są nazwy klasy i metody.

W powyższym przykładzie utworzono dodatkowy węzeł tworzenia, SampleFunctions: nie udostępniliśmy konstruktora bezpośrednio, więc został on utworzony automatycznie. Można tego uniknąć, tworząc pusty konstruktor prywatny w klasie SampleFunctions.

1. Dodatek Dynamo zaimportował metodę jako węzeł tworzenia

Dodawanie odwołań do pakietów NuGet dodatku Dynamo

Ten węzeł mnożenia jest bardzo prosty i nie są wymagane żadne odwołania do dodatku Dynamo. Aby uzyskać dostęp do dowolnej funkcji dodatku Dynamo na przykład w celu utworzenia geometrii, należy odwołać się do pakietów NuGet dodatku Dynamo.

Aby utworzyć odwołanie do tych pakietów w projekcie programu Visual Studio, należy pobrać pakiet z witryny NuGet za pomocą powyższych linków i ręcznie utworzyć odwołanie do plików .dll lub użyć Menedżera pakietów NuGet w programie Visual Studio. Najpierw omówimy sposób ich instalowania za pomocą menedżera NuGet w programie Visual Studio.

1. Otwórz Menedżera pakietów NuGet, wybierając opcję Tools > NuGet Package Manager > Manage NuGet Packages for Solution...

To jest Menedżer pakietów NuGet. W tym oknie wyświetlane są pakiety zainstalowane dla projektu. Użytkownik może w nim też przeglądać inne pakiety. Jeśli zostanie wydana nowa wersja pakietu DynamoServices, w tym miejscu można zaktualizować pakiety lub przywrócić ich wcześniejszą wersję.

1. Wybierz opcję przeglądania i wyszukaj dodatek DynamoVisualProgramming, aby wywołać pakiety dodatku Dynamo.

2. Pakiety dodatku Dynamo. Wybranie jednego z nich spowoduje wyświetlenie bieżącej wersji i opisu zawartości.

3. Wybierz potrzebną wersję pakietu i kliknij przycisk instalowania. Spowoduje to zainstalowanie pakietu dla określonego projektu, w którym pracujesz. Używasz najnowszej stabilnej wersji dodatku Dynamo w wersji 1.3, więc wybierz odpowiednią dla niej wersję pakietu.

Aby ręcznie dodać pakiet pobrany z przeglądarki, otwórz Menedżera odnośników w Eksploratorze rozwiązań i wyszukaj pakiet.

1. Kliknij prawym przyciskiem myszy opcję References i wybierz polecenie Add Reference.

2. Wybierz opcję Browse, aby przejść do lokalizacji pakietu.

Program Visual Studio jest teraz właściwie skonfigurowany i pomyślnie dodano plik .dll do dodatku Dynamo, więc mamy dobrze przygotowane środowisko do dalszej pracy. Jest to dopiero początek, dlatego postępuj zgodnie z instrukcjami, aby dowiedzieć się więcej na temat tworzenia węzła niestandardowego.

Wprowadzenie

Ta sekcja zawiera informacje na temat problemów, które mogą wystąpić podczas migrowania wykresów, pakietów i bibliotek do dodatku Dynamo 3.x.

Dodatek Dynamo 3.0 jest wersją główną i niektóre interfejsy API zostały w nim zmienione lub usunięte. Największą zmianą, która może mieć konsekwencje dla programisty lub użytkownika dodatku Dynamo 3.x, jest przejście na platformę .NET8.

Dotnet/.NET to środowisko wykonawcze obsługujące język C#, w którym jest napisany dodatek Dynamo. Zaktualizowaliśmy środowisko wykonawcze do najnowszej wersji wraz z resztą ekosystemu firmy Autodesk.

Więcej informacji można znaleźć w .

Zgodność pakietów

Korzystanie z pakietów dodatku Dynamo 2.x w dodatku Dynamo 3.x

Ponieważ dodatek Dynamo 3.x działa teraz w środowisku wykonawczym .NET8, nie ma gwarancji, że pakiety utworzone dla dodatku Dynamo 2.x (przy użyciu platformy .NET48) będą działać w dodatku Dynamo 3.x. W przypadku próby pobrania w dodatku Dynamo 3.x pakietu opublikowanego w wersji Dynamo starszej niż 3.0 zostanie wyświetlone ostrzeżenie, że pakiet pochodzi ze starszej wersji dodatku Dynamo.

To nie oznacza, że pakiet nie będzie działał. Jest to po prostu ostrzeżenie, że mogą wystąpić problemy ze zgodnością, i że ogólnie warto sprawdzić, czy nie istnieje nowsza wersja, która została opracowana specjalnie dla dodatku Dynamo 3.x.

Ten typ ostrzeżenia może też pojawiać się w plikach dziennika dodatku Dynamo podczas wczytywania pakietu. Jeśli wszystko działa poprawnie, można zignorować to ostrzeżenie.

Korzystanie z pakietów dodatku Dynamo 3.x w dodatku Dynamo 2.x

Jest bardzo mało prawdopodobne, że pakiet utworzony dla dodatku Dynamo 3.x (przy użyciu platformy .Net8) będzie działał w dodatku Dynamo 2.x. Ponadto w przypadku pobierania w starszej wersji dodatku Dynamo pakietów przeznaczonych dla nowszych wersji również są wyświetlane ostrzeżenia.

Platformę Dynamo zaprojektowano tak, aby umożliwić współtworzenie wszystkim użytkownikom, niezależnie od poziomu doświadczenia. Dostępnych jest kilka opcji programowania odpowiednich do różnych rodzajów i poziomów umiejętności, z których każda ma zalety i wady w zależności od zamierzonego celu. Poniżej omówimy te różne opcje i sposób wyboru między nimi.

Trzy środowiska programistyczne: program Visual Studio, Edytor języka Python i język Code Block DesignScript

Jakie mam opcje?

Opcje programowania rozwiązań dla dodatku Dynamo należą przede wszystkim do dwóch kategorii: dla dodatku Dynamo i w dodatku Dynamo. Te dwie kategorie należy rozumieć tak: „w” dodatku Dynamo oznacza zawartość tworzoną za pomocą środowiska IDE dodatku Dynamo, która ma być używana w dodatku Dynamo; natomiast „dla” dodatku Dynamo oznacza tworzenie za pomocą narzędzi zewnętrznych zawartości, która ma być importowana do dodatku Dynamo w celu jej używania. W tym podręczniku skoncentrowano się na programowaniu dla dodatku Dynamo, ale poniżej opisano zasoby dotyczące wszystkich procesów.

Dla dodatku Dynamo

Te węzły umożliwiają najwyższy stopień dostosowania. Wiele pakietów jest kompilowanych za pomocą tej metody i jest ona niezbędna do współtworzenia źródła dodatku Dynamo. Proces ich kompilowania zostanie omówiony w tym podręczniku.

• Węzły Zero-Touch

• Węzły pochodne od klasy NodeModel

• Rozszerzenia

W poniższym omówieniu jako środowisko programistyczne dla węzłów Zero-Touch i NodeModel jest używany program Visual Studio.

Interfejs programu Visual Studio z projektem, który będziemy opracowywać

W dodatku Dynamo

• Węzły z bokami kodu, Code Block, uwidaczniają kod DesignScript w środowisku programowania wizualnego, umożliwiając używanie elastycznych procesów roboczych węzłów i skryptów tekstowych. Funkcję w węźle Code Block może wywołać dowolny element w obszarze roboczym.

• Węzły niestandardowe są kontenerami dla kolekcji węzłów, a nawet całych wykresów. Są one skutecznym sposobem gromadzenia często używanych procedur i udostępniania ich społeczności.

• Węzły w języku Python są interfejsem skryptowym w obszarze roboczym programowania wizualnego, podobnie jak węzły Code Block. W bibliotekach Autodesk.DesignScript używa się zapisu kropkowego podobnego do tego używanego w języku DesignScript.

Programowanie w obszarze roboczym dodatku Dynamo to wydajne rozwiązanie umożliwiające natychmiastowe uzyskanie informacji zwrotnych.

Programowanie w obszarze roboczym dodatku Dynamo za pomocą węzła w języku Python

Jakie są zalety/wady poszczególnych opcji?

Opcje programowania dla dodatku Dynamo zaprojektowano z uwzględnieniem złożoności wymagań dotyczących dostosowywania. Niezależnie od tego, czy celem jest napisanie skryptu cyklicznego w języku Python, czy opracowanie całkowicie niestandardowego interfejsu użytkownika węzła, dostępne są opcje implementowania kodu obejmujące tylko czynności niezbędne do przygotowania działającego rozwiązania.

Węzły Code Block, węzeł w języku Python i węzły niestandardowe w dodatku Dynamo

Są to proste opcje pisania kodu w środowisku programowania wizualnego dodatku Dynamo. Obszar roboczy programowania wizualnego dodatku Dynamo zapewnia dostęp do języka Python i języka DesignScript oraz możliwość umieszczania wielu węzłów wewnątrz węzła niestandardowego.

Te metody zapewniają następujące możliwości:

• Rozpoczęcie pisania w języku Python lub DesignScript przy niewielkiej konfiguracji lub w ogóle bez niej.

• Importowanie bibliotek języka Python do dodatku Dynamo.

• Udostępnianie społeczności węzłów Code Block, węzłów w języku Python i węzłów niestandardowych dodatku Dynamo w ramach pakietu.

Węzły Zero-Touch

Zero-Touch to prosta metoda importowania bibliotek C# przez wskazanie i kliknięcie. Dodatek Dynamo odczyta publiczne metody z pliku .dll i przekonwertuje je na węzły Dynamo. Za pomocą metody Zero-Touch można tworzyć własne pakiety i węzły niestandardowe.

Co można zrobić za pomocą tej metody:

• Pisanie metod w języku C# i łatwe używanie ich jako węzłów w dodatku Dynamo

• Udostępnianie społeczności dodatku Dynamo biblioteki C# jako węzłów w pakiecie

Węzły pochodne od klasy NodeModel

Te węzły są osadzone nieco głębiej w strukturze dodatku Dynamo. Są one oparte na klasie NodeModel i napisane w języku C#. Mimo że ta metoda zapewnia największą elastyczność i największe możliwości, wymaga jednak wyraźnego zdefiniowania większości aspektów węzła i umieszczenia funkcji w osobnym zespole.

Co można zrobić za pomocą tej metody:

• Tworzenie w pełni konfigurowalnego interfejsu użytkownika węzła z suwakami, obrazami, kolorem itp. (np. węzeł ColorRange)

• Uzyskiwanie dostępu do informacji o tym, co się dzieje w obszarze rysunku dodatku Dynamo, i wpływanie na to

• Dostosowywanie skratowania

• Wczytywanie do dodatku Dynamo w postaci pakietu

Omówienie obsługi wersji dodatku Dynamo i zmian w interfejsie API (z wersji 1.x do wersji 2.x)

Ponieważ dodatek Dynamo jest regularnie aktualizowany, w części interfejsu API używanej przez pakiet mogą być wprowadzane zmiany. Śledzenie tych zmian jest ważne na potrzeby zapewnienia dalszego poprawnego działania istniejących pakietów.

Uprawnienia do dystrybucji plików binarnych w pakiecie

Należy nadzorować pliki .dll zawarte w pakiecie przekazywanym do Menedżera pakietów. Jeśli autor pakietu nie utworzył danego pliku .dll, musi mieć uprawnienia do jego udostępniania.

Jeśli pakiet zawiera pliki binarne, użytkownicy muszą być monitowani podczas pobierania z informacją o tym, że pakiet zawiera pliki binarne.

Wykonywanie skryptów w języku Python w węzłach Zero-Touch (C#)

Jeśli użytkownik potrafi pisać skrypty w języku Python i chce uzupełnić węzły standardowe dodatku w języku Python Dynamo o więcej funkcji, może utworzyć własny za pomocą funkcji Zero-Touch. Zacznijmy od prostego przykładu umożliwiającego przekazanie skryptu w języku Python jako ciągu do węzła Zero-Touch, w którym wykonywany jest skrypt i zwracany jest wynik. Ta analiza przypadku jest oparta na przewodnikach i przykładach z sekcji „Pierwsze kroki”. Użytkownicy dopiero zaczynający tworzenie węzłów Zero-Touch powinni się z nimi zapoznać.

Węzeł Zero-Touch wykonujący ciąg skryptu w języku Python

Silnik języka Python

Ten węzeł bazuje na wystąpieniu silnika skryptów IronPython. Aby to obsłużyć, należy utworzyć odwołanie do kilku dodatkowych zespołów. Wykonaj poniższe czynności, aby skonfigurować szablon podstawowy w programie Visual Studio:

• Tworzenie nowego projektu klasy programu Visual Studio

• Dodaj odwołanie do pliku IronPython.dll znajdującego się tutaj: C:\Program Files (x86)\IronPython 2.7\IronPython.dll

• Dodaj odwołanie do pliku Microsoft.Scripting.dll znajdującego się tutaj: C:\Program Files (x86)\IronPython 2.7\Platforms\Net40\Microsoft.Scripting.dll

• Dołącz do tej klasy instrukcje IronPython.Hosting i Microsoft.Scripting.Hosting using

• Dodaj pusty konstruktor prywatny, aby zapobiec dodaniu dodatkowego węzła do biblioteki Dynamo wraz z pakietem

• Utwórz nową metodę, która przyjmuje pojedynczy ciąg jako parametr wejściowy

• W ramach tej metody utworzymy wystąpienie nowego silnika języka Python i utworzymy pusty zakres skryptu. Ten zakres można sobie wyobrazić jako zmienne globalne w wystąpieniu interpretera języka Python

• Następnie wywołaj operację Execute dla silnika, przekazując ciąg wejściowy i zakres jako parametry

• Na koniec pobierz i zwróć wyniki skryptu, wywołując operację GetVariable dla zakresu i przekazując nazwę zmiennej ze skryptu w języku Python zawierającą wartość, którą próbujesz zwrócić. (Więcej informacji znajduje się w poniższym przykładzie)

Poniższy kod stanowi przykład kroku opisanego powyżej. Skompilowanie rozwiązania spowoduje utworzenie nowego pliku .dll znajdującego się w folderze bin projektu. Ten plik .dll można teraz zaimportować do dodatku Dynamo jako część pakietu lub przechodząc do polecenia File < Import Library...

Wiele pozycji danych wyjściowych

Jednym z ograniczeń standardowych węzłów języka Python jest to, że mają one tylko jeden port wyjściowy. Jeśli więc chcemy zwrócić wiele obiektów, musimy utworzyć listę i umieścić na niej poszczególne obiekty. Jeśli zmodyfikujemy powyższy przykład tak, aby zwracał słownik, możemy dodać dowolną liczbę portów wyjściowych. Więcej informacji na temat słowników znajduje się w temacie „Dalsze kroki z Zero-Touch” w sekcji dotyczącej zwracania wielu wartości.

Ten węzeł umożliwia zwrócenie zarówno objętości prostopadłościanu, jak i jego centroidy.

Zmodyfikujmy poprzedni przykład, wykonując następujące czynności:

• Dodaj odwołanie do pliku DynamoServices.dll z Menedżera pakietów NuGet

• Oprócz poprzednich zespołów dołącz zespoły System.Collections.Generic i Autodesk.DesignScript.Runtime

• Zmień typ zwracany w metodzie, aby zwracać słownik, który będzie zawierał dane wyjściowe

• Każda pozycja wyjściowa musi zostać osobno pobrana z zakresu (dla większych zestawów danych wyjściowych rozważ skonfigurowanie prostej pętli)

Do tego przykładowego skryptu w języku Python dodaliśmy również dodatkową zmienną wyjściową (output2). Należy pamiętać, że te zmienne mogą używać dowolnych konwencji nazewnictwa języka Python, dlatego określenia „output” (dane wyjściowe) użyto wyłącznie w celu zachowania przejrzystości w tym przykładzie.

Jeśli szukasz przykładów ułatwiających programowanie rozwiązań dla dodatku Dynamo, zapoznaj się z poniższymi zasobami:

Repozytoria przykładowe

Te przykładowe szablony programu Visual Studio umożliwiają rozpoczęcie własnego projektu:

• ZeroTouchEssentials: szablon podstawowych węzłów ZeroTouch.

  • Zwracanie wielu pozycji danych wyjściowych: kod

  • Używanie natywnego obiektu geometrii z dodatku Dynamo: kod

  • Przykładowa właściwość (węzeł zapytania): kod

• HelloDynamo: szablony podstawowych węzłów NodeModel i dostosowywanie widoku.

  • Podstawowy szablon NodeModel: HelloNodeModel.cs

    • Definiowanie atrybutów węzłów (nazw danych wejściowych/wyjściowych, opisów, typów): kod

    • Zwracanie węzła null, jeśli nie ma danych wejściowych: kod

    • Tworzenie wywołania funkcji: kod

  • Podstawowy szablon dostosowywania widoku NodeModel: HelloGui.cs, HelloGuiNodeView.cs, Slider.xaml, Slider.xaml.cs

    • Wysyłanie do interfejsu użytkownika alertów o tyn, że element wymaga aktualizacji: kod

    • Dostosowywanie klasy NodeModel: kod

    • Definiowanie atrybutów suwaka: kod

    • Określanie logiki interakcji dla suwaka: kod

• DynamoSamples: szablony dla rozwiązań ZeroTouch, niestandardowy interfejs użytkownika, testy i rozszerzenia widoku.

  • Przykłady interfejsu użytkownika

    • Tworzenie podstawowego niestandardowego węzła interfejsu użytkownika: CustomNodeModel.cs

    • Tworzenie menu rozwijanego: DropDown.cs

  • Testy

    • Testy systemu: HelloDynamoSystemTests.cs

    • Testy ZeroTouch: HelloDynamoZeroTouchTests.cs

  • Przykłady ZeroTouch:

    • Przykładowe węzły ZeroTouch, w tym węzły, w których zaimplementowano interfejs IGraphicItem w celu wpływania na renderowanie geometrii: BasicExample.cs

    • Przykładowe węzły ZeroTouch do kolorowania geometrii z użyciem interfejsu IRenderPackage: ColorExample.cs

  • Przykładowe rozszerzenia widoku: implementacja interfejsu IViewExtension powodująca wyświetlenie okna niemodalnego po kliknięciu jej elementu MenuItem.

• NodeModelsEssentials: szablony do zaawansowanego opracowywania pakietów dodatku Dynamo za pomocą klasy NodeModel.

  • Przykłady podstawowe:

    • Error

    • MultiOperation

    • Multiply

    • Timeout

  • Przykłady geometrii:

    • CustomPreview

    • SurfaceFrom4Points

    • UVPlanesOnSurface

    • WobblySurface

  • Przykłady interfejsu użytkownika:

    • Button

    • ButtonFunction

    • CopyableWatch

    • Slider

    • SliderBound

    • State

DynaText: biblioteka ZeroTouch umożliwiająca tworzenie tekstu w dodatku Dynamo.

Analizy przypadków

Programiści zewnętrzni znacząco i bardzo pozytywnie przyczynili się do rozwoju tej platformy, a wiele z ich prac jest dostępnych na licencji open source. Poniższe projekty to wyjątkowe przykłady możliwości pracy z dodatkiem Dynamo.

Ladybug to biblioteka języka Python umożliwiająca wczytywanie, analizowanie i modyfikowanie plików meteorologicznych EnergyPlus (epw).

https://github.com/ladybug-tools/ladybug

Honeybee to biblioteka języka Python umożliwiająca tworzenie, uruchamianie i wizualizowanie wyników analizy światła dziennego (RADIANCE) i analizy energetycznej (EnergyPlus/OpenStudio).

https://github.com/ladybug-tools/honeybee

Bumblebee to wtyczka umożliwiająca współdziałanie programów Excel i Dynamo (GPL).

https://github.com/ksobon/Bumblebee

Clockwork to kolekcja węzłów niestandardowych do obsługi czynności związanych z programem Revit oraz do innych celów, takich jak zarządzanie listami, operacje matematyczne, operacje na ciągach, operacje geometryczne (dotyczące głównie ramek ograniczających, siatek, płaszczyzn, punktów, powierzchni, UV i wektorów) oraz panelowanie.

https://github.com/andydandy74/ClockworkForDynamo

Platforma Dynamo polega na kreatywności i zaangażowaniu społeczności, więc zespół dodatku Dynamo zachęca współtwórców do badania możliwości, testowania pomysłów i zbierania opinii w społeczności. Mimo że zachęcamy do tworzenia innowacji, zmiany zostaną scalone tylko w przypadku, gdy ułatwiają korzystanie z dodatku Dynamo i spełniają wytyczne zdefiniowane w tym dokumencie. Zmiany zapewniające jedynie niewielkie korzyści nie zostaną scalone.

Oczekiwania dotyczące próśb o ściągnięcie (pull)

Zespół dodatku Dynamo oczekuje, że prośby o ściągnięcie (pull) będą zgodne z następującymi wskazówkami:

• Przestrzegaj naszych standardów kodowania i standardów nazewnictwa węzłów.

• Uwzględnij testy jednostkowe podczas dodawania nowych funkcji.

• Podczas naprawiania błędu dodaj test jednostkowy wskazujący, że bieżące zachowanie jest niewłaściwe.

• Skoncentruj się na jednym problemie. Jeśli pojawi się nowe lub powiązane zagadnienie, utwórz nowy problem.

Oto kilka wskazówek dotyczących tego, czego nie należy robić:

• Zaskakiwanie nas, prośbami o ściągnięcie (pull) zmian o dużych rozmiarach. Zamiast tego należy zgłosić problem i rozpocząć dyskusję, aby można było uzgodnić kierunek prac przed zainwestowaniem dużej ilości czasu.

• Zatwierdzanie (commit) kodu, którego nie napisano samodzielnie. W przypadku znalezienia kodu, który warto byłoby dodać do dodatku Dynamo, przed kontynuowaniem należy zgłosić problem i rozpocząć dyskusję.

• Przesyłanie próśb o ściągnięcie (pull), które zmieniają nagłówki lub pliki związane z licencjami. Jeśli uważasz, że jest z nimi jakiś problem, zgłoś to, a chętnie to omówimy.

• Dodawanie elementów w interfejsie API bez zgłaszania problemu i omówienia tego z nami.

Wypełnianie szablonu prośby o ściągnięcie (pull)

W przypadku przesyłania prośby o ściągnięcie (pull) należy użyć domyślnego szablonu prośby o ściągnięcie. Przed przesłaniem prośby o ściągnięcie (pull) należy się upewnić, że cel został jasno opisany i wszystkie poniższe stwierdzenia można uznać za prawdziwe:

• Po przesłaniu tej prośby o ściągnięcie (pull) baza kodu będzie w lepszym stanie

• Rozwiązanie udokumentowano zgodnie ze standardami

• Poziom przetestowania rozwiązania, którego dotyczy ta prośba o ściągnięcie (pull), jest odpowiedni

• Jeśli istnieją ciągi widoczne dla użytkownika, są one wyodrębnione do plików *.resx

• Wszystkie testy zostały zakończone pomyślnie z wykorzystaniem samoobsługowej ciągłej integracji

• Migawka zmian interfejsu użytkownika, jeśli takie zmiany istnieją

• Zmiany w interfejsie API są zgodne z semantyczną obsługą wersji i są opisane w dokumencie zmian w interfejsie API.

Zespół Dynamo przypisze do prośby o ściągnięcie (pull) odpowiedniego recenzenta.

Proces weryfikacji prośby o ściągnięcie (pull)

Po przesłaniu prośby o ściągnięcie (pull) może być konieczne dalsze zaangażowanie w proces weryfikacji. Należy pamiętać o następujących kryteriach przeglądu:

• Zespół dodatku Dynamo spotyka się raz w miesiącu, aby przejrzeć prośby o ściągnięcie (pull), od najstarszych do najnowszych.

• Jeśli w przypadku przejrzanej prośby o ściągnięcie (pull) wymagane jest wprowadzenie zmian przez jej właściciela, ten właściciel ma 30 dni na odpowiedź. Jeśli dla danej prośby o ściągnięcie (pull) nie będzie żadnej aktywności do następnej sesji, zostanie ona zamknięta przez zespół lub w zależności od jej przydatności zostanie przejęta przez kogoś z zespołu.

• Do przesyłania próśb o ściągnięcie (pull) należy używać domyślnego szablonu prośby o ściągnięcie dodatku Dynamo.

• Prośby o ściągnięcie (pull), dla których nie wypełniono całkowicie szablonów próśb o ściągnięcie dodatku Dynamo z podaniem wszystkich deklaracji, nie zostaną przejrzane.

Wybieranie zatwierdzeń dodatku Dynamo Revit

Ponieważ na rynku dostępnych jest wiele wersji programu Revit, może być konieczne wprowadzenie zmian w określonych gałęziach wersji dodatku DynamoRevit, tak aby różne wersje programu Revit mogły korzystać z nowych funkcji. Podczas procesu przeglądu współtwórcy odpowiadają za wybranie ich zweryfikowanych zatwierdzeń (commit) w innych gałęziach dodatku DynamoRevit zgodnie z wytycznymi zespołu Dynamo.

Rozszerzenia jako pakiety

Omówienie

Rozszerzenia dodatku Dynamo można wdrażać w Menedżerze pakietów, tak jak zwykłe biblioteki węzłów dodatku Dynamo. Jeśli zainstalowany pakiet zawiera rozszerzenie widoku, jest ono wczytywane podczas wykonywania wraz z wczytaniem dodatku Dynamo. Aby upewnić się, że rozszerzenie zostało poprawnie wczytane, można sprawdzić konsolę dodatku Dynamo.

Struktura pakietu

Struktura pakietu rozszerzenia jest taka sama jak zwykłego pakietu i zawiera:

C:\Users\User\AppData\Roaming\Dynamo\Dynamo Core\2.1\packages\Sample View Extension
│   pkg.json
├───bin
│       SampleViewExtension.dll
├───dyf
└───extra
        SampleViewExtension_ViewExtensionDefinition.xml

Przy założeniu, że już skompilowano rozszerzenie, będzie istnieć (co najmniej) zespół .NET i plik manifestu. Zespół powinien zawierać klasę z zaimplementowanym interfejsem IViewExtension lub IExtension. Plik manifestu .XML informuje dodatek Dynamo, wystąpienie której klasy ma utworzyć w celu uruchomienia rozszerzenia. Aby Menedżer pakietów poprawnie zlokalizował rozszerzenie, plik manifestu powinien być w pełni zgodny z położeniem zespołu i nazewnictwem.

Umieść wszystkie pliki zespołu w folderze bin, a pliki manifestu w folderze extra. W tym folderze można również umieścić wszelkie dodatkowe zasoby.

Przykładowy plik manifestu .XML:

<ViewExtensionDefinition>
  <AssemblyPath>..\bin\MyViewExtension.dll</AssemblyPath>
  <TypeName>MyViewExtension.MyViewExtension</TypeName>
</ViewExtensionDefinition>

Przekazywanie

Po utworzeniu folderu zawierającego podkatalogi opisane powyżej wszystko jest gotowe do wysłania (przekazania) do Menedżera pakietów. Należy jednak pamiętać, że obecnie nie można publikować pakietów z trybu Dynamo Sandbox. Oznacza to, że należy używać dodatku Dynamo Revit. W dodatku Revit Dynamo przejdź do opcji Packages (Pakiety) => Publish New Package (Publikuj nowy pakiet). Spowoduje to wyświetlenie monitu o zalogowanie się na koncie Autodesk, z którym ma zostać skojarzony pakiet.

W tym momencie powinno być wyświetlone normalne okno publikowania pakietu, w którym należy wypełnić wszystkie wymagane pola dotyczące pakietu/rozszerzenia. Bardzo ważną dodatkową czynnością jest upewnienie się, że żaden plik zespołu nie jest oznaczony jako biblioteka węzłów. W tym celu kliknij prawym przyciskiem myszy zaimportowane pliki (folder pakietu utworzony powyżej). Zostanie wyświetlone menu kontekstowe, które umożliwia zaznaczenie (lub cofnięcie zaznaczenia) tej opcji. Żadne zespoły rozszerzenia nie powinny być zaznaczone.

Przed opublikowaniem publicznie należy zawsze opublikować lokalnie, aby upewnić się, że wszystko działa zgodnie z oczekiwaniami. Gdy to zostanie już sprawdzone, możesz wysłać pakiet w świat, wybierając opcję publikowania.

Ściąganie (pull)

Aby upewnić się, że pakiet został pomyślnie przekazany, potwierdź, że możesz wyszukać go na podstawie nazw i słów kluczowych określonych w kroku publikowania. Na koniec należy pamiętać, że do działania niektórych rozszerzeń wymagane jest ponowne uruchomienie dodatku Dynamo. Zazwyczaj te rozszerzenia wymagają określenia parametrów podczas uruchamiania dodatku Dynamo.

Pliki źródłowe dodatku DynamoRevit są również przechowywane w witrynie DynamoDS w serwisie GitHub dla programistów, którzy mogą współtworzyć dodatek i kompilować wersje beta. Kompilowanie dodatku DynamoRevit ze źródła zazwyczaj przebiega tak samo jak w przypadku dodatku Dynamo, z wyjątkiem kilku ważnych szczegółów:

• Dodatek DynamoRevit odwołuje się do zespołów dodatku Dynamo, dlatego należy go utworzyć za pomocą zgodnych pakietów NuGet. Na przykład dodatek DynamoRevit 2.x nie zostanie wczytany do dodatku Dynamo 1.3.

• Dodatek DynamoRevit jest powiązany z konkretną wersją programu Revit, na przykład: gałąź dodatku DynamoRevit 2018 powinna być uruchamiana w programie Revit 2018.

W tym podręczniku używamy następujących składników:

• Revit 2023

• Najnowsza kompilacja dodatku DynamoRevit w gałęzi Revit2023

• Najnowsza kompilacja dodatku Dynamo

Aby zapewnić pomyślną kompilację, sklonujemy i skompilujemy repozytoria dodatku Dynamo i dodatku DynamoRevit, które będą używane w tym przewodniku.

Uwaga: ręczne skompilowanie dodatku Dynamo przed rozpoczęciem kompilowania dodatku DynamoRevit jest wymagane tylko w przypadku kompilowania dodatków Dynamo 1.x i DynamoRevit 1.x — nowsze wersje repozytorium DynamoRevit używają Menedżera pakietów NuGet do obsługi zależności dodatku Dynamo wymaganych do skompilowania. Mimo że skompilowanie dodatku DynamoRevit 2.x nie wymaga ręcznego ściągnięcia (pull) dodatku Dynamo, nadal są potrzebne podstawowe biblioteki (dlls) w innym miejscu, aby faktycznie uruchomić składnik addin dodatku DynamoRevit — warto więc jednak ściągnąć i skompilować dodatek Dynamo. Zobacz więcej poniżej: Kompilowanie repozytorium za pomocą programu Visual Studio

Znajdowanie repozytorium DynamoRevit w serwisie Github

Kod projektu DynamoRevit znajduje się w serwisie Github w repozytorium oddzielnym od podstawowego kodu źródłowego dodatku Dynamo. To repozytorium zawiera pliki źródłowe dla węzłów charakterystycznych dla programu Revit i dodatek programu Revit, który wczytuje dodatek Dynamo. Kompilacje dodatku DynamoRevit dla różnych wersji programu Revit (na przykład 2016, 2017 lub 2018) są zorganizowane jako gałęzie w repozytorium.

Źródło dodatku DynamoRevit znajduje się tutaj: https://github.com/DynamoDS/DynamoRevit

1. Klonowanie lub pobieranie repozytorium

2. Gałęzie dodatku DynamoRevit odnoszą się do wersji programu Revit

Klonowanie repozytorium przy użyciu narzędzia git

W procesie podobnym do ściągania (pull) repozytorium dodatku Dynamo użyjemy polecenia git clone, aby sklonować dodatek DynamoRevit i określić gałąź, która odpowiada używanej wersji programu Revit. Aby rozpocząć, otworzymy interfejs wiersza polecenia i ustawimy jako bieżący katalog, do którego mają zostać sklonowane pliki.

Polecenie cd C:\Users\username\Documents\GitHub zmienia katalog bieżący

Zastąp ciąg username swoją nazwą użytkownika

Teraz możemy sklonować repozytorium do tego katalogu. Mimo że musimy określić gałąź repozytorium, po sklonowaniu możemy przejść do tej gałęzi.

Polecenie git clone https://github.com/DynamoDS/DynamoRevit.git klonuje repozytorium ze zdalnego adresu URL i domyślnie przełącza do głównej gałęzi.

Po zakończeniu klonowania repozytorium zmień katalog bieżący na folder repozytorium i przełącz na gałąź odpowiadającą zainstalowanej wersji programu Revit. W tym przykładzie używamy programu Revit RC2.13.1_Revit2023. Wszystkie gałęzie zdalne można wyświetlić na stronie serwisu Github w menu rozwijanym Branch (Gałąź).

Polecenie cd C:\Users\username\Documents\GitHub\DynamoRevit zmienia katalog na DynamoRevit. Polecenie git checkout RC2.13.1_Revit2023 ustawia bieżącą gałąź RC2.13.1_Revit2023. Polecenie git branch sprawdza, w której gałęzi pracujemy, i wyświetla inne istniejące lokalnie.

Gałąź z gwiazdką jest obecnie wyrejestrowana. Wyświetlana jest gałąź Revit2018, ponieważ wcześniej ją wyrejestrowano, więc istnieje ona lokalnie.

Ważne jest wybranie właściwej gałęzi repozytorium, aby zapewnić, że podczas kompilowania projektu w programie Visual Studio będzie on odwoływał się do zespołów we właściwej wersji katalogu instalacyjnego programu Revit, w szczególności do plików RevitAPI.dll i RevitAPIUI.dll.

Kompilowanie repozytorium za pomocą programu Visual Studio

Przed skompilowaniem repozytorium musimy przywrócić pakiety NuGet za pomocą pliku restorepackages.bat znajdującego się w folderze src. Ten plik bat wykorzystuje Menedżera pakietów nuget do ściągnięcia (pull) skompilowanych plików binarnych podstawowych elementów dodatku Dynamo wymaganych przez dodatek DynamoRevit. Można również zdecydować się na skompilowanie ich ręcznie, ale tylko w przypadku wprowadzania zmian w dodatku DynamoRevit, a nie w elementach podstawowych dodatku Dynamo. Dzięki temu można szybciej rozpocząć pracę. Ten plik należy uruchomić z uprawnieniami administratora.

1. Kliknij prawym przyciskiem myszy plik restorepackages.bat i wybierz polecenie Run as administrator

Jeśli pakiety zostaną pomyślnie przywrócone, do folderu src zostanie dodany folder packages z najnowszymi pakietami beta NuGet.

1. Najnowsze pakiety NuGet dodatku Dynamo w wersji beta

Po przywróceniu pakietów otwórz plik rozwiązania programu Visual Studio DynamoRevit.All.sln w folderze src i skompiluj rozwiązanie. Kompilacja może początkowo mieć problemy ze znalezieniem pliku AssemblySharedInfo.cs. W takim przypadku ponowne uruchomienie kompilacji rozwiąże ten problem.

1. Wybierz opcję Build > Build Solution

2. Sprawdź, czy kompilacja została zakończona pomyślnie w oknie danych wyjściowych. Komunikat powinien wyglądać tak: ===== Build: 13 succeeded, 0 failed, 0 up-to-date, 0 skipped =====.

Uruchamianie kompilacji lokalnej dodatku DynamoRevit w programie Revit

Program Revit wymaga pliku dodatku w celu rozpoznania dodatku DynamoRevit. Instalator tworzy go automatycznie. W trakcie opracowywania musimy ręcznie utworzyć plik dodatku, który wskazuje kompilację dodatku DynamoRevit, której chcemy użyć, a konkretnie zespół DynamoRevitDS.dll. Musimy również wskazać dodatkowi DynamoRevit kompilację dodatku Dynamo.

Utwórz plik Dynamo.addin w folderze dodatku programu Revit znajdującym się w katalogu C:\ProgramData\Autodesk\Revit\Addins\2023. Zainstalowano już wersję dodatku DynamoRevit, dlatego wystarczy edytować istniejący plik, aby wskazać nową kompilację.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>Dynamo For Revit</Name>
<Assembly>"C:\Users\username\Documents\GitHub\DynamoRevit\bin\AnyCPU\Debug\Revit\DynamoRevitDS.dll"</Assembly>
<AddInId>8D83C886-B739-4ACD-A9DB-1BC78F315B2B</AddInId>
<FullClassName>Dynamo.Applications.DynamoRevitApp</FullClassName>
<VendorId>ADSK</VendorId>
<VendorDescription>Dynamo</VendorDescription>
</AddIn>
</RevitAddIns>

• Określ ścieżkę pliku DynamoRevitDS.dll wewnątrz tagu <Assembly>...</Assembly>.

Ewentualnie można skonfigurować w dodatku wczytywanie selektora wersji zamiast określonego zespołu.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<RevitAddIns>
<AddIn Type="Application">
<Name>Dynamo For Revit</Name>
<Assembly>"C:\Users\username\Documents\GitHub\DynamoRevit\bin\AnyCPU\Debug\Revit\DynamoRevitVersionSelector.dll"</Assembly>
<AddInId>8D83C886-B739-4ACD-A9DB-1BC78F315B2B</AddInId>
<FullClassName>Dynamo.Applications.VersionLoader</FullClassName>
<VendorId>ADSK</VendorId>
<VendorDescription>Dynamo</VendorDescription>
</AddIn>
</RevitAddIns>

• Ustaw ścieżkę pliku w tagu <Assembly>...</Assembly> na DynamoRevitVersionSelector.dll

• Tag <FullClassName>...</FullClassName> określa klasę, której wystąpienie należy utworzyć na podstawie zespołu wskazanego za pomocą powyższej ścieżki elementu Assembly. Ta klasa będzie punktem wejścia dla dodatku.

Ponadto musimy usunąć istniejący dodatek Dynamo dostarczany z programem Revit. Aby to zrobić, przejdź do folderu C:\\Program Files\Autodesk\Revit 2023\AddIns i usuń dwa foldery zawierające dodatek Dynamo — DynamoForRevit i DynamoPlayerForRevit. Można je usunąć lub utworzyć ich kopię zapasową w oddzielnym folderze na wypadek późniejszej potrzeby odzyskania oryginalnego dodatku Dynamo dla programu Revit.

Drugim krokiem jest dodanie ścieżki pliku dla zespołów podstawowych dodatku Dynamo do pliku Dynamo.config w folderze bin dodatku DynamoRevit. Dodatek DynamoRevit wczyta je po otwarciu go w programie Revit. Ten plik konfiguracji umożliwia wskazanie dodatkowi DynamoRevit różnych wersji dodatku Dynamo na potrzeby opracowywania i testowania zmian zarówno w dodatku podstawowym, jak i w dodatku DynamoRevit.

Kod powinien wyglądać następująco:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
     <add key="DynamoRuntime" value="C:\Users\username\Documents\GitHub\Dynamo\bin\AnyCPU\Debug"/>
  </appSettings>
</configuration>

• Dodaj ścieżkę katalogu folderu bin do części <add key/>

Tuż przed przystąpieniem do tego przewodnika sklonowaliśmy i skompilowaliśmy dodatek Dynamo, aby zapewnić jego sprawne współdziałanie z dodatkiem DynamoRevit. Ta ścieżka katalogu wskazuje tę kompilację.

Teraz po otwarciu programu Revit na karcie Zarządzaj powinien istnieć dodatek Dynamo.

1. Wybierz opcję Manage

2. Kliknij ikonę dodatku Dynamo

3. Wystąpienie dodatku DynamoRevit

Jeśli pojawia się okno dialogowe błędu brakujących zespołów, prawdopodobnie występuje niezgodność między wersjami dodatku DynamoCore, przy których wykonywano kompilację, a tymi, które są wczytywane w środowisku wykonywania. Na przykład dodatek DynamoRevit z najnowszymi pakietami beta w wersji 2.0 dodatku DynamoCore nie będzie działać w przypadku uruchomienia go za pomocą dodatku bibliotek dll dodatku Dynamo 1.3. Upewnij się, że oba repozytoria są w tej samej wersji, a dodatek DynamoRevit ściąga (pull) zgodną wersję zależności nuget. Są one zdefiniowane w pliku package.json repozytorium DynamoRevit.

Debugowanie dodatku DynamoRevit za pomocą programu Visual Studio

W poprzedniej sekcji, Kompilowanie dodatku Dynamo ze źródła, krótko omówiono debugowanie w programie Visual Studio i sposób dołączania programu Visual Studio do procesu. Używając wyjątku w węźle Wall.ByCurveAndHeight jako przykładu, omówimy sposób dołączania do procesu, ustawiania punktów przerwania, krokowe wykonywanie kodu i używania stosu wywołań w celu określenia źródła wyjątku. Te narzędzia debugowania mają ogólne zastosowanie do procesów roboczych opracowywania rozwiązań .net i warto zapoznać się z nimi w zakresie wykraczającym poza ten podręcznik.

• Dołączenie do procesu umożliwia połączenie uruchomionej aplikacji z programem Visual Studio w celu debugowania. Aby debugować zachowanie występujące w kompilacji dodatku DynamoRevit, można otworzyć pliki źródłowe dodatku DynamoRevit w programie Visual Studio i dołączyć proces Revit.exe, który jest procesem nadrzędnym dodatku DynamoRevit. Program Visual Studio używa pliku symboli (.pbd), aby utworzyć połączenie między zespołami wykonywanymi w dodatku DynamoRevit a kodem źródłowym.

• Punkty przerwania określają wiersze w kodzie źródłowym, w których działanie aplikacji zostanie wstrzymane przed dalszym wykonywaniem. Jeśli węzeł powoduje awarię dodatku DynamoRevit lub zwracanie przez niego nieoczekiwanego wyniku, można dodać do źródła węzła punkt przerwania, aby wstrzymać proces, przejść do kodu i sprawdzić wartości zmiennych na żywo aż do znalezienia źródła problemu.

• Krokowe wykonywanie kodu to przechodzenie przez źródło wiersz po wierszu. Możemy uruchamiać funkcje pojedynczo, wchodzić krokowo do wywołania funkcji lub wyskakiwać z aktualnie wykonywanej funkcji.

• Stos wywołań pokazuje funkcję obecnie uruchomioną w procesie w odniesieniu do poprzednich wywołań funkcji, które wywołały tę funkcję. W programie Visual Studio jest to wyświetlane w oknie stosu wywołań. Jeśli na przykład dojdziemy do wyjątku poza kodem źródłowym, pojawi się ścieżka do kodu wywołującego w stosie wywołań.

  „2,000 Things You Should Know About C#” (2000 rzeczy, które należy wiedzieć o języku C#): tu znajdziesz bardziej szczegółowe wyjaśnienie stosów wywołań

Węzeł Wall.ByCurveAndHeight zgłasza wyjątek po przekazaniu mu krzywej PolyCurve jako krzywej wejściowej (curve) i zwraca komunikat: „To BSPlineCurve Not Implemented” (Nie zaimplementowano do BSPlineCurve). Podczas debugowania możemy ustalić, dlaczego dokładnie węzeł nie akceptuje tego typu geometrii jako danych wejściowych dla parametru krzywej (curve). W tym przykładzie założono, że dodatek DynamoRevit pomyślnie skompilowano i można go uruchomić jako dodatek dla programu Revit.

1. Węzeł Wall.ByCurveAndHeight zgłasza wyjątek

Rozpocznij od otwarcia pliku rozwiązania DynamoRevit.All.sln, uruchom program Revit i uruchom dodatek DynamoRevit. Następnie dołącz program Visual Studio do procesu programu Revit za pomocą okna Attach to Process.

Program Revit i dodatek DynamoRevit muszą być uruchomione, aby były widoczne jako dostępne procesy

1. Otwórz okno Attach to Process, wybierając opcję Debug > Attach to Process...

2. Ustaw opcję Transport na wartość Default

3. Wybierz opcję Revit.exe

4. Wybierz opcję Attach

Po dołączeniu programu Visual Studio do programu Revit otwórz kod źródłowy węzła Wall.ByCurveAndHeight w pliku Wall.cs. Tę zawartość można znaleźć w Eksploratorze rozwiązań w części Libraries > RevitNodes > Elements w obszarze Public static constructors pliku. Ustaw punkt przerwania w konstruktorze typu wall, tak aby po uruchomieniu węzła w dodatku Dynamo proces został przerwany i można było krokowo wykonać poszczególne wiersze kodu. Nazwy konstruktorów typów Zero-Touch dodatku Dynamo zazwyczaj zaczynają się od By<parameters>.

1. Plik klasy z konstruktorem dla węzła Wall.ByCurveAndHeight

2. Ustaw punkt przerwania, klikając po lewej stronie numeru wiersza lub klikając prawym przyciskiem myszy wiersz kodu i wybierając polecenie Breakpoint > Insert Breakpoint.

Po ustawieniu punktu przerwania należy zadbać o to, aby proces przebiegł przez funkcję Wall.ByCurveAndHeight. Funkcję można ponownie wykonać w dodatku Dynamo, ponownie łącząc przewód do jednego z portów węzła, co spowoduje ponowne uruchomienie tego węzła. W programie Visual Studio zostanie wyzwolony punkt przerwania.

1. Ikona punktu przerwania zmienia się po jego wyzwoleniu

2. Okno stosu wywołań z następną metodą

Teraz krokowo wykonuj poszczególne wiersze w konstruktorze, aż zostanie zwrócony wyjątek. Kod wyróżniony na żółto to następna instrukcja do uruchomienia.

1. Narzędzia do debugowania do nawigowania po kodzie

2. Naciśnij opcję Step Over, aby uruchomić wyróżniony kod, a następnie wstrzymać wykonywanie po zwróceniu przez funkcję wyniku

3. Następna instrukcja do uruchomienia oznaczona żółtym wyróżnieniem i strzałką

Jeśli będziemy kontynuować wykonywanie krokowe, w końcu zostanie zwrócony wyjątek, który pojawił się wcześniej w oknie dodatku DynamoRevit. W oknie stosu wywołań widać, że wyjątek został pierwotnie zwrócony z metody o nazwie Autodesk.Revit.CurveAPIUtils.CreateNurbsCurve. Na szczęście wyjątek jest tutaj obsługiwany, więc dodatek Dynamo nie uległ awarii. Proces debugowania zapewnił kontekst dla problemu, przenosząc nas do innej metody w kodzie źródłowym.

Ponieważ nie jest to biblioteka open source, nie możemy tam wprowadzać zmian. Mamy teraz więcej informacji, więc możemy zgłosić problem z szerszym kontekstem, zgłaszając problem w serwisie GitHub, lub zaproponować obejście tego problemu, wysyłając prośbę o ściągnięcie (pull).

1. Po dotarciu do instrukcji powodującej wyjątek w pliku Walls.cs proces debugowania maksymalnie przybliża nas do problemu źródłowego w kodzie użytkownika w pliku ProtoToRevitCurve.cs.

2. Instrukcja powodująca wyjątek w pliku ProtoToRevitCurve.cs

3. W oknie stosu wywołań widać, że wyjątek pochodzi z kodu innego niż kod użytkownika

4. Okno podręczne z informacjami o wyjątku

Ten proces można zastosować do wszystkich plików źródłowych, z którymi pracujemy. W przypadku tworzenia biblioteki węzłów Zero-Touch dla programu Dynamo Studio można otworzyć źródło biblioteki i dołączyć proces dodatku Dynamo w celu debugowania tej biblioteki węzłów. Nawet jeśli wszystko działa doskonale, debugowanie to doskonały sposób na przeglądanie kodu i analizowanie jego działania.

Ściąganie (pull) najnowszej kompilacji

Proces ten jest niemal identyczny jak w przypadku ściągania (pull) zmian dla dodatku Dynamo, ale należy upewnić się, że jest używana właściwa gałąź. Użyj polecenia git branch w repozytorium DynamoRevit, aby sprawdzić, które gałęzie są dostępne lokalnie i które są obecnie wyrejestrowane.

Polecenie cd C:\Users\username\Documents\GitHub\DynamoRevit ustawia repozytorium DynamoRevit jako katalog bieżący. Polecenie git branch sprawdza, czy używana jest właściwa gałąź, czyli RC2.13.1_Revit2023. Polecenie git pull origin RC2.13.1_Revit2023 ściąga zmiany z gałęzi RC2.13.1_Revit2023 zdalnej wersji oryginalnej.

Wersja oryginalna wskazuje po prostu adres URL sklonowanej wersji oryginalnej.

Najlepiej jest pilnować tego, która gałąź jest używana i z której jest ściągana (pull) zawartość, aby na przykład uniknąć ściągnięcia zmian z gałęzi RC2.13.1_Revit2023 do wersji Revit2018.

Jak wspomniano w temacie Kompilowanie dodatku Dynamo ze źródła, gdy wszystko będzie gotowe do przesłania zmiany do repozytorium DynamoRevit, można utworzyć prośbę o ściągnięcie zgodnie z wytycznymi zespołu dodatku Dynamo podanymi w sekcji „Prośby o ściągnięcie (pull)”.

Węzły oparte na klasie NodeModel zapewniają znacznie większą elastyczność i możliwości niż węzły Zero-Touch. W tym przykładzie przeniesiemy węzeł siatki Zero-Touch na następny poziom, dodając zintegrowany suwak losowo ustawiający rozmiar prostokąta.

Ten suwak umożliwia skalowanie komórek względem ich rozmiaru, dzięki czemu użytkownik nie musi udostępniać suwaka z odpowiednim zakresem.

Wzorzec Model-View-Viewmodel

Dodatek Dynamo jest oparty na wzorcu architektury oprogramowania model-view-viewmodel (MVVM), który umożliwia oddzielenie interfejsu użytkownika od zaplecza. W przypadku tworzenia węzłów ZeroTouch dodatek Dynamo tworzy powiązanie danych między danymi węzła a jego interfejsem użytkownika. Aby utworzyć niestandardowy interfejs użytkownika, należy dodać logikę powiązania danych.

Ogólnie istnieją dwie części ustanawiania relacji model-widok (model-view) w dodatku Dynamo:

• Klasa NodeModel ustanawiająca podstawową logikę węzła („model”)

• Klasa INodeViewCustomization umożliwiająca dostosowanie sposobu wyświetlania modelu NodeModel („widok”, ang. „view”)

Obiekty NodeModel mają już skojarzoną relację widok-model (NodeViewModel), więc można skupić się na modelu i widoku dla niestandardowego interfejsu użytkownika.

Jak zaimplementować klasę NodeModel

W tym przykładzie omówimy kilka istotnych różnic między węzłami NodeModel a węzłami Zero-Touch. Zanim przejdziemy do dostosowywania interfejsu użytkownika, rozwińmy logikę klasy NodeModel.

1. Tworzenie struktury projektu:

Węzeł NodeModel może tylko wywoływać funkcje, dlatego należy rozdzielić węzeł NodeModel i funkcje między różnymi bibliotekami. Standardowym sposobem realizacji tego w przypadku pakietów dodatku Dynamo jest utworzenie oddzielnych projektów dla obu tych typów zawartości. Zacznij od utworzenia nowego rozwiązania obejmującego te projekty.

1. Wybierz opcję File > New > Project

2. Wybierz opcję Other Project Types, aby wywołać opcję rozwiązania

3. Wybierz opcję Blank Solution

4. Nadaj rozwiązaniu nazwę CustomNodeModel

5. Wybierz przycisk Ok

Utwórz w rozwiązaniu dwa projekty biblioteki klas C#: jeden dla funkcji, a drugi dla interfejsu NodeModel.

1. Kliknij prawym przyciskiem myszy rozwiązanie i wybierz pozycję Add > New Project

2. Wybierz bibliotekę klas

3. Nadaj jej nazwę CustomNodeModel

4. Kliknij przycisk Ok

5. Powtórz ten proces, aby dodać kolejny projekt o nazwie CustomNodeModelFunctions

Następnie należy zmienić nazwy automatycznie utworzonych bibliotek klas i dodać je do projektu CustomNodeModel. Klasa GridNodeModel służy do zaimplementowania klasy abstrakcyjnej NodeModel, a GridNodeView do dostosowania widoku. Natomiast klasa GridFunction ma zawierać wszystkie funkcje, które będą wywoływane.

1. Dodaj kolejną klasę, klikając prawym przyciskiem myszy projekt CustomNodeModel, wybierając polecenie Add > New Item... i wybierając opcję Class.

2. W projekcie CustomNodeModel potrzebne są klasy GridNodeModel.cs i GridNodeView.cs

3. W projekcie CustomNodeModelFunction potrzebna jest klasa GridFunctions.cs

Przed dodaniem kodu do klas dodaj wymagane dla tego projektu pakiety. Projekt CustomNodeModel będzie wymagać bibliotek ZeroTouchLibrary i WpfUILibrary. Natomiast projekt CustomNodeModelFunction będzie wymagać tylko biblioteki ZeroTouchLibrary. Biblioteka WpfUILibrary zostanie użyta podczas dostosowywania interfejsu użytkownika, które wykonamy później, a biblioteka ZeroTouchLibrary — do tworzenia geometrii. Pakiety można dodawać dla projektów pojedynczo. Ponieważ te pakiety mają zależności, składniki Core i DynamoServices zostaną zainstalowane automatycznie.

1. Kliknij prawym przyciskiem myszy projekt i wybierz pozycję Manage NuGet Packages

2. Zainstaluj tylko wymagane pakiety dla tego projektu

Program Visual Studio skopiuje pakiety NuGet, do których dodaliśmy odwołania w katalogu kompilacji. Dla tej pozycji można ustawić wartość false (fałsz), aby w pakiecie nie było żadnych niepotrzebnych plików.

1. Wybierz pakiety NuGet dodatku Dynamo

2. Ustaw wartość false (fałsz) dla pozycji Copy Local

2. Dziedziczenie klasy NodeModel

Jak wspomniano wcześniej, główna różnica między węzłem NodeModel a węzłem ZeroTouch polega na tym, że ten pierwszy zawiera implementację klasy NodeModel. Węzeł NodeModel wymaga kilku funkcji z tej klasy, które można uzyskać, dodając po nazwie klasy :NodeModel.

Skopiuj następujący kod do pliku GridNodeModel.cs.

using System;
using System.Collections.Generic;
using Dynamo.Graph.Nodes;
using CustomNodeModel.CustomNodeModelFunction;
using ProtoCore.AST.AssociativeAST;
using Autodesk.DesignScript.Geometry;

namespace CustomNodeModel.CustomNodeModel
{
    [NodeName("RectangularGrid")]
    [NodeDescription("An example NodeModel node that creates a rectangular grid. The slider randomly scales the cells.")]
    [NodeCategory("CustomNodeModel")]
    [InPortNames("xCount", "yCount")]
    [InPortTypes("double", "double")]
    [InPortDescriptions("Number of cells in the X direction", "Number of cells in the Y direction")]
    [OutPortNames("Rectangles")]
    [OutPortTypes("Autodesk.DesignScript.Geometry.Rectangle[]")]
    [OutPortDescriptions("A list of rectangles")]
    [IsDesignScriptCompatible]
    public class GridNodeModel : NodeModel
    {
        private double _sliderValue;
        public double SliderValue
        {
            get { return _sliderValue; }
            set
            {
                _sliderValue = value;
                RaisePropertyChanged("SliderValue");
                OnNodeModified(false);
            }
        }
        public GridNodeModel()
        {
            RegisterAllPorts();
        }
        public override IEnumerable<AssociativeNode> BuildOutputAst(List<AssociativeNode> inputAstNodes)
        {
            if (!HasConnectedInput(0) || !HasConnectedInput(1))
            {
                return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), AstFactory.BuildNullNode()) };
            }
            var sliderValue = AstFactory.BuildDoubleNode(SliderValue);
            var functionCall =
              AstFactory.BuildFunctionCall(
                new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid),
                new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue });

            return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), functionCall) };
        }
    }
}

To różnica w stosunku do węzłów Zero-Touch. Przeanalizujmy funkcje poszczególnych części.

• Określ atrybuty węzła, takie jak nazwa, kategoria, nazwy portów wejściowych/wyjściowych, typy portów wejściowych/wyjściowych oraz opisy.

• public class GridNodeModel : NodeModel to klasa dziedzicząca klasę NodeModel z Dynamo.Graph.Nodes.

• public GridNodeModel() { RegisterAllPorts(); } to konstruktor rejestrujący dane wejściowe i wyjściowe węzła.

• BuildOutputAst() zwraca drzewo AST (Abstract Syntax Tree), strukturę wymaganą do zwracania danych z węzła NodeModel.

• metoda AstFactory.BuildFunctionCall() wywołuje funkcję RectangularGrid z pliku GridFunctions.cs.

• Instrukcja new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid) określa tę funkcję i jej parametry.

• Instrukcja new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue }); odwzorowuje dane wejściowe węzła na parametry funkcji

• Metoda AstFactory.BuildNullNode() tworzy węzeł o wartości null, jeśli porty wejściowe nie są połączone. Zapobiega to wyświetleniu ostrzeżenia dotyczącego tego węzła.

• Instrukcja RaisePropertyChanged("SliderValue") powiadamia interfejs użytkownika o zmianie wartości suwaka

• Instrukcja var sliderValue = AstFactory.BuildDoubleNode(SliderValue) tworzy węzeł AST reprezentujący wartość suwaka

• Zmień dane wejściowe na zmienną sliderValue w zmiennej functionCall new List<AssociativeNode> { inputAstNodes[0], sliderValue });

3. Wywoływanie funkcji

Projekt CustomNodeModelFunction zostanie skompilowany jako zespół oddzielny od projektu CustomNodeModel, dzięki czemu będzie można go wywołać.

Skopiuj następujący kod do pliku GridFunction.cs.

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

namespace CustomNodeModel.CustomNodeModelFunction
{
    [IsVisibleInDynamoLibrary(false)]
    public class GridFunction
    {
        [IsVisibleInDynamoLibrary(false)]
        public static List<Rectangle> RectangularGrid(int xCount = 10, int yCount = 10, double rand = 1)
        {
            double x = 0;
            double y = 0;

            Point pt = null;
            Vector vec = null;
            Plane bP = null;

            Random rnd = new Random(2);

            var pList = new List<Rectangle>();
            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    double rNum = rnd.NextDouble();
                    double scale = rNum * (1 - rand) + rand;
                    x++;
                    pt = Point.ByCoordinates(x, y);
                    vec = Vector.ZAxis();
                    bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, scale, scale);
                    pList.Add(rect);
                }
            }
            pt.Dispose();
            vec.Dispose();
            bP.Dispose();
            return pList;
        }
    }
}

Ta klasa funkcji jest bardzo podobna do tej z analizy przypadku siatki Zero-Touch z jedną różnicą:

• Instrukcja [IsVisibleInDynamoLibrary(false)] „ukrywa” przed dodatkiem Dynamo następującą metodę i klasę, ponieważ ta funkcja jest już wywoływana z projektu CustomNodeModel.

Tak jak dodaliśmy odwołania do pakietów NuGet, projekt CustomNodeModel musi odwoływać się do projektu CustomNodeModelFunction, aby wywołać funkcję.

Instrukcja using dla projektu CustomNodeModel będzie nieaktywna, dopóki nie będzie odwołania do tej funkcji

1. Kliknij prawym przyciskiem myszy pozycję CustomNodeModel i wybierz polecenie Add > Reference

2. Wybierz opcję Projects > Solution

3. Zaznacz pozycję CustomNodeModelFunction

4. Kliknij przycisk Ok

4. Dostosowywanie widoku

Aby utworzyć suwak, należy dostosować interfejs użytkownika przez zaimplementowanie interfejsu INodeViewCustomization.

Skopiuj następujący kod do pliku GridNodeView.cs

using Dynamo.Controls;
using Dynamo.Wpf;

namespace CustomNodeModel.CustomNodeModel
{
    public class CustomNodeModelView : INodeViewCustomization<GridNodeModel>
    {
        public void CustomizeView(GridNodeModel model, NodeView nodeView)
        {
            var slider = new Slider();
            nodeView.inputGrid.Children.Add(slider);
            slider.DataContext = model;
        }

        public void Dispose()
        {
        }
    }
}

• Instrukcja public class CustomNodeModelView : INodeViewCustomization<GridNodeModel> definiuje funkcje niezbędne do dostosowania interfejsu użytkownika.

Po skonfigurowaniu struktury projektu należy za pomocą środowiska projektowego programu Visual Studio utworzyć element sterujący użytkownika i zdefiniować jego parametry w pliku .xaml. Z pola przybornika dodaj suwak do części <Grid>...</Grid>.

1. Kliknij prawym przyciskiem myszy pozycję CustomNodeModel i wybierz polecenie Add > New Item

2. Wybierz opcję WPF

3. Nadaj elementowi sterującemu użytkownika nazwę Slider

4. Kliknij opcję Add

Skopiuj następujący kod do pliku Slider.xaml

<UserControl x:Class="CustomNodeModel.CustomNodeModel.Slider"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
             xmlns:local="clr-namespace:CustomNodeModel.CustomNodeModel"
             mc:Ignorable="d" 
             d:DesignHeight="75" d:DesignWidth="100">
    <Grid Margin="10">
        <Slider Grid.Row="0" Width="80" Minimum="0" Maximum="1" IsSnapToTickEnabled="True" TickFrequency="0.01" Value="{Binding SliderValue}"/>
    </Grid>
</UserControl>

• Parametry suwaka są zdefiniowane w pliku .xaml. Atrybuty Minimum i Maximum definiują zakres liczbowy tego suwaka.

• Wewnątrz tagów <Grid>...</Grid> można umieszczać różne elementy sterujące użytkownika z przybornika programu Visual Studio

Po utworzeniu pliku Slider.xaml program Visual Studio automatycznie utworzył plik z kodem C# o nazwie Slider.xaml.cs, który inicjuje suwak. Zmień przestrzeń nazw w tym pliku.

using System.Windows.Controls;

namespace CustomNodeModel.CustomNodeModel
{
    /// <summary>
    /// Interaction logic for Slider.xaml
    /// </summary>
    public partial class Slider : UserControl
    {
        public Slider()
        {
            InitializeComponent();
        }
    }
}

• Przestrzenią nazw powinna być CustomNodeModel.CustomNodeModel

Plik GridNodeModel.cs definiuje logikę obliczeń suwaka.

5. Konfigurowanie jako pakiet

Ostatnią czynnością przed rozpoczęciem kompilowania projektu jest dodanie pliku pkg.json, aby umożliwić dodatkowi Dynamo odczytanie pakietu.

1. Kliknij prawym przyciskiem myszy pozycję CustomNodeModel i wybierz polecenie Add > New Item

2. Wybierz opcję Web

3. Wybierz opcję JSON File

4. Nadaj plikowi nazwę pkg.json

5. Kliknij opcję Add

• Skopiuj następujący kod do pliku pkg.json

{
  "license": "MIT",
  "file_hash": null,
  "name": "CustomNodeModel",
  "version": "1.0.0",
  "description": "Sample node",
  "group": "CustomNodes",
  "keywords": [ "grid", "random" ],
  "dependencies": [],
  "contents": "Sample node",
  "engine_version": "1.3.0",
  "engine": "dynamo",
  "engine_metadata": "",
  "site_url": "",
  "repository_url": "",
  "contains_binaries": true,
  "node_libraries": [
    "CustomNodeModel, Version=1.0.0, Culture=neutral, PublicKeyToken=null",
    "CustomNodeModelFunction, Version=1.0.0, Culture=neutral, PublicKeyToken=null"
  ]
}

• "name": określa nazwę pakietu i jego grupę w bibliotece dodatku Dynamo

• "keywords": określa terminy wyszukiwania na potrzeby wyszukiwania w bibliotece dodatku Dynamo

• "node_libraries": [] biblioteki skojarzone z pakietem

  Ostatnią czynnością jest skompilowanie rozwiązania i opublikowanie go jako pakietu dodatku Dynamo. Zapoznaj się z rozdziałem dotyczącym wdrażania pakietów, aby dowiedzieć się, jak utworzyć pakiet lokalny przed opublikowaniem go online i jak skompilować pakiet bezpośrednio z programu Visual Studio.

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

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. 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ć atrybutu MultiReturn. 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>

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) }
            };
        }
    }
}

Zobacz przykład kodu w pliku ZeroTouchEssentials.cs

Węzeł zwracający wiele pozycji danych wyjściowych.

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

1. 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 wyszukiwania

• Tag /// <param name="inputName">...</param> tworzy dokumentację dla określonych parametrów wejściowych

• Tag /// <returns>...</returns> tworzy dokumentację dla parametru wyjściowego

• Tag /// <returns name = "outputName">...</returns> tworzy dokumentację dla wielu parametrów wyjściowych

• Tag /// <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.

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

Zobacz przykład kodu w pliku ZeroTouchEssentials.cs

Należy zwrócić uwagę, że kod dla tego węzła przykładowego zawiera:

1. Podsumowanie węzła

2. Opis danych wejściowych

3. 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 wymaganiami

• Skonstruuj 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.

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);
        }
    }
}

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.

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

Zobacz przykład kodu w pliku ZeroTouchEssentials.cs

Węzeł, który pobiera długość krzywej i podwaja ją.

1. 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:

  Copy

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

  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:

  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;

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

• W pliku .xml utwórz pojedynczy element <migrations>...</migrations>

• W tym elemencie migrations utwórz elementy <priorNameHint>...</priorNameHint> dla każdej zmiany nazwy

• Dla każdej zmiany nazwy dodaj element <oldName>...</oldName> i element <newName>...</newName>

1. Kliknij prawym przyciskiem myszy i wybierz polecenie Add > New Item

2. Wybierz opcję XML File

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

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

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.

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

Użycie typu ogólnego z typem ustawionym w tym przykładzie spowoduje zaimportowanie do dodatku Dynamo.

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

Rozszerzenia są zaawansowanym narzędziem programistycznym w ekosystemie dodatku Dynamo. Umożliwiają programistom sterowanie funkcjami niestandardowymi opartymi na interakcjach i logice dodatku Dynamo. Rozszerzenia można podzielić na dwie główne kategorie, rozszerzenia i rozszerzenia widoku. Jak sugeruje nazwa, struktura rozszerzeń widoku umożliwia rozszerzenie interfejsu użytkownika dodatku Dynamo przez zarejestrowanie niestandardowych elementów menu. Zwykłe rozszerzenia działają w bardzo podobny sposób, ale bez interfejsu użytkownika. Przykładowo można utworzyć rozszerzenie rejestrujące określone informacje w konsoli dodatku Dynamo. Ten scenariusz nie wymaga niestandardowego interfejsu użytkownika i dlatego można go zrealizować również za pomocą rozszerzenia.

Analiza przypadku rozszerzenia

Korzystając z przykładu SampleViewExtension z repozytorium DynamoSamples z serwisu Github, przeanalizujemy czynności niezbędne do utworzenia prostego okna niemodalnego, w którym wyświetlane są aktywne węzły na wykresie w czasie rzeczywistym. Rozszerzenie widoku wymaga utworzenia interfejsu użytkownika dla tego okna i powiązania wartości z modelem widoku.

1. To okno rozszerzenia widoku opracowano na podstawie przykładu SampleViewExtension z repozytorium Github.

Mimo że utworzymy tu ten przykład od podstaw, można również pobrać i skompilować repozytorium DynamoSamples, a następnie używać go jako odniesienia.

Repozytorium DynamoSamples: https://github.com/DynamoDS/DynamoSamples

W tym przewodniku będziemy odwoływać się konkretnie do projektu o nazwie SampleViewExtension znajdującego się w folderze DynamoSamples/src/.

Jak zaimplementować rozszerzenie widoku

Rozszerzenie widoku zawiera trzy zasadnicze części:

• Zespół zawierający klasę z zaimplementowanym interfejsem IViewExtension oraz klasę tworzącą model widoku

• Plik .xml informujący dodatek Dynamo, gdzie należy szukać tego zespołu w czasie wykonywania oraz jaki jest typ rozszerzenia

• Plik .xaml, który wiąże dane z wyświetlaniem grafiki i określa wygląd okna

1. Tworzenie struktury projektu

Rozpocznij od utworzenia nowego projektu Class Library o nazwie SampleViewExtension.

1. Utwórz nowy projekt, wybierając opcję File > New > Project

2. Wybierz opcję Class Library

3. Nadaj projektowi nazwę SampleViewExtension

4. Wybierz przycisk Ok

W tym projekcie będą potrzebne dwie klasy. W jednej klasie zostanie zaimplementowany interfejs IViewExtension, a w drugiej — klasa NotificationObject. Interfejs IViewExtension będzie zawierać wszystkie informacje o sposobie wdrażania, wczytywania, i usuwania rozszerzenia oraz odwoływania się do niego. Klasa NotificationObject będzie udostępniać powiadomienia o zmianach w dodatku Dynamo i interfejsie IDisposable. Po wprowadzeniu zmiany liczba zostanie odpowiednio zaktualizowana.

1. Plik klasy o nazwie SampleViewExtension.cs, w której zostanie zaimplementowany interfejs IViewExtension

2. Plik klasy o nazwie SampleWindowViewMode.cs, w której zostanie zaimplementowana klasa NotificationObject

Aby można było użyć interfejsu IViewExtension, potrzebny jest pakiet NuGet WpfUILibrary. Zainstalowanie tego pakietu spowoduje automatyczne zainstalowanie pakietów Core, Services i ZeroTouchLibrary.

1. Wybierz pakiet WpfUILibrary

2. Wybierz opcję Install, aby zainstalować wszystkie pakiety zależne

2. Implementowanie klasy IViewExtension

W klasie IViewExtension określimy, co się dzieje podczas uruchamiania dodatku Dynamo, gdy rozszerzenie jest wczytywane i gdy dodatek Dynamo zostaje zamknięty. W pliku klasy SampleViewExtension.cs dodaj następujący kod:

using System;
using System.Windows;
using System.Windows.Controls;
using Dynamo.Wpf.Extensions;

namespace SampleViewExtension
{

    public class SampleViewExtension : IViewExtension
    {
        private MenuItem sampleMenuItem;

        public void Dispose()
        {
        }

        public void Startup(ViewStartupParams p)
        {
        }

        public void Loaded(ViewLoadedParams p)
        {
            // Save a reference to your loaded parameters.
            // You'll need these later when you want to use
            // the supplied workspaces

            sampleMenuItem = new MenuItem {Header = "Show View Extension Sample Window"};
            sampleMenuItem.Click += (sender, args) =>
            {
                var viewModel = new SampleWindowViewModel(p);
                var window = new SampleWindow
                {
                    // Set the data context for the main grid in the window.
                    MainGrid = { DataContext = viewModel },

                    // Set the owner of the window to the Dynamo window.
                    Owner = p.DynamoWindow
                };

                window.Left = window.Owner.Left + 400;
                window.Top = window.Owner.Top + 200;

                // Show a modeless window.
                window.Show();
            };
            p.AddMenuItem(MenuBarType.View, sampleMenuItem);
        }

        public void Shutdown()
        {
        }

        public string UniqueId
        {
            get
            {
                return Guid.NewGuid().ToString();
            }  
        } 

        public string Name
        {
            get
            {
                return "Sample View Extension";
            }
        } 

    }
}

Klasa SampleViewExtension tworzy element menu, który można kliknąć, służący do otwierania okna, i łączy go z oknem i modelem widoku.

• Instrukcja public class SampleViewExtension : IViewExtension SampleViewExtension powoduje dziedziczenie po interfejsie IViewExtension i udostępnia wszystkie funkcje potrzebne do utworzenia elementu menu.

• Instrukcja sampleMenuItem = new MenuItem { Header = "Show View Extension Sample Window" }; tworzy element MenuItem i dodaje go do menu View.

1. Element menu

• Instrukcja sampleMenuItem.Click += (sender, args) wyzwala zdarzenie, które powoduje otwarcie nowego okna po kliknięciu elementu menu

• Instrukcja MainGrid = { DataContext = viewModel } ustawia kontekst danych dla siatki głównej w oknie, odwołując się do elementu Main Grid w pliku .xaml, który zostanie utworzony

• Instrukcja Owner = p.DynamoWindow ustawia dodatek Dynamo jako właściciela wyskakującego okna. Oznacza to, że nowe okno jest zależne od dodatku Dynamo, więc takie operacje jak zminimalizowanie, zmaksymalizowanie i przywrócenie dodatku Dynamo spowodują, że nowe okno będzie działało tak samo

• Metoda window.Show(); wyświetla okno, w którym ustawiono dodatkowe właściwości okna

3. Implementowanie modelu widoku

Po ustaleniu niektórych podstawowych parametrów okna dodamy logikę reagowania na różne zdarzenia związane z dodatkiem Dynamo i poinstruujemy interfejs użytkownika, aby dokonał aktualizacji na podstawie tych zdarzeń. Skopiuj następujący kod do pliku klasy SampleWindowViewModel.cs:

using System;
using Dynamo.Core;
using Dynamo.Extensions;
using Dynamo.Graph.Nodes;

namespace SampleViewExtension
{
    public class SampleWindowViewModel : NotificationObject, IDisposable
    {
        private string activeNodeTypes;
        private ReadyParams readyParams;

        // Displays active nodes in the workspace
        public string ActiveNodeTypes
        {
            get
            {
                activeNodeTypes = getNodeTypes();
                return activeNodeTypes;
            }
        }

        // Helper function that builds string of active nodes
        public string getNodeTypes()
        {
            string output = "Active nodes:\n";

            foreach (NodeModel node in readyParams.CurrentWorkspaceModel.Nodes)
            {
                string nickName = node.Name;
                output += nickName + "\n";
            }

            return output;
        }

        public SampleWindowViewModel(ReadyParams p)
        {
            readyParams = p;
            p.CurrentWorkspaceModel.NodeAdded += CurrentWorkspaceModel_NodesChanged;
            p.CurrentWorkspaceModel.NodeRemoved += CurrentWorkspaceModel_NodesChanged;
        }

        private void CurrentWorkspaceModel_NodesChanged(NodeModel obj)
        {
            RaisePropertyChanged("ActiveNodeTypes");
        }

        public void Dispose()
        {
            readyParams.CurrentWorkspaceModel.NodeAdded -= CurrentWorkspaceModel_NodesChanged;
            readyParams.CurrentWorkspaceModel.NodeRemoved -= CurrentWorkspaceModel_NodesChanged;
        }
    }
}

Ta implementacja klasy modelu widoku nasłuchuje elementu CurrentWorkspaceModel i wyzwala zdarzenie w przypadku dodania lub usunięcia węzła z obszaru roboczego. Powoduje to zgłoszenie zmiany właściwości i powiadomienie interfejsu użytkownika lub powiązanych elementów o zmianie danych i konieczności ich zaktualizowania. Wywoływany jest mechanizm pobierania ActiveNodeTypes, który wewnętrznie wywołuje dodatkową funkcję pomocniczą getNodeTypes(). Ta funkcja iteruje przez wszystkie aktywne węzły w obszarze rysunku, wypełnia ciąg zawierający nazwy tych węzłów i zwraca ten ciąg do powiązania w pliku .xaml do wyświetlenia w wyskakującym oknie.

Po zdefiniowaniu logiki podstawowej rozszerzenia określimy teraz szczegóły wyglądu okna za pomocą pliku .xaml. Wystarczy proste okno, w którym ten ciąg będzie wyświetlany za pomocą powiązania właściwości ActiveNodeTypes w kontrolce TextBlock Text.

1. Kliknij prawym przyciskiem myszy projekt i wybierz pozycję Add > New Item...

2. Wybierz szablon kontroli użytkownika, który zmienimy w celu utworzenia okna

3. Nadaj nowemu plikowi nazwę SampleWindow.xaml

4. Wybierz opcję Add

W kodzie .xaml okna należy powiązać element SelectedNodesText z blokiem tekstowym. Dodaj następujący kod do pliku SampleWindow.xaml:

<Window x:Class="SampleViewExtension.SampleWindow"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
             xmlns:local="clr-namespace:SampleViewExtension"
             mc:Ignorable="d" 
             d:DesignHeight="300" d:DesignWidth="300"
            Width="500" Height="100">
    <Grid Name="MainGrid" 
          HorizontalAlignment="Stretch"
          VerticalAlignment="Stretch">
        <TextBlock HorizontalAlignment="Stretch" Text="{Binding ActiveNodeTypes}" FontFamily="Arial" Padding="10" FontWeight="Medium" FontSize="18" Background="#2d2d2d" Foreground="White"/>
    </Grid>
</Window>

• Instrukcja Text="{Binding ActiveNodeTypes}" wiąże wartość właściwości ActiveNodeTypes w pliku SampleWindowViewModel.cs z wartością Text elementu TextBlock w oknie.

Teraz zainicjujemy okno przykładowe w pliku zaplecza pliku C# .xaml: SampleWindow.xaml.cs. Dodaj następujący kod do pliku SampleWindow.xaml:

using System.Windows;

namespace SampleViewExtension
{
    /// <summary>
    /// Interaction logic for SampleWindow.xaml
    /// </summary>
    public partial class SampleWindow : Window
    {
        public SampleWindow()
        {
            InitializeComponent();
        }
    }
}

Rozszerzenie widoku jest teraz gotowe do skompilowania i dodania do dodatku Dynamo. Dodatek Dynamo wymaga pliku xml, aby zarejestrować wynikowy plik .dll jako rozszerzenie.

1. Kliknij prawym przyciskiem myszy projekt i wybierz pozycję Add > New Item...

2. Wybierz plik XML

3. Nadaj plikowi nazwę SampleViewExtension_ViewExtensionDefinition.xml

4. Wybierz opcję Add

• Ta nazwa pliku jest zgodna ze standardem dodatku Dynamo dotyczącego odwoływania się do zespołu rozszerzenia: "extensionName"_ViewExtensionDefinition.xml

W pliku xml dodaj następujący kod, aby wskazać dodatkowi Dynamo, gdzie ma szukać zespołu rozszerzenia:

<ViewExtensionDefinition>
  <AssemblyPath>C:\Users\username\Documents\Visual Studio 2015\Projects\SampleViewExtension\SampleViewExtension\bin\Debug\SampleViewExtension.dll</AssemblyPath>
  <TypeName>SampleViewExtension.SampleViewExtension</TypeName>
</ViewExtensionDefinition>

• W tym przykładzie skompilowaliśmy zespół w domyślnym folderze projektu programu Visual Studio. Zastąp położenie docelowe <AssemblyPath>...</AssemblyPath> położeniem zespołu.

Ostatnią czynnością jest skopiowanie pliku SampleViewExtension_ViewExtensionDefinition.xml do folderu rozszerzeń widoku dodatku Dynamo znajdującego się w katalogu instalacyjnym Dynamo Core C:\Program Files\Dynamo\Dynamo Core\1.3\viewExtensions. Należy pamiętać, że istnieją oddzielne foldery dla rozszerzeń extensions i viewExtensions. Umieszczenie pliku xml w niewłaściwym folderze może spowodować błąd podczas wczytywania pliku w trakcie wykonywania.

1. Plik .xml skopiowany do folderu rozszerzeń widoku dodatku Dynamo

Jest to podstawowe wprowadzenie do rozszerzeń widoku. Bardziej zaawansowaną analizę przypadku zawiera pakiet DynaShape, projekt open source w serwisie GitHub. Ten pakiet zawiera rozszerzenie widoku umożliwiające edycję na żywo w widoku modelu dodatku Dynamo.

Instalator pakietu DynaShape można pobrać z forum dodatku Dynamo: https://forum.dynamobim.com/t/dynashape-published/11666

Kod źródłowy można sklonować z serwisu GitHub: https://github.com/LongNguyenP/DynaShape

Jeśli opracowujesz zespoły, które mają być publikowane jako pakiet dla dodatku Dynamo, projekt można skonfigurować tak, aby zgrupować wszystkie niezbędne zasoby i umieścić je w strukturze katalogów zgodnej z pakietem. Dzięki temu projekt zostanie szybko przetestowany jako pakiet i będzie mógł symulować środowisko użytkownika.

Jak kompilować bezpośrednio w folderze pakietu

Istnieją dwie metody kompilowania pakietu w programie Visual Studio:

• Dodanie zdarzeń po kompilacji za pomocą okna dialogowego ustawień projektu, w których niezbędne pliki są kopiowane za pomocą polecenia xcopy lub skryptów w języku Python

• Utworzenie zadań kopiowania plików i katalogów za pomocą obiektu docelowego kompilacji „AfterBuild” w pliku .csproj

Opcja „AfterBuild” jest metodą preferowaną w przypadku tych typów operacji (i to ją opisano w tym podręczniku), ponieważ nie jest oparta na kopiowaniu plików, które może nie być dostępne na komputerze kompilacji.

Kopiowanie plików pakietu metodą AfterBuild

Skonfiguruj strukturę katalogów w repozytorium, tak aby pliki źródłowe były oddzielone od plików pakietu. Używając analizy przypadku CustomNodeModel, umieść projekt programu Visual Studio i wszystkie skojarzone pliki w nowym folderze src. Wszystkie pakiety wygenerowane przez projekt będą zapisywane w tym folderze. Struktura folderów powinna teraz wyglądać tak:

CustomNodeModel
> src
  > CustomNodeModel
  > CustomNodeModelFunction
  > packages
  > CustomNodeModel.sln

1. Przenieś pliki projektu do nowego folderu src

Pliki źródłowe znajdują się już w oddzielnym folderze. Dodaj obiekt docelowy AfterBuild do pliku CustomNodeModel.csproj w programie Visual Studio. Powinno to spowodować skopiowanie potrzebnych plików do nowego folderu pakietu. Otwórz plik CustomNodeModel.csproj w edytorze tekstu (użyliśmy edytora Atom) i umieść obiekt docelowy kompilacji przed tagiem zamykającym </Project>. Ten obiekt docelowy AfterBuild spowoduje skopiowanie wszystkich plików .dll, .pbd, .xml i .config do nowego folderu bin oraz utworzenie folderów dyf i extra.

  <Target Name="AfterBuild">
    <ItemGroup>
      <Dlls Include="$(OutDir)*.dll" />
      <Pdbs Include="$(OutDir)*.pdb" />
      <Xmls Include="$(OutDir)*.xml" />
      <Configs Include="$(OutDir)*.config" />
    </ItemGroup>
    <Copy SourceFiles="@(Dlls)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <Copy SourceFiles="@(Pdbs)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <Copy SourceFiles="@(Xmls)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <Copy SourceFiles="@(Configs)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />
    <MakeDir Directories="$(SolutionDir)..\packages\CustomNodeModel\dyf" />
    <MakeDir Directories="$(SolutionDir)..\packages\CustomNodeModel\extra" />
  </Target>

Musimy upewnić się, że obiekt docelowy dodano do pliku CustomNodeModel.csproj (a nie innego pliku projektu) i że projekt nie ma żadnych istniejących ustawień po kompilacji (Post-Build).

1. Umieść element AfterBuild przed tagiem zamykającym </Project>.

W sekcji <ItemGroup> zdefiniowano szereg zmiennych reprezentujących określone typy plików. Na przykład zmienna Dll reprezentuje wszystkie pliki w katalogu wyjściowym mające rozszerzenie .dll.

<ItemGroup>
  <Dlls Include="$(OutDir)*.dll" />
</ItemGroup>

Zadanie Copy polega na skopiowaniu wszystkich plików .dll do katalogu, a konkretnie do folderu kompilowanego pakietu.

<Copy SourceFiles="@(Dlls)" DestinationFolder="$(SolutionDir)..\packages\CustomNodeModel\bin\" />

Pakiety dodatku Dynamo zazwyczaj zawierają foldery dyf i extra na węzły niestandardowe dodatku Dynamo i inne zasoby, takie jak obrazy. Aby utworzyć te foldery, należy użyć zadania MakeDir. To zadanie utworzy folder, jeśli on nie istnieje. Pliki można dodać do tego folderu ręcznie.

<MakeDir Directories="$(SolutionDir)..\packages\CustomNodeModel\extra" />

W przypadku kompilowania projektu folder projektu powinien teraz zawierać folder packages obok utworzonego wcześniej folderu src. W katalogu packages znajduje się folder zawierający wszystkie elementy potrzebne do utworzenia pakietu. Musimy również skopiować plik pkg.json do folderu pakietu, aby dodatek Dynamo wiedział, że ma wczytać pakiet.

1. Nowy folder packages utworzony przez obiekt docelowy AfterBuild

2. Istniejący folder src z projektem

3. Foldery dyf i extra utworzone z obiektu docelowego AfterBuild

4. Ręcznie skopiuj plik pkg.json.

Teraz można opublikować pakiet za pomocą Menedżera pakietów dodatku Dynamo lub bezpośrednio skopiować go do katalogu pakietu dodatku Dynamo: <user>\AppData\Roaming\Dynamo\1.3\packages.

Publikowanie pakietu

Pakiety to wygodny sposób przechowywania węzłów i udostępniania ich społeczności dodatku Dynamo. Pakiet może zawierać wszystko, od węzłów niestandardowych utworzonych w obszarze roboczym dodatku Dynamo po węzły pochodne od klasy NodeModel. Pakiety publikuje się i instaluje za pomocą Menedżera pakietów. Oprócz tej strony, także przewodnik Primer zawiera ogólne wskazówki dotyczące pakietów.

Czym jest Menedżer pakietów?

Menedżer pakietów dodatku Dynamo to rejestr oprogramowania (podobny do programu npm), do którego można uzyskać dostęp z poziomu dodatku Dynamo lub w przeglądarce internetowej. Menedżer pakietów umożliwia instalowanie, publikowanie, aktualizowanie i przeglądanie pakietów. Podobnie jak w przypadku programu npm, obsługuje on różne wersje pakietów. Pomaga również w zarządzaniu zależnościami projektu.

W przeglądarce wyszukaj pakiety i wyświetl statystyki: https://dynamopackages.com/

• W dodatku Dynamo Menedżer pakietów umożliwia instalowanie, publikowanie i aktualizowanie pakietów.

1. Wyszukaj pakiety online: Packages > Search for a Package...

2. Wyświetl/edytuj zainstalowane pakiety: Packages > Manage Packages...

3. Opublikuj nowy pakiet: Packages > Publish New Package...

Publikowanie pakietu

Pakiety publikuje się z poziomu Menedżera pakietów w dodatku Dynamo. Zalecanym procesem jest opublikowanie pakietu lokalnie, przetestowanie go, a następnie opublikowanie go online w celu udostępnienia go społeczności. Korzystając z analizy przypadku NodeModel, wykonamy czynności niezbędne do opublikowania węzła RectangularGrid jako pakietu lokalnie, a następnie w trybie online.

Uruchom dodatek Dynamo i wybierz opcję Packages > Publish New Package..., aby otworzyć okno Publish a Package.

1. Wybierz opcję Add file..., aby wyszukać pliki, które mają zostać dodane do pakietu

2. Wybierz dwa pliki .dll z analizy przypadku NodeModel

3. Wybierz przycisk Ok

Po dodaniu plików do zawartości pakietu nadaj pakietowi nazwę oraz dodaj do niego opis i wersję. Opublikowanie pakietu przy użyciu dodatku Dynamo powoduje automatyczne utworzenie pliku pkg.json.

Pakiet gotowy do opublikowania.

1. Podaj wymagane informacje dotyczące nazwy, opisu i wersji.

2. Opublikuj, klikając opcję „Opublikuj lokalnie” i wybierając folder pakietu dodatku Dynamo: AppData\Roaming\Dynamo\Dynamo Core\1.3\packages, aby węzeł był dostępny w składniku Core. Dopóki pakiet nie będzie gotowy do udostępnienia, zawsze publikuj lokalnie.

Po opublikowaniu pakietu węzły będą dostępne w bibliotece dodatku Dynamo w kategorii CustomNodeModel.

1. Właśnie utworzony pakiet w bibliotece dodatku Dynamo

Gdy pakiet będzie gotowy do opublikowania w trybie online, otwórz Menedżera pakietów i wybierz opcję Publish, a następnie opcję Publish Online.

1. Aby sprawdzić, jak dodatek Dynamo sformatował pakiet, kliknij pionowy trzykropek po prawej stronie pozycji „CustomNodeModel” i wybierz opcję „Pokaż katalog główny”.

2. Wybierz opcję Publish, a następnie opcję Publish Online w oknie „Publikowanie pakietów Dynamo”.

3. Aby usunąć pakiet, wybierz opcję Delete.

Jak mogę zaktualizować pakiet?

Aktualizowanie pakietu jest procesem podobnym do publikowania. Otwórz Menedżera pakietów i wybierz opcję Publish Version... dla pakietu wymagającego aktualizacji, a następnie wprowadź nowszą wersję.

1. Wybierz opcję Publish Version, aby zaktualizować istniejący pakiet o nowe pliki w katalogu głównym, a następnie określ, czy ma on zostać opublikowany lokalnie, czy online.

Klient internetowy Menedżera pakietów

Klient internetowy Menedżera pakietów służy wyłącznie do wyszukiwania i wyświetlania danych pakietu, na przykład informacji o wersjach i statystyki pobierania.

Dostęp do klienta internetowego Menedżera pakietów można uzyskać za pomocą tego linku: https://dynamopackages.com/

Wprowadzenie:

Dodatek Dynamo 2.0 jest wersją główną i niektóre interfejsy API zostały w nim zmienione lub usunięte. Jedną z największych zmian istotnych dla twórców węzłów i pakietów jest przejście na format pliku JSON.

Ogólnie twórcy węzłów Zero Touch nie muszą robić wiele albo w ogóle nic, aby zadbać o działanie pakietów w wersji 2.0.

Zadbanie o działanie w wersji 2.x węzłów interfejsu użytkownika i węzłów pochodnych bezpośrednio od klasy NodeModel wymaga więcej pracy.

Twórcy rozszerzeń również mogą być zmuszeni do wprowadzenia pewnych zmian w zależności od tego, w jakim stopniu wykorzystują w rozszerzeniach podstawowe interfejsy API dodatku Dynamo.

Ogólne zasady dotyczące pakowania:

• Nie należy łączyć z pakietem plików .dll dodatku Dynamo ani dodatku Dynamo Revit. Te biblioteki dll zostaną już wczytane przez dodatek Dynamo. W przypadku utworzenia pakietu z wersją inną niż wersja wczytana przez użytkownika (na przykład zostanie utworzona dystrybucja Dynamo Core 1.3, podczas gdy użytkownik uruchamia pakiet w dodatku Dynamo 2.0) wystąpią tajemnicze błędy w czasie wykonywania. Obejmuje to pliki dll takie jak DynamoCore.dll, DynamoServices.dll, DSCodeNodes.dll, ProtoGeometry.dll

• Należy w miarę możliwości unikać dodawania do pakietu i dystrybuowania z pakietem pliku newtonsoft.json.net. Ten plik dll również zostanie wcześniej wczytany przez dodatek Dynamo 2.x. Może wystąpić ten sam problem co powyżej.

• Należy w miarę możliwości unikać dodawania do pakietu i dystrybuowania z pakietem pliku CEFSharp. Ten plik dll również zostanie wcześniej wczytany przez dodatek Dynamo 2.x. Może wystąpić ten sam problem co powyżej.

• Ogólnie należy unikać udostępniania zależności wraz z dodatkiem Dynamo lub programem Revit, jeśli zachodzi potrzeba kontrolowania wersji tej zależności.

Typowe problemy:

1) Po otwarciu wykresu niektóre węzły mają wiele portów o tej samej nazwie, mimo że wykres wyglądał dobrze podczas zapisywania. Ten problem może mieć kilka przyczyn.

Typową przyczyną jest to, że węzeł utworzono za pomocą konstruktora ponownie tworzącego porty. Zamiast tego należało użyć konstruktora wczytującego porty. Te konstruktory mają zwykle oznaczenie [JsonConstructor] zobacz przykłady poniżej

Inna możliwa przyczyna:

• Nie było zgodnych elementów [JsonConstructor] lub nie przekazano elementów Inports i Outports z pliku JSON.dyn.

• W tym samym czasie do tego samego procesu wczytano dwie wersje JSON.net, co spowodowało błąd środowiska uruchomieniowego .NET, więc nie można było poprawnie użyć atrybutu [JsonConstructor] do oznaczenia konstruktora.

• Do pakietu dołączono plik DynamoServices.dll w wersji innej niż bieżąca wersja dodatku Dynamo i powoduje to, że środowisko uruchomieniowe .NET nie może zidentyfikować atrybutu [MultiReturn], więc dla węzłów Zero-Touch oznaczonych różnymi atrybutami nie można zastosować tych atrybutów. Może się okazać, że węzeł zwraca jeden słownik wyjściowy zamiast wielu portów.

2) Całkowicie brakuje węzłów po wczytaniu wykresu z pewnymi błędami w konsoli.

• Może tak się zdarzyć, jeśli z jakiegoś powodu nie powiedzie się deserializacja. Zaleca się serializowanie tylko potrzebnych właściwości. Można używać atrybutu [JsonIgnore] w przypadku złożonych właściwości, których nie trzeba wczytywać ani zapisywać, aby je zignorować. Chodzi o właściwości takie jak function pointer, delegate, action, czy event. Nie należy ich serializować, ponieważ zazwyczaj nie można ich zdeserializować i powodują one błąd w trakcie wykonywania.

Szczegółowe omówienie uaktualnienia:

Węzły niestandardowe z wersji 1.3 do wersji 2.0

Organizowanie węzłów niestandardowych w pliku librarie.js

Znane problemy:

• Zbieżna nazwa węzła niestandardowego i nazwa kategorii na tym samym poziomie w pliku librarie.js skutkuje nieoczekiwanym zachowaniem. QNTM-3653 — unikaj używania tych samych nazw kategorii i węzłów.

• Komentarze zostaną zamienione na komentarze blokowe zamiast komentarzy jednowierszowych.

• Krótkie nazwy typów zostaną zastąpione pełnymi nazwami. Jeśli na przykład podczas ponownego wczytywania węzła niestandardowego nie został określony typ, pojawi się var[]..[] — ponieważ jest to typ domyślny.

Węzły Zero-Touch z wersji 1.3 do wersji 2.0

• W dodatku Dynamo 2.0 typy List (lista) i Dictionary (słownik) zostały rozdzielone, a składnia tworzenia list i słowników została zmieniona. Listy inicjuje się przy użyciu [], a słowniki przy użyciu {}. Jeśli wcześniej używano atrybutu DefaultArgument do oznaczania parametrów w węzłach Zero-Touch i używano składni listy w celu utworzenia konkretnej listy domyślnej, takiej jak someFunc([DefaultArgument("{0,1,2}")]), nie będzie to już poprawne. Należy zmodyfikować fragment kodu DesignScript, stosując nową składnię inicjowania list.

• Jak wspomniano powyżej, nie należy dystrybuować plików dll dodatku Dynamo wraz z pakietami. (DynamoCore, DynamoServices itp.)

Węzły Node Model z wersji 1.3 do wersji 2.0

Zaktualizowanie węzłów Node Model do wersji Dynamo 2.x wymaga najwięcej pracy. Ogólnie należy zaimplementować konstruktory, które będą używane tylko do wczytywania węzłów z pliku json obok zwykłych konstruktorów klasy nodeModel używanych do tworzenia nowych wystąpień typów węzłów. Aby odróżnić te elementy, należy oznaczyć konstruktory czasu ładowania atrybutem [JsonConstructor], który jest atrybutem z biblioteki newtonsoft.Json.net.

Nazwy parametrów w konstruktorze powinny zasadniczo odpowiadać nazwom właściwości JSON — jednak to odwzorowanie jest bardziej skomplikowane w przypadku nadpisywania nazw serializowanych przy użyciu atrybutów [JsonProperty]. Więcej informacji można znaleźć w dokumentacji Json.net.

Konstruktory JSON

Najczęstszą zmianą, jaką należy wprowadzić w celu zaktualizowania węzłów pochodnych od klasy bazowej NodeModel (lub innych klas bazowych dodatku Dynamo, na przykład DSDropDownBase), jest konieczność dodania do klasy konstruktora JSON.

Oryginalny konstruktor bez parametrów nadal będzie obsługiwał inicjowanie nowego węzła tworzonego w dodatku Dynamo (na przykład za pomocą biblioteki). Konstruktor JSON jest wymagany do zainicjowania węzła, który został zdeserializowany (wczytany) z zapisanego pliku .dyn lub .dyf.

Konstruktor JSON różni się od konstruktora bazowego tym, że ma parametry PortModel dla portów inPorts i outPorts, które są dostarczane przez logikę ładowania JSON. Wywołanie w celu zarejestrowania portów dla węzła nie jest tutaj wymagane, ponieważ dane istnieją w pliku .dyn. Przykład konstruktora JSON wygląda tak:

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) { }

Ta składnia :base(Inports,outPorts){} wywołuje konstruktor bazowy nodeModel i przekazuje do niego zdeserializowane porty.

Nie jest wymagane powtarzanie w tym konstruktorze żadnej specjalnej logiki istniejącej w konstruktorze klasy, która obejmuje zainicjowanie określonych danych zserializowanych do pliku .dyn (na przykład ustawiania rejestracji portu, strategii skratowania itp.), ponieważ te wartości można odczytać z pliku JSON.

Jest to główna różnica między konstruktorami JSON i innymi konstruktorami NC w przypadku klas nodeModel. Konstruktory JSON są wywoływane podczas wczytywania z pliku i są do nich przekazywane wczytane dane. W konstruktorze JSON należy jednak powielić inną logikę użytkownika (na przykład inicjowanie obsługi zdarzeń dla węzła lub dołączanie).

Przykłady można znaleźć tutaj w repozytorium DynamoSamples -> ButtonCustomNodeModel, DropDown lub SliderCustomNodeModel

Właściwości publiczne i serializowanie

Wcześniej programista mógł serializować i deserializować określone dane modelu do dokumentu xml za pomocą metod SerializeCore i DeserializeCore. Te metody nadal istnieją w interfejsie API, ale zostaną wycofane w przyszłej wersji dodatku Dynamo (przykład można znaleźć tutaj). Dzięki implementacji JSON.NET właściwości public klasy pochodnej od klasy NodeModel można teraz serializować bezpośrednio do pliku .dyn. W środowisku JSON.Net dostępnych jest wiele atrybutów umożliwiających sterowanie sposobem serializowania właściwości.

W repozytorium dodatku Dynamo, tutaj, można znaleźć przykład określający atrybut PropertyName.

[JsonProperty(PropertyName = "InputValue")]

public DSColor DsColor {...

Konwertery:

Uwaga Jeśli tworzysz własną klasę konwertera JSON.net: dodatek Dynamo nie ma obecnie mechanizmu umożliwiającego wstrzyknięcie jej do metod wczytywania i zapisywania, więc nawet jeśli oznaczysz tę klasę atrybutem [JsonConverter], może ona nie zostać użyta. Zamiast tego możesz wywołać ten konwerter bezpośrednio w mechanizmie ustawiania (setter) lub pobierania (getter). //DO OPRACOWANIA Wymagane jest potwierdzenie tego ograniczenia. Wszelkie dowody są mile widziane.

W repozytorium dodatku Dynamo, tutaj, można znaleźć przykład określający metodę serializacji do konwertowania właściwości na ciąg.

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

public ConversionMetricUnit SelectedMetricConversion{...

Ignorowanie właściwości

Właściwości public, które nie są przeznaczone do serializacji, muszą mieć dodany atrybut [JsonIgnore]. Po zapisaniu węzłów w pliku .dyn zapewnia to ignorowanie tych danych przez mechanizm serializowania, więc nie będą one powodować nieoczekiwanych konsekwencji po ponownym otwarciu wykresu. Przykład tego można znaleźć tutaj w repozytorium dodatku Dynamo.

Cofanie/ponawianie

Jak wspomniano powyżej, w przeszłości używano metod SerializeCore i DeserializeCore do zapisywania i wczytywania węzłów do pliku xml .dyn. Dodatkowo były też używane do zapisywania i wczytywania stanu węzła na potrzeby operacji cofania/ponawiania — i nadal są. Aby zaimplementować złożone funkcje cofania/ponawiania dla węzła interfejsu użytkownika nodeModel, należy zaimplementować te metody i zserializować je w obiekcie dokumentu XML dostarczanym jako parametr tych metod. Powinno to być stosowane rzadko, w przypadku złożonych węzłów interfejsu użytkownika.

Interfejsy API portów wejściowych i wyjściowych

Jedną z typowych sytuacji w przypadku węzłów nodeModel, na którą wpływają zmiany interfejsu API 2.0, jest rejestracja portów w konstruktorze węzła. Wcześniej podczas przyglądania się przykładom w repozytorium Dynamo lub DynamoSamples można było znaleźć przypadki użycia metody InPortData.Add() lub OutPortData.Add(). Wcześniej w interfejsie API dodatku Dynamo właściwości publiczne InPortData i OutPortData były oznaczone jako wycofane. W wersji 2.0 właściwości te zostały usunięte. Programiści powinni teraz korzystać z metod InPorts.Add() i OutPorts.Add(). Ponadto te dwie metody Add() mają nieco inne sygnatury:

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

w porównaniu z nową

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

Przykłady przekonwertowanego kodu można znaleźć tutaj w repozytorium dodatku Dynamo -> DynamoConvert.cs lub FileSystem.cs

Inny typowy przypadek użycia, na który wpływają zmiany interfejsu API 2.0, dotyczy metod powszechnie używanych w metodzie BuildAst() w celu określania zachowania węzłów na podstawie występowania lub braku złączy portów. Wcześniej do sprawdzania stanu połączenia portu używano metody HasConnectedInput(index). Programiści powinni teraz sprawdzać stan połączenia portu za pomocą właściwości InPorts[0].IsConnected. Przykład tego można znaleźć w pliku ColorRange.cs w repozytorium dodatku Dynamo.

Przykłady:

Przeanalizujmy proces uaktualniania węzła interfejsu użytkownika w wersji 1.3 do wersji Dynamo 2.x.

using System;
using System.Collections.Generic;
using Dynamo.Graph.Nodes;
using CustomNodeModel.CustomNodeModelFunction;
using ProtoCore.AST.AssociativeAST;
using Autodesk.DesignScript.Geometry;

namespace CustomNodeModel.CustomNodeModel
{
    [NodeName("RectangularGrid")]
    [NodeDescription("An example NodeModel node that creates a rectangular grid. The slider randomly scales the cells.")]
    [NodeCategory("CustomNodeModel")]
    [InPortNames("xCount", "yCount")]
    [InPortTypes("double", "double")]
    [InPortDescriptions("Number of cells in the X direction", "Number of cells in the Y direction")]
    [OutPortNames("Rectangles")]
    [OutPortTypes("Autodesk.DesignScript.Geometry.Rectangle[]")]
    [OutPortDescriptions("A list of rectangles")]
    [IsDesignScriptCompatible]
    public class GridNodeModel : NodeModel
    {
        private double _sliderValue;
        public double SliderValue
        {
            get { return _sliderValue; }
            set
            {
                _sliderValue = value;
                RaisePropertyChanged("SliderValue");
                OnNodeModified(false);
            }
        }
        public GridNodeModel()
        {
            RegisterAllPorts();
        }
        public override IEnumerable<AssociativeNode> BuildOutputAst(List<AssociativeNode> inputAstNodes)
        {
            if (!HasConnectedInput(0) || !HasConnectedInput(1))
            {
                return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), AstFactory.BuildNullNode()) };
            }
            var sliderValue = AstFactory.BuildDoubleNode(SliderValue);
            var functionCall =
              AstFactory.BuildFunctionCall(
                new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid),
                new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue });

            return new[] { AstFactory.BuildAssignment(GetAstIdentifierForOutputIndex(0), functionCall) };
        }
    }
}

W przypadku klasy nodeModel, aby zapewnić poprawne wczytywanie i zapisywanie portów w wersji 2.0, wystarczy tylko dodać konstruktor jsonConstructor do obsługi wczytywania portów. Po prostu przekazujemy porty do konstruktora bazowego, a ta implementacja jest pusta.

[JsonConstructor]
protected GridNodeModel(IEnumerable<PortModel> Inports, IEnumerable<PortModel> Outports ) :
base(Inports,Outports)
{

}

Uwaga: nie należy wywoływać operacji RegisterPorts() ani jej odmian w konstruktorze JsonConstructor — użyje ona atrybutów parametrów wejściowych i wyjściowych w klasie węzła w celu utworzenia nowych portów. Nie chcemy, aby tak się stało, ponieważ chcemy używać wczytanych portów, które są przekazywane do konstruktora.

[InPortNames("xCount", "yCount")]
[InPortTypes("double", "double")]

W tym przykładzie dodano minimalny konstruktor JSON wczytywania. Co jednak zrobić, jeśli trzeba utworzyć bardziej złożoną logikę konstrukcji, na przykład skonfigurować pewne detektory do obsługi zdarzeń wewnątrz konstruktora. Następny przykład pochodzący z repozytorium DynamoSamples połączono powyżej części JsonConstructors Section w tym dokumencie.

Poniżej przedstawiono bardziej złożony konstruktor węzła interfejsu użytkownika:

 public ButtonCustomNodeModel()
        {
            // When you create a UI node, you need to do the
            // work of setting up the ports yourself. To do this,
            // you can populate the InPorts and the OutPorts
            // collections with PortData objects describing your ports.
            InPorts.Add(new PortModel(PortType.Input, this, new PortData("inputString", "a string value displayed on our button")));

            // Nodes can have an arbitrary number of inputs and outputs.
            // If you want more ports, just create more PortData objects.
            OutPorts.Add(new PortModel(PortType.Output, this, new PortData("button value", "returns the string value displayed on our button")));
            OutPorts.Add(new PortModel(PortType.Output, this, new PortData("window value", "returns the string value displayed in our window when button is pressed")));

            // This call is required to ensure that your ports are
            // properly created.
            RegisterAllPorts();

            // Listen for input port disconnection to trigger button UI update
            this.PortDisconnected += ButtonCustomNodeModel_PortDisconnected;

            // The arugment lacing is the way in which Dynamo handles
            // inputs of lists. If you don't want your node to
            // support argument lacing, you can set this to LacingStrategy.Disabled.
            ArgumentLacing = LacingStrategy.Disabled;

            // We create a DelegateCommand object which will be 
            // bound to our button in our custom UI. Clicking the button 
            // will call the ShowMessage method.
            ButtonCommand = new DelegateCommand(ShowMessage, CanShowMessage);

            // Setting our property here will trigger a 
            // property change notification and the UI 
            // will be updated to reflect the new value.
            ButtonText = defaultButtonText;
            WindowText = defaultWindowText;
        }

Podczas dodawania konstruktora JSON na potrzeby wczytywania tego węzła z pliku należy ponownie utworzyć niektóre elementy tej logiki, ale nie należy dodawać kodu tworzącego porty, ustawiającego skratowanie ani ustawiającego wartości domyślne właściwości, który można wczytać z pliku.

        // This constructor is called when opening a Json graph.

        [JsonConstructor]
        ButtonCustomNodeModel(IEnumerable<PortModel> inPorts, IEnumerable<PortModel> outPorts) : base(inPorts, outPorts)
        {
            this.PortDisconnected += ButtonCustomNodeModel_PortDisconnected;
            ButtonCommand = new DelegateCommand(ShowMessage, CanShowMessage);
        }

Należy pamiętać, że inne właściwości publiczne zserializowane do pliku JSON, takie jak ButtonText i WindowText, nie powinny być dodawane do konstruktora jako parametry jawne — są one ustawiane automatycznie przez środowisko JSON.net za pomocą mechanizmów ustawiania (setter) tych właściwości.