Jaký je účel této příručky?

Účelem této příručky je pomoci vám zorientovat se v možnostech vývoje aplikace Dynamo v jazyce C#, od vytváření uzlů Zero-Touch až po tvorbu rozšíření.

Zdroj pro aplikaci Dynamo na GitHubu

Jaké další zdroje pro vývojáře poskytujeme?

Dynamo: Stažení nejnovějšího stabilního a denního sestavení aplikace Dynamo.

https://dynamobuilds.com/

GitHub aplikace Dynamo: Dynamo je projekt s otevřeným zdrojovým kódem na GitHubu.

https://github.com/DynamoDS/Dynamo

Wiki aplikace Dynamo na GitHubu: Toto byl hlavní zdroj dokumentace pro vývojáře.

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

Standardy pojmenování uzlů: Standardy a pokyny pro pojmenování kategorií, uzlů a vstupních a výstupních portů v aplikaci Dynamo.

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

Příručka k jazyku a rozhraní API aplikace Dynamo: Dokumentace k rozhraní API aplikace Dynamo aktuálně pokrývá hlavní funkce.

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

DynamoBIM: Nejlepší zdroj dalších informací, výukových materiálů a komunitních diskuzí je webová stránka DynamoBIM.

https://dynamobim.org

Slovník aplikace Dynamo: Databáze všech uzlů aplikace Dynamo, ve které lze vyhledávat.

https://dictionary.dynamobim.com/

Příručka jazyka DesignScript: Příručka ve formátu PDF pro psaní v jazyce DesignScript.

PDF

Jak mohu navrhnout změny této příručky?

Tato dokumentace je otevřená návrhům. Úpravy lze navrhovat přímo v Githubu vytvořením požadavků na změny.

Zdroj aplikace Dynamo je hostován na Githubu, kde jej může kdokoli klonovat a přispívat do něj. V této kapitole si ukážeme, jak klonovat úložiště pomocí gitu, kompilovat zdrojové soubory pomocí aplikace Visual Studio, spustit a ladit místní sestavení a získat všechny nové změny z Githubu.

Vyhledání úložišť aplikace Dynamo na Githubu

Github je hostovací služba založená na gitu, systému pro správu verzí, který slouží ke sledování změn a koordinaci práce mezi lidmi. Git je nástroj, který můžeme využít ke stažení zdrojových souborů aplikace Dynamo a jejich aktualizaci pomocí několika příkazů. Použitím této metody se vyhnete zbytečné a nepřehledné práci se stahováním a ručním nahrazováním zdrojových souborů při každé aktualizaci. Systém správy verzí git bude sledovat veškeré rozdíly mezi místním a vzdáleným úložištěm kódů.

Zdroj aplikace Dynamo je hostován na Githubu DynamoDS v tomto úložišti: https://github.com/DynamoDS/Dynamo.

Zdrojové soubory aplikace Dynamo.

1. Klonování nebo stáhnutí celého úložiště

2. Zobrazení dalších úložišť DynamoDS

3. Zdrojové soubory aplikace Dynamo

4. Specifické soubory Gitu

Získání úložiště aplikace Dynamo pomocí gitu

Než bude možné úložiště klonovat, je třeba nainstalovat git. V této krátké příručce naleznete postup instalace a nastavení uživatelského jména a e-mailu pro GitHub. V tomto příkladu použijeme git na příkazovém řádku. Tato příručka předpokládá, že budete používat systém Windows, ale ke klonování zdroje aplikace Dynamo můžete použít také git v systému Mac nebo Linux.

Potřebujeme adresu URL úložiště aplikace Dynamo, ze kterého se bude klonovat. Tu najdeme v tlačítku Clone or download (Klonovat nebo stáhnout) na stránce úložiště. Zkopírujte adresu URL, kterou chcete vložit do příkazového řádku.

1. Vyberte možnost Clone or download (Klonovat nebo stáhnout).

2. Zkopírujte adresu URL.

S nainstalovaným gitem můžeme klonovat úložiště aplikace Dynamo. Začněte otevřením příkazového řádku. Poté pomocí příkazu pro změnu adresáře cd přejděte do složky, do které chcete zdrojové soubory klonovat. V tomto případě jsme vytvořili složku s názvem Github ve složce Documents.

cd C:\Users\username\Documents\GitHub

Parametr „username“ nahraďte svým uživatelským jménem.

V dalším kroku spustíme příkaz gitu, který naklonuje úložiště aplikace Dynamo do zadaného umístění. Adresu URL v příkazu získáte kliknutím na tlačítko Clone or download (Klonovat nebo stáhnout) na Githubu. Tento příkaz spusťte v příkazovém řádku. Tímto příkazem se naklonuje hlavní větev úložiště aplikace Dynamo, která obsahuje nejaktuálnější verzi kódu aplikace Dynamo. Tato větev se denně mění.

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

Pokud byla operace klonování úspěšně dokončena, víme, že git funguje. V Průzkumníku souborů přejděte do adresáře, do kterého jste klonovali, a zobrazte zdrojové soubory. Struktura adresáře by měla vypadat stejně jako hlavní větev úložiště aplikace Dynamo na Githubu.

1. Zdrojové soubory aplikace Dynamo

2. Soubory Git

Vytvoření úložiště pomocí aplikace Visual Studio

Pomocí zdrojových souborů, které jsou nyní klonovány do místního počítače, můžeme vytvořit spustitelný soubor pro aplikaci Dynamo. Za tímto účelem je nutné nastavit prostředí Visual Studio IDE a zajistit instalaci rozhraní .NET Framework a DirectX.

• Stáhněte a nainstalujte Microsoft Visual Studio Community 2015, bezplatné, plně vybavené integrované vývojové prostředí (IDE – mohou fungovat i novější verze).

• Stáhněte a nainstalujte rozhraní Microsoft .NET Framework 4.5 nebo novější.

• Nainstalujte rozhraní Microsoft DirectX z místního úložiště aplikace Dynamo (Dynamo\tools\install\Extra\DirectX\DXSETUP.exe).

Rozhraní .NET a DirectX již mohou být nainstalována.

Po dokončení instalace můžete spustit aplikaci Visual Studio a otevřít řešení Dynamo.All.sln, které se nachází v umístění Dynamo\src.

1. Vyberte File > Open > Project/Solution.

2. Přejděte do úložiště aplikace Dynamo a otevřete složku src.

3. Vyberte soubor řešení Dynamo.All.sln.

4. Klikněte na tlačítko Open.

Než budeme moct vytvořit řešení, je třeba zadat několik nastavení. Nejprve bychom měli vytvořit ladicí verzi aplikace Dynamo, aby aplikace Visual Studio mohla získat další informace při ladění, které nám pomůžou s vývojem, přičemž jako platformu vybereme možnost „AnyCPU“.

Tyto složky se stanou složkami ve složce bin.

1. V tomto příkladu jsme jako konfiguraci řešení vybrali Debug.

2. Nastavte platformu řešení na Any CPU

S otevřeným projektem můžeme vytvořit řešení. Tento proces vytvoří soubor DynamoSandbox.exe, který můžeme spustit.

Vytvořením projektu se obnoví závislosti NuGet.

1. Vyberte Build > Build Solution.

2. V okně Výstup ověřte, zda sestavení proběhlo úspěšně. Měla by se zobrazit zpráva podobná této: ==== Build: 69 succeeded, 0 failed, 0 up-to-date, 0 skipped ====

Spuštění místního sestavení

Pokud sestavení aplikace Dynamo proběhlo úspěšně, vytvoří se v úložišti aplikace Dynamo složka bin se souborem DynamoSandbox.exe. V našem případě vytváříme sestavení s možností Debug, takže spustitelný soubor se nachází v umístění bin\AnyCPU\Debug. Spuštěním tohoto souboru otevřete místní sestavení aplikace Dynamo.

1. Spustitelný soubor DynamoSandbox, který jsme právě vytvořili. Jeho spuštěním spustíte aplikaci Dynamo.

Nyní jsme téměř plně připraveni začít s vývojem pro aplikaci Dynamo.

Pokyny k vytváření aplikace Dynamo pro další platformy (například Linux nebo OS X) naleznete na této stránce Wiki.

Ladění místního sestavení pomocí aplikace Visual Studio

Ladění je proces identifikace, izolování a opravy chyby nebo problému. Po úspěšném sestavení aplikace Dynamo ze zdroje můžeme pomocí několika nástrojů v aplikaci Visual Studio ladit spuštěnou aplikaci, například doplněk DynamoRevit. Můžeme analyzovat jeho zdrojový kód a najít příčinu problému nebo sledovat aktuálně prováděný kód. Podrobnější informace o tom, jak ladit a procházet kód v aplikaci Visual Studio, naleznete v dokumentaci k aplikaci Visual Studio.

V případě samostatné aplikace Dynamo, DynamoSandbox, se budeme zabývat dvěma možnostmi ladění:

• Sestavení a spuštění aplikace Dynamo přímo z aplikace Visual Studio

• Připojení aplikace Visual Studio ke spuštěnému procesu aplikace Dynamo

Spuštění aplikace Dynamo z aplikace Visual Studio v případě potřeby znovu sestaví řešení pro každou relaci ladění, takže pokud jsme provedli změny zdroje, budou při ladění začleněny. Se stále otevřeným řešením Dynamo.All.sln vyberte v rozevíracích nabídkách možnosti Debug, AnyCPU a DynamoSandbox a klikněte na tlačítko Start. Tím se vytvoří aplikace Dynamo, spustí se nový proces (DynamoSandbox.exe) a připojí se k němu ladicí program aplikace Visual Studio.

Vytvořte a spusťte aplikaci přímo z aplikace Visual Studio.

1. Nastavte konfiguraci na Debug.

2. Nastavte platformu na Any CPU.

3. Nastavte spouštěný projekt na DynamoSandbox.

4. Kliknutím na tlačítko Start zahajte proces ladění.

Případně můžete chtít ladit proces aplikace Dynamo, který je již spuštěný, abyste vyřešili problém s konkrétním otevřeným grafem nebo balíčkem. Za tímto účelem otevřete zdrojové soubory projektu v aplikaci Visual Studio a připojte je ke spuštěnému procesu aplikace Dynamo pomocí položky nabídky ladění Attach to Process.

Připojení spuštěného procesu k aplikaci Visual Studio

1. Vyberte Debug > Attach to Process....

2. Zvolte soubor DynamoSandbox.exe.

3. Klikněte na tlačítko Attach.

V obou případech připojujeme ladicí program k procesu, který chceme ladit. V kódu můžeme před nebo po spuštění ladicího programu nastavit body přerušení, které způsobí, že se proces zastaví bezprostředně před provedením tohoto řádku kódu. Pokud je během ladění vyvolána nezachycená výjimka, aplikace Visual Studio přejde na místo jejího výskytu ve zdrojovém kódu. Jedná se o efektivní metodu hledání jednoduchých selhání, neošetřených výjimek a pochopení toku spuštění aplikace.

Při ladění aplikace DynamoSandbox jsme nastavili bod přerušení v konstruktoru uzlu Colour.ByARGB, který způsobí pozastavení procesu aplikace Dynamo při vytvoření instance uzlu. Pokud tento uzel způsobí výjimku nebo selhání aplikace Dynamo, můžeme postupně projít jednotlivé řádky konstruktoru a zjistit, kde k problému došlo.

1. Bod přerušení

2. Zásobník volání zobrazující funkci, která je právě vykonávána, a předchozí volání funkcí.

V další části Sestavení doplňku DynamoRevit ze zdroje si ukážeme konkrétní příklad ladění a vysvětlíme, jak nastavit body přerušení, krokovat kód a číst zásobník volání.

Získání nejnovějšího sestavení

Protože je zdroj aplikace Dynamo hostován na Githubu, nejjednodušším způsobem, jak aktualizovat místní zdrojové soubory, je získávání změn pomocí příkazů git.

Pomocí příkazového řádku nastavte aktuální adresář na úložiště aplikace Dynamo:

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

Parametr "username" nahraďte svým uživatelským jménem.

K získání nejnovějších změn použijte následující příkaz:

git pull origin master

1. Zde je vidět, že místní úložiště bylo aktualizováno změnami ze vzdáleného úložiště.

Kromě získávání aktualizací je třeba znát další čtyři pracovní postupy gitu.

• Rozvětvením úložiště aplikace Dynamo vytvoříte kopii oddělenou od originálu. Jakékoli změny zde provedené nebudou mít vliv na původní úložiště a aktualizace mohou být získávány z úložiště nebo do něj odesílány pomocí žádostí o přijetí změn. Rozvětvení (fork) není příkaz gitu. Je to pracovní postup, který přidává github – rozvětvení a žádost o přijetí změn je jedním z nejběžnějších pracovních postupů pro přispívání do projektů s otevřeným zdrojovým kódem online. Chcete-li přispívat do aplikace Dynamo, je vhodné se ho naučit.

• Větev (branch) – umožňuje pracovat na experimentech nebo nových prvcích izolovaně od ostatní práce ve větvích. Díky tomu je odesílání žádostí o přijetí změn jednodušší.

• Často provádějte zápisy (commit), zejména po dokončení pracovní jednotky a po změně, kterou možná budete chtít vrátit zpět. Zápis zaznamenává změny v úložišti a bude viditelný při zadávání žádosti o přijetí změn do hlavního úložiště aplikace Dynamo.

• Vytvářejte žádosti o přijetí změn (pull request), když jsou změny připraveny k oficiálnímu navržení do hlavního úložiště aplikace Dynamo.

Tým aplikace Dynamo má konkrétní pokyny pro vytváření žádostí o přijetí změn. Podrobnější informace najdete v části Žádosti o přijetí změn v této dokumentaci.

Na této stránce dokumentace naleznete referenční seznam příkazů git.

Zdrojové soubory doplňku DynamoRevit jsou také umístěny na Githubu DynamoDS, kde mohou vývojáři vytvářet příspěvky a sestavovat beta verze. Sestavení doplňku DynamoRevit ze zdroje obecně probíhá stejným způsobem jako u aplikace Dynamo s výjimkou několika důležitých detailů:

• Doplněk DynamoRevit odkazuje na sestavy aplikace Dynamo, proto by měly být vytvořeny pomocí odpovídajících balíčků NuGet. Doplněk DynamoRevit 2.x například nebude načten do aplikace Dynamo 1.3.

• Doplněk DynamoRevit je specifický pro konkrétní verzi aplikace Revit, například větev doplňku DynamoRevit 2018 by měla být spuštěna v aplikaci Revit 2018.

V této příručce použijeme následující zdroje:

• Revit 2023

• Nejnovější sestavení doplňku DynamoRevit založené na větvi aplikace Revit2023

• Nejnovější sestavení aplikace Dynamo

Abychom zajistili úspěšné sestavení, naklonujeme a sestavíme úložiště aplikace Dynamo a doplňku DynamoRevit, která použijeme v této ukázce.

Poznámka: Ruční sestavení aplikace Dynamo před doplňkem DynamoRevit je nutné pouze v případě, že vytváříte aplikaci Dynamo 1.x a doplněk DynamoRevit 1.x. Novější verze úložiště doplňku DynamoRevit se při tvorbě závislostí aplikace Dynamo potřebných k sestavení spoléhají na správce balíčků NuGet. I když sestavení doplňku DynamoRevit 2.x nevyžaduje ruční stažení aplikace Dynamo, budete stále potřebovat základní knihovny dlls, abyste mohli add-in DynamoRevit skutečně spustit, proto se vyplatí aplikaci Dynamo stáhnout a sestavit tak jako tak. Další informace naleznete níže: Tvorba úložiště pomocí aplikace Visual Studio

Vyhledání úložiště doplňku DynamoRevit na Githubu

Kód projektu doplňku DynamoRevit se nachází v samostatném úložišti na Githubu, které je odděleno od základního zdrojového kódu aplikace Dynamo. Toto úložiště obsahuje zdrojové soubory pro uzly specifické pro aplikaci Revit a doplněk aplikace Revit, který načítá aplikaci Dynamo. Sestavení doplňku DynamoRevit pro různé verze aplikace Revit (například 2016, 2017 nebo 2018) jsou v úložišti uspořádána jako větve.

Zdroj doplňku DynamoRevit je hostován zde: https://github.com/DynamoDS/DynamoRevit

1. Klonování nebo stáhnutí úložiště

2. Větve doplňku DynamoRevit odkazují na verze aplikace Revit.

Klonování úložiště pomocí systému git

Podobně jako při získávání úložiště aplikace Dynamo použijeme příkaz git clone ke klonování doplňku DynamoRevit a k určení větve, která odpovídá verzi aplikace Revit. Nejprve otevřeme rozhraní příkazového řádku a nastavíme aktuální adresář do umístění, do kterého chcete soubory klonovat.

cd C:\Users\username\Documents\GitHub změní aktuální adresář

Parametr username nahraďte svým uživatelským jménem.

Nyní můžeme do tohoto adresáře naklonovat úložiště. I když bude nutné zadat větev úložiště, můžeme se na ni po klonování přepnout.

Příkaz git clone https://github.com/DynamoDS/DynamoRevit.git naklonuje úložiště ze vzdálené adresy URL a ve výchozím nastavení přepne na hlavní větev.

Po dokončení klonování úložiště změňte aktuální adresář na složku úložiště a přepněte na větev, která odpovídá nainstalované verzi aplikace Revit. V tomto příkladu používáme aplikaci Revit RC2.13.1_Revit2023. Všechny vzdálené větve lze zobrazit na stránce Githubu v rozevírací nabídce Branch (Větev).

Příkaz cd C:\Users\username\Documents\GitHub\DynamoRevit změní adresář na DynamoRevit. Příkaz git checkout RC2.13.1_Revit2023 nastaví aktuální větev na RC2.13.1_Revit2023. Příkaz git branch ověří, ve které větvi se nacházíme, a zobrazí ostatní větve, které existují místně.

Větev s hvězdičkou je aktuálně rezervovaná větev. Větev Revit2018 se zobrazuje, protože jsme ji dříve zarezervovali, takže existuje místně.

Je důležité vybrat správnou větev úložiště, abyste zajistili, že při vytváření projektu v aplikaci Visual Studio bude projekt odkazovat na sestavy ve správné verzi instalačního adresáře aplikace Revit, konkrétně RevitAPI.dll a RevitAPIUI.dll.

Vytvoření úložiště pomocí aplikace Visual Studio

Před vytvořením úložiště bude nutné obnovit balíčky NuGet se souborem restorepackages.bat umístěným ve složce src. Tento soubor BAT používá správce balíčku NuGet k získání vestavěných sestavených binárních souborů jádra aplikace Dynamo, které potřebuje doplněk DynamoRevit. Můžete se také rozhodnout sestavit je ručně, ale pouze pokud provádíte změny v doplňku DynamoRevit a ne v jádře aplikace Dynamo. Díky tomu bude začátek práce rychlejší. Nezapomeňte tento soubor spustit jako správce.

.

1. Klikněte pravým tlačítkem myši na soubor restorepackages.bat a vyberte příkaz Run as administrator.

Pokud jsou balíčky úspěšně obnoveny, složka packages bude přidána do složky src s nejnovějšími balíčky NuGet beta verze aplikace.

1. Nejnovější balíčky NuGet beta verze aplikace Dynamo

Po obnovení balíčků otevřete soubor řešení aplikace Visual Studio DynamoRevit.All.sln ve složce src a vytvořte řešení. Sestavení může mít zpočátku potíže s vyhledáním souboru AssemblySharedInfo.cs. Pokud se tak stane, vyřešte tento problém opětovným spuštěním sestavení.

1. Vyberte Build > Build Solution.

2. V okně Výstup ověřte, zda sestavení proběhlo úspěšně. Měla by se zobrazit následující zpráva: ===== Build: 13 succeeded, 0 failed, 0 up-to-date, 0 skipped =====.

Spuštění místního sestavení doplňku DynamoRevit v aplikaci Revit

Aplikace Revit vyžaduje k rozpoznání doplňku DynamoRevit soubor doplňku, který instalační program vytvoří automaticky. Při vývoji je nutné ručně vytvořit soubor doplňku odkazující na sestavení doplňku DynamoRevit, které chceme používat, konkrétně na sestavu DynamoRevitDS.dll. Také musíme doplněk DynamoRevit odkázat na sestavení aplikace Dynamo.

Vytvořte soubor Dynamo.addin ve složce doplňku aplikace Revit, která se nachází v umístění C:\ProgramData\Autodesk\Revit\Addins\2023. Již jsme nainstalovali verzi doplňku DynamoRevit, takže stačí upravit existující soubor tak, aby ukazoval na nové sestavení.

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

• Zadejte cestu k souboru DynamoRevitDS.dll uvnitř parametru <Assembly>...</Assembly>.

Případně můžeme nechat doplněk načíst nástroj pro výběr verze místo konkrétní sestavy.

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

• Nastavte cestu k souboru <Assembly>...</Assembly> na DynamoRevitVersionSelector.dll.

• Parametr <FullClassName>...</FullClassName> určuje, pro kterou třídu se má vytvořit instance ze sestavy, na kterou jsme odkázali pomocí výše uvedené cesty k prvku sestavy. Tato třída bude vstupním bodem pro náš doplněk.

Kromě toho je nutné odebrat existující aplikaci Dynamo dodávanou s aplikací Revit. Přejděte do složky C:\\Program Files\Autodesk\Revit 2023\AddIns a odstraňte dvě složky, které obsahují aplikaci Dynamo – DynamoForRevit a DynamoPlayerForRevit. Můžete je buď odstranit, nebo je zálohovat do samostatné složky, pokud potřebujete obnovit původní aplikaci Dynamo pro aplikaci Revit.

Druhým krokem je přidání cesty k souborům sestav jádra aplikace Dynamo do souboru Dynamo.config ve složce bin doplňku DynamoRevit. Doplněk DynamoRevit je načte při otevření doplňku v aplikaci Revit. Tento konfigurační soubor umožňuje odkazovat doplněk DynamoRevit na různé verze jádra aplikace Dynamo při vývoji a testování změn v jádru i v doplňku DynamoRevit.

Kód by měl vypadat následovně:

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

• Přidejte cestu adresáře složky bin do <add key/>

Aplikaci Dynamo jsme naklonovali a vytvořili těsně před touto ukázkou, abychom zajistili, že bude s doplňkem DynamoRevit dobře fungovat. Cesta adresáře odkazuje na toto sestavení.

Když nyní otevřete aplikaci Revit, měl by se na kartě Správa nacházet doplněk Dynamo.

1. Vyberte kartu Manage.

2. Klikněte na ikonu doplňku Dynamo.

3. Instance doplňku DynamoRevit

Pokud se zobrazí chybové okno s chybějícími sestavami, je pravděpodobné, že se neshodují verze DynamoCore, které jste sestavili, a verze, které se načítají za běhu. Například doplněk DynamoRevit s nejnovějšími balíčky DynamoCore verze 2.0 beta nebude fungovat, pokud se jej pokusíte spustit pomocí knihoven DLL aplikace Dynamo 1.3. Ujistěte se, že obě úložiště mají stejnou verzi a doplněk DynamoRevit získává odpovídající verzi závislých položek NuGet. Ty jsou definovány v souboru package.json úložiště DynamoRevit.

Ladění doplňku DynamoRevit pomocí aplikace Visual Studio

V předchozí části popisující sestavení aplikace Dynamo ze zdroje jsme stručně představili ladění v aplikaci Visual Studio a způsob připojení aplikace Visual Studio k procesu. Na příkladu výjimky v uzlu Wall.ByCurveAndHeight si ukážeme, jak se připojit k procesu, nastavíme body přerušení, projdeme kód a pomocí zásobníku volání určíme zdroj výjimky. Tyto nástroje pro ladění platí obecně pro pracovní postupy vývoje v prostředí .net a stojí za to je prozkoumat i mimo tuto příručku.

• Připojení k procesu propojí spuštěnou aplikaci s aplikací Visual Studio za účelem ladění. Pokud chceme ladit chování, které se vyskytuje v sestavení doplňku DynamoRevit, můžeme otevřít zdrojové soubory doplňku DynamoRevit v aplikaci Visual Studio a připojit proces Revit.exe, který je nadřazeným procesem doplňku DynamoRevit. Aplikace Visual Studio používá k vytvoření připojení mezi sestavami spouštěné doplňkem DynamoRevit a zdrojovým kódem soubor symbolů (.pbd).

• Body přerušení vytvoří ve zdrojovém kódu řádky, ve kterých bude aplikace před spuštěním pozastavena. Pokud nějaký uzel způsobuje selhání doplňku DynamoRevit nebo vrací neočekávaný výsledek, můžeme do zdroje uzlu přidat bod přerušení a proces pozastavit, zobrazit kód a kontrolovat živé hodnoty proměnných, dokud nenajdeme příčinu problému.

• Krokování kódem prochází zdrojový kód řádek po řádku. Můžeme spouštět funkce jednu po druhé, vstoupit do volání funkce nebo vyskočit z právě prováděné funkce.

• Zásobník volání zobrazuje funkci, kterou proces právě spouští, ve vztahu k předchozím voláním funkcí, která vyvolala toto volání funkce. Aplikace Visual Studio nabízí k tomuto zobrazení okno zásobníku volání. Pokud například dojde k výjimce mimo zdrojový kód, můžeme v zásobníku volání vidět cestu k volajícímu kódu.

  Na webu 2 000 Things You Should Know About C# (2 000 věcí, které byste měli vědět o C#) naleznete podrobnější vysvětlení zásobníků hovorů.

Uzel Wall.ByCurveAndHeight vyvolá výjimku, pokud je jako vstup křivky zadán objekt PolyCurve, s následující zprávou: „Metoda převodu na objekt BSPlineCurve není implementována.“ Pomocí ladění můžeme zjistit, proč přesně tento typ geometrie uzel nepřijme jako vstup pro parametr křivky. V tomto příkladu předpokládáme, že doplněk DynamoRevit byl úspěšně vytvořen a lze jej spustit jako doplněk aplikace Revit.

1. Uzel Wall.ByCurveAndHeight vyvolávající výjimku

Začněte otevřením souboru řešení DynamoRevit.All.sln, spuštěním aplikace Revit a spuštěním doplňku DynamoRevit. Poté pomocí okna Attach to Process připojte aplikaci Visual Studio k procesu aplikace Revit.

Aplikace Revit a doplněk DynamoRevit je třeba spustit, aby se zobrazily jako dostupný proces.

1. Výběrem nabídky Debug > Attach to Process... otevřete okno Attach to Process.

2. Nastavte Transport na Default

3. Vyberte proces Revit.exe.

4. Klikněte na tlačítko Attach.

S aplikací Visual Studio připojenou k aplikaci Revit otevřete zdrojový kód uzlu Wall.ByCurveAndHeight v souboru Wall.cs. Tento kód naleznete v Průzkumníku řešení v části Libraries > RevitNodes > Elements v oblasti Public static constructors souboru. Nastavte bod přerušení v konstruktoru typu stěny tak, aby se při spuštění uzlu v aplikaci Dynamo proces přerušil a mohli jsme jednotlivě procházet každý řádek kódu. Konstruktory typu Zero-Touch aplikace Dynamo obvykle začínají na By<parameters>.

1. Soubor třídy s konstruktorem pro uzel Wall.ByCurveAndHeight

2. Bod přerušení nastavíte buď kliknutím vlevo od čísla řádku, nebo kliknutím pravým tlačítkem myši na řádek kódu a výběrem možnosti Breakpoint > Insert Breakpoint.

Po nastavení bodu přerušení je potřeba, aby proces proběhl včetně spuštění funkce Wall.ByCurveAndHeight. Funkci lze v aplikaci Dynamo znovu spustit opakovaným připojením drátu k jednomu z portů uzlu, což vynutí opakované spuštění uzlu. Proces dojde v aplikaci Visual Studio až do bodu přerušení.

1. Po dosažení bodu přerušení se změní jeho ikona.

2. Okno Call Stack (Zásobník volání) zobrazující metodu, která je na řadě.

Nyní procházejte jednotlivé řádky v konstruktoru, dokud nenarazíte na výjimku. Kód zvýrazněný žlutě je další příkaz, který má být spuštěn.

1. Nástroje ladění pro navigaci v kódu

2. Stisknutím ikony Step Over spustíte zvýrazněný kód a po návratu funkce pozastavíte jeho provádění.

3. Další příkaz, který se má spustit, označený žlutým zvýrazněním a šipkou

Když budeme funkcí dále procházet, narazíme na výjimku, která se zobrazí v okně doplňku DynamoRevit. Při pohledu na okno zásobníku volání je vidět, že výjimka byla původně vyvolána metodou s názvem Autodesk.Revit.CurveAPIUtils.CreateNurbsCurve. Naštěstí je zde tato výjimka ošetřena, takže aplikace Dynamo neselhala. Proces ladění nám poskytl kontext problému tím, že nás přivedl k jiné metodě ve zdrojovém kódu.

Protože se nejedná o knihovnu s otevřeným zdrojovým kódem, nemůžeme zde provádět změny. Když nyní máme více informací, můžeme problém nahlásit s poskytnutím širšího kontextu vyplněním problému na Githubu nebo můžeme navrhnout řešení tohoto problému podáním žádosti o přijetí změn.

1. Když narazíme na příkaz způsobující výjimku v souboru Walls.cs, proces ladění nás přivede co nejblíže k jádru problému v uživatelském kódu uvnitř souboru ProtoToRevitCurve.cs.

2. Příkaz způsobující výjimku v souboru ProtoToRevitCurve.cs.

3. V zásobníku volání vidíme, že výjimka pochází z neuživatelského kódu.

4. Místní okno s informacemi o výjimce.

Tento proces lze použít u všech zdrojových souborů, se kterými pracujete. Pokud vyvíjíme knihovnu uzlů Zero-Touch pro aplikaci Dynamo Studio, můžeme otevřít zdroj knihovny a připojit proces aplikace Dynamo pro účely ladění knihovny uzlů. I když vše funguje bezchybně, ladění je skvělý způsob, jak prozkoumat kód a zjistit, jak věci fungují.

Získání nejnovějšího sestavení

Tento proces je téměř identický se získáváním změn pro aplikaci Dynamo, jen je třeba se ujistit, že se nacházíme ve správné větvi. Pomocí příkazu git branch v úložišti aplikace DynamoRevit zjistíte, které větve jsou k dispozici místně a které jsou aktuálně zarezervované.

Příkaz cd C:\Users\username\Documents\GitHub\DynamoRevit nastaví aktuální adresář do úložiště aplikace DynamoRevit. Příkaz git branch ověřuje, zda se nacházíte ve správné větvi, tj. RC2.13.1_Revit2023. Příkaz git pull origin RC2.13.1_Revit2023 získává změny ze vzdálené původní větve RC2.13.1_Revit2023.

Parametr origin jednoduše odkazuje na původní adresu URL, kterou jsme klonovali.

Chceme si být vědomi, ve které větvi se momentálně nacházíme a ze které se získáváme změny, abychom se vyhnuli například získávání změn z RC2.13.1_Revit2023 do Revit2018.

Jak je uvedeno v části popisující sestavení aplikace Dynamo ze zdroje, až budeme připraveni odeslat změnu do úložiště doplňku DynamoRevit, můžeme vytvořit požadavek na přijetí změn podle pokynů týmu aplikace Dynamo uvedených v části Žádosti o přijetí změn.

Kdy se tato wiki použije

Při práci na nové funkci nebo při aktualizaci stávající závislosti byste měli před vložením nové závislosti do úložiště aplikace Dynamo vyhodnotit následující skutečnosti.

Skutečnosti ke zvážení:

1. Jaká je licence nové nebo aktualizované závislosti. Bez konzultace s právním oddělením společnosti Autodesk jsou schváleny pouze některé licence open source.

   • Po vyřešení otázky licence se ujistěte, že jsou v interní wiki zaznamenány informace o závislostech a verzi.

   • Pokud je licence LGPL, GPL nebo Apache, musí být licenční soubor zkopírován do podsložky Open Source Licenses sestavení aplikace Dynamo.

   • Jestliže je licence LGPL, musí být na stránku www.autodesk.com/lgplsource nahrán úplný zdrojový kód všech komponent třetích stran spolu s textovými kopiemi jejich příslušných licencí open source.

2. Změnil se při aktualizaci typ licence oproti předchozí verzi?

3. Je závislost multiplatformní?

   • Má nativní komponenty (jako CEFSharp nebo ImageMagick)? Pokud ano, ztíží to nasazení napříč platformami.

   • Obsahuje reference pouze na systém Windows? Pokud ano, neměla by to být závislost na komponentě Dynamo Core nebo jiných multiplatformních částech Dynama (hladina modelu).

4. Je závislost při sestavení správně přibalena do složky bin se všemi požadovanými závislostmi?

   • Jsou při aktualizaci v důsledku aktualizace odebrány některé soubory? Je tato verze aplikace Dynamo určena pro minoritní verze hostitelských produktů? Pokud ano, budete muset ponechat staré binární soubory až do vydání globální (hlavní) verze, abyste mohli podporovat instalační programy oprav. Viz podrobnosti zde.

5. Je závislost nebo její strom závislostí v konfliktu s jinými existujícími závislostmi v aplikaci Dynamo?

6. ?? Je závislost nebo její strom závislostí v konfliktu s existujícími závislostmi v produktech, které integrují aplikaci Dynamo do procesu (Revit, Civil atd.)? To je důležité, protože tyto problémy lze odhalit až v době integrace, pokud není předem provedena kontrola.

Platforma Dynamo je navržena tak, aby se přispěvateli mohli stát všichni uživatelé, bez ohledu na úroveň jejich zkušeností. Existuje několik možností vývoje, které se zaměřují na různé schopnosti a úrovně dovedností, přičemž každá má své silné a slabé stránky v závislosti na cíli. Níže uvádíme různé možnosti a způsob, jak si vybrat jednu z nich.

Tři vývojová prostředí: Visual Studio, Editor jazyka Python a Blok kódů s jazykem DesignScript

Jaké máte možnosti?

Možnosti vývoje pro aplikaci Dynamo spadají primárně do dvou kategorií: pro aplikaci Dynamo a v aplikaci Dynamo. Tyto dvě kategorie si lze představit takto: „v“ aplikaci Dynamo znamená obsah vytvořený pomocí vývojového prostředí aplikace Dynamo, který bude použit v aplikaci Dynamo, a „pro“ aplikaci Dynamo znamená použití externích nástrojů k vytvoření obsahu, který bude importován do aplikace Dynamo a poté zde použit. Ačkoliv je tato příručka zaměřena na vývoj pro aplikaci Dynamo, níže jsou popsány zdroje pro všechny procesy.

Pro aplikaci Dynamo

Tyto uzly umožňují nejvyšší stupeň přizpůsobení. Touto metodou je sestaveno mnoho balíčků a je nezbytná pro přispívání do zdrojů aplikace Dynamo. Proces jejich sestavení bude popsán v této příručce.

• Uzly Zero Touch

• Uzly odvozené z uzlů NodeModel

• Rozšíření

V této příručce naleznete pokyny k importu knihoven Zero-Touch.

V následujícím pojednání je jako vývojové prostředí pro uzly Zero-Touch a NodeModel použita aplikace Visual Studio.

Rozhraní aplikace Visual Studio s projektem, který budeme vyvíjet.

V aplikaci Dynamo

Ačkoli tyto procesy existují v pracovním prostoru vizuálního programování a jsou poměrně přímočaré, všechny představují vhodné možnosti pro přizpůsobení aplikace Dynamo. Tato příručka se jimi podrobně zabývá a v kapitole Strategie skriptování poskytuje tipy a osvědčené postupy.

• Bloky kódu zobrazují jazyk DesignScript ve vizuálním programovacím prostředí a umožňují flexibilní práci s textovým skriptem a uzly. Funkci v bloku kódu může volat cokoli v pracovním prostoru.

  Stáhněte si příklad bloku kódu (klikněte pravým tlačítkem a uložte jej) nebo si v této příručce prohlédněte podrobnou ukázku.

• Vlastní uzly jsou kontejnery pro kolekce uzlů nebo dokonce celých grafů. Jsou účinným způsobem, jak shromažďovat často používané postupy a sdílet je s komunitou.

  Stáhněte si příklad vlastního uzlu (klikněte pravým tlačítkem a uložte jej) nebo si v této příručce prohlédněte podrobnou ukázku.

• Uzly jazyka Python jsou skriptovací rozhraní v pracovním prostoru vizuálního programování, podobně jako bloky kódu. Knihovny Autodesk.DesignScript používají tečkovou notaci podobnou jazyku DesignScript.

  Stáhněte si příklad uzlu jazyka Python (klikněte pravým tlačítkem a uložte jej) nebo si v této příručce prohlédněte podrobnou ukázku.

Vývoj v pracovním prostoru Dynamo představuje výkonný nástroj pro získání okamžité zpětné vazby.

Vývoj v pracovním prostoru aplikace Dynamo pomocí uzlu jazyka Python

Jaké jsou výhody/nevýhody jednotlivých možností vývoje?

Možnosti vývoje aplikace Dynamo byly navrženy tak, aby řešily složitost potřeby přizpůsobení. Ať už je cílem napsat rekurzivní skript v jazyce Python, nebo sestavit vlastní uživatelské rozhraní uzlu, existují možnosti implementace kódu, které zahrnují pouze to, co je nezbytné pro spuštění.

Bloky kódu, uzel jazyka Python a vlastní uzly v aplikaci Dynamo

Toto jsou přímé možnosti pro psaní kódu ve vizuálním programovacím prostředí aplikace Dynamo. Pracovní prostor vizuálního programování aplikace Dynamo poskytuje přístup k jazyku Python a jazyku DesignScript a umožňuje zahrnout více uzlů do vlastního uzlu.

Pomocí těchto metod můžeme:

• Začít psát kód v jazyce Python nebo DesignScript bez větších nároků na nastavení.

• Importovat knihovny jazyka Python do aplikace Dynamo.

• Sdílet bloky kódu, uzly jazyka Python a vlastní uzly s komunitou aplikace Dynamo v rámci balíčku.

Uzly Zero Touch

Zero-Touch označuje jednoduchou metodu importu knihoven C# pomocí najetí kurzoru a kliknutí. Aplikace Dynamo přečte veřejné metody knihovny .dll a převede je na uzly aplikace Dynamo. Pomocí funkce Zero-Touch můžete vyvíjet své vlastní uzly a balíčky.

Pomocí této metody můžeme:

• Importovat knihovnu, která nebyla nezbytně vyvinuta pro aplikaci Dynamo, a automaticky vytvořit sadu nových uzlů, viz příklad A-Forge v příručce Primer.

• Psát metody C# a snadno je používat jako uzly v aplikaci Dynamo.

• Sdílet knihovny C# jako uzly s komunitou aplikace Dynamo v balíčku

Uzly odvozené z uzlů NodeModel

Tyto uzly jsou krokem hlouběji do struktury aplikace Dynamo. Jsou založeny na třídě NodeModel a napsány v jazyce C#. Tato metoda sice poskytuje největší flexibilitu a výkon, ale většina aspektů uzlu musí být explicitně definována a funkce musí být umístěny v samostatné sestavě.

Pomocí této metody můžeme:

• Vytvářet plně přizpůsobitelné uživatelské rozhraní uzlu s posuvníky, obrázky, barvami atd. (např. uzel ColorRange).

• Přistupovat k tomu, co se děje na kreslicí ploše aplikace Dynamo, a ovlivňovat to.

• Přizpůsobit vázání.

• Načítat uzly do aplikace Dynamo jako balíček.

Informace o změnách verzí aplikace Dynamo a rozhraní API (1.x → 2.x)

Protože je aplikace Dynamo pravidelně aktualizována, mohou být provedeny změny v části rozhraní API, které jsou používány v balíčku. Sledování těchto změn je důležité pro zajištění správné funkce stávajících balíčků.

Změny rozhraní API jsou sledovány na stránce Wiki aplikace Dynamo na Githubu. Sledovány jsou změny v jádru aplikace Dynamo, knihovnách a pracovních prostorech.

Příkladem nadcházející významné změny je přechod z formátu XML na formátu souboru JSON ve verzi 2.0. Uzly odvozené z uzlu NodeModel nyní potřebují konstruktor JSON, jinak se neotevřou v aplikaci Dynamo 2.0.

Dokumentace rozhraní API aplikace Dynamo aktuálně pokrývá hlavní funkce: http://dynamods.github.io/DynamoAPI

Oprávnění k distribuci binárních souborů v balíčku

Dávejte pozor na soubory DLL obsažené v balíčku, který je nahráván do správce balíčků. Pokud autor balíčku nevytvořil knihovnu .dll, musí mít práva na její sdílení.

Jestliže balíček obsahuje binární soubory, je nutné uživatele při stahování upozornit, že balíček obsahuje binární soubory.

Důležité informace o výkonu uživatelského rozhraní aplikace Dynamo

V době psaní tohoto článku používá aplikace Dynamo k vykreslování uživatelského rozhraní primárně WPF (Windows Presentation Foundation). WPF je složitý a výkonný systém založený na XAML/vazbě. Vzhledem k tomu, že Dynamo má složité uživatelské rozhraní, je snadné způsobit jeho zablokování, úniky paměti nebo zabalit provádění grafu a aktualizace uživatelského rozhraní dohromady způsobem, který snižuje výkon.

Podívejte se na stránku wiki zabývající se různými aspekty výkonu aplikace Dynamo, která vám pomůže vyhnout se několika běžným nástrahám při provádění změn v kódu aplikace Dynamo.

Než se pustíte do vývoje, je důležité vybudovat pevné základy nového projektu. V komunitě vývojářů aplikace Dynamo existuje několik šablon projektů, které jsou vynikajícím východiskem pro zahájení práce, ale ještě cennější je porozumět tomu, jak začít projekt od začátku. Vytvoření projektu od základů umožní hlubší pochopení procesu vývoje.

Vytvoření projektu aplikace Visual Studio

Visual Studio je výkonné integrované vývojové prostředí, ve kterém můžeme vytvořit projekt, přidat odkazy, vytvořit knihovny .dlls a provádět ladění. Při tvorbě nového projektu vytvoří aplikace Visual Studio také tzv. řešení, což je struktura pro uspořádání projektů. V rámci jednoho řešení může existovat více projektů, které lze vytvářet společně. Chcete-li vytvořit uzel ZeroTouch, bude nutné vytvořit nový projekt aplikace Visual Studio, do kterého zapíšeme knihovnu tříd C# a vytvoříme knihovnu .dll.

Okno Nový projekt v aplikaci Visual Studio

1. Začněte otevřením aplikace Visual Studio a vytvořením nového projektu: File > New > Project.

2. Vyberte šablonu projektu Class Library.

3. Pojmenujte projekt (v tomto příkladu je název projektu MyCustomNode).

4. Nastavte cestu k souboru projektu. V tomto příkladu jej necháme ve výchozím umístění.

5. Klikněte na tlačítko Ok.

Aplikace Visual Studio automaticky vytvoří a otevře soubor v jazyce C#. Měli bychom mu dát vhodný název, nastavit pracovní prostor a nahradit výchozí kód touto metodou násobení.

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

1. Z nabídky View otevřete okna Průzkumník řešení a Výstup.

2. V Průzkumníku řešení na pravé straně přejmenujte soubor Class1.cs na SampleFunctions.cs.

3. Přidejte výše uvedený kód pro funkci násobení. Způsob, jak aplikace Dynamo přečte vaše třídy C#, probereme později.

4. Průzkumník řešení: Poskytuje přístup ke všem položkám v projektu.

5. Okno Výstup: Později jej budeme potřebovat, abychom zjistili, zda bylo sestavení úspěšné.

Dalším krokem je sestavení projektu, ale před provedením tohoto kroku je třeba zkontrolovat několik nastavení. Nejprve se ujistěte, že jako cílová platforma je vybrána možnost Any CPU nebo x64 a že ve vlastnostech projektu není zaškrtnuto políčko Prefer 32-bit.

1. Otevřete vlastnosti projektu výběrem Project > "ProjectName" Properties.

2. Vyberte stránku Build.

3. V rozevírací nabídce vyberte možnost Any CPU nebo x64.

4. Ujistěte se, že není zaškrtnuto políčko Prefer 32-bit.

Nyní můžeme sestavit projekt, který vytvoří knihovnu .dll. To provedete buď výběrem položky Build Solution v nabídce Build nebo pomocí klávesové zkratky CTRL+SHIFT+B.

1. Vyberte Build > Build Solution.

2. Úspěšné sestavení projektu můžete ověřit v okně Výstup.

Pokud byl projekt úspěšně vytvořen, bude ve složce projektu bin uvedena knihovna .dll s názvem MyCustomNode. V tomto příkladu jsme pro cestu k souborům projektu ponechali výchozí nastavení aplikace Visual Studio, tj. c:\users\username\documents\visual studio 2015\Projects. Podívejme se na strukturu souborů projektu.

1. Složka bin obsahuje knihovnu .dll vytvořenou z aplikace Visual Studio.

2. Soubor projektu aplikace Visual Studio.

3. Soubor třídy.

4. Protože byla konfigurace řešení nastavena na Debug, bude knihovna .dll vytvořena ve složce bin\Debug.

Nyní můžeme otevřít aplikaci Dynamo a importovat knihovnu .dll. Pomocí funkce Přidat přejděte do umístění projektu bin a vyberte knihovnu .dll, kterou chcete otevřít.

1. Klikněte na tlačítko Přidat, abyste mohli importovat knihovnu .dll.

2. Přejděte do umístění projektu. Projekt se nachází ve výchozí cestě k souborům aplikace Visual Studio: C:\Users\username\Documents\Visual Studio 2015\Projects\MyCustomNode

3. Vyberte soubor MyCustomNode.dll, který chcete importovat.

4. Kliknutím na tlačítko Open načtěte soubor .dll.

Pokud je v knihovně vytvořena kategorie s názvem MyCustomNode, byla knihovna .dll úspěšně importována! Aplikace Dynamo však vytvořila dva uzly, přičemž my jsme chtěli mít pouze jeden uzel. V další části vysvětlíme, proč k tomu dochází a jak aplikace Dynamo načítá knihovnu .dll.

1. Kategorie MyCustomNode v knihovně aplikace Dynamo. Kategorie knihovny je určena názvem knihovny .dll.

2. Uzel SampleFunctions.MultiplyByTwo na kreslicí ploše.

Jak aplikace Dynamo čte třídy a metody

Když aplikace Dynamo načte knihovnu .dll, zobrazí všechny veřejné statické metody jako uzly. Konstruktory, metody a vlastnosti budou převedeny na uzly pro tvorbu, akci a dotazování. V našem příkladu násobení se metoda MultiplyByTwo() v aplikaci Dynamo stane uzlem akce. Je tomu tak proto, že uzel byl pojmenován na základě své metody a třídy.

1. Vstup je pojmenován inputNumber na základě názvu parametru metody.

2. Ve výchozím nastavení je výstup pojmenován double, protože se jedná o tento vrácený typ dat.

3. Uzel je pojmenován SampleFunctions.MultiplyByTwo, protože se jedná o názvy tříd a metod.

Ve výše uvedeném příkladu byl vytvořen uzel tvorby SampleFunctions, protože jsme explicitně neposkytli konstruktor, a proto byl vytvořen automaticky. Tomu se můžeme vyhnout vytvořením prázdného soukromého konstruktoru ve třídě SampleFunctions.

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

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

1. Aplikace Dynamo naimportovala naši metodu jako uzel tvorby.

Přidání referencí na balíčky NuGet aplikace Dynamo

Uzel násobení je velmi jednoduchý a nejsou nutné žádné odkazy na aplikaci Dynamo. Pokud ale chceme získat přístup k některé z funkcí aplikace Dynamo, například k vytváření geometrie, bude nutné odkazovat na balíčky NuGet aplikace Dynamo.

• ZeroTouchLibrary – Balíček pro vytváření knihoven uzlů Zero Touch pro aplikaci Dynamo, který obsahuje následující knihovny: DynamoUnits.dll a ProtoGeometry.dll.

• WpfUILibrary – Balíček pro vytváření knihoven uzlů pro aplikaci Dynamo s vlastním uživatelským rozhraním ve WPF, který obsahuje následující knihovny: DynamoCoreWpf.dll, CoreNodeModels.dll a CoreNodeModelWpf.dll.

• DynamoServices – Knihovna DynamoServices pro aplikaci Dynamo.

• Core – Infrastruktura pro testování jednotek a systémů pro aplikaci Dynamo, která obsahuje následující knihovny: DSIronPython.dll, DynamoApplications.dll, DynamoCore.dll, DynamoInstallDetective.dll, DynamoShapeManager.dll, DynamoUtilities.dll, ProtoCore.dll a VMDataBridge.dll.

• Tests – Infrastruktura pro testování jednotek a systémů aplikace Dynamo, která obsahuje následující knihovny: DynamoCoreTests.dll, SystemTestServices.dll a TestServices.dll.

• DynamoCoreNodes – Balíček pro vytváření hlavních uzlů pro aplikaci Dynamo, který obsahuje následující knihovny: Analysis.dll, GeometryColour.dll a DSCoreNodes.dll.

Chcete-li v projektu aplikace Visual Studio odkazovat na tyto balíčky, stáhněte si požadovaný balíček z webu NuGet pomocí výše uvedených odkazů a ručně odkazujte na knihovny .dll, nebo použijte Správce balíčků NuGet v aplikaci Visual Studio. Nejprve si ukážeme, jak je nainstalovat pomocí Správce balíčků NuGet v aplikaci Visual Studio.

1. Otevřete Správce balíčků NuGet výběrem možnosti Tools > NuGet Package Manager > Manage NuGet Packages for Solution....

Toto je Správce balíčků NuGet. Toto okno ukazuje, jaké balíčky byly pro projekt nainstalovány, a umožňuje uživateli vyhledat další. Pokud je vydána nová verze balíčku DynamoServices, lze odtud balíčky aktualizovat nebo vrátit ke starší verzi.

1. Klikněte na tlačítko Procházet a vyhledáním položky DynamoVisualProgramming zobrazte balíčky aplikace Dynamo.

2. Balíčky aplikace Dynamo Výběrem některého z nich zobrazíte jeho aktuální verzi a popis toho, co je uvnitř.

3. Vyberte verzi balíčku, kterou potřebujete, a klikněte na tlačítko Instalovat. Tím se nainstaluje balíček pro konkrétní projekt, se kterým pracujete. Protože používáme nejnovější stabilní verzi aplikace Dynamo, verzi 1.3, vyberte odpovídající verzi balíčku.

Chcete-li ručně přidat balíček stažený z prohlížeče, otevřete Správce odkazů z Průzkumníku řešení a vyhledejte požadovaný balíček.

1. Klikněte pravým tlačítkem myši na položku References a vyberte příkaz Add Reference.

2. Klikněte na tlačítko Browse a přejděte do umístění balíčku.

Nyní, když je aplikace Visual Studio správně nakonfigurována a úspěšně jsme přidali knihovnu .dll do aplikace Dynamo, máme pevný základ pro další koncepty. Toto je pouze začátek, proto pokračujte dalším tématem, ve kterém se dozvíte více o tom, jak vytvořit vlastní uzel.

Po spuštění projektu v aplikaci Visual Studio si ukážeme, jak vytvořit vlastní uzel, který vytvoří obdélníkovou osnovu buněk. Ačkoli bychom ji mohli vytvořit pomocí několika standardních uzlů, jedná se o užitečný nástroj, který lze snadno umístit v uzlu Zero-Touch. Na rozdíl od čar osnovy lze velikost buněk měnit kolem středových bodů, dotazovat se na rohové vrcholy nebo je zabudovat do ploch.

V tomto příkladu si představíme několik funkcí a konceptů, které je třeba znát při vytváření uzlu Zero-Touch. Po vytvoření vlastního uzlu a jeho přidání do aplikace Dynamo si projděte stránku Další práce s funkcí Zero-Touch, kde naleznete podrobnější informace o výchozích vstupních hodnotách, vrácení více hodnot, dokumentaci, objektech, použití typů geometrií aplikace Dynamo a migraci.

Vlastní uzel obdélníkové osnovy

Chcete-li začít vytvářet uzel osnovy, vytvořte nový projekt knihovny tříd aplikace Visual Studio. Podrobné informace o nastavení projektu naleznete na stránce Začínáme.

1. Vyberte Class Library pro typ projektu.

2. Pojmenujte projekt jako CustomNodes.

Protože budeme vytvářet geometrii, je nutné odkazovat na příslušný balíček NuGet. Ze správce balíčků NuGet nainstalujte balíček ZeroTouchLibrary. Tento balíček je nezbytný pro příkaz using Autodesk.DesignScript.Geometry;.

1. Procházením vyhledejte balíček ZeroTouchLibrary.

2. Tento uzel použijeme v aktuálním sestavení aplikace Dynamo Studio, které je 1.3. Vyberte verzi balíčku, která odpovídá této verzi.

3. Všimněte si, že jsme také přejmenovali soubor třídy na Grids.cs.

Dále je potřeba vytvořit jmenný prostor a třídu, ve které bude umístěna metoda RectangularGrid. Uzel bude v aplikaci Dynamo pojmenován podle názvů metod a tříd. Tento kód ještě není nutné kopírovat do aplikace 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
        }
    }
}

Autodesk.DesignScript.Geometry; odkazuje na soubor ProtoGeometry.dll v balíčku ZeroTouchLibrary. System.Collections.Generic je nutný k vytváření seznamů.

Nyní můžeme přidat metodu pro kreslení obdélníků. Soubor třídy by měl vypadat takto a lze jej zkopírovat do aplikace 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;
        }
    }
}

Pokud projekt vypadá podobně jako tento, pokračujte a zkuste sestavit knihovnu .dll.

1. Zvolte Sestavit > Sestavit řešení.

Zkontrolujte složku projektu bin pro knihovnu .dll. Pokud bylo sestavení úspěšné, můžeme přidat knihovnu .dll do aplikace Dynamo.

1. Vlastní uzel RectangularGrids v knihovně aplikace Dynamo

2. Vlastní uzel na kreslicí ploše

3. Tlačítko Přidat pro přidání knihovny .dll do aplikace Dynamo

Úpravy vlastních uzlů

Ve výše uvedeném příkladu jsme vytvořili poměrně jednoduchý uzel, který kromě metody RectangularGrids nedefinoval nic dalšího. Můžeme však chtít vytvořit popisky pro vstupní porty nebo poskytnout uzlu souhrn jako u standardních uzlů aplikace Dynamo. Přidání těchto funkcí do vlastních uzlů usnadní jejich používání, zejména pokud je uživatel chce vyhledávat v knihovně.

1. Výchozí vstupní hodnota

2. Popisek pro vstup xCount

Uzel RectangularGrid potřebuje některé z těchto základních funkcí. V níže uvedeném kódu jsme přidali popisy vstupních a výstupních portů, souhrn a výchozí vstupní hodnoty.

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

• Přiřazením hodnot parametrům metody přiřaďte vstupům výchozí hodnoty: RectangularGrid(int xCount = 10, int yCount = 10)

• Vytvořte popisky vstupu a výstupu, klíčová slova pro vyhledávání a souhrn s dokumentací XML, před nimiž zadejte ///.

K přidání popisků je potřeba soubor XML v adresáři projektu. V aplikaci Visual Studio je možné automaticky vytvořit soubor .xml, pokud tuto možnost povolíte.

1. Zde povolte soubor dokumentace XML a zadejte cestu k souboru. Tím se vytvoří soubor XML.

A je to! Vytvořili jsme nový uzel s několika standardními funkcemi. Následující kapitola Základy funkce Zero-Touch obsahuje podrobnější informace o vývoji uzlů Zero-Touch a o problémech, na které je třeba dávat pozor.

Provádění skriptů jazyka Python v uzlech Zero-Touch (C#)

Pokud umíte psát skripty v jazyce Python a chcete více funkcí, než vám mohou nabídnout standardní uzly jazyka Python aplikace Dynamo, můžete si pomocí funkce Zero-Touch vytvořit vlastní uzel. Začneme jednoduchým příkladem, který nám umožní předat skript jazyka Python jako řetězec uzlu Zero-Touch, kde se skript provede a vrátí se výsledek. Tato případová studie bude vycházet z ukázek a příkladů v části Začínáme. Pokud s tvorbou uzlů Zero-Touch úplně začínáte, podívejte se na ně.

Uzel Zero-Touch, který provede řetězec skriptu jazyka Python

Modul jazyka Python

Tento uzel se spoléhá na instanci skriptovacího modulu IronPython. K tomu potřebujeme odkazovat na několik dalších sestav. Podle následujících kroků nastavte základní šablonu v aplikaci Visual Studio:

• Vytvořte nový projekt třídy aplikace Visual Studio.

• Přidejte odkaz na soubor IronPython.dll umístěný ve složce C:\Program Files (x86)\IronPython 2.7\IronPython.dll.

• Přidejte odkaz na soubor Microsoft.Scripting.dll umístěný ve složce C:\Program Files (x86)\IronPython 2.7\Platforms\Net40\Microsoft.Scripting.dll.

• Zahrňte do třídy příkazy IronPython.Hosting a Microsoft.Scripting.Hosting using.

• Přidejte soukromý prázdný konstruktor, abyste zabránili přidání dalšího uzlu do knihovny aplikace Dynamo spolu s naším balíčkem.

• Vytvořte novou metodu, která jako vstupní parametr přijímá jeden řetězec.

• V rámci této metody vytvoříme novou instanci modulu jazyka Python a prázdný rozsah skriptu. Tento rozsah si můžete představit jako globální proměnné v rámci instance interpretu jazyka Python.

• Poté pro modul volejte Execute a jako parametry předejte vstupní řetězec a rozsah.

• Nakonec načtěte a vraťte výsledky skriptu voláním GetVariable pro modul a předáním názvu proměnné ze skriptu jazyka Python, která obsahuje hodnotu, kterou se pokoušíte vrátit. (Další podrobnosti naleznete v níže uvedeném příkladu.)

Následující kód představuje příklad výše uvedených kroků. Sestavením řešení se vytvoří nová knihovna .dll umístěná ve složce bin našeho projektu. Tuto knihovnu .dll lze nyní importovat do aplikace Dynamo jako součást balíčku nebo pomocí příkazu File < Import Library....

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

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

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

Skript jazyka Python vrací proměnnou output, což znamená, že ve skriptu jazyka Python budeme potřebovat proměnnou output. K otestování uzlu v aplikaci Dynamo použijte tento vzorový skript. Pokud jste někdy v aplikaci Dynamo použili uzel jazyka Python, měl by vám následující skript být povědomý. Další informace naleznete v části Python v příručce Primer.

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

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

Více výstupů

Jedním z omezení standardních uzlů jazyka Python je, že mají pouze jeden výstupní port, takže pokud chceme vrátit více objektů, musíme sestavit seznam a načíst každý objekt v něm. Pokud upravíme výše uvedený příklad tak, aby vracel slovník, můžeme přidat libovolný počet výstupních portů. Další informace o slovnících naleznete v části Vrácení více hodnot v tématu Další práce s funkcí Zero-Touch.

Tento uzel umožňuje vrátit objem kvádru i jeho těžiště.

Upravte předchozí příklad pomocí následujících kroků:

• Přidejte odkaz na knihovnu DynamoServices.dll ze Správce balíčků NuGet.

• Kromě předchozích sestav zahrňte System.Collections.Generic a Autodesk.DesignScript.Runtime.

• Upravte návratový typ naší metody tak, aby vracela slovník, který bude obsahovat naše výstupy.

• Každý výstup musí být z rozsahu načten jednotlivě (pro větší sady výstupů zvažte vytvoření jednoduché smyčky).

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

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

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

Do vzorového skriptu jazyka Python jsme také přidali další výstupní proměnnou (output2). Mějte na paměti, že tyto proměnné mohou používat jakékoli dovolené konvence pojmenování v jazyce Python, název „output“ byl v tomto příkladu použit výhradně kvůli srozumitelnosti.

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

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

Když nyní víme, jak vytvořit projekt Zero-Touch, můžeme se podrobněji seznámit se specifiky vytváření uzlu a projít si příklad ZeroTouchEssentials na Githubu aplikace Dynamo.

Mnoho standardních uzlů aplikace Dynamo jsou v podstatě uzly Zero-Touch, například většina výše uvedených uzlů Math, Color a DateTime.

Nejprve si stáhněte projekt ZeroTouchEssentials z tohoto umístění: https://github.com/DynamoDS/ZeroTouchEssentials

V aplikaci Visual Studio otevřete soubor řešení ZeroTouchEssentials.sln a sestavte řešení.

Soubor ZeroTouchEssentials.cs obsahuje všechny metody, které budeme importovat do aplikace Dynamo.

Otevřete aplikaci Dynamo a importujte knihovnu ZeroTouchEssentials.dll, abyste získali uzly, na které budeme odkazovat v následujících příkladech.

Příklady kódu jsou získány ze souboru ZeroTouchEssentials.cs a obecně se s ním shodují. Dokumentace XML byla odstraněna, aby byl projekt stručnější, a každý příklad kódu vytvoří uzel na obrázku nad ním.

Výchozí vstupní hodnota

Aplikace Dynamo podporuje definici výchozích hodnot vstupních portů v uzlu. Tyto výchozí hodnoty budou do uzlu zadány, pokud porty nemají žádná připojení. Výchozí hodnoty jsou vyjádřeny pomocí mechanismu jazyka C# pro zadávání volitelných argumentů popsaném v Příručce programování v jazyce C#. Výchozí hodnoty jsou určeny následujícím způsobem:

• Nastavte parametry metody na výchozí hodnotu: 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. Výchozí hodnota se zobrazí, když umístíte kurzor nad vstupní port uzlu.

Vrácení více hodnot

Vracení více hodnot je o něco složitější než vytváření více vstupů a je třeba je vracet pomocí slovníku. Položky slovníku se stanou porty na výstupní straně uzlu. Porty vracející více hodnot se vytvářejí následujícím způsobem:

• Přidejte using System.Collections.Generic; pro použití položky Dictionary<>.

• Přidejte using Autodesk.DesignScript.Runtime; pro použití atributu MultiReturn. Tento kód odkazuje na knihovnu DynamoServices.dll z balíčku DynamoServices NuGet.

• Přidejte do metody atribut [MultiReturn(new[] { "string1", "string2", ... more strings here })]. Řetězce odkazují na klíče ve slovníku a stanou se názvy výstupních portů.

• Vraťte Dictionary<> z funkce s klíči, které odpovídají názvům parametrů v atributu: 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) }
            };
        }
    }
}

Podívejte se na tento příklad kódu v souboru ZeroTouchEssentials.cs.

Uzel, který vrací více výstupů.

1. Všimněte si, že nyní existují dva výstupní porty pojmenované podle řetězců, které jsme zadali pro klíče slovníku.

Dokumentace, popisky a vyhledávání

Osvědčeným postupem je přidat k uzlům aplikace Dynamo dokumentaci, která popisuje funkci uzlu, vstupy, výstupy, vyhledávací štítky atd. To se provádí pomocí štítků dokumentace XML. Dokumentace XML je vytvořena následujícím způsobem:

• Za dokumentaci se považuje jakýkoli text komentáře, kterému předcházejí tři lomítka.

  • Například: /// Documentation text and XML goes here

• Za třemi lomítky vytvořte nad metodami štítky XML, které aplikace Dynamo přečte při importu knihovny DLL.

  • Například: /// <summary>...</summary>

• Povolte dokumentaci XML v aplikaci Visual Studio výběrem možnosti Project > [Project] Properties > Build > Output a zaškrtnutím políčka Documentation file.

1. Aplikace Visual Studio vygeneruje soubor XML v zadaném umístění.

Typy štítků jsou následující:

• /// <summary>...</summary> je hlavní dokumentace pro uzel a zobrazí se jako popisek nad uzlem v levém postranním panelu vyhledávání.

• /// <param name="inputName">...</param> vytvoří dokumentaci pro specifické vstupní parametry.

• /// <returns>...</returns> vytvoří dokumentaci pro výstupní parametr.

• /// <returns name = "outputName">...</returns> vytvoří dokumentaci pro více výstupních parametrů.

• /// <search>...</search> porovná uzel s výsledky hledání na základě seznamu odděleného čárkou. Pokud například vytvoříme uzel, který rozdělí síť, může být vhodné přidat štítky jako „sít“, „dělení“ a „catmull-clark“.

Níže je uveden příklad uzlu s popisem vstupu a výstupu a také souhrnem, který se zobrazí v knihovně.

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

Podívejte se na tento příklad kódu v souboru ZeroTouchEssentials.cs.

Všimněte si, že kód pro tento vzorový uzel obsahuje:

1. Souhrn uzlu

2. Popis vstupu

3. Popis výstupu

Popisy uzlů aplikace Dynamo – osvědčené postupy

Popisy uzlů stručně popisují funkci a výstup uzlu. V aplikaci Dynamo se objevují na dvou místech:

• V popisku nástroje uzlu.

• V Prohlížeči dokumentace.

Dodržováním těchto pokynů zajistíte konzistenci a ušetříte čas při psaní nebo aktualizaci popisů uzlů.

Přehled

Popis by měl obsahovat jednu až dvě věty. Pokud jsou potřeba další informace, uveďte je v Prohlížeči dokumentace v části Podrobnosti.

Větná stavba (první slovo věty a vlastní podstatná jména pište s velkým počátečním písmenem). Na konci není tečka.

Jazyk by měl být co nejsrozumitelnější a nejjednodušší. Definujte zkratky při první zmínce, pokud nejsou známé i neodborným uživatelům.

Vždy upřednostněte srozumitelnost, i kdyby to mělo znamenat, že se odchýlíte od těchto pokynů.

Pokyny

Upozornění a chyby uzlu v aplikaci Dynamo

Upozornění a chyby uzlů upozorňují uživatel na problém s grafem. Uživatel je na problémy, které narušují normální fungování grafu, upozorněn zobrazením ikony a rozšířenou textovou bublinou nad uzlem. Chyby a upozornění uzlů se mohou lišit podle závažnosti: některé grafy mohou běžet dostatečně i s upozorněními, zatímco jiné blokují očekávané výsledky. Ve všech případech jsou chyby a upozornění uzlů důležitými nástroji, které uživatel průběžně informují o problémech s grafem.

Pokyny k zajištění konzistence a úspoře času při psaní nebo aktualizaci upozornění a chybových zpráv uzlů naleznete na wiki stránce Vzor obsahu: Upozornění a chyby uzlů.

Objekty

Aplikace Dynamo nemá klíčové slovo new, takže objekty bude nutné konstruovat pomocí statických konstrukčních metod. Objekty jsou konstruovány následujícím způsobem:

• Změňte konstruktor na vnitřní internal ZeroTouchEssentials(), pokud není vyžadováno jinak.

• Konstruujte objekt pomocí statické metody, například public static ZeroTouchEssentials ByTwoDoubles(a, b).

Poznámka: Aplikace Dynamo používá předponu „By“ pro označení statické metody jako konstruktoru, a i když je to volitelné, použití předpony „By“ pomůže vaší knihovně lépe se přizpůsobit existujícímu stylu aplikace 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);
        }
    }
}

Podívejte se na tento příklad kódu v souboru ZeroTouchEssentials.cs.

Po importu knihovny dll ZeroTouchEssentials bude v knihovně uzel ZeroTouchEssentials. Tento objekt lze vytvořit pomocí uzlu ByTwoDoubles.

Použití typů geometrie aplikace Dynamo

Knihovny aplikace Dynamo mohou jako vstupy použít nativní typy geometrie aplikace Dynamo a jako výstupy vytvořit novou geometrii. Typy geometrie se vytvářejí následujícím způsobem:

• Odkaz na knihovnu ProtoGeometry.dll v projektu vložte pomocíusing Autodesk.DesignScript.Geometry; na začátek souboru C# a přidáním balíčku ZeroTouchLibrary NuGet do projektu.

• Důležité: Spravujte zdroje geometrie, které nejsou vráceny z funkcí. Další informace naleznete v části Příkazy dispose/using níže.

Poznámka: Objekty geometrie aplikace Dynamo jsou používány jako jakékoli jiné objekty předávané funkcím.

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

Podívejte se na tento příklad kódu v souboru ZeroTouchEssentials.cs.

Uzel, který získá délku křivky a zdvojnásobí ji.

1. Tento uzel přijímá jako vstup typ geometrie Křivka.

Příkazy dispose/using

Zdroje geometrie, které nejsou vráceny z funkcí, bude nutné spravovat ručně, pokud nepoužíváte aplikaci Dynamo verze 2.5 nebo novější. V aplikaci Dynamo 2.5 a novějších verzích jsou zdroje geometrie interně zpracovány systémem, ale i přesto může být nutné odstranit geometrii ručně, pokud máte složitý případ použití nebo potřebujete omezit paměť v pevně dané době. Modul aplikace Dynamo zpracuje všechny zdroje geometrie, které jsou vráceny z funkcí. Zdroje geometrie, které nejsou vráceny, lze zpracovat ručně následujícími způsoby:

• Pomocí příkazu using:

  Copy

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

  Příkaz using je zdokumentován zde.

  Další informace o nových funkcích stability v aplikaci Dynamo 2.5 naleznete v části Vylepšení stability geometrie aplikace Dynamo.

• Pomocí ručního volání příkazu 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;

Migrace

Při publikování novější verze knihovny se mohou změnit názvy uzlů. Změny názvů lze zadat v souboru migrace, aby grafy vytvořené na základě předchozích verzí knihovny správně fungovaly i po aktualizaci. Migrace jsou implementovány následujícím způsobem:

• Vytvořte soubor .xml ve stejné složce jako soubor .dll v následujícím formátu: „BaseDLLName“.Migrations.xml.

• V souboru .xml vytvořte jeden prvek <migrations>...</migrations>.

• V prvku migrace vytvořte prvky <priorNameHint>...</priorNameHint> pro každou změnu názvu.

• Pro každou změnu názvu zadejte prvek <oldName>...</oldName> a <newName>...</newName>.

1. Klikněte pravým tlačítkem myši a vyberte příkaz Add > New Item.

2. Zvolte XML File.

3. Pro tento projekt bychom soubor migrace pojmenovali ZeroTouchEssentials.Migrations.xml.

Tento vzorový kód sděluje aplikaci Dynamo, že každý uzel s názvem GetClosestPoint má nyní název ClosestPointTo.

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

Podívejte se na tento příklad kódu v souboru ProtoGeometry.Migrations.xml.

Obecné typy

Funkce Zero-Touch v současné době nepodporuje použití generických typů. Lze je použít, ale ne v kódu, který je přímo importován tam, kde tento typ není nastaven. Metody, vlastnosti nebo třídy, které jsou obecné a nemají sadu typů, nelze zpřístupnit.

V níže uvedeném příkladu nebude importován uzel Zero-Touch typu T. Pokud bude zbytek knihovny importován do aplikace Dynamo, budou existovat výjimky chybějících typů.

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

Použití obecného typu s typem nastaveným v tomto příkladu bude importováno do aplikace Dynamo.

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

Se základními znalostmi ZeroTouch se v této části seznámíme s výhodami přizpůsobení uzlů aplikace Dynamo za účelem zlepšení funkčnosti i usnadnění práce uživatelům. Přidáním funkcí, jako jsou varovné zprávy, informační zprávy a vlastní ikony, můžete vytvářet uzly, které jsou intuitivnější, informativnější a vizuálně poutavější. Tato přizpůsobení nejen pomáhají uživatelům porozumět potenciálním problémům nebo optimalizovat jejich pracovní postupy, ale také díky nim vaše uzly vyniknou jako profesionální a uživatelsky přívětivé nástroje.

Přizpůsobení uzlů je vynikající způsob, jak zajistit, aby vaše řešení byla jasná, spolehlivá a přizpůsobená konkrétním potřebám projektu.

Generování vlastních zpráv s upozorněním pomocí metody OnLogWarningMessage

Metoda OnLogWarningMessage v aplikaci Dynamo umožňuje protokolovat upozornění přímo do konzole aplikace Dynamo. Jedná se o velmi užitečnou funkci, zejména pro uzly Zero Touch, protože umožňuje vývojářům upozornit uživatele na problémy se vstupy nebo parametry, které by mohly vést k neočekávanému chování. V této příručce se dozvíte, jak implementovat metodu OnLogWarningMessage v libovolném uzlu Zero Touch.

Postup implementace metody OnLogWarningMessage

Krok 1: Importujte požadovaný jmenný prostor

Metoda OnLogWarningMessage je součástí jmenného prostoru DynamoServices, takže začněte tím, že ji přidáte do souboru projektu.

using DynamoServices;

Krok 2: Určete, kdy protokolovat upozornění

Před přidáním zprávy s upozorněním zvažte logiku své metody:

• Jaké podmínky mohou způsobit nesprávné nebo neočekávané výsledky?

• Existují specifické vstupní hodnoty nebo parametry, které metoda vyžaduje ke správnému fungování?

Příklady podmínek ke kontrole:

• Hodnoty mimo rozsah (např. if (inputValue < 0)).

• Kolekce s hodnotou null nebo prázdné kolekce (např. if (list == null || list.Count == 0)).

• Neshody datových typů (např. pokud typ souboru není podporován).

Krok 3: Použijte metodu OnLogWarningMessage k protokolování upozornění

Umístěte volání OnLogWarningMessage tam, kde zjistíte podmínky, které by mohly způsobit problémy. Pokud je splněna podmínka, zaprotokolujte zprávu s upozorněním, která uživateli poskytne jasné pokyny.

Syntaxe pro metodu OnLogWarningMessage

LogWarningMessageEvents.OnLogWarningMessage("Your warning message here.");

Příklady implementací metody OnLogWarningMessage

Pro demonstraci možností použití metody OnLogWarningMessage naleznete níže různé scénáře, se kterými se můžete setkat při vytváření uzlu Zero Touch.

Příklad 1: Ověření číselných vstupů

V tomto příkladu budeme vycházet z vlastního uzlu vytvořeném v předchozí části Případová studie funkce Zero-Touch – uzel osnovy; metody pojmenované RectangularGrid, která generuje osnovu obdélníků na základě vstupů xCount a yCount. Otestujeme, zda je vstup neplatný a pak pomocí metody OnLogWarningMessage zaprotokolujeme upozornění a zastavíme zpracování.

Použití metody OnLogWarningMessage k ověření vstupu

Chcete vygenerovat osnovu založenou na vstupech xCount a yCount. Než budete pokračovat, ujistěte se, že obě hodnoty jsou kladná celá čísla.

public static List<Rectangle> CreateGrid(int xCount, int yCount)
{
    // Check if xCount and yCount are positive
    if (xCount <= 0 || yCount <= 0)
    {
        LogWarningMessageEvents.OnLogWarningMessage("Grid count values must be positive integers.");
        return new List<Rectangle>();  // Return an empty list if inputs are invalid
    }
    // Proceed with grid creation...
}

V tomto příkladu:

• Podmínka: Pokud je hodnota xCount nebo yCount menší nebo rovna nule.

• Zpráva: "Grid count values must be positive integers."

Pokud uživatel zadá nulové nebo záporné hodnoty, zobrazí se v aplikaci Dynamo upozornění, které mu pomůže pochopit očekávaný vstup.

Když nyní víme, jak zprávu vytvořit, můžeme ji implementovat do ukázkového uzlu Grids:

using Autodesk.DesignScript.Geometry;
using DynamoServices;

namespace CustomNodes
{
    public class Grids
    {
        // The empty private constructor.
        // This will not be imported into Dynamo.
        private 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)
        {
            // Check for valid input values
            if (xCount <= 0 || yCount <= 0)
            {
                // Log a warning message if the input values are invalid
                LogWarningMessageEvents.OnLogWarningMessage("Grid count values must be positive integers.");
                return new List<Rectangle>(); // Return an empty list if inputs are invalid
            }

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

Příklad 2: Kontrola prázdných kolekcí nebo kolekcí s hodnotou null

Pokud vaše metoda vyžaduje seznam bodů, ale uživatel předá prázdný nebo nulový seznam, můžete ho o problému informovat pomocí metody OnLogWarningMessage.

public static Polygon CreatePolygonFromPoints(List<Point> points)
{
    if (points == null || points.Count < 3)
    {
        LogWarningMessageEvents.OnLogWarningMessage("Point list cannot be null or have fewer than three points.");
        return null;  // Return null if the input list is invalid
    }
    // Proceed with polygon creation...
}

V tomto příkladu:

• Podmínka: Pokud má seznam points hodnotu null nebo obsahuje méně než tři body.

• Zpráva: "Point list cannot be null or have fewer than three points."

Tato zpráva uživatele upozorní, že k vytvoření mnohoúhelníku je třeba předat platný seznam s alespoň třemi body.

Příklad 3: Ověření kompatibility typů souborů

U uzlu, který zpracovává cesty k souborům, můžete chtít zajistit, že budou povoleny pouze určité typy souborů. Pokud bude zjištěn nepodporovaný typ souboru, bude zaprotokolováno upozornění.

public static void ProcessFile(string filePath)
{
    if (!filePath.EndsWith(".csv"))
    {
        LogWarningMessageEvents.OnLogWarningMessage("Only CSV files are supported.");
        return;
    }
    // Proceed with file processing...
}

V tomto příkladu:

• Podmínka: Pokud cesta k souboru nekončí příponou .csv.

• Zpráva: "Only CSV files are supported."

Tato zpráva uživatele upozorňuje, aby se ujistili, že předávají soubor CSV, což pomáhá předcházet problémům souvisejícím s nekompatibilními formáty souborů.

Přidávání informačních zpráv pomocí metody OnLogInfoMessage

Metoda OnLogInfoMessage z jmenného prostoru DynamoServices v aplikaci Dynamo umožňuje vývojářům protokolovat informační zprávy přímo do konzole aplikace Dynamo. To se hodí k potvrzování úspěšných operací, sdělování informací o průběhu nebo poskytování dalších přehledů o akcích uzlů. V této příručce se dozvíte, jak přidat metodu OnLogInfoMessage do libovolného uzlu Zero Touch, abyste zlepšili zpětnou vazbu a usnadnili uživatelům práci.

Postup implementace metody OnLogInfoMessage

Krok 1: Importujte požadovaný jmenný prostor

Metoda OnLogInfoMessage je součástí jmenného prostoru DynamoServices, takže začněte tím, že ji přidáte do souboru projektu.

Krok 2: Určete, kdy protokolovat informace

Před přidáním informační zprávy se zamyslete nad účelem vaší metody:

• Jaké informace by bylo užitečné potvrdit po dokončení akce?

• Existují v rámci metody klíčové kroky nebo milníky, o kterých by uživatelé mohli chtít vědět?

Příklady užitečných potvrzení:

• Zprávy o dokončení (např. při úplném vytvoření osnovy nebo modelu).

• Podrobnosti o zpracovávaných údajích (např. „10 úspěšně zpracovaných položek“).

• Souhrnné informace o provedení (např. parametry použité v procesu).

Krok 3: Použijte metodu OnLogInfoMessage k protokolování informačních zpráv

Umístěte volání OnLogInfoMessage ve smysluplných bodech metody. V klíčovém kroku nebo při dokončení zaprotokolujte informační zprávu, která uživatele informuje o tom, co se stalo.

Syntaxe pro metodu OnLogInfoMessage

LogWarningMessageEvents.OnLogInfoMessage("Your info message here.");

Příklady implementací metody OnLogInfoMessage

Níže jsou uvedeny různé scénáře demonstrující použití metody OnLogInfoMessage v uzlech Zero Touch.

Příklad 1: Ověření číselných vstupů

V tomto příkladu budeme vycházet z vlastního uzlu vytvořeném v předchozí části Případová studie funkce Zero-Touch – uzel osnovy; metody pojmenované RectangularGrid, která generuje osnovu obdélníků na základě vstupů xCount a yCount. Otestujeme, zda je vstup neplatný a pak pomocí metody OnLogInfoMessage poskytneme informace po dokončení spuštění uzlu.

Použití metody OnLogInfoMessage k ověření vstupu

Chcete vygenerovat osnovu založenou na vstupech xCount a yCount. Po vygenerování osnovy chcete její vytvoření potvrdit zaprotokolováním informační zprávy s rozměry osnovy.

public static List<Rectangle> CreateGrid(int xCount, int yCount)
{
    var pList = new List<Rectangle>();
    // Grid creation code here...

    // Confirm successful grid creation
    LogWarningMessageEvents.OnLogInfoMessage($"Successfully created a grid with dimensions {xCount}x{yCount}.");

    return pList;
}

V tomto příkladu:

• Podmínka: Proces vytváření osnovy byl dokončen.

• Zpráva: "Successfully created a grid with dimensions {xCount}x{yCount}."

Tato zpráva uživatele informuje, že osnova byla vytvořena podle zadání, a pomůže jim potvrdit, že uzel fungoval podle očekávání.

Když nyní víme, jak zprávu vytvořit, můžeme ji implementovat do ukázkového uzlu Grids:

using Autodesk.DesignScript.Geometry;
using DynamoServices;

namespace CustomNodes
{
    public class Grids
    {
        // The empty private constructor.
        // This will not be imported into Dynamo.
        private 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();
                }
            }

            // Log an info message indicating the grid was successfully created
            LogWarningMessageEvents.OnLogInfoMessage($"Successfully created a grid with dimensions {xCount}x{yCount}.");

            return pList;
        }
    }
}

Příklad 2: Poskytnutí informací o počtu dat

Pokud vytváříte uzel, který zpracovává seznam bodů, můžete chtít zaznamenat, kolik bodů bylo úspěšně zpracováno. To může být užitečné u velkých datových sad.

public static List<Point> ProcessPoints(List<Point> points)
{
    var processedPoints = new List<Point>();
    foreach (var point in points)
    {
        // Process each point...
        processedPoints.Add(point);
    }

    // Log info about the count of processed points
    LogWarningMessageEvents.OnLogInfoMessage($"{processedPoints.Count} points were processed successfully.");

    return processedPoints;
}

V tomto příkladu:

• Podmínka: Po dokončení smyčky se zobrazí počet zpracovaných položek.

• Zpráva: "6 points were processed successfully."

Tato zpráva pomůže uživatelům pochopit výsledek zpracování a potvrdí, že byly zpracovány všechny body.

Příklad 3: Souhrn použitých parametrů

V některých případech je užitečné potvrdit vstupní parametry, které uzel použil k dokončení akce. Pokud například uzel exportuje data do souboru, můžete zaprotokolováním názvu souboru a cesty uživatele ujistit, že byl použit správný soubor.

public static void ExportData(string filePath, List<string> data)
{
    // Code to write data to the specified file path...

    // Log the file path used for export
    LogWarningMessageEvents.OnLogInfoMessage($"Data exported successfully to {filePath}.");

}

V tomto příkladu:

• Podmínka: Proces exportu byl úspěšně dokončen.

• Zpráva: "Data exported successfully to {filePath}."

Tato zpráva uživatelům potvrdí, že export proběhl, a zobrazí přesnou cestu k souboru, aby nedocházelo k nejasnostem ohledně umístění souborů.

Vytváření a přidávání vlastní dokumentace k uzlům

Dokumentace k vlastním uzlům

V minulosti existovala v aplikaci Dynamo omezení, pokud jde o způsob, jakým mohli autoři balíčků poskytovat dokumentaci ke svým uzlům. Autoři vlastních uzlů mohli pouze zadat krátký popis, který se zobrazí v popisku uzlu, nebo dodat balíček s ukázkovými grafy s velkým množstvím poznámek.

Nový způsob

Aplikace Dynamo nyní autorům balíčků nabízí vylepšený systém, který umožňuje poskytovat lepší a podrobnější dokumentaci k vlastním uzlům. Tento nový přístup využívá uživatelsky přívětivý jazyk Markdown pro psaní textu a rozšíření pohledu Prohlížeče dokumentace k zobrazení jazyka Markdown v aplikaci Dynamo. Použití jazyka Markdown poskytuje autorům balíčků širokou škálu nových možností při tvorbě dokumentace k vlastním uzlům.

Co je jazyk Markdown?

Markdown je odlehčený značkovací jazyk, který slouží k formátování textových dokumentů ve formátu prostého textu. Od roku 2004, kdy byl jazyk Markdown vytvořen, jeho popularita neustále roste a nyní je jedním z nejoblíbenějších značkovacích jazyků na světě.

Začínáme s jazykem Markdown

Vytváření souborů Markdown je snadné – potřebujete pouze jednoduchý textový editor, například Poznámkový blok, a můžete začít. Existují však jednodušší způsoby, jak psát v jazyce Markdown, než pomocí Poznámkového bloku. Existuje několik online editorů, jako je Dillinger, které umožňují zobrazit změny v reálném čase, jakmile je provedete. Dalším oblíbeným způsobem úprav souborů Markdown je použití editoru kódu, jako je Visual Studio Code.

Jaké jsou možnosti jazyka Markdown?

Markdown je velmi flexibilní jazyk, který poskytuje dostatek funkcí pro snadnou tvorbu dobré dokumentace, a to včetně přidávání mediálních souborů, jako jsou obrázky nebo videa, vytváření tabulek s různými formami obsahu a samozřejmě jednoduché funkce formátování textu, jako je tučné písmo nebo kurzíva. To vše a mnohem více je možné při psaní dokumentů v jazyce Markdown. Další informace najdete v této příručce, v níž je popsána základní syntaxe jazyka Markdown.

Přidání rozšířené dokumentace k uzlům

Přidání dokumentace k uzlům je snadné. Dokumentaci lze přidat do všech variant vlastních uzlů, které zahrnují:

• Přednastavené uzly aplikace Dynamo.

• Vlastní uzly (.dyf) – kolekce předem připravených uzlů nebo uzlů jiných balíčků.

• Vlastní uzly balíčků v jazyce C#. (Označované také jako uzly Zero Touch. Tyto vlastní uzly vypadají jako předem připravené uzly.)

• Uzly NodeModel (uzly, které obsahují speciální funkce uživatelského rozhraní, například rozevírací seznamy nebo tlačítka výběru).

• Uzly NodeModel s vlastním uživatelským rozhraním (uzly, které obsahují jedinečné funkce uživatelského rozhraní, například grafiku na uzlu).

Postupujte podle následujících několika kroků, aby se soubory Markdown zobrazily v aplikaci Dynamo.

Otevírání souborů dokumentace v aplikaci Dynamo

Dynamo používá k zobrazení dokumentace uzlů rozšíření pohledu Prohlížeče dokumentace. Chcete-li otevřít dokumentaci uzlů, klikněte pravým tlačítkem na uzel a vyberte nápovědu. Tím se otevře Prohlížeč dokumentace a zobrazí se soubor Markdown přiřazený k danému uzlu, pokud je k dispozici.

Dokumentace zobrazená v Prohlížeči dokumentace se skládá ze dvou částí. První je část Node Info, která je automaticky generována z informací extrahovaných z uzlu, jako jsou vstupy/výstupy, kategorie uzlu, název/jmenný prostor uzlu a krátký popis uzlů. Druhá část zobrazuje dokumentaci vlastních uzlů, což je soubor Markdown, který je poskytován k dokumentaci uzlu.

Složka doc balíčku

Chcete-li přidat soubory dokumentace ke svým uzlům v aplikaci Dynamo, vytvořte v adresáři balíčku novou složku s názvem /doc. Po načtení balíčku Dynamo tento adresář prohledá a získá všechny soubory dokumentace v jazyce Markdown, které se v něm nacházejí.

Pojmenování souborů Markdown

Aby aplikace Dynamo poznala, který soubor má při požadavku na konkrétní uzel otevřít, musí být název souboru Markdown v určitém formátu. Soubor Markdown by měl být pojmenován podle jmenného prostoru uzlu, který dokumentuje. Pokud si nejste jisti jmenným prostorem uzlu, podívejte se po kliknutí na tlačítko Help na uzlu do části Node Info a pod názvem uzlu uvidíte celý jmenný prostor vybraného uzlu.

Tento jmenný prostor by měl být název souboru Markdown pro daný uzel. Například jmenný prostor uzlu CustomNodeExample z obrázků výše je TestPackage.TestCategory.CustomNodeExample, proto by měl být soubor Markdown pro tento uzel pojmenován jako TestPackage.TestCategory.CustomNodeExample.md

Ve speciálních případech s přetížením uzlů (uzly se stejným názvem, ale různými vstupy), budete nutné přidat názvy vstupů do () za jmenný prostor uzlu. Například vestavěný uzel Geometry.Translate má několik přetížení. V tomto případě bychom soubory Markdown pro níže uvedené uzly pojmenovali následujícím způsobem: Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction).md Autodesk.DesignScript.Geometry.Geometry.Translate(geometry,direction,distance).md

Úpravy souborů Markdown při otevření v aplikaci Dynamo

Aby bylo možné soubory dokumentace snadno upravovat, implementuje Prohlížeč dokumentace do otevřeného souboru dokumentace nástroj pro sledování souboru. Díky tomu můžete provádět změny v souboru Markdown, přičemž tyto změny okamžitě uvidíte v aplikaci Dynamo.

Přidání nových souborů dokumentace lze provést i v případě, kdy je aplikace Dynamo otevřená. Jednoduše přidejte do složky /doc nový soubor Markdown s názvem odpovídajícím uzlu, který dokumentuje.

Přidání vlastních ikon do uzlů Zero Touch

Přehled

Díky vlastním ikonám uzlů Zero Touch budou vaše uzly v aplikaci Dynamo vizuálně rozlišitelné a snadněji rozpoznatelné v knihovně. Přidáním ikon na míru můžete své uzly odlišit od ostatních a umožnit uživatelům jejich rychlou identifikaci v seznamu.

V této příručce se dozvíte, jak přidat ikony do uzlů Zero Touch.

Postup přidání vlastních ikon uzlů

Krok 1: Nastavte projekt

Začněte tím, že vytvoříte projekt knihovny tříd aplikace Visual Studio (.NET Framework) pro své uzly Zero Touch. Pokud projekt ještě nemáte, přečtěte si část Začínáme, ve které najdete podrobné pokyny k jeho vytvoření.

Ujistěte se, že máte alespoň jeden funkční uzel Zero Touch, protože ikony lze přidávat pouze do existujících uzlů. Pokyny najdete v části Případová studie funkce Zero-Touch – uzel osnovy.

Krok 2: Vytvořte obrázky ikon

Vytvoření vlastních ikon:

1. Navrhněte své ikony: Pomocí editoru obrázků vytvořte jednoduché a vizuálně zřetelné ikony uzlů.

2. Specifikace obrázku:

   • Malá ikona: 32×32 pixelů (používá se na bočním panelu knihovny a na samotném uzlu).

   • Velká ikona: 128×128 pixelů (používá se ve vlastnostech uzlu při umístění kurzoru nad uzel v knihovně).

3. Konvence pojmenování souboru:

   • Názvy souborů musí odpovídat níže uvedenému formátu, aby byly přiřazeny ke správnému uzlu:

     • <ProjectName>.<ClassName>.<MethodName>.Small.png (pro malou ikonu).

     • <ProjectName>.<ClassName>.<MethodName>.Large.png (pro velkou ikonu).

Příklad: Pokud je projekt ZeroTouchNodeIcons, třída je Grids a metoda je RectangularGrid, soubory by měly být pojmenovány následovně:

• ZeroTouchNodeIcons.Grids.RectangularGrid.Small.png

• ZeroTouchNodeIcons.Grids.RectangularGrid.Large.png

Tip: U všech ikon zachovejte jednotný motiv designu, abyste dosáhli profesionálního vzhledu.

Krok 3: Přidejte soubor zdrojů do projektu

Pokud chcete vložit ikony do .dll, vytvořte soubor zdrojů:

1. Přidejte nový soubor zdrojů:

• Klikněte pravým tlačítkem myši na projekt v nástroji Solution Explorer.

• Přejděte do nabídky Add > New Item a vyberte možnost Resources File.

• Pojmenujte soubor jako <ProjectName>Images.resx. Příklad: ZeroTouchNodeIconsImages.resx.

1. Zrušte zaškrtnutí vlastnosti Custom Tool:

   • Vyberte soubor zdrojů v nástroji Solution Explorer.

   • Na panelu Properties vymažte pole Custom Tool odebráním hodnoty ResXFileCodeGenerator.

POZNÁMKA: Pokud se nepodaří vymazat pole Custom Tool, Visual Studio převede v názvech zdrojů tečky na podtržítka. Před sestavením ověřte, že názvy zdrojů mají tečky oddělující názvy tříd, nikoli podtržítka.

Krok 4: Přidejte obrázky jako zdroje

1. Otevřete soubor zdrojů pomocí nástroje Managed Resources Editor (Legacy):

   • Pokud používáte aplikaci Visual Studio 17.11 nebo novější, klikněte pravým tlačítkem myši na soubor prostředků, zvolte Open With a vyberte položku Managed Resources Editor (Legacy).

   • Pokud používáte verzi aplikace Visual Studio starší než 17.11, dvojím kliknutím na soubor zdrojů jej otevřete v nástroji Resources Editor (který ve vaší verzi aplikace Visual Studio ještě není starší verzí).

1. Přidejte obrázky:

   • Přetáhněte soubory obrázků do editoru nebo použijte možnost Add Existing File.

1. Aktualizace vlastnosti Persistence:

   • Vyberte obrázky v nástroji Resources Editor (pokud je vyberete v nástroji Solution Explorer, nebude to fungovat) a změňte vlastnost Persistence na panelu Properties na Embedded in .resx. Tím zajistíte, že obrázky budou zahrnuty do vaší knihovny .dll.

Krok 5: Převeďte projekt do stylu SDK

Pokud váš projekt ještě není ve stylu SDK (nutné pro vkládání prostředků), převeďte ho:

1. V aplikaci Visual Studio nainstalujte rozšíření .NET Upgrade Assistant z nabídky Extensions > Manage Extensions.

1. Klikněte pravým tlačítkem myši na projekt v nástroji Solution Explorer a vyberte možnost Upgrade > Convert project to SDK-style.

1. Počkejte na dokončení převodu.

Krok 6: Přidejte skript po sestavení pro vložení zdrojů

1. Uvolněte projekt:

   • Klikněte pravým tlačítkem myši na projekt v nástroji Solution Explorer a vyberte možnost Unload Project.

1. Upravte soubor .csproj:

   • Mezi </ItemGroup> a </Project> přidejte následující prvek <Target>:

<Target Name="CreateNodeIcons" AfterTargets="PostBuildEvent">
		<!-- Get System.Drawing.dll     -->
		<GetReferenceAssemblyPaths TargetFrameworkMoniker=".NETFramework, Version=v4.8">
			<Output TaskParameter="FullFrameworkReferenceAssemblyPaths" PropertyName="FrameworkAssembliesPath" />
		</GetReferenceAssemblyPaths>
		<!-- Get assembly -->
		<GetAssemblyIdentity AssemblyFiles="$(OutDir)$(TargetName).dll">
			<Output TaskParameter="Assemblies" ItemName="AssemblyInfo" />
		</GetAssemblyIdentity>
		<!-- Generate customization dll -->
		<GenerateResource SdkToolsPath="$(TargetFrameworkSDKToolsDirectory)" UseSourcePath="true" Sources="$(ProjectDir)ZeroTouchNodeIconsImages.resx" OutputResources="$(ProjectDir)ZeroTouchNodeIconsImages.resources" References="$(FrameworkAssembliesPath)System.Drawing.dll" />
		<AL SdkToolsPath="$(TargetFrameworkSDKToolsDirectory)" TargetType="library" EmbedResources="$(ProjectDir)ZeroTouchNodeIconsImages.resources" OutputAssembly="$(OutDir)ZeroTouchNodeIcons.customization.dll" Version="%(AssemblyInfo.Version)" />
	</Target>

1. Nahraďte všechny instance ZeroTouchNodeIcons názvem projektu.

2. Znovu načtěte projekt:

   • Klikněte pravým tlačítkem myši na uvolněný projekt a vyberte možnost Reload Project.

Krok 7: Sestavte svou knihovnu .dll a načtěte ji do aplikace Dynamo

1. Sestavení projektu:

   • Po přidání skriptu po sestavení sestavte projekt v aplikaci Visual Studio.

1. Kontrola výstupních souborů:

   • Ujistěte se, že vaše knihovny .dll a .customization.dll jsou ve složce bin.

2. Přidejte knihovnu .dll do aplikace Dynamo:

   • V aplikaci Dynamo importujte svou knihovnu .dll pomocí tlačítka Importovat knihovnu.

1. Vaše vlastní uzly by se nyní měly zobrazit s příslušnými ikonami.

Obecné informace o typech interoperability

Co jsou typy COM? – https://learn.microsoft.com/en-us/windows/win32/com/the-component-object-model

Standardním způsobem, jak používat typy COM v jazyce C#, je odkazovat a dodávat primární sestavení interoperability (v podstatě velká kolekce rozhraní API) s balíčkem.

Alternativou k tomu je vložení PIA (primary interop assemblies – primární sestavení interoperability) do spravovaného sestavení. To v podstatě zahrnuje pouze typy a členy, které jsou skutečně používány spravovaným sestavením. Tento přístup má však některé další problémy, jako je ekvivalence typů.

Tento článek tuto problematiku dobře popisuje:

• https://learn.microsoft.com/en-us/dotnet/framework/interop/type-equivalence-and-embedded-interop-types

Jak Dynamo spravuje ekvivalenci typů

Dynamo deleguje ekvivalenci typů na modul runtime .NET. Například 2 typy se stejným názvem a jmenným prostorem, pocházející z různých sestavení, nebudou považovány za ekvivalentní a Dynamo nahlásí chybu při načítání konfliktních sestavení. Pokud jde o typy interoperability, Dynamo zkontroluje, zda jsou ekvivalentní pomocí rozhraní API IsEquivalentTo.

Jak se vyhnout konfliktům mezi vloženými typy interoperability

Některé balíčky již byly vytvořeny s vloženými typy interoperability (např. CivilConnection). Načtení 2 balíčků s vloženými sestaveními interoperability, která nejsou považována za ekvivalentní (různé verze, jak je definováno zde), způsobí chybovou zprávu package load error. Z tohoto důvodu doporučujeme, aby autoři balíčků používali pro typy interoperability dynamickou vazbu (tzv. pozdní vazbu) (řešení je také popsáno tady).

Můžete postupovat podle tohoto příkladu:

public class Application
    {
        string m_sProdID = "SomeNamespace.Application";
        public dynamic m_oApp = null; // Use dynamic so you do not need the PIA types

        public Application()
        {
            this.GetApplication();
        }

        internal void GetApplication()
        {
            try

            {
                m_oApp = System.Runtime.InteropServices.Marshal.GetActiveObject(m_sProdID);
            }
            catch (Exception /*ex*/)
            {}
        }
    }
}

Uzly založené na uzlech NodeModel poskytují podstatně větší flexibilitu a výkon než uzly Zero-Touch. V tomto příkladu posuneme uzel mřížky Zero-Touch na další úroveň přidáním integrovaného posuvníku, který náhodně nastaví velikost obdélníku.

Posuvník změní měřítko buněk vzhledem k jejich velikosti, takže uživatel nemusí zadávat posuvník se správným rozsahem.

Vzor Model-View-Viewmodel

Aplikace Dynamo je založena na vzoru architektury model-view-viewmodel (MVVM), aby bylo uživatelské rozhraní odděleno od back-endu. Při vytváření uzlů ZeroTouch aplikace Dynamo provádí vazbu dat mezi daty uzlu a jeho uživatelským rozhraním. Chcete-li vytvořit vlastní uživatelské rozhraní, je nutné přidat logiku vazby dat.

Vytvoření vztahu mezi modelem a pohledem (model-view) v aplikaci Dynamo se skládá ze dvou částí:

• Třída NodeModel slouží ke stanovení základní logiky uzlu („model“).

• Třída INodeViewCustomization slouží k přizpůsobení způsobu zobrazení třídy NodeModel („view“).

K objektům NodeModel je již přiřazen vzor view-model (NodeViewModel), takže se můžeme zaměřit pouze na model a pohled pro vlastní uživatelské rozhraní.

Implementace rozhraní NodeModel

Uzly NodeModel mají několik významných rozdílů oproti uzlům Zero-Touch, kterými se budeme zabývat v tomto příkladu. Než přejdeme k přizpůsobení uživatelského rozhraní, začneme vytvořením logiky NodeModel.

1. Vytvoření struktury projektu:

Uzel NodeModel může volat pouze funkce, takže je potřeba rozdělit uzel NodeModel a funkce do různých knihoven. Standardním způsobem, jak to provést u balíčků aplikace Dynamo, je vytvořit pro každý z nich samostatné projekty. Začněte vytvořením nového řešení, které bude zahrnovat projekty.

1. Vyberte File > New > Project.

2. Výběrem možnosti Other Project Types zobrazte možnost Řešení.

3. Vyberte Blank Solution.

4. Pojmenujte řešení jako CustomNodeModel.

5. Klikněte na tlačítko Ok.

Vytvořte v řešení dva projekty knihovny třídy C#: jeden pro funkce a jeden pro implementaci rozhraní NodeModel.

1. Klikněte pravým tlačítkem na položku Řešení a vyberte Add > New Project.

2. Vyberte knihovnu tříd.

3. Pojmenujte projekt jako CustomNodeModel.

4. Klikněte na tlačítko Ok.

5. Zopakujte tento postup a přidejte další projekt s názvem CustomNodeModelFunctions.

Dále je nutné přejmenovat knihovny tříd, které byly automaticky vytvořeny, a jednu přidat do projektu CustomNodeModel. Třída GridNodeModel implementuje abstraktní třídu NodeModel, třída GridNodeView se používá k přizpůsobení pohledu a třída GridFunction obsahuje všechny funkce, které je nutné volat.

1. Klikněte pravým tlačítkem na projekt CustomNodeModel, vyberte položku Add > New Item... a výběrem položky Class přidejte další třídu.

2. V projektu CustomNodeModel potřebujeme třídy GridNodeModel.cs a GridNodeView.cs.

3. V projektu CustomNodeModelFunction potřebujeme třídu GridFunctions.cs.

Než přidáme kód do tříd, přidejte potřebné balíčky pro tento projekt. Projekt CustomNodeModel bude potřebovat ZeroTouchLibrary a WpfUILibrary a projekt CustomNodeModelFunction bude potřebovat pouze ZeroTouchLibrary. Balíček WpfUILibrary bude použit při pozdějším přizpůsobení uživatelského rozhraní a balíček ZeroTouchLibrary bude použit k vytvoření geometrie. Balíčky lze přidávat jednotlivě pro projekty. Protože tyto balíčky mají závislosti, budou automaticky nainstalovány knihovny Core a DynamoServices.

1. Klikněte pravým tlačítkem na projekt a vyberte Manage NuGet Packages.

2. Nainstalujte pouze balíčky požadované pro daný projekt.

Aplikace Visual Studio zkopíruje balíčky NuGet, na které jsme odkazovali v adresáři sestavení. Tuto možnost můžeme nastavit na hodnotu false, aby v balíčku nebyly žádné nepotřebné soubory.

1. Vyberte balíčky Dynamo NuGet.

2. Nastavte Copy Local na hodnotu False.

2. Zdědění třídy NodeModel

Jak bylo zmíněno výše, primárním aspektem, který odlišuje uzel NodeModel od uzlu ZeroTouch, je jeho implementace třídy NodeModel. Uzel NodeModel vyžaduje několik funkcí z této třídy, které můžeme získat přidáním :NodeModel za název třídy.

Zkopírujte následující kód do 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) };
        }
    }
}

Tento kód se liší od uzlů Zero-Touch. Podívejme se, co dělají jednotlivé části.

• Zadejte atributy uzlu, jako jsou název, kategorie, názvy a typy vstupního/výstupního portu a popisy.

• public class GridNodeModel : NodeModel je třída, která dědí třídu NodeModel z Dynamo.Graph.Nodes.

• public GridNodeModel() { RegisterAllPorts(); } je konstruktor, který zaregistruje vstupy a výstupy uzlu.

• BuildOutputAst() vrací AST (abstraktní syntaktický strom), což je požadovaná struktura pro vrácení dat z uzlu NodeModel.

• AstFactory.BuildFunctionCall() volá funkci RectangularGrid z GridFunctions.cs.

• new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid) určuje funkci a její parametry.

• new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue }); mapuje vstupy uzlu na parametry funkce.

• AstFactory.BuildNullNode() vytvoří nulový uzel, pokud nejsou připojeny vstupní porty. Tím se vyhnete zobrazení upozornění na uzlu.

• RaisePropertyChanged("SliderValue") upozorní uživatelské rozhraní, když se změní hodnoty posuvníku.

• var sliderValue = AstFactory.BuildDoubleNode(SliderValue) vytvoří uzel v AST, který reprezentuje hodnotu posuvníku.

• Změňte vstup na proměnnou sliderValue v proměnné functionCall new List<AssociativeNode> { inputAstNodes[0], sliderValue });.

3. Volání funkce

Projekt CustomNodeModelFunction bude z projektu CustomNodeModel vyčleněn do samostatné sestavy, aby jej bylo možné volat.

Zkopírujte následující kód do třídy 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;
        }
    }
}

Tato třída funkce je velmi podobná případové studii funkce Zero-Touch – uzel osnovy s jedním rozdílem:

• [IsVisibleInDynamoLibrary(false)] brání aplikaci Dynamo v rozpoznání následující metody a třídy, protože funkce je již volána z projektu CustomNodeModel.

Stejně jako jsme přidali odkazy na balíčky NuGet, bude nutné CustomNodeModel odkazovat na CustomNodeModelFunction, aby bylo možné volat funkci.

Příkaz using pro CustomNodeModel bude neaktivní, dokud neodkážeme na funkci.

1. Klikněte pravým tlačítkem na CustomNodeModel a vyberte Add > Reference.

2. Zvolte Projects > Solution.

3. Zaškrtněte políčko CustomNodeModelFunction.

4. Klikněte na tlačítko Ok.

4. Přizpůsobení pohledu

Abychom mohli vytvořit posuvník, je nutné přizpůsobit uživatelské rozhraní implementací rozhraní INodeViewCustomization.

Zkopírujte následující kód do 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()
        {
        }
    }
}

• public class CustomNodeModelView : INodeViewCustomization<GridNodeModel> definuje nezbytné funkce pro přizpůsobení uživatelského rozhraní.

Po nastavení struktury projektu vytvořte pomocí návrhového prostředí aplikace Visual Studio uživatelský ovládací prvek a definujte jeho parametry v souboru .xaml. Ze sady nástrojů přidejte posuvník do části <Grid>...</Grid>.

1. Klikněte pravým tlačítkem na CustomNodeModel a vyberte Add > New Item.

2. Vyberte WPF.

3. Pojmenujte uživatelský ovládací prvek jako Slider.

4. Klikněte na tlačítko Add

Zkopírujte následující kód do souboru 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 posuvníku jsou definovány v souboru .xaml. Atributy Minimální a Maximální definují číselný rozsah tohoto posuvníku.

• V části <Grid>...</Grid> můžeme umístit různé uživatelské ovládací prvky ze sady nástrojů aplikace Visual Studio.

Když jsme vytvořili soubor Slider.xaml, aplikace Visual Studio automaticky vytvořila soubor C# s názvem Slider.xaml.cs, který inicializuje posuvník. Změňte jmenný prostor v tomto souboru.

using System.Windows.Controls;

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

• Jmenný prostor by měl být CustomNodeModel.CustomNodeModel.

Soubor GridNodeModel.cs definuje logiku výpočtu posuvníku.

5. Konfigurace balíčku

Před vytvořením projektu je posledním krokem přidání souboru pkg.json, aby aplikace Dynamo mohla načíst balíček.

1. Klikněte pravým tlačítkem na CustomNodeModel a vyberte Add > New Item.

2. Vyberte Web.

3. Vyberte JSON File.

4. Pojmenujte soubor jako pkg.json.

5. Klikněte na tlačítko Add

• Zkopírujte následující kód do souboru 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": určuje název balíčku a jeho skupinu v knihovně aplikace Dynamo.

• "keywords": poskytuje vyhledávací termíny pro vyhledávání v knihovně aplikace Dynamo.

• "node_libraries": [] definuje knihovny asociované s balíčkem.

  Posledním krokem je vytvoření řešení a publikování jako balíčku aplikace Dynamo. Informace o tom, jak vytvořit místní balíček před publikováním online a jak sestavit balíček přímo z aplikace Visual Studio, naleznete v kapitole Rozmístění balíčku.

Úvod:

Aplikace Dynamo 2.0 je hlavní verzí, ve které byla změněna nebo odstraněna některá rozhraní API. Jednou z největších změn, která se dotkne autorů uzlů a balíčků, je přechod na formát souborů JSON.

Obecně platí, že autoři uzlů Zero Touch nebudou mít se zprovozněním svých balíčků ve verzi 2.0 mnoho práce.

Zprovoznění uzlů uživatelského rozhraní a uzlů, které se odvozují přímo z uzlu NodeModel, bude ve verzi 2.x vyžadovat větší úsilí.

Autoři rozšíření mohou také provést některé potenciální změny – v závislosti na tom, kolik rozhraní API jádra aplikace Dynamo používají ve svých rozšířeních.

Obecná pravidla pro tvorbu balíčků:

• Nezahrnujte do svých balíčků knihovny DLL aplikace Dynamo nebo Dynamo Revit. Tyto knihovny DLL již budou načteny aplikací Dynamo. Pokud přibalíte jinou verzi, než má uživatel načtenou (tj. distribuujete jádro aplikace Dynamo 1.3, ale uživatel spouští balíček v aplikaci Dynamo 2.0), bude docházet k neočekávaným chybám za běhu. To zahrnuje knihovny DLL jako DynamoCore.dll, DynamoServices.dll, DSCodeNodes.dll a ProtoGeometry.dll.

• Pokud se tomu můžete vyhnout, nezahrnujte do svého balíčku knihovnu newtonsoft.json.net a nedistribuujte ji. Tato knihovna DLL již bude načtena aplikací Dynamo 2.x. Může dojít ke stejnému problému jako výše.

• Pokud se tomu můžete vyhnout, nezahrnujte do svého balíčku knihovnu CEFSharp a nedistribuujte ji. Tato knihovna DLL již bude načtena aplikací Dynamo 2.x. Může dojít ke stejnému problému jako výše.

• Obecně se vyhněte sdílení závislostí s aplikací Dynamo nebo Revit, pokud potřebujete kontrolovat verzi dané závislosti.

Běžné problémy:

1. Po otevření grafu mají některé uzly více portů se stejným názvem, ale při uložení vypadal graf v pořádku. Tento problém může mít několik příčin.

Obvyklou hlavní příčinou je, že uzel byl vytvořen pomocí konstruktoru, který znovu vytvořil porty. Místo toho měl být použit konstruktor, který porty načte. Tyto konstruktory jsou obvykle označeny [JsonConstructor] viz příklady níže.

K tomu může dojít z následujících důvodů:

• Jednoduše nebyl nalezen odpovídající konstruktor [JsonConstructor] nebo mu nebyly předány Inports a Outports ze souboru .dyn JSON.

• Do stejného procesu byly načteny dvě verze rozhraní JSON.net současně, což způsobilo chybu modulu runtime rozhraní .net, takže atribut [JsonConstructor] nebylo možné správně použít k označení konstruktoru.

• K balíčku byl přibalen soubor DynamoServices.dll s jinou verzí, než je aktuální verze aplikace Dynamo, což způsobuje, že modul runtime rozhraní .net nedokáže identifikovat atribut [MultiReturn], takže u uzlů Zero Touch označených různými atributy nebudou tyto atributy použity. Může se stát, že uzel vrací jeden výstup slovníku místo více portů.

1. Při načítání grafu zcela chybí uzly a v konzoli se zobrazují chyby.

• K tomu může dojít, pokud se z nějakého důvodu nezdařila deserializace. Je vhodné serializovat pouze vlastnosti, které potřebujete. Chcete-li ignorovat složité vlastnosti, které není nutné načíst nebo uložit, můžete použít [JsonIgnore]. Jedná se o vlastnosti jako function pointer, delegate, action, nebo event atd. Tyto vlastnosti by neměly být serializovány, protože se je obvykle nepodaří deserializovat a způsobí chybu za běhu.

Podrobné informace o aktualizaci:

Vlastní uzly1.3 -> 2.0

Uspořádání vlastních uzlů v souboru librarie.js

Známé problémy:

• Shodný název vlastního uzlu a název kategorie na stejné úrovni v souboru librarie.js způsobuje neočekávané chování. QNTM-3653 – vyhněte se použití stejných názvů pro kategorie a uzly.

• Komentáře budou namísto řádkových komentářů převedeny na blokové komentáře.

• Krátké názvy typů budou nahrazeny úplnými názvy. Pokud jste například nezadali typ, při opětovném načtení vlastního uzlu se zobrazí var[]..[], protože se jedná o výchozí typ.

Uzly Zero Touch 1.3 -> 2.0

• V aplikaci Dynamo 2.0 byly rozděleny typy seznamů a slovníků a byla změněna syntaxe pro vytváření seznamů a slovníků. Seznamy jsou inicializovány pomocí [], zatímco slovníky používají {}. Pokud jste dříve používali atribut DefaultArgument k označení parametrů v uzlech Zero Touch a používali syntaxi seznamu pro výchozí nastavení konkrétního seznamu, například someFunc([DefaultArgument("{0,1,2}")]), toto již nebude platné a bude nutné upravit úryvek jazyka DesignScript, aby používal novou inicializační syntaxi pro seznamy.

• Jak bylo uvedeno výše, nedistribuujte knihovny DLL aplikace Dynamo s balíčky (DynamoCore, DynamoServices atd.).

Uzly Node Model 1.3 -> 2.0

Uzly Node Model vyžadují při aktualizaci na verzi Dynamo 2.x nejvíce práce. Na vysoké úrovni budete kromě běžných konstruktorů nodeModel, které se používají k vytváření instancí nových instancí typů uzlů, muset implementovat konstruktory, které budou použity pouze k načtení uzlů ze JSON. K jejich rozlišení označte konstruktory načítání pomocí [JsonConstructor], což je atribut z rozhraní newtonsoft.Json.net.

Názvy parametrů v konstruktoru by obecně měly odpovídat názvům vlastností JSON. Toto mapování se však komplikuje, pokud přepíšete názvy, které jsou serializovány, pomocí atributů [JsonProperty]. Další informace naleznete v dokumentaci k rozhraní Json.net.

Konstruktory JSON

Nejčastější změnou vyžadovanou k aktualizaci uzlů odvozených ze základní třídy NodeModel (nebo jiných základních tříd jádra aplikace Dynamo, tj. DSDropDownBase), je nutnost přidat do třídy konstruktor JSON.

Původní bezparametrický konstruktor bude stále schopen inicializovat nový uzel vytvořený v aplikaci Dynamo (například prostřednictvím knihovny). Konstruktor JSON je vyžadován k inicializaci uzlu, který je deserializován (načten) z uloženého souboru .dyn nebo .dyf.

Konstruktor JSON se liší od základního konstruktoru tím, že obsahuje parametry PortModel pro inPorts a outPorts, které jsou poskytovány logikou načítání JSON. Volání k registraci portů pro uzel zde není vyžadováno, protože data existují v souboru .dyn. Příklad konstruktoru JSON vypadá následovně:

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

Tato syntaxe :base(Inports,outPorts){} volá základní konstruktor nodeModel a předává mu deserializované porty.

Jakékoli speciální logiky, které existovaly v konstruktoru třídy a zahrnují inicializaci specifických dat serializovaných do souboru .dyn (například nastavení registrace portů, strategie vázání atd.), není nutné v tomto konstruktoru opakovat, protože tyto hodnoty lze načíst ze JSON.

Jedná se o hlavní rozdíl mezi konstruktorem JSON a jinými konstruktory, pro vaše uzly nodeModel. Konstruktory JSON jsou vyvolány při načítání ze souboru a jsou jim předána načtená data. Ostatní uživatelská logika však musí být duplikována v konstruktoru JSON (například inicializace ovladačů událostí pro uzel nebo připojování).

Příklady naleznete v úložišti DynamoSamples - > ButtonCustomNodeModel, DropDown nebo SliderCustomNodeModel.

Veřejné vlastnosti a serializace

Dříve mohl vývojář serializovat a deserializovat konkrétní data modelu do dokumentu XML pomocí metod SerializeCore a DeserializeCore. Tyto metody v rozhraní API stále existují, ale v budoucí verzi aplikace Dynamo budou vyřazeny (příklad naleznete zde). Díky implementaci rozhraní JSON.NET lze nyní vlastnosti public odvozené třídy NodeModel serializovat přímo do souboru .dyn. Rozhraní JSON.Net poskytuje několik atributů pro řízení způsobu serializace vlastností.

Tento příklad, který určuje PropertyName, naleznete zde v úložišti Dynamo.

[JsonProperty(PropertyName = "InputValue")]

public DSColor DsColor {...

Převodníky:

Poznámka Pokud vytvoříte vlastní třídu převodníku JSON.net, aplikace Dynamo v současné době nemá mechanismus, který by umožňoval jeho začlenění do metod načítání a ukládání, takže i když svou třídu označíte atributem [JsonConverter], nemusí být použita – místo toho můžete volat převodník přímo v metodě setter nebo getter. //Toto omezení je třeba potvrdit. Všechny důkazy jsou vítány.

Příklad, který určuje metodu serializace pro převod vlastnosti na řetězec, naleznete zde v úložišti Dynamo.

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

public ConversionMetricUnit SelectedMetricConversion{...

Ignorování vlastností

Vlastnostem public, které nejsou určeny pro serializaci, musí mít přidán atribut [JsonIgnore]. Při uložení uzlů do souboru .dyn je zajištěno, že tato data budou serializačním mechanismem ignorována a nezpůsobí neočekávané následky při dalším otevření grafu. Příklad si můžete prohlédnout zde v úložišti Dynamo.

Vrácení a opakování změn

Jak je uvedeno výše, metody SerializeCore a DeserializeCore se v minulosti používaly k ukládání a načítání uzlů do souboru xml s příponou .dyn. Kromě toho se také používaly a stále používají k ukládání a načítání stavu uzlu pro operace Zpět/Znovu. Pokud chcete pro uzel nodeModel uživatelského rozhraní implementovat složité funkce Zpět/Znovu, bude nutné tyto metody implementovat a serializovat do objektu dokumentu XML, který je těmto metodám poskytován jako parametr. To by měl být vzácný případ použití s výjimkou složitých uzlů uživatelského rozhraní.

Rozhraní API vstupních a výstupních portů

Jednou z běžných událostí v uzlech nodeModel, kterých se týkají změny rozhraní API verze 2.0, je registrace portu v konstruktoru uzlu. Při prohlížení příkladů v úložišti Dynamo nebo DynamoSamples jste dříve mohli zaznamenat použití metod InPortData.Add() nebo OutPortData.Add(). V rozhraní API aplikace Dynamo byly dříve veřejné vlastnosti InPortData a OutPortData označeny jako zastaralé. Ve verzi 2.0 byly tyto vlastnosti odstraněny. Vývojáři by nyní měli používat metody InPorts.Add() a OutPorts.Add(). Kromě toho mají tyto dvě metody Add() mírně odlišné signatury:

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

vs.

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

Příklady převedeného kódu naleznete zde v úložišti Dynamo -> DynamoConvert.cs nebo FileSystem.cs.

Další běžný případ použití, který je ovlivněn změnami rozhraní API verze 2.0, se týká metod běžně používaných v metodě BuildAst() k určení chování uzlu na základě přítomnosti nebo nepřítomnosti konektorů portů. Dříve se k ověření stavu připojeného portu používala metoda HasConnectedInput(index). Vývojáři by nyní měli kontrolovat stav připojení portu pomocí vlastnosti InPorts[0].IsConnected. Příklad naleznete v souboru ColourRange.cs v úložišti Dynamo.

Příklady:

Nyní si ukážeme aktualizaci uzlu uživatelského rozhraní verze 1.3 na verzi 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) };
        }
    }
}

Vše, co je potřeba udělat s touto třídou nodeModel, aby se správně načítala a ukládala ve verzi 2.0, je přidat konstruktor jsonConstructor, který se stará o načítání portů. Jednoduše předáme porty základnímu konstruktoru a tato implementace je prázdná.

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

}

Poznámka: Nevolejte v konstruktoru JsonConstructor funkci RegisterPorts() nebo některou její variantu – ta by použila atributy vstupních a výstupních parametrů třídy uzlů k vytvoření nových portů! To je nežádoucí chování, protože chceme používat načtené porty, které jsou předány konstruktoru.

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

Tento příklad přidává minimální možné načítání konstruktoru JSON. Co když však potřebujeme provést složitější konstrukční logiku, například nastavit některé podprocesy naslouchání pro obsluhu událostí uvnitř konstruktoru. Další ukázka převzatá z úložiště DynamoSamples je uvedena výše v části JsonConstructors Section tohoto dokumentu.

Zde je složitější konstruktor pro uzel uživatelského rozhraní:

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

Když přidáme konstruktor JSON pro načtení tohoto uzlu ze souboru, je nutné znovu vytvořit část této logiky, ale všimněte si, že nezadáváme kód, který vytváří porty, nastavuje vázání nebo nastavuje výchozí hodnoty vlastností, které lze ze souboru načíst.

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

Všimněte si, že další veřejné vlastnosti, které byly serializovány do souboru JSON, jako ButtonText a WindowText, nebudou přidány jako explicitní parametry ke konstruktoru – jsou automaticky nastaveny rozhraním JSON.net pomocí metod setter pro tyto vlastnosti.

Úvod

Tato část obsahuje informace o problémech, se kterými se můžete setkat při migraci grafů, balíčků a knihoven do aplikace Dynamo 3.x.

Aplikace Dynamo 3.0 je hlavní verzí, ve které byla změněna nebo odstraněna některá rozhraní API. Největší změnou, která se vás jako vývojáře nebo uživatele aplikace Dynamo 3.x pravděpodobně dotkne, je přechod na rozhraní .NET 8.

Rozhraní .NET je modul runtime, který používá jazyk C#, v němž je aplikace Dynamo napsána. Spolu s ostatními částmi ekosystému Autodesk jsme aktualizovali na moderní verzi tohoto modulu runtime.

Další informace naleznete v tomto příspěvku na blogu.

Kompatibilita balíčku

Používání balíčků aplikace Dynamo 2.x v aplikaci Dynamo 3.x

Protože aplikace Dynamo 3.x nyní využívá rozhraní .NET 8, není u balíčků, které byly vytvořeny pro aplikaci Dynamo 2.x (pomocí rozhraní .NET 48), zaručeno, že budou fungovat v aplikaci Dynamo 3.x. Při pokusu o stažení balíčku v aplikaci Dynamo 3.x, který byl publikován z verze aplikace Dynamo nižší než 3.0, se zobrazí upozornění, že balíček pochází ze starší verze aplikace.

To neznamená, že balíček nebude fungovat. Jedná se pouze o upozornění, že může dojít k problémům s kompatibilitou, a obecně je vhodné zkontrolovat, zda existuje novější verze, která byla vytvořena speciálně pro aplikaci Dynamo 3.x.

Tento typ upozornění můžete také zaznamenat v souborech protokolu aplikace Dynamo při načítání balíčku. Pokud vše funguje správně, můžete ho ignorovat.

Používání balíčků aplikace Dynamo 3.x v aplikaci Dynamo 2.x

Je velmi nepravděpodobné, že balíček vytvořený pro aplikaci Dynamo 3.x (pomocí rozhraní .Net 8) bude fungovat v aplikaci Dynamo 2.x. Při stahování balíčků vytvořených pro novější verze systému Dynamo se při používání starší verze zobrazí upozornění.

Rozšíření jsou v ekosystému aplikace Dynamo velmi účinným nástrojem pro vývoj. Umožňují vývojářům vytvářet vlastní funkce založené na interakcích a logice aplikace Dynamo. Rozšíření lze rozdělit na dvě hlavní kategorie: rozšíření a rozšíření pohledu. Jak již název napovídá, systém rozšíření pohledu umožňuje rozšířit uživatelské rozhraní aplikace Dynamo registrací vlastních položek nabídky. Běžná rozšíření fungují velmi podobným způsobem bez uživatelského rozhraní. Můžeme například vytvořit rozšíření, které bude do konzoly aplikace Dynamo zaznamenávat konkrétní informace. Tento scénář nevyžaduje žádné vlastní uživatelské rozhraní, a proto by jej bylo možné provést také pomocí rozšíření.

Případová studie rozšíření

S využitím příkladu SampleViewExtension z úložiště DynamoSamples na Githubu projdeme kroky potřebné k vytvoření jednoduchého nemodálního okna, které zobrazuje aktivní uzly v grafu v reálném čase Rozšíření pohledu vyžaduje, abychom pro okno vytvořili uživatelské rozhraní a svázali hodnoty s modelem pohledu.

1. Okno rozšíření pohledu vytvořené podle příkladu SampleViewExtension v úložišti na Githubu.

Ačkoliv budeme tento příklad vytvářet od základů, můžete si také stáhnout a vytvořit úložiště DynamoSamples, které vám poslouží jako reference.

Úložiště DynamoSamples: https://github.com/DynamoDS/DynamoSamples

Tato ukázka bude konkrétně odkazovat na projekt s názvem SampleViewExtension, který se nachází v umístění DynamoSamples/src/.

Implementace rozšíření pohledu

Rozšíření pohledu má tři základní součásti:

• Sestava obsahující třídu, která implementuje IViewExtension, a třídu, která vytváří model pohledu.

• Soubor .xml, který aplikaci Dynamo říká, kde má tuto sestavu za běhu hledat a jaký typ rozšíření má hledat.

• Soubor .xaml, který sváže data s grafickým zobrazením a určuje vzhled okna.

1. Vytvoření struktury projektu

Začněte vytvořením nového projektu Class Library s názvem SampleViewExtension.

1. Vytvořte nový projekt výběrem možnosti File > New > Project.

2. Vyberte Class Library.

3. Pojmenujte projekt jako SampleViewExtension.

4. Klikněte na tlačítko Ok.

V tomto projektu budeme potřebovat dvě třídy. Jedna třída implementuje IViewExtension a druhá implementuje NotificationObject.. IViewExtension bude obsahovat všechny informace o tom, jak bude rozšíření nasazeno, načteno, odkazováno a zrušeno. NotificationObject bude poskytovat oznámení o změnách v aplikaci Dynamo a IDisposable. Pokud dojde ke změně, počet se odpovídajícím způsobem aktualizuje.

1. Soubor třídy s názvem SampleViewExtension.cs, který implementuje IViewExtension.

2. Soubor třídy s názvem SampleWindowViewMode.cs, který implementuje NotificationObject.

K použití IViewExtension budeme potřebovat balíček NuGet WpfUILibrary. Instalace tohoto balíčku automaticky nainstaluje balíčky Core, Services a ZeroTouchLibrary.

1. Vyberte balíček WpfUILibrary.

2. Kliknutím na tlačítko Install nainstalujte všechny závislé balíčky.

2. Implementace třídy IViewExtension

Ve třídě IViewExtension určíme, co se stane při spuštění aplikace Dynamo, při načtení rozšíření a při ukončení aplikace Dynamo. Do souboru třídy SampleViewExtension.cs přidejte následující kód:

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

    }
}

Třída SampleViewExtension vytvoří položku nabídky pro otevření okna, na kterou lze kliknout, a propojí ji k modelu pohledu a oknu.

• public class SampleViewExtension : IViewExtension SampleViewExtension zdědí z rozhraní IViewExtension vše, co je k vytvoření položky nabídky potřeba.

• sampleMenuItem = new MenuItem { Header = "Show View Extension Sample Window" }; vytvoří objekt MenuItem a přidá jej do nabídky View.

1. Položka nabídky

• sampleMenuItem.Click += (sender, args) aktivuje událost, která při kliknutí na položku nabídky otevře nové okno.

• MainGrid = { DataContext = viewModel } nastaví kontext dat pro hlavní osnovu v okně, s odkazem na Main Grid v souboru .xaml, který vytvoříme

• Owner = p.DynamoWindow nastaví jako vlastníka našeho místního okna aplikaci Dynamo. To znamená, že nové okno je závislé na aplikaci Dynamo, takže akce, například minimalizace, maximalizace a obnovení aplikace Dynamo, způsobí, že nové okno bude mít stejné chování.

• window.Show(); zobrazí okno, kterému byly nastaveny další vlastnosti okna.

3. Implementace modelu pohledu

Nyní, když jsme zadali některé základní parametry okna, přidáme logiku pro reakci na různé události související s aplikací Dynamo a instruujeme uživatelské rozhraní, aby se aktualizovalo na základě těchto událostí. Do souboru třídy SampleWindowViewModel.cs zkopírujte následující kód:

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

Tato implementace třídy modelu pohledu naslouchá CurrentWorkspaceModel a aktivuje událost, když je uzel přidán nebo odstraněn z pracovního prostoru. To vyvolá změnu vlastnosti, která upozorní uživatelské rozhraní nebo vázané prvky, že data byla změněna a je nutné je aktualizovat. Je volán getter ActiveNodeTypes, který interně volá další pomocnou funkcigetNodeTypes(). Tato funkce iteruje všechny aktivní uzly na kreslicí ploše, vyplní řetězec obsahující názvy těchto uzlů a vrátí tento řetězec do vazby v souboru XAML, který se zobrazí v našem místním okně.

Po definování základní logiky rozšíření nyní zadáme podrobnosti týkající se vzhledu okna pomocí souboru .xaml. Vše, co potřebujeme, je jednoduché okno, které zobrazí řetězec prostřednictvím vazby vlastnosti ActiveNodeTypes v TextBlock Text.

1. Klikněte pravým tlačítkem na projekt a vyberte Add > New Item....

2. Vyberte šablonu User Control, kterou změníme a vytvoříme okno.

3. Pojmenujte nový soubor jako SampleWindow.xaml.

4. Klikněte na tlačítko Add.

V kódu .xaml okna bude nutné svázat SelectedNodesText k textovému bloku. Přidejte následující kód do souboru 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>

• Text="{Binding ActiveNodeTypes}" se váže k hodnotě vlastnosti ActiveNodeTypes v souboru SampleWindowViewModel.cs s hodnotou TextBlock Textv okně.

Nyní inicializujeme ukázkové okno v záložním souboru XAML C# SampleWindow.xaml.cs. Přidejte následující kód do souboru SampleWindow.xaml:

using System.Windows;

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

Rozšíření pohledu je nyní připraveno k sestavení a přidání do aplikace Dynamo. Aplikace Dynamo vyžaduje soubor xml, aby bylo možné zaregistrovat výstup .dll jako rozšíření.

1. Klikněte pravým tlačítkem na projekt a vyberte Add > New Item....

2. Vyberte soubor XML.

3. Pojmenujte soubor jako SampleViewExtension_ViewExtensionDefinition.xml.

4. Klikněte na tlačítko Add.

• Název souboru se řídí standardem aplikace Dynamo pro odkazování na sestavu rozšíření takto: "extensionName"_ViewExtensionDefinition.xml

V souboru xml přidejte následující kód, který aplikaci Dynamo řekne, kde má hledat sestavu rozšíření:

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

• V tomto příkladu jsme sestavu vytvořili do výchozí složky projektu aplikace Visual Studio. Nahraďte cíl <AssemblyPath>...</AssemblyPath> umístěním sestavy.

Posledním krokem je zkopírování souboru SampleViewExtension_ViewExtensionDefinition.xml do složky rozšíření pohledů aplikace Dynamo, která se nachází v instalačním adresáři jádra aplikace Dynamo C:\Program Files\Dynamo\Dynamo Core\1.3\viewExtensions. Je důležité si uvědomit, že existují samostatné složky pro extensions a viewExtensions. Umístění souboru xml do nesprávné složky může způsobit nesprávné načtení za běhu.

1. Soubor .xml, který jsme zkopírovali do složky rozšíření pohledů aplikace Dynamo.

Toto je základní úvod k rozšířením pohledu. Propracovanější případovou studii naleznete v balíčku DynaShape, projektu s otevřeným zdrojovým kódem na Githubu. Tento balíček používá rozšíření pohledu, které umožňuje živé úpravy v pohledu modelu aplikace Dynamo.

Instalační program balíčku DynaShape lze stáhnout z fóra aplikace Dynamo: https://forum.dynamobim.com/t/dynashape-published/11666

Zdrojový kód lze klonovat z Githubu: https://github.com/LongNguyenP/DynaShape

Dosažení požadovaného rozvržení balíčku závisí na typech uzlů, které do balíčku zahrnete. Uzly odvozené z uzlů NodeModel, uzly ZeroTouch a vlastní uzly mají mírně odlišný proces definování kategorizace. Tyto typy uzlů můžete kombinovat v rámci stejného balíčku, ale bude to vyžadovat kombinaci níže uvedených strategií.

NodeModel

Knihovny NodeModel jsou ve výchozím nastavení uspořádány na základě struktury tříd.

namespace SampleLibraryUI.Examples

// Class Attribute
[NodeName("MyNodeModel")]
public class MyNewNodeModel : NodeModel

// or

// Constructor
public ButtonCustomNodeModel()
{
    this.Name = "MyNodeModel";
}

Uzel bude umístěn v doplňcích v následující cestě:

SampleLibraryUI/Examples/MyNodeModel

Kategorii můžete také přepsat pomocí atributu NodeCategory ve třídě nebo v konstruktoru, jak je zobrazeno níže.

// Class Attribute
[NodeCategory("NewSampleLibraryUI.Examples")]

// or

// Constructor
public ButtonCustomNodeModel()
{
    this.Category = "NewSampleLibraryUI.Examples";
}

Uzel se nyní bude nacházet v doplňcích v cestě:

NewSampleLibraryUI/Examples/MyNodeModel

ZeroTouch

Knihovny ZeroTouch jsou také ve výchozím nastavení uspořádány podle struktury tříd.

namespace MyZTLibrary

public class Utilities
{
    public double doubleValue(double num)
    {
        return num * 2;
    }
}

Uzel bude umístěn v doplňcích v následující cestě:

MyZTLibrary/Utilities/doubleValue

Umístění struktury třídy lze rovněž přepsat pomocí souboru XML Dynamo Customization.

• Soubor XML musí mít odpovídající název a musí se nacházet ve složce extra balíčku.

  • PackageName_DynamoCustomization.xml

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MeshToolkit</name>
    </assembly>
    <namespaces>
        <!--Remap Namespaces-->
        <namespace name="Autodesk.Dynamo.MeshToolkit">
            <category>MeshToolkit</category>
        </namespace>
        <namespace name="Autodesk.Dynamo.MeshToolkit.Display">
                <category>Display</category>
        </namespace>
    </namespaces>
    <classes>
        <!--Remap Class Names-->
        <class name="Autodesk.Dynamo.MeshToolkit.Display.MeshDisplay" shortname="MeshDisplay"/>
        <class name="Autodesk.Dynamo.MeshToolkit.Mesh" shortname="Mesh"/>
    </classes>
</doc>

Vlastní uzly

Vlastní uzly jsou uspořádány na základě parametru Category Name zadaného během vytváření uzlů (v novém dialogu Vlastní uzel).

UPOZORNĚNÍ Použití tečkové notace v názvech nebo kategoriích uzlů bude mít za následek vytvoření dalších vnořených podkategorií. Tečka . bude fungovat jako oddělovač určující další hierarchii. Jedná se o nové chování v knihovně v aplikaci Dynamo 2.0.

Název kategorie lze později aktualizovat v souboru .dyf (XML nebo JSON),

{
  "Uuid": "85066088-1616-40b1-96e1-c33e685c6948",
  "IsCustomNode": true,
  "Category": "MyCustomNodes.Utilities.Actions",
  "Description": "This is an example custom nodes.",
  "Name": "doubleValue",
  "ElementResolver": {
    "ResolutionMap": {}
  },...

<Workspace Version="1.3.0.0000" X="100" Y="100" zoom="1.0000000" Description="This is an example custom nodes." Category="MyCustomNodes.Utilities.Actions" Name="doubleValue" ID="85066088-1616-40b1-96e1-c33e685c6948">

Strategie migrace uzlů balíčků

Pokud se autor balíčku rozhodne v nové verzi přejmenovat dříve existující uzel, měl by poskytnout prostředky pro migraci grafů, které obsahují uzly se starými názvy. Toho lze dosáhnout následujícími způsoby:

Uzly ZeroTouch používají soubor Namespace.Migrations.XML umístěný v balíčcích ve složce bin. Viz například:

MyZeroTouchLib.MyNodes.SayHello na MyZeroTouchLib.MyNodes.SayHelloRENAMED

<?xml version="1.0"?>
<migrations>
  <priorNameHint>
    <oldName>MyZeroTouchLib.MyNodes.SayHello</oldName>
    <newName>MyZeroTouchLib.MyNodes.SayHelloRENAMED</newName>
  </priorNameHint>
</migrations>

Uzly odvozené z uzlů NodeModel používají atribut AlsoKnownAs třídy. Viz například:

SampleLibraryUI.Examples.DropDownExample na SampleLibraryUI.Examples.DropDownExampleRENAMED

namespace SampleLibraryUI.Examples
{
    [NodeName("Drop Down Example")]
    [NodeDescription("An example drop down node.")]
    [IsDesignScriptCompatible]
    [AlsoKnownAs("SampleLibraryUI.Examples.DropDownExample")]
    public class DropDownExampleRENAMED : DSDropDownBase
    {
        ...
    }
{

  -o, -O, --OpenFilePath        Instruct Dynamo to open a command file and run the commands it contains at 
                                this path, this option is only supported when run from DynamoSandbox

  -c, -C, --CommandFilePath     Instruct Dynamo to open a command file and run the commands it contains at 
                                this path, this option is only supported when run from DynamoSandbox                      

  -v, -V, --Verbose             Instruct Dynamo to output all evaluations it performs to an XML file at this path

  -g, -G, --Geometry            Instruct Dynamo to output geometry from all evaluations to a JSON file at this path

  -h, -H, --help                Get some help

  -i, -I, --Import              Instruct Dynamo to import an assembly as a node library. This argument should be a 
                                file path to a single.dll - if you wish to import multiple dlls - list the dlls 
                                separated by a space: -i 'assembly1.dll' 'assembly2.dll'

  --GeometryPath                Relative or absolute path to a directory containing ASM. When supplied, instead of 
                                searching the hard disk for ASM, it will be loaded directly from this path

  -k, -K, --KeepAlive           Keepalive mode, leave the Dynamo process running until a loaded extension shuts it 
                                down

  --HostName                    Identify Dynamo variation associated with the host

  -s, -S, --SessionId           Identify Dynamo host analytics session id

  -p, -P, --ParentId            Identify Dynamo host analytics parent id

  -x, -X, --ConvertFile         When used in combination with the 'O' flag, opens a .dyn file from the specified 
                                path and converts it to .json. The file will have the .json extension and be 
                                located in the same directory as the original file

  -n, -N, --NoConsole           Don't rely on the console window to interact with CLI in Keepalive mode

  -u, -U  --UserData            Specify user data folder to be used by PathResolver with CLI

  --CommonData                  Specify common data folder to be used by PathResolver with CLI

  --DisableAnalytics            Disables analytics in Dynamo for the process lifetime

  --CERLocation                 Specify the crash error report tool located on the disk

  --ServiceMode                 Specify the service mode startup

K čemu to slouží?

Dynamo můžete chtít ovládat z příkazového řádku z různých důvodů. Mezi ně patří například:

• Automatizace mnoha spuštění aplikace Dynamo.

• Testování grafů aplikace Dynamo (při použití aplikace DynamoSandbox se podívejte také na možnost -c).

• Spuštění posloupnosti grafů aplikace Dynamo v určitém pořadí.

• Tvorba dávkových souborů, které spouštějí více příkazových řádků.

• Tvorba dalšího programu, který bude řídit a automatizovat spuštění grafů aplikace Dynamo a provádět s výsledky těchto výpočtů další skvělé akce.

Co to je?

Rozhraní příkazového řádku (DynamoCLI) je doplněk k aplikaci DynamoSandbox. Jedná se o nástroj příkazového řádku typu DOS / terminál určený k pohodlnému spouštění aplikace Dynamo pomocí argumentů příkazového řádku. Ve své první implementaci se nespouští samostatně, ale musí být spuštěn ze složky, kde se nacházejí binární soubory aplikace Dynamo, protože závisí na stejných základních knihovnách DLL jako Sandbox. Nemůže spolupracovat s jinými sestaveními aplikace Dynamo.

Rozhraní příkazového řádku (CLI) lze spustit několika různými způsoby: z příkazového řádku DOS, z dávkových souborů DOS a jako zástupce na ploše systému Windows, jehož cesta je upravena tak, aby obsahovala zadané příznaky příkazového řádku. Specifikace souboru DOS může být plně kvalifikovaná nebo relativní a podporovány jsou také mapované jednotky a syntaxe adres URL. Lze jej také sestavit pomocí platformy Mono a spustit v systému Linux nebo Mac z terminálu.

Balíčky Dynamo jsou nástrojem podporovány, nelze však načíst vlastní uzly (DYF), pouze samostatné grafy (DYN).

Při předběžném testování nástroj CLI podporuje lokalizované verze systému Windows a argumenty filespec lze zadávat velkými znaky ASCII.

K CLI lze přistupovat prostřednictvím aplikace DynamoCLI.exe. Tato aplikace umožňuje uživateli nebo jiné aplikaci komunikovat s vyhodnocovacím modelem aplikace Dynamo vyvoláním souboru DynamoCLI.exe s řetězcem příkazu. Ten může vypadat například takto:

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

Tento příkaz aplikaci Dynamo sdělí, aby otevřela zadaný soubor v umístění "C:\someReallyCoolDynamoFile.Dyn" bez vykreslení uživatelského rozhraní a poté jej spustila. Po dokončení běhu grafu se aplikace Dynamo ukončí.

Novinka ve verzi 2.1: Aplikace DynamoWPFCLI.exe. Tato aplikace podporuje vše, co aplikace DynamoCLI.exe, navíc s možností Geometry (-g). Aplikace DynamoWPFCLI.exe je určena pouze pro systém Windows.

Důležité poznámky

• Upřednostňovanou metodou interakce s DynamoCLI je rozhraní příkazového řádku.

• V tuto chvíli je rozhraní DynamoCLI třeba spouštět z jeho instalačního umístění ve složce [Verze aplikace Dynamo]. Rozhraní CLI potřebuje přístup ke stejným knihovnám DLL jako aplikace Dynamo, proto by se nemělo přesouvat.

• Měli byste být schopni spouštět grafy, které jsou aktuálně otevřené v aplikaci Dynamo, ale může to způsobit nežádoucí vedlejší účinky.

• Všechny cesty k souborům jsou plně kompatibilní se systémem DOS, takže by relativní a plně kvalifikované cesty měly fungovat, ale nezapomeňte cesty uzavřít do uvozovek: "C:cesta\k\soubor.dyn".

• DynamoCLI je nová funkce, která se v současné době vyvíjí: aktuálně CLI načítá pouze podmnožinu standardních knihoven Dynamo. Mějte to na paměti, pokud se graf nespustí správně. Tyto knihovny jsou uvedeny zde

• V současné době není k dispozici žádný standardní výstup. Pokud nedojde k žádným chybám, CLI se po dokončení běhu jednoduše ukončí.

Jak se to používá?

-o: Aplikaci Dynamo můžete otevřít tak, že bude odkazovat na soubor .dyn, a to v bezobslužném režimu, který spustí graf.

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

-v: Lze použít, když je aplikace Dynamo spuštěna v bezobslužném režimu (pokud jste k otevření souboru použil příznak -o). Tento příznak iteruje všechny uzly v grafu a vypíše jejich výstupní hodnoty do jednoduchého souboru XML. Vzhledem k tomu, že příznak --ServiceMode může vynutit, aby aplikace Dynamo spustila více vyhodnocení grafu, bude výstupní soubor obsahovat hodnoty pro každé vyhodnocení, ke kterému dojde.

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

Výstupní soubor XML by měl následující podobu:

    <evaluations>
        <evaluation0>
            <Node guid="e2a6a828-19cb-40ab-b36c-cde2ebab1ed3">
                <output0 value="str" />
            </Node>
            <Node guid="67139026-e3a5-445c-8ba5-8a28be5d1be0">
                <output0 value="C:\Users\Dale\state1.txt" />
            </Node>
            <Node guid="579ebcb8-dc60-4faa-8fd0-cb361443ed94">
                <output0 value="null" />
            </Node>
        </evaluation0>
        <evaluation1>
            <Node guid="e2a6a828-19cb-40ab-b36c-cde2ebab1ed3">
                <output0 value="str" />
            </Node>
            <Node guid="67139026-e3a5-445c-8ba5-8a28be5d1be0">
                <output0 value="C:\Users\Dale\state2.txt" />
            </Node>
            <Node guid="579ebcb8-dc60-4faa-8fd0-cb361443ed94">
                <output0 value="null" />
            </Node>
        </evaluation1>
    </evaluations>

-g: Lze použít, když je aplikace Dynamo spuštěna v bezobslužném režimu (pokud jste k otevření souboru použil příznak -o). Tento příznak vygeneruje graf a poté vypíše výslednou geometrii do souboru JSON.

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

Soubor geometrie JSON by měl následující podobu:

 TBD - Work in progress

-h: Slouží k získání seznamu možných možností.

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

Příznak -i je možné použít vícekrát k importu více sestavení, která graf, jenž se pokoušíte otevřít, vyžaduje ke spuštění.

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

Příznak -l je možné použít ke spuštění aplikace Dynamo v jiném nastavení národního prostředí. Nastavení národního prostředí však obvykle neovlivňuje výsledky grafu

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

Příznak --GeometryPath lze použít k nasměrování aplikace DynamoSandbox nebo CLI na konkrétní sadu binárních souborů ASM. Použijte jej jako v následujícím příkladu:

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

nebo

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

Příznak -k lze použít k tomu, aby proces aplikace Dynamo běžel, dokud jej načtené rozšíření nevypne.

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

Příznak --HostName lze použít k identifikaci variace aplikace Dynamo přidružené k hostiteli.

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

nebo

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

Příznak -s lze použít k identifikaci ID relace analytického hostitele aplikace Dynamo.

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

Příznak -p lze použít k identifikaci ID nadřazeného analytického hostitele Dynamo.

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

Vítejte v dokumentaci pro tvorbu integrací pro vizuální programovací jazyk aplikace Dynamo.

Tato příručka se zabývá různými aspekty hostování aplikace Dynamo ve vaší aplikaci, abyste uživatelům umožnili interakci s vaší aplikací pomocí vizuálního programování.

Obsah:

• Tento úvod Základní přehled toho, co tato příručka obsahuje a o čem je aplikace Dynamo.

• Vlastní vstupní bod aplikace Dynamo Jak vytvořit DynamoModel a kde začít.

• Vázání a trasování prvků Použití mechanismu trasování aplikace Dynamo ke svázání uzlů v grafu s jejich výsledky v hostiteli.

• Uzly Selection doplňku Dynamo Revit Jak implementovat uzly, které uživatelům umožňují vybírat objekty nebo data z hostitele a předávat je jako vstupy do grafu Dynamo.

• Přehled vestavěných balíčků aplikace Dynamo Co je standardní knihovna Dynamo a jak používat základní mechanismus k dodávání balíčků s integrací.

Poznámky k terminologii:

V této příručce budeme k označení kódu, který uživatelé vytvářejí v aplikaci Dynamo, používat zaměnitelné termíny skript, graf a program aplikace Dynamo.

Vlastní vstupní bod aplikace Dynamo

Dynamo Revit jako příklad

https://github.com/DynamoDS/DynamoRevit/blob/master/src/DynamoRevit/DynamoRevit.cs#L534

DynamoModel je vstupním bodem pro aplikaci hostující Dynamo; představuje aplikaci Dynamo. Model je kořenový objekt nejvyšší úrovně, který obsahuje odkazy na další důležité datové struktury a objekty, které tvoří aplikaci Dynamo a virtuální počítač DesignScript.

Objekt konfigurace se používá k nastavení běžných parametrů DynamoModel při jeho vytváření.

Příklady v tomto dokumentu jsou převzaty z implementace DynamoRevit, což je integrace, kde Revit hostuje DynamoModel jako doplněk. (Architektura modulu plug-in pro aplikaci Revit). Po načtení tohoto doplňku se spustí DynamoModel a ten se zobrazí uživateli pomocí DynamoView a DynamoViewModel.

Dynamo je projekt využívající jazyk C# a rozhraní .NET a chcete-li jej použít v procesu ve vaší aplikaci, musíte být schopni hostovat a spouštět kód rozhraní .NET.

DynamoCore je multiplatformní výpočetní modul a kolekce základních modelů, které lze vytvořit pomocí rozhraní .NET nebo Mono (v budoucnu .Net Core). DynamoCoreWPF však obsahuje komponenty uživatelského rozhraní Dynamo pouze pro systém Windows a na jiných platformách se nezkompiluje.

Kroky k přizpůsobení vstupního bodu aplikace Dynamo

K inicializaci DynamoModel budou muset integrátory provést tyto kroky v kódu hostitele.

Předběžné načtení sdílených knihoven DLL aplikace Dynamo z hostitele.

V současné době seznam v D4R obsahuje pouze knihovnu Revit\SDA\bin\ICSharpCode.AvalonEdit.dll.. Důvodem je to, aby se zabránilo konfliktům verzí knihoven v aplikacích Dynamo a Revit. Pokud například dojde ke konfliktům s knihovnou AvalonEdit, může být funkce bloku kódu zcela nefunkční. Tento problém je hlášen pro aplikaci Dynamo 1.1.x na adrese https://github.com/DynamoDS/Dynamo/issues/7130 a je také ručně reprodukovatelný. Pokud integrátory zjistí konflikty knihoven mezi hostitelskou funkcí a aplikací Dynamo, doporučujeme provést tento krok jako první. Někdy je to nutné, aby jiný modul plug-in nebo samotná hostitelská aplikace nenačetly nekompatibilní verzi aplikace jako sdílenou závislost. Lepším řešením je vyřešit konflikt verzí vyrovnáním verze nebo použít přesměrování vazby .NET v souboru app.config hostitele, pokud je to možné.

Načítání ASM

Co jsou ASM a LibG

ASM je knihovna geometrie aplikace ADSK, na které je postavena aplikace Dynamo.

LibG je uživatelsky přívětivá obálka rozhraní .Net kolem jádra geometrie ASM. LibG sdílí své schéma správy verzí s ASM – používá stejné číslo hlavní a vedlejší verze ASM, které označuje, že se jedná o odpovídající obálku konkrétní verze ASM. Když je zadána verze ASM, odpovídající verze LibG by měla být stejná. Obálka LibG by ve většině případů měla fungovat se všemi verzemi ASM konkrétní hlavní verze. Například verze LibG 223 by měla být schopna načíst libovolnou verzi ASM 223.

Načítání ASM aplikací Dynamo Sandbox

Aplikace Dynamo Sandbox je navržena tak, aby byla schopna pracovat s více verzemi ASM. Za tímto účelem je k jádru přibaleno a dodáváno více verzí LibG. Nástroj Dynamo Shape Manager obsahuje vestavěnou funkci k vyhledávání produktů Autodesk dodávaných s ASM, takže aplikace Dynamo může načítat ASM z těchto produktů a nechat uzly geometrie pracovat, aniž by byly explicitně načteny do hostitelské aplikace. Seznam produktů je v současné podobě následující:

private static readonly List<string> ProductsWithASM = new List<string>() 

 { "Revit", "Civil", "Robot Structural Analysis", "FormIt" }; 

Aplikace Dynamo prohledá registr systému Windows a zjistí, zda jsou v počítači uživatele nainstalovány produkty Autodesk uvedené v tomto seznamu. Pokud jsou některé z nich nainstalovány, vyhledá binární soubory ASM, zjistí jejich verzi a vyhledá odpovídající verzi libG v aplikaci Dynamo.

S ohledem na verzi ASM vybere následující rozhraní API ShapeManager odpovídající umístění předběžného načtení obálky libG, která se má načíst. Pokud existuje přesná shoda verzí, bude použita, jinak se načte nejbližší nižší verze libG, ale se stejnou hlavní verzí.

Pokud například aplikace Dynamo integrována s vývojovým sestavením aplikace Revit, které obsahuje novější sestavení ASM 225.3.0, pokusí se aplikace Dynamo použít libG 225.3.0, pokud existuje, jinak se pokusí použít nejbližší hlavní verzi nižší než první volba, tj. 225.0.0.

public static string GetLibGPreloaderLocation(Version asmVersion, string dynRootFolder)

Načtení ASM integrací aplikace Dynamo z hostitele

Revit je první položkou v seznamu vyhledávání produktů ASM, což znamená, že ve výchozím nastavení se soubor DynamoSandbox.exe pokusí načíst ASM nejprve z aplikace Revit. Přitom chceme zajistit, aby integrovaná pracovní relace D4R načítala ASM z aktuální verze hostitelské aplikace Revit: např. pokud má uživatel v počítači nainstalovanou aplikaci R2018 i R2020, při spuštění D4R z aplikace R2020 by se měla použít ASM 225 z aplikace R2020 místo ASM 223 z aplikace R2018. Integrátory budou muset implementovat podobná volání, jako je níže uvedené, aby vynutili načtení jimi určené verze.

internal static Version PreloadAsmFromRevit() 

{ 

     var asmLocation = AppDomain.CurrentDomain.BaseDirectory; 
     Version libGVersion = findRevitASMVersion(asmLocation); 
     var dynCorePath = DynamoRevitApp.DynamoCorePath; 
     var preloaderLocation = DynamoShapeManager.Utilities.GetLibGPreloaderLocation(libGVersion, dynCorePath); 
     Version preLoadLibGVersion = PreloadLibGVersion(preloaderLocation); 
     DynamoShapeManager.Utilities.PreloadAsmFromPath(preloaderLocation, asmLocation); 
     return preLoadLibGVersion; 

} 

Načtení ASM aplikací Dynamo z přizpůsobené cesty

Nedávno jsme do souborů DynamoSandbox.exe a DynamoCLI.exe přidali možnost načíst konkrétní verzi ASM. Chcete-li přeskočit běžné chování vyhledávání v registru, můžete pomocí příznaku �gp vynutit, aby aplikace Dynamo načetla ASM z konkrétní určité cesty.

DynamoSandbox.exe -gp �somePath/To/ASMDirectory/�

Vytvoření souboru StartConfiguration

Soubor StartupConfiguration se používá jako parametr k inicializaci objektu DynamoModel, což znamená, že obsahuje téměř všechny definice, jak chcete přizpůsobit nastavení relace Dynamo. V závislosti na tom, jak jsou nastaveny následující vlastnosti, se může integrace aplikace Dynamo u různých integrátorů lišit. Různé integrátory mohou například nastavit různé cesty k šablonám jazyka Python nebo formáty zobrazovaných čísel.

Skládá se z následujících částí:

• DynamoCorePath // Umístění načítaných binárních souborů DynamoCore.

• DynamoHostPath // Umístění binárních souborů integrace aplikace Dynamo.

• GeometryFactoryPath // Umístění načtených binárních souborů libG.

• PathResolver // Objekt, který pomáhá rozpoznat různé soubory.

• PreloadLibraryPaths // Umístění binárních souborů předběžně načítaných uzlů, např. DSOffice.dll.

• AdditionalNodeDirectories // Umístění binárních souborů dalších uzlů.

• AdditionalResolutionPaths // Cesta k sestavení pro další závislosti, které mohou být vyžadovány při načítání knihoven.

• UserDataRootFolder // Složka uživatelských dat, např. "AppData\Roaming\Dynamo\Dynamo Revit".

• CommonDataRootFolder // Výchozí složka pro ukládání vlastních definic, ukázek, atd.

• Kontext // Název hostitele integrátoru + verze (Revit<BuildNum>).

• SchedulerThread // Vlákno plánovače integrátoru implementující ISchedulerThread – pro většinu integrátorů je to hlavní vlákno uživatelského rozhraní nebo jakékoli vlákno, ze kterého mohou přistupovat ke svému rozhraní API.

• StartInTestMode // Určuje, zda je aktuální relace testovací automatizační relací. Mění řadu chování aplikace Dynamo – nepoužívejte, pokud nepíšete testy.

• AuthProvider // Implementace IAuthProvider v integrátoru, např. implementace RevitOxygenProvider v knihovně Greg.dll. Používá se k odesílání integrace nástrojem Package Manager.

Předvolby

Výchozí cesta k nastavení předvoleb je řízena parametrem PathManager.PreferenceFilePath, např. "AppData\\Roaming\\Dynamo\\Dynamo Revit\\2.5\\DynamoSettings.xml". Integrátory se mohou rozhodnout, zda chtějí do umístění, které je třeba sladit se správcem cest, dodat také přizpůsobený soubor nastavení předvoleb. Následují vlastnosti nastavení předvoleb, které jsou serializovány:

• IsFirstRun // Označuje, zda je tato verze aplikace Dynamo spuštěna poprvé, používá se například k určení, zda je nutné zobrazit zprávu o přihlášení/odhlášení GA. Slouží také k určení, zda je při spuštění nové verze Dynamo nutné migrovat starší nastavení předvoleb aplikace Dynamo, aby uživatelé měli konzistentní prostředí.

• IsUsageReportingApproved // Označuje, zda jsou schváleny zprávy o využití či nikoli.

• IsUsageReportingApproved // Označuje, zda jsou schváleny analytické zprávy či nikoli.

• LibraryWidth // Šířka levého panelu knihovny aplikace Dynamo.

• ConsoleHeight // Výška zobrazení konzole.

• ShowPreviewBubbles // Označuje, zda se zobrazí bubliny náhledu.

• ShowConnector // Označuje, zda se zobrazí konektory.

• ConnectorType // Označuje typ konektoru: beziérova křivka nebo křivka

• BackgroundPreviews // Označuje aktivní stav zadaného náhledu na pozadí.

• RenderPrecision // Úroveň přesnosti rendrování – nižší generuje sítě s menším počtem trojúhelníků. Vyšší přesnost vygeneruje hladší geometrii v náhledu na pozadí. Dobré číslo pro rychlé rendrování geometrie náhledu je 128.

• ShowEdges // Označuje, zda budou rendrovány hrany povrchů a těles.

• ShowDetailedLayout // NEPOUŽÍVANÉ

• WindowX, WindowY // Poslední souřadnice X, Y okna aplikace Dynamo.

• WindowW, WindowH // Poslední šířka a výška okna aplikace Dynamo.

• UseHardwareAcceleration // Aplikace Dynamo použije hardwarovou akceleraci, pokud je podporována.

• NumberFormat // Přesnost na desetinná místa použitá k zobrazení čísel v bublině náhledu toString().

• MaxNumRecentFiles // Maximální počet posledních cest k souborům, které mají být uloženy.

• RecentFiles // Seznam cest k naposledy otevřených souborům. Změna tohoto nastavení přímo ovlivní seznam posledních souborů na úvodní stránce aplikace Dynamo

• BackupFiles // Seznam cest k záložním souborům.

• CustomPackageFolders // Seznam složek obsahujících binární soubory Zero-Touch a cesty k adresářům, u kterých budou kontrolovány balíčky a vlastní uzly.

• PackageDirectoriesToUninstall // Seznam balíčků, pomocí nichž nástroj Package Manager určuje, které balíčky jsou označeny k odstranění. Pokud je to možné, budou tyto cesty odstraněny během spuštění aplikace Dynamo.

• PythonTemplateFilePath // Cesta k souboru jazyka Python (.py), který se použije jako výchozí šablona při vytváření nového uzlu PythonScript. Lze ji použít k nastavení vlastní šablony jazyka Python pro vaši integraci.

• BackupInterval // Označuje, jak dlouho (v milisekundách) se bude graf automaticky ukládat.

• BackupFilesCount // Označuje, kolik záloh bude vytvořeno.

• PackageDownloadTouAccepted // Označuje, zda uživatel přijal podmínky používání pro stahování balíčků z nástroje Package Manager.

• OpenFileInManualExecutionMode // Označuje výchozí stav zaškrtávacího políčka Otevřít v režimu ručního spuštění v dialogu pro otevření souboru.

• NamespacesToExcludeFromLibrary //Určuje, které (pokud existují) jmenné prostory by se neměly zobrazovat v knihovně uzlů aplikace Dynamo. Formát řetězce: „[název knihovny]:[plně kvalifikovaný jmenný prostor]“

Příklad nastavení serializovaných předvoleb:

<PreferenceSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 

<IsFirstRun>false</IsFirstRun> 

<IsUsageReportingApproved>false</IsUsageReportingApproved> 

<IsAnalyticsReportingApproved>false</IsAnalyticsReportingApproved> 

<LibraryWidth>204</LibraryWidth> 

<ConsoleHeight>0</ConsoleHeight> 

<ShowPreviewBubbles>true</ShowPreviewBubbles> 

<ShowConnector>true</ShowConnector> 

<ConnectorType>BEZIER</ConnectorType> 

<BackgroundPreviews> 

<BackgroundPreviewActiveState> 

<Name>IsBackgroundPreviewActive</Name> 

<IsActive>true</IsActive> 

</BackgroundPreviewActiveState> 

<BackgroundPreviewActiveState> 

<Name>IsRevitBackgroundPreviewActive</Name> 

<IsActive>true</IsActive> 

</BackgroundPreviewActiveState> 

</BackgroundPreviews> 

<IsBackgroundGridVisible>true</IsBackgroundGridVisible> 

<RenderPrecision>128</RenderPrecision> 

<ShowEdges>false</ShowEdges> 

<ShowDetailedLayout>true</ShowDetailedLayout> 

<WindowX>553</WindowX> 

<WindowY>199</WindowY> 

<WindowW>800</WindowW> 

<WindowH>676</WindowH> 

<UseHardwareAcceleration>true</UseHardwareAcceleration> 

<NumberFormat>f3</NumberFormat> 

<MaxNumRecentFiles>10</MaxNumRecentFiles> 

<RecentFiles> 

<string></string> 

</RecentFiles> 

<BackupFiles> 

<string>..AppData\Roaming\Dynamo\Dynamo Revit\backup\backup.DYN</string> 

</BackupFiles> 

<CustomPackageFolders> 

<string>..AppData\Roaming\Dynamo\Dynamo Revit\2.5</string> 

</CustomPackageFolders> 

<PackageDirectoriesToUninstall /> 

<PythonTemplateFilePath /> 

<BackupInterval>60000</BackupInterval> 

<BackupFilesCount>1</BackupFilesCount> 

<PackageDownloadTouAccepted>true</PackageDownloadTouAccepted> 

<OpenFileInManualExecutionMode>false</OpenFileInManualExecutionMode> 

<NamespacesToExcludeFromLibrary> 

<string>ProtoGeometry.dll:Autodesk.DesignScript.Geometry.TSpline</string> 

</NamespacesToExcludeFromLibrary> 

</PreferenceSettings>