Con un progetto di Visual Studio attivo e funzionante, illustreremo come creare un nodo personalizzato che crea una griglia rettangolare di celle. Sebbene sia possibile crearlo con diversi nodi standard, è uno strumento utile che può essere facilmente contenuto in un nodo zero-touch. A differenza delle linee della griglia, le celle possono essere messe in scala rispetto ai loro punti centrali, sottoposte a query per conoscere i loro vertici d'angolo o integrate in facce.

Questo esempio riguarda alcune delle funzionalità e dei concetti di cui tenere conto durante la creazione di un nodo zero-touch. Dopo aver creato il nodo personalizzato e averlo aggiunto a Dynamo, assicurarsi di consultare la pagina Ulteriori informazioni sul concetto di zero-touch per esaminare in modo più approfondito valori di input di default, restituzione di più valori, documentazione, oggetti, utilizzo dei tipi di geometria di Dynamo e migrazioni.

Nodo griglia rettangolare personalizzata

Per iniziare a creare il nodo griglia, creare un nuovo progetto della libreria di classi di Visual Studio. Fare riferimento alla pagina Per iniziare per una simulazione dettagliata di come impostare un progetto.

1. Scegliere Class Library per il tipo di progetto.

2. Assegnare al progetto il nome CustomNodes.

Poiché creeremo la geometria, dobbiamo fare riferimento al pacchetto NuGet appropriato. Installare il pacchetto ZeroTouchLibrary da Gestione pacchetti NuGet. Questo pacchetto è necessario per l'istruzione using Autodesk.DesignScript.Geometry;.

1. Cercare il pacchetto ZeroTouchLibrary.

2. Utilizzeremo questo nodo nella build corrente di Dynamo Studio, ossia 1.3. Selezionare la versione del pacchetto corrispondente.

3. Notare che è stato anche rinominato il file di classe in Grids.cs.

Successivamente, dobbiamo stabilire uno spazio dei nomi e una classe in cui sarà presente il metodo RectangularGrid. Il nome del nodo verrà assegnato in Dynamo in base ai nomi del metodo e della classe. Non dobbiamo ancora copiare il file in 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; fa riferimento a ProtoGeometry.dll nel pacchetto ZeroTouchLibrary. System.Collections.Generic è necessario per la creazione di elenchi.

Ora è possibile aggiungere il metodo per il disegno dei rettangoli. Il file di classe dovrebbe essere simile al seguente e può essere copiato in 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;
        }
    }
}

Se il progetto è simile a questo, procedere e provare a creare il file .dll.

1. Scegliere Build > Build Solution.

Cercare un file bin nella cartella .dll del progetto. Se la creazione è stata eseguita correttamente, possiamo aggiungere il file .dll a Dynamo.

1. Il nodo RectangularGrids personalizzato nella libreria di Dynamo

2. Il nodo personalizzato nell'area di disegno

3. Il pulsante Aggiungi per aggiungere .dll a Dynamo

Modifiche di nodi personalizzati

Nell'esempio precedente, abbiamo creato un nodo piuttosto semplice che non definiva molto altro al di fuori del metodo RectangularGrids. Tuttavia, potremmo voler creare delle descrizioni comandi per le porte di input o assegnare al nodo un riepilogo come i nodi standard di Dynamo. L'aggiunta di queste funzionalità ai nodi personalizzati ne semplifica l'utilizzo, soprattutto se un utente desidera cercarle nella libreria.

1. Un valore di input di default

2. Una descrizione comando per l'input xCount

Il nodo RectangularGrid richiede alcune di queste funzionalità di base. Nel codice riportato di seguito sono state aggiunte descrizioni delle porte di input e di output, un riepilogo e valori di input di default.

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

• Fornire i valori di default degli input assegnando valori ai parametri del metodo: RectangularGrid(int xCount = 10, int yCount = 10).

• Creare descrizioni comandi di input e output, parole chiave di ricerca e un riepilogo con la documentazione XML preceduta da ///.

Per aggiungere descrizioni comandi, abbiamo bisogno di un file XML nella directory del progetto. Un file .xml può essere generato automaticamente da Visual Studio attivando l'opzione.

1. Attivare qui il file della documentazione XML e specificarne il percorso. In questo modo viene generato un file XML.

L'operazione è completata. È stato creato un nuovo nodo con diverse funzionalità standard. Nel capitolo seguente sui concetti di base zero-touch sono illustrati in modo più dettagliato lo sviluppo di nodi zero-touch e i problemi di cui è necessario tenere conto.

Indipendentemente dal livello di esperienza, la piattaforma Dynamo è progettata per consentire a tutti gli utenti di contribuire. Esistono diverse opzioni di sviluppo che si rivolgono a diversi livelli di abilità e competenze, ciascuno con i suoi punti di forza e di debolezza a seconda dell'obiettivo. Di seguito illustreremo le diverse opzioni e come scegliere una piuttosto che un'altra.

Tre ambienti di sviluppo: Visual Studio, l'editor Python Editor e la sintassi DesignScript di Code Block

Quali sono le opzioni disponibili?

Le opzioni di sviluppo per Dynamo si suddividono principalmente in due categorie: per Dynamo anziché in Dynamo. Le due categorie possono essere considerate come segue: "in" Dynamo implica che il contenuto creato con l'IDE Dynamo deve essere utilizzato in Dynamo e "per" Dynamo implica che devono essere utilizzati strumenti esterni per creare il contenuto da importare in Dynamo. Sebbene questa guida si concentri sullo sviluppo per Dynamo, le risorse per tutti i processi sono descritte qui di seguito.

Per Dynamo

Questi nodi consentono il massimo grado di personalizzazione. Molti pacchetti vengono creati con questo metodo ed è necessario per contribuire ai file di origine di Dynamo. Il processo di creazione sarà descritto in questa guida.

• Nodi zero-touch

• Nodi derivati da NodeModel

• Estensioni

La Guida introduttiva contiene una guida sull'importazione di librerie zero-touch.

Per la discussione seguente, Visual Studio viene utilizzato come ambiente di sviluppo per i nodi zero-touch e NodeModel.

L'interfaccia di Visual Studio con un progetto che verrà sviluppato

In Dynamo

Sebbene questi processi esistano nell'area di lavoro di programmazione visiva e siano relativamente semplici, sono tutte opzioni valide per personalizzare Dynamo. La Guida introduttiva li tratta ampiamente e fornisce suggerimenti e pratiche ottimali di scripting nel capitolo Strategie di scripting.

• I Code Block espongono DesignScript nell'ambiente di programmazione visiva, consentendo workflow flessibili per gli script di testo e i nodi. Una funzione in un Code Block può essere chiamata da qualsiasi elemento dell'area di lavoro.

  Scaricare un esempio di Code Block (fare clic con il pulsante destro del mouse e salvare con nome) o vedere una simulazione dettagliata nella Guida introduttiva.

• I nodi personalizzati sono contenitori per raccolte di nodi o anche interi grafici. Sono un modo efficace per raccogliere le routine utilizzate più di frequente e condividerle con la comunità.

  Scaricare un esempio di nodo personalizzato (fare clic con il pulsante destro del mouse e salvare con nome) o vedere una simulazione dettagliata nella Guida introduttiva.

• I nodi Python sono un'interfaccia di scripting nell'area di lavoro di programmazione visiva, simile ai Code Block. Le librerie Autodesk.DesignScript utilizzano una notazione con punto simile a DesignScript.

  Scaricare un esempio di nodo Python (fare clic con il pulsante destro del mouse e salvare con nome) o vedere una simulazione dettagliata nella Guida introduttiva

Lo sviluppo nell'area di lavoro di Dynamo è un potente strumento per ottenere un feedback immediato.

Sviluppo nell'area di lavoro di Dynamo con il nodo Python

Quali sono i vantaggi/gli svantaggi di ciascuna opzione?

Le opzioni di sviluppo per Dynamo sono state progettate per soddisfare la complessità di un'esigenza di personalizzazione. Sia che si tratti di scrivere uno script ricorsivo in Python o di creare un'interfaccia utente del nodo completamente personalizzata, esistono opzioni per l'implementazione del codice che comportano solo lo stretto necessario per essere operativi.

Code Block, nodo Python e nodi personalizzati in Dynamo

Si tratta di opzioni semplici per la scrittura di codice nell'ambiente di programmazione visiva Dynamo. L'area di lavoro di programmazione visiva di Dynamo consente di accedere a Python, DesignScript e alla possibilità di contenere più nodi all'interno di un nodo personalizzato.

Con questi metodi è possibile:

• Iniziare a scrivere Python o DesignScript quasi senza alcuna impostazione.

• Importare le librerie di Python in Dynamo.

• Condividere Code Block, nodi Python e nodi personalizzati con la comunità Dynamo come parte di un pacchetto.

Nodi zero-touch

Il termine zero-touch si riferisce ad un semplice metodo di puntamento e clic per l'importazione di librerie C#. Dynamo consentirà di leggere i metodi pubblici di un file .dll e di convertirli in nodi di Dynamo. È possibile utilizzare il metodo zero-touch per sviluppare nodi e pacchetti personalizzati.

Con questo metodo è possibile:

• Importare una libreria non necessariamente sviluppata per Dynamo e creare automaticamente una suite di nuovi nodi, come l'esempio AForge nella Guida introduttiva.

• Scrivere metodi C# e utilizzare facilmente i metodi come nodi in Dynamo.

• Condividere una libreria C# come nodi con la comunità Dynamo in un pacchetto.

Nodi derivati da NodeModel

Questi nodi sono un livello più basso nella struttura di Dynamo. Si basano sulla classe NodeModel e sono scritti in C#. Sebbene questo metodo offra la massima flessibilità e potenza, la maggior parte degli aspetti del nodo deve essere definita esplicitamente e le funzioni devono risiedere in un assieme separato.

Con questo metodo è possibile:

• Creare un'interfaccia utente del nodo completamente personalizzabile con dispositivi di scorrimento, immagini, colori e così via (ad esempio, nodo ColorRange).

• Accedere a ciò che accade nell'area di disegno di Dynamo e intervenire.

• Personalizzare il collegamento.

• Caricare elementi in Dynamo come pacchetto.

Informazioni sul controllo sulle modifiche all'API e delle versioni di Dynamo (1.x → 2.x)

Poiché Dynamo viene aggiornato regolarmente, potrebbero essere apportate modifiche a parte dell'API utilizzata da un pacchetto. Il monitoraggio di queste modifiche è importante per garantire che i pacchetti esistenti continuino a funzionare correttamente.

Le modifiche all'API vengono registrate nella pagina Wiki di Dynamo su GitHub. Vengono descritte le modifiche apportate a DynamoCore, alle librerie e alle aree di lavoro.

Un esempio di modifica significativa imminente è la transizione dal formato di file XML a JSON nella versione 2.0. I nodi derivati da NodeModel ora richiedono un costruttore JSON, altrimenti non si apriranno in Dynamo 2.0.

La documentazione sull'API di Dynamo attualmente copre le funzionalità principali: http://dynamods.github.io/DynamoAPI.

Autorizzazione alla distribuzione di file binari in un pacchetto

Tenere presente che i file .dll inclusi in un pacchetto vengono caricati nel gestore di pacchetti. Se l'autore del pacchetto non ha creato il file .dll, deve disporre dei diritti per condividerlo.

Se un pacchetto include file binari, al momento del download si deve richiedere conferma agli utenti che il pacchetto contiene file binari.

L'origine di Dynamo è ospitata su GitHub per consentire a chiunque di clonare e apportare contributi. In questo capitolo verrà illustrato come clonare il repository utilizzando git, compilare i file di origine con Visual Studio, eseguire una build locale e sottoporla a debug e infine effettuare eventuali nuove modifiche da GitHub.

Individuazione dei repository di Dynamo su GitHub

GitHub è un servizio di hosting basato su git, un sistema di controllo delle versioni per tenere traccia delle modifiche e coordinare il lavoro tra le persone. git è uno strumento che possiamo sfruttare per scaricare i file di origine di Dynamo e mantenerli aggiornati con alcuni comandi. Utilizzando questo metodo si evita il lavoro superfluo e inevitabilmente complicato di dover scaricare e sostituire manualmente i file di origine ad ogni aggiornamento. Il sistema di controllo della versione di git consente di rilevare le differenze tra un repository di codici locale e remoto.

L'origine di Dynamo è ospitata nella pagina di DynamoDS su GitHub in questo repository: https://github.com/DynamoDS/Dynamo

I file di origine di Dynamo.

1. Clonare o scaricare l'intero repository.

2. Visualizza altri repository di DynamoDS.

3. File di origine di Dynamo.

4. File specifici di git.

Pull del repository di Dynamo utilizzando git

Prima di poter clonare il repository, è necessario installare git. Seguire questa breve guida per la procedura di installazione e per impostare un nome utente e un indirizzo e-mail di GitHub. In questo esempio, si utilizzerà git nella riga di comando. Questa guida presuppone che si utilizzi Windows, ma è possibile utilizzare git anche su Mac o Linux per clonare i file di origine di Dynamo.

È necessario un URL dal quale clonare il repository di Dynamo. Questo è disponibile nel pulsante "Clone or download" nella pagina del repository. Copiare l'URL da incollare nella riga di comando.

1. Selezionare "Clone or download".

2. Copiare l'URL.

Con git installato, è possibile clonare il repository di Dynamo. Iniziare aprendo la riga di comando. Quindi, utilizzare il comando di cambio della directory cd per individuare la cartella in cui si desidera clonare i file di origine. In questo caso, è stata creata una cartella denominata Github in Documents.

cd C:\Users\username\Documents\GitHub

Sostituire "username" con il nome utente.

Nel passaggio successivo verrà eseguito un comando di git per clonare il repository di Dynamo nella posizione specificata. L'URL del comando si ottiene facendo clic sul pulsante "Clone or Download" su GitHub. Eseguire questo comando nel terminale di comando. Si noti che questa operazione consente di clonare il ramo principale del repository di Dynamo, che è il codice più aggiornato per Dynamo e che conterrà la versione più recente del codice di Dynamo. Questo ramo cambia ogni giorno.

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

Sappiamo che git funziona se l'operazione di clonazione è stata completata correttamente. In Esplora file, individuare la directory in cui è stata eseguita la clonazione per vedere i file di origine. La struttura della directory dovrebbe essere identica al ramo principale del repository di Dynamo su GitHub.

1. File di origine di Dynamo.

2. File di git

Compilazione del repository utilizzando Visual Studio

Con i file di origine ora clonati nel computer locale, è possibile creare un file eseguibile per Dynamo. A tale scopo, è necessario configurare l'IDE Visual Studio e verificare che siano installati .NET Framework e DirectX.

• Scaricare e installare Microsoft Visual Studio Community 2015, un IDE (ambiente di sviluppo integrato) gratuito e completo ( potrebbero funzionare anche le versioni successive).

• Scaricare e installare Microsoft .NET Framework 4.5 o versione successiva.

• Installazione di Microsoft DirectX dal repository locale di Dynamo (Dynamo\tools\install\Extra\DirectX\DXSETUP.exe)

È possibile che .NET e DirectX siano già installati.

Al termine dell'installazione, è possibile avviare Visual Studio e aprire la soluzione Dynamo.All.sln situata in Dynamo\src.

1. Selezionare File > Apri > Progetto/Soluzione.

2. Individuare il repository di Dynamo e aprire la cartella src.

3. Selezionare il file della soluzione Dynamo.All.sln.

4. Selezionare Apri.

Prima di poter creare la soluzione, è necessario specificare alcune impostazioni. È necessario innanzitutto creare una versione di debug di Dynamo in modo che Visual Studio possa raccogliere più informazioni durante il debug per facilitare lo sviluppo e si desidera dedicarsi a qualsiasi CPU.

Queste diventeranno cartelle all'interno della cartella bin.

1. In questo esempio è stata scelta Debug come configurazione della soluzione.

2. Impostare la piattaforma della soluzione su Any CPU.

Con il progetto aperto, è possibile creare la soluzione. Questo processo creerà un file DynamoSandbox.exe che è possibile eseguire.

La compilazione del progetto ripristinerà le dipendenze NuGet.

1. Selezionare Compilazione > Compila soluzione.

2. Verificare che la build sia stata eseguita correttamente nella finestra Output. Il risultato dovrebbe essere simile a ==== Build: 69 succeeded, 0 failed, 0 up-to-date, 0 skipped ====.

Esecuzione di una build locale

Se Dynamo viene compilato correttamente, nel repository di Dynamo verrà creata una cartella bin con il file DynamoSandbox.exe. In questo caso, si sta eseguendo la compilazione con l'opzione Debug, in modo che il file eseguibile si trovi in bin\AnyCPU\Debug. L'esecuzione di questa operazione consente di aprire una build locale di Dynamo.

1. Il file eseguibile di DynamoSandbox appena creato. Eseguire questo file per avviare Dynamo.

Ora siamo quasi completamente pronti per iniziare lo sviluppo per Dynamo.

Per istruzioni sulla compilazione di Dynamo per altre piattaforme (ad esempio, Linux o OS X), visitare questa pagina Wiki.

Debug di una build locale mediante Visual Studio

Il debug è un processo di identificazione, isolamento e correzione di un bug o di un problema. Una volta che Dynamo è stato creato correttamente dall'origine, è possibile utilizzare diversi strumenti in Visual Studio per eseguire il debug di un'applicazione in esecuzione, ad esempio il modulo aggiuntivo DynamoRevit. È possibile analizzare il codice sorgente per individuare la causa di un problema o controllare il codice attualmente in esecuzione. Per una spiegazione più dettagliata su come eseguire il debug e spostarsi all'interno del codice in Visual Studio, consultare i documenti su Visual Studio.

Per l'applicazione Dynamo indipendente, DynamoSandbox, verranno descritte due opzioni per il debug:

• Compilazione e avvio di Dynamo direttamente da Visual Studio

• Associazione di Visual Studio ad un processo in esecuzione di Dynamo.

Se si avvia Dynamo da Visual Studio, viene ricreata la soluzione per ogni sessione di debug, se necessario, pertanto se si apportano modifiche all'origine, queste verranno incorporate durante il debug. Con la soluzione Dynamo.All.sln ancora aperta, selezionare Debug, AnyCPU e DynamoSandbox dai menu a discesa, quindi fare clic su Start. In questo modo verrà compilato Dynamo e verrà avviato un nuovo processo (DynamoSandbox.exe), al quale viene associato il debugger di Visual Studio.

Compilazione e avvio dell'applicazione direttamente da Visual Studio

1. Impostare la configurazione su Debug.

2. Impostare la piattaforma su Any CPU.

3. Impostare il progetto di avvio su DynamoSandbox.

4. Fare clic su Start per avviare il processo di debug.

In alternativa, è possibile eseguire il debug di un processo di Dynamo che è già in esecuzione per risolvere un problema con un determinato pacchetto o grafico aperto. A questo scopo, si aprono i file di origine del progetto in Visual Studio e si associano ad un processo di Dynamo in esecuzione utilizzando la voce di menu di debug Attach to Process.

Associazione di un processo in esecuzione a Visual Studio

1. Selezionare Debug > Connetti a processo.

2. Scegliere DynamoSandbox.exe.

3. Selezionare Connetti.

In entrambe le situazioni, il debugger viene associato ad un processo di cui si desidera eseguire il debug. È possibile impostare punti di interruzione nel codice prima o dopo l'avvio del debugger, in modo che il processo venga messo in pausa immediatamente prima di eseguire quella riga di codice. Se durante il debug viene generata un'eccezione non rilevata, Visual Studio passerà alla posizione in cui si è verificata nel codice sorgente. Si tratta di un metodo efficiente per individuare semplici arresti anomali, eccezioni non gestite e per comprendere il flusso di esecuzione di un'applicazione.

Durante il debug di DynamoSandbox, viene impostato un punto di interruzione nel costruttore del nodo Color.ByARGB che fa sì che il processo di Dynamo si metta in pausa quando viene creata l'istanza del nodo. Se questo nodo generava un'eccezione o causava l'arresto anomalo di Dynamo, si poteva eseguire ogni riga del costruttore per individuare il punto in cui si verificava il problema.

1. Il punto di interruzione

2. Lo stack di chiamate che mostra la funzione attualmente in esecuzione e le chiamate di funzioni precedenti.

Nella sezione successiva, Compilazione di DynamoRevit dall'origine, verrà illustrato un esempio specifico di debug e verrà descritto come impostare punti di interruzione, eseguire il codice una riga alla volta e leggere lo stack di chiamate.

Pull della build più recente

Poiché l'origine di Dynamo è ospitata su GitHub, il modo più semplice per mantenere aggiornati i file di origine locali è quello di eseguire il pull delle modifiche utilizzando i comandi di git.

Utilizzando la riga di comando, impostare la directory corrente sul repository di Dynamo:

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

Sostituire "username" con il nome utente.

Utilizzare il seguente comando per eseguire il pull delle modifiche più recenti:

git pull origin master

1. Qui è possibile vedere che il repository locale è stato aggiornato con le modifiche da quello remoto.

Oltre al pull degli aggiornamenti, ci sono altri quattro workflow di git da conoscere.

• Eseguire il fork del repository di Dynamo per creare una copia separata dall'originale. Eventuali modifiche apportate qui non influiranno sul repository originale e gli aggiornamenti possono essere recuperati da o inviati con richieste pull. Il fork non è un comando di git, ma è un workflow che GitHub aggiunge: fork, il modello della richiesta pull, è uno dei workflow più comuni per contribuire ai progetti open source in linea. Vale la pena di imparare se si vuole contribuire a Dynamo.

• Ramo: si lavora a esperimenti o a nuove funzionalità isolate da altri lavori nei rami. In questo modo, è più semplice inviare richieste pull.

• Eseguire spesso i commit dopo aver completato un'unità di lavoro e dopo una modifica che potrebbe essere utile annullare. Un commit registra le modifiche apportate al repository e sarà visibile quando si esegue una richiesta pull nel repository di Dynamo principale.

• Creare richieste pull quando le modifiche sono pronte per essere ufficialmente proposte al repository di Dynamo principale.

Il team di Dynamo dispone di istruzioni specifiche per la creazione di richieste pull. Per informazioni più dettagliate sugli argomenti da trattare, fare riferimento alla sezione Richieste pull.

Vedere questa pagina della documentazione per un elenco di riferimento dei comandi di git.

Prima di dedicarci al tema dello sviluppo, è importante costruire una solida base per un nuovo progetto. Nella comunità di sviluppatori di Dynamo sono disponibili diversi modelli di progetto che rappresentano ottimi punti di partenza, ma è ancora più importante comprendere come iniziare un progetto da zero. Creare un progetto dalle fondamenta consente di comprendere meglio il processo di sviluppo.

Creazione di un progetto di Visual Studio

Visual Studio è un potente IDE in cui è possibile creare un progetto, aggiungere riferimenti, creare file .dll ed eseguire il debug. Quando si crea un nuovo progetto, in Visual Studio viene creata anche una soluzione, una struttura per l'organizzazione dei progetti. Più progetti possono coesistere all'interno di un'unica soluzione ed essere costruiti insieme. Per creare un nodo ZeroTouch, è necessario avviare un nuovo progetto di Visual Studio in cui scrivere una libreria di classi C# e creare un file .dll.

La finestra di un nuovo progetto in Visual Studio

1. Iniziare aprendo Visual Studio e creando un nuovo progetto: File > New > Project.

2. Scegliere il modello di progetto Class Library.

3. Assegnare un nome al progetto (abbiamo denominato il progetto MyCustomNode).

4. Impostare il percorso del file per il progetto. In questo esempio, lo lasceremo nella posizione di default.

5. Selezionare Ok.

In Visual Studio si creerà e si aprirà automaticamente un file C#. Dobbiamo assegnargli un nome appropriato, impostare l'area di lavoro e sostituire il codice di default con questo metodo di moltiplicazione.

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

1. Aprire le finestre Esplora soluzioni e Output da Visualizza.

2. Rinominare il file Class1.cs con SampleFunctions.cs in Esplora soluzioni a destra.

3. Aggiungere il codice riportato sopra per la funzione di moltiplicazione. Descriveremo le specifiche di come Dynamo leggerà le classi C# in un secondo momento.

4. Esplora soluzioni: consente di accedere a tutto ciò che è presente nel progetto.

5. La finestra Output: ci servirà in seguito per vedere se la creazione è andata a buon fine.

Il passaggio successivo consiste nella creazione del progetto, ma prima di procedere con questa operazione dobbiamo verificare alcune impostazioni. Assicurarsi innanzitutto che l'opzione Any CPU o x64 sia selezionata in Platform target e che l'opzione Prefer 32-bit sia deselezionata in Project Properties.

1. Aprire le proprietà del progetto selezionando Progetto > "NomeProgetto" > Properties.

2. Selezionare la pagina Compilazione.

3. Selezionare Any CPU o x64 dal menu a discesa.

4. Assicurarsi che l'opzione Preferisci 32 bit sia deselezionata.

Ora possiamo realizzare il progetto per creare un file .dll. A tale scopo, selezionare Compila soluzione dal menu Compilazione o utilizzare il tasto di scelta rapida CTRL+SHIFT+B.

1. Selezionare Compilazione > Compila soluzione.

2. È possibile determinare se il progetto è stato creato correttamente controllando la finestra Output.

Se il progetto è stato creato correttamente, nella cartella bin del progetto sarà presente un file .dll denominato MyCustomNode. Per questo esempio abbiamo lasciato il percorso del file del progetto di default di Visual Studio: c:\users\username\documents\visual studio 2015\Projects. Diamo un'occhiata alla struttura dei file del progetto.

1. La cartella bin contiene il file .dll creato da Visual Studio.

2. Il file del progetto di Visual Studio.

3. Il file della classe.

4. Poiché la configurazione della nostra soluzione è stata impostata su Debug, il file .dll verrà creato in bin\Debug.

Ora possiamo aprire Dynamo e importare il file .dll. Con la funzione Add-ons, accedere alla posizione bin del progetto e selezionare il file .dll da aprire.

1. Selezionare il pulsante Add-ons per importare un file .dll.

2. Individuare la posizione del progetto. Il nostro progetto si trova nel percorso dei file di default di Visual Studio: C:\Users\username\Documents\Visual Studio 2015\Projects\MyCustomNode.

3. Selezionare il file MyCustomNode.dll da importare.

4. Fare clic su Apri per caricare il file .dll.

Se nella libreria viene creata una categoria denominata MyCustomNode, il file .dll è stato importato correttamente. Tuttavia, Dynamo ha creato due nodi da quello che voleva essere un singolo nodo. Nella sezione successiva spiegheremo perché ciò accade e come Dynamo legge un file .dll.

1. MyCustomNode nella libreria di Dynamo. La categoria Libreria è determinata dal nome .dll.

2. SampleFunctions.MultiplyByTwo nell'area di disegno.

Modalità di lettura di classi e metodi in Dynamo

Quando Dynamo carica un file .dll, espone tutti i metodi statici pubblici come nodi. I costruttori, i metodi e le proprietà verranno convertiti rispettivamente in nodi Create, Action e Query. Nel nostro esempio di moltiplicazione, il metodo MultiplyByTwo() diventa un nodo Action in Dynamo. Ciò è dovuto al fatto che il nome del nodo è stato assegnato in base al metodo e alla classe corrispondenti.

1. L'input viene denominato inputNumber in base al nome del parametro del metodo.

2. Per default, l'output viene denominato double perché è il tipo di dati restituito.

3. Il nodo viene denominato SampleFunctions.MultiplyByTwo, perché si tratta dei nomi della classe e del metodo.

Nell'esempio precedente, è stato creato il nodo Create SampleFunctions aggiuntivo perché non è stato fornito esplicitamente un costruttore e pertanto ne è stato creato uno automaticamente. Per evitare questo problema, è possibile creare un costruttore privato vuoto nella nostra classe 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. Dynamo ha importato il metodo come nodo Create.

Aggiunta di riferimenti ai pacchetti NuGet di Dynamo

Il nodo di moltiplicazione è molto semplice e non sono necessari riferimenti a Dynamo. Se si desidera accedere ad una qualsiasi delle funzionalità di Dynamo per creare, ad esempio, la geometria, sarà necessario fare riferimento ai pacchetti NuGet di Dynamo.

• ZeroTouchLibrary: pacchetto per la creazione di librerie di nodi zero touch per Dynamo che contiene le seguenti librerie: DynamoUnits.dll, ProtoGeometry.dll

• WpfUILibrary: pacchetto per la creazione di librerie di nodi per Dynamo con interfaccia utente personalizzata in WPF che contiene le seguenti librerie: DynamoCoreWpf.dll, CoreNodeModels.dll, CoreNodeModelWpf.dll

• DynamoServices: libreria di DynamoServices per Dynamo

• Core: infrastruttura di unit test e test di sistema per Dynamo che contiene le seguenti librerie: DSIronPython.dll, DynamoApplications.dll, DynamoCore.dll, DynamoInstallDetective.dll, DynamoShapeManager.dll, DynamoUtilities.dll, ProtoCore.dll, VMDataBridge.dll

• Test: infrastruttura di unit test e test di sistema per Dynamo che contiene le seguenti librerie: DynamoCoreTests.dll, SystemTestServices.dll, TestServices.dll

• DynamoCoreNodes: pacchetto per la creazione di nodi di base per Dynamo che contiene le seguenti librerie: Analysis.dll, GeometryColor.dll, DSCoreNodes.dll

Per fare riferimento a questi pacchetti in un progetto di Visual Studio, scaricare il pacchetto da NuGet nei collegamenti precedenti e fare riferimento manualmente ai file .dll oppure utilizzare Gestione pacchetti NuGet in Visual Studio. Per prima cosa possiamo illustrare come installarli con NuGet in Visual Studio.

1. Aprire Gestione pacchetti NuGet selezionando Strumenti > Gestione pacchetti NuGet > Gestione pacchetti NuGet per la soluzione.

Questo è Gestione pacchetti NuGet. Questa finestra mostra i pacchetti installati per il progetto e consente all'utente di cercarne altri. Se viene rilasciata una nuova versione del pacchetto DynamoServices, è possibile aggiornare i pacchetti da questa posizione o ripristinare una versione precedente.

1. Selezionare Sfoglia e cercare DynamoVisualProgramming per visualizzare i pacchetti di Dynamo.

2. I pacchetti di Dynamo. Selezionandone uno, verranno mostrate la versione corrente e la descrizione del loro contenuto.

3. Selezionare la versione del pacchetto desiderata e fare clic su Installa. In questo modo viene installato un pacchetto per il progetto specifico in cui si sta lavorando. Poiché si sta utilizzando la release stabile più recente di Dynamo, versione 1.3, scegliere la versione del pacchetto corrispondente.

Per aggiungere manualmente un pacchetto scaricato dal browser, aprire Gestione riferimenti da Esplora soluzioni e cercare il pacchetto.

1. Fare clic con il pulsante destro del mouse su Riferimenti e selezionare Aggiungi riferimento.

2. Selezionare Sfoglia per accedere alla posizione del pacchetto.

Ora che Visual Studio è configurato correttamente e abbiamo aggiunto un file .dll a Dynamo, abbiamo una solida base per i concetti futuri. Questo è solo l'inizio, quindi è bene continuare a seguirci per ulteriori informazioni su come creare un nodo personalizzato.

Qual è lo scopo di questa guida?

Lo scopo di questa guida è quello di aiutare l'utente a navigare tra le varie possibilità di sviluppo in C# per Dynamo, da come creare nodi zero-touch alla compilazione di estensioni.

La sorgente di Dynamo su GitHub

Quali risorse aggiuntive per gli sviluppatori forniamo?

Dynamo: scaricare le build stabili e giornaliere più recenti di Dynamo.

https://dynamobuilds.com/

Dynamo GitHub: Dynamo è un progetto di sviluppo open source su GitHub.

https://github.com/DynamoDS/Dynamo

Wiki per Dynamo su GitHub: questa è stata la risorsa principale per la documentazione per gli sviluppatori.

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

Standard di denominazione dei nodi: forniscono standard e linee guida per la denominazione di categorie, nodi e porte di input e output in Dynamo.

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

Guida all'API/alla lingua di Dynamo: la documentazione sull'API di Dynamo attualmente copre le funzionalità principali.

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

DynamoBIM La migliore fonte per ulteriori informazioni, contenuto di formazione e forum è il sito Web di DynamoBIM.

https://dynamobim.org

Dizionario di Dynamo: un database consultabile di tutti i nodi di Dynamo.

https://dictionary.dynamobim.com/

Guida al linguaggio DesignScript: una guida in formato PDF per la scrittura di DesignScript.

PDF

In che modo è possibile suggerire modifiche a questa guida?

Questa documentazione è aperta a eventuali suggerimenti. Questi possono essere creati direttamente in GitHub creando richieste di modifica.

Dopo aver capito come si crea un progetto zero-touch, possiamo approfondire le specifiche della creazione di un nodo, illustrando l'esempio ZeroTouchEssentials nella pagina di Dynamo su Github.

Molti dei nodi standard di Dynamo sono essenzialmente nodi zero-touch, come la maggior parte dei nodi Math, Color e DateTime riportati sopra.

Per iniziare, scaricare il progetto ZeroTouchEssentials da qui: https://github.com/DynamoDS/ZeroTouchEssentials.

In Visual Studio, aprire il file della soluzione ZeroTouchEssentials.sln e creare la soluzione.

Il file ZeroTouchEssentials.cs contiene tutti i metodi che importeremo in Dynamo.

Aprire Dynamo e importare ZeroTouchEssentials.dll per ottenere i nodi a cui faremo riferimento negli esempi seguenti.

Gli esempi di codice derivano da e in genere corrispondono a ZeroTouchEssentials.cs. La documentazione XML è stata rimossa per mantenerli concisi e ogni esempio di codice creerà il nodo nell'immagine che si trova sopra.

Valori di input di default

Dynamo supporta la definizione dei valori di default per le porte di input in un nodo. Questi valori di default verranno forniti al nodo se le porte non dispongono di connessioni. I valori di default vengono espressi utilizzando il meccanismo C# di definizione degli argomenti facoltativi nella Guida per programmatori C#. Le impostazioni di default vengono specificate nel seguente modo:

• Impostare i parametri del metodo su un valore di default: 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. Il valore di default verrà mostrato quando si posiziona il cursore sulla porta di input del nodo.

Restituzione di più valori

La restituzione di più valori è un po' più complessa rispetto alla creazione di più input e dovrà essere eseguita utilizzando un dizionario. Le voci del dizionario diventano porte sul lato di output del nodo. Vengono create più porte restituite nel modo seguente:

• Aggiungere using System.Collections.Generic; per utilizzare Dictionary<>.

• Aggiungere using Autodesk.DesignScript.Runtime; per utilizzare l'attributo MultiReturn. Fa riferimento a "DynamoServices.dll" dal pacchetto NuGet di DynamoServices.

• Aggiungere l'attributo [MultiReturn(new[] { "string1", "string2", ... more strings here })] al metodo. Le stringhe fanno riferimento alle chiavi del dizionario e diventeranno i nomi delle porte di output.

• Restituire Dictionary<> dalla funzione con le chiavi che corrispondono ai nomi dei parametri nell'attributo: 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) }
            };
        }
    }
}

Fare riferimento a questo esempio di codice in ZeroTouchEssentials.cs.

Un nodo che restituisce più output.

1. Notare che ora sono presenti due porte di output denominate in base alle stringhe immesse per le chiavi del dizionario.

Documentazione, descrizioni comandi e ricerca

È buona norma aggiungere ai nodi Dynamo una documentazione che descriva la funzione del nodo, gli input, gli output, i tag di ricerca, ecc. Questa operazione viene eseguita tramite i tag della documentazione XML. La documentazione XML viene creata nel modo seguente:

• Qualsiasi testo di commento preceduto da tre barre è considerato documentazione.

  • Ad esempio: /// Documentation text and XML goes here

• Dopo le tre barre, creare tag XML sopra i metodi che Dynamo leggerà durante l'importazione del file .dll.

  • Ad esempio: /// <summary>...</summary>

• Attivare la documentazione XML in Visual Studio scegliendo Progetto > NomeProgetto > Properties > Compilazione e selezionando File di documentazione XML.

1. Visual Studio genererà un file XML nella posizione specificata.

I tipi di tag sono i seguenti:

• /// <summary>...</summary> è la documentazione principale per il nodo e comparirà come descrizione comando sul nodo nella barra laterale di ricerca sinistra.

• /// <param name="inputName">...</param> creerà la documentazione per parametri di input specifici.

• /// <returns>...</returns> creerà la documentazione per un parametro di output.

• /// <returns name = "outputName">...</returns> creerà la documentazione per più parametri di output.

• /// <search>...</search> abbinerà il nodo ai risultati della ricerca in base ad un elenco separato da virgole. Ad esempio, se si crea un nodo che suddivide una maglia, si possono aggiungere tag come "mesh", "subdivision" e "catmull-clark".

Di seguito è riportato un nodo di esempio con descrizioni di input e output, nonché una sintesi che verrà visualizzata nella libreria.

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

Fare riferimento a questo esempio di codice in ZeroTouchEssentials.cs.

Notare che il codice per questo nodo di esempio contiene:

1. Un riepilogo del nodo

2. Una descrizione dell'input

3. Descrizione di un output

Oggetti

Dynamo non dispone di una parola chiave new, pertanto gli oggetti dovranno essere costruiti utilizzando metodi di costruzione statici. Gli oggetti vengono costruiti nel modo seguente:

• Rendere interno il costruttore internal ZeroTouchEssentials(), se non diversamente richiesto.

• Costruire l'oggetto con un metodo statico, ad esempio public static ZeroTouchEssentials ByTwoDoubles(a, b).

Nota Dynamo utilizza il prefisso "By" per indicare che un metodo statico è un costruttore e, sebbene sia facoltativo, l'utilizzo di "By" aiuterà la libreria ad adattarsi meglio allo stile esistente di 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);
        }
    }
}

Fare riferimento a questo esempio di codice in ZeroTouchEssentials.cs.

Dopo l'importazione del file dll ZeroTouchEssentials, nella libreria sarà presente un nodo ZeroTouchEssentials. Questo oggetto può essere creato utilizzando il nodo ByTwoDoubles

Utilizzo dei tipi di geometria di Dynamo

Le librerie di Dynamo possono utilizzare tipi di geometria di Dynamo nativi come input e creare nuova geometria come output. I tipi di geometria vengono creati nel seguente modo:

• Fare riferimento al file ProtoGeometry.dll nel progetto includendo using Autodesk.DesignScript.Geometry; nella parte superiore del file C# e aggiungendo il pacchetto NuGet ZeroTouchLibrary al progetto.

• Importante Per gestire le risorse della geometria non restituite dalle funzioni, vedere la sezione Istruzioni Dispose/using riportata di seguito.

Nota Gli oggetti geometrici di Dynamo vengono utilizzati come qualsiasi altro oggetto trasferito alle funzioni.

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

Fare riferimento a questo esempio di codice in ZeroTouchEssentials.cs.

Un nodo che ottiene la lunghezza di una curva e la raddoppia.

1. Questo nodo accetta un tipo di geometria curve come input.

Istruzioni Dispose/using

Le risorse della geometria che non vengono restituite dalle funzioni dovranno essere gestite manualmente, a meno che non si stia utilizzando Dynamo versione 2.5 o successiva. In Dynamo 2.5 e versioni successive, le risorse della geometria vengono gestite internamente dal sistema, tuttavia, potrebbe essere ancora necessario rimuovere la geometria manualmente se si dispone di un caso di utilizzo complesso o se è necessario ridurre la memoria in un determinato momento. Il motore di Dynamo gestirà eventuali risorse della geometria restituite da funzioni. Le risorse della geometria non restituite possono essere gestite manualmente nei seguenti modi:

• Con un'istruzione using:

  Copy

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

  L'istruzione using è documentata qui.

  Per ulteriori informazioni sulle nuove funzionalità di stabilità introdotte in Dynamo 2.5, vedere Dynamo Geometry Stability Improvements.

• Con le chiamate manuali di 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;

Migrazioni

Quando si pubblica una versione più recente di una libreria, i nomi dei nodi potrebbero cambiare. Le modifiche ai nomi possono essere specificate in un file Migrations in modo che i grafici creati con versioni precedenti di una libreria continuino a funzionare correttamente quando si esegue un aggiornamento. Le migrazioni vengono implementate nel seguente modo:

• Creare un file .xml nella stessa cartella di .dll con il seguente formato: "BaseDLLName".Migrations.xml.

• Nel file .xml, creare un singolo elemento <migrations>...</migrations>.

• All'interno dell'elemento migrations, creare elementi <priorNameHint>...</priorNameHint> per ogni modifica del nome.

• Per ogni modifica del nome, fornire un elemento <oldName>...</oldName> e <newName>...</newName>.

1. Fare clic con il pulsante destro del mouse e selezionare Aggiungi > Nuovo elemento.

2. Scegliere File XML.

3. Per questo progetto, il nome del file Migrations è ZeroTouchEssentials.Migrations.xml.

Questo codice di esempio indica a Dynamo che qualsiasi nodo denominato GetClosestPoint è ora denominato ClosestPointTo.

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

Fare riferimento a questo esempio di codice in ProtoGeometry.Migrations.xml.

Generics

Zero-Touch attualmente non supporta l'uso di generics. Possono essere utilizzati, ma non nel codice che viene importato direttamente dove il tipo non è impostato. I metodi, le proprietà o le classi che sono generici e senza il tipo impostato non possono essere esposti.

Nell'esempio seguente, un nodo zero-touch di tipo T non verrà importato. Se il resto della libreria viene importato in Dynamo, risulteranno mancante delle eccezioni del tipo.

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

L'utilizzo di un tipo generico con il tipo impostato in questo esempio verrà importato in Dynamo.

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

I file di origine di DynamoRevit sono inoltre ospitati sulla pagina di DynamoDS su GitHub per consentire agli sviluppatori di apportare contributi e compilare versioni beta. La compilazione di DynamoRevit dall'origine segue generalmente lo stesso processo di Dynamo, ad eccezione di alcuni dettagli importanti:

• DynamoRevit fa riferimento agli assiemi di Dynamo, quindi questi devono essere creati con i pacchetti NuGet corrispondenti. Ad esempio, DynamoRevit 2.x non verrà caricato in Dynamo 1.3.

• DynamoRevit è specifico delle versioni di Revit, ad esempio: il ramo di DynamoRevit 2018 deve essere eseguita in Revit 2018.

Per questa guida utilizzeremo i seguenti elementi:

• Revit 2023

• La build più recente di DynamoRevit sul ramo Revit2023

• La build più recente di Dynamo

Per garantire una corretta compilazione, verranno clonati e creati entrambi i repository di Dynamo e DynamoRevit da utilizzare in questa simulazione.

Nota La creazione manuale di Dynamo prima di DynamoRevit è necessaria solo se si sta creando Dynamo 1.x e DynamoRevit 1.x. Le versioni più recenti del repository di DynamoRevit si basano su Gestione pacchetti NuGet per le dipendenze di Dynamo necessarie per la creazione. Sebbene una build di DynamoRevit 2.x non richieda il pull manuale di Dynamo, sarà comunque necessario disporre dei file dlls di Core in un altro punto per eseguire effettivamente DynamoRevitaddin, pertanto vale la pena di eseguire il pull e la compilazione di Dynamo comunque. Per ulteriori informazioni, vedere .

Individuazione del repository di DynamoRevit su GitHub

Il codice per il progetto di DynamoRevit si trova in un repository su GitHub separato dal codice sorgente di Dynamo principale. Questo repository contiene i file di origine per i nodi specifici di Revit e il modulo aggiuntivo di Revit che carica Dynamo. Le build di DynamoRevit per versioni diverse di Revit (ad esempio, 2016, 2017 o 2018) sono organizzate come rami nel repository.

L'origine di DynamoRevit è ospitata qui: .

1. Clonare o scaricare il repository.

2. I rami di DynamoRevit fanno riferimento alle versioni di Revit.

Clonazione del repository mediante git

In un processo simile al pull del repository di Dynamo, utilizzeremo il comando clone di git per clonare DynamoRevit e specificare il ramo che corrisponde alla nostra versione di Revit. Per iniziare, apriremo un'interfaccia della riga di comando e imposteremo la directory corrente sul percorso in cui desideriamo clonare i file.

cd C:\Users\username\Documents\GitHub modifica la directory corrente.

Sostituire username con il nome utente.

Ora possiamo clonare il repository in questa directory. Sebbene sia necessario specificare un ramo del repository, possiamo passare a questo ramo dopo la clonazione.

git clone https://github.com/DynamoDS/DynamoRevit.git clona il repository da un URL remoto e, per default, passa al ramo principale.

Una volta terminata la clonazione del repository, cambiare la directory corrente con la cartella del repository e passare al ramo corrispondente alla versione di Revit installata. In questo esempio, utilizziamo Revit RC2.13.1_Revit2023. Tutti i rami remoti possono essere visualizzati nella pagina su GitHub nel menu a discesa Branch.

cd C:\Users\username\Documents\GitHub\DynamoRevit modifica la directory in DynamoRevit. git checkout RC2.13.1_Revit2023 imposta il ramo corrente su RC2.13.1_Revit2023. git branch verifica in quale ramo siamo e mostra gli altri che esistono localmente.

Il ramo con un asterisco è quello attualmente estratto. Il ramo Revit2018 è visibile perché lo abbiamo estratto in precedenza, pertanto esiste localmente.

È importante scegliere il ramo corretto del repository per assicurarsi che, quando il progetto viene compilato in Visual Studio, faccia riferimento agli assiemi nella versione corretta della directory di installazione di Revit, in particolare RevitAPI.dll e RevitAPIUI.dll.

Compilazione del repository utilizzando Visual Studio

1. Fare clic con il pulsante destro del mouse su restorepackages.bat e selezionare Run as administrator.

Se i pacchetti vengono ripristinati correttamente, una cartella packages verrà aggiunta alla cartella src con i pacchetti NuGet della versione beta più recenti.

1. I pacchetti NuGet di Dynamo della versione beta più recenti

Una volta ripristinati i pacchetti, aprire il file della soluzione di Visual Studio DynamoRevit.All.sln in src e creare la soluzione. Inizialmente la build potrebbe avere problemi a trovare AssemblySharedInfo.cs. In questo caso, la riesecuzione della build risolverà il problema.

1. Selezionare Build > Build Solution.

2. Verificare che la build sia stata eseguita correttamente nella finestra Output. Dovrebbe essere visualizzato il messaggio ===== Build: 13 succeeded, 0 failed, 0 up-to-date, 0 skipped =====.

Esecuzione di una build locale di DynamoRevit in Revit

Creare un file Dynamo.addin nella cartella Addins di Revit che si trova in C:\ProgramData\Autodesk\Revit\Addins\2023. Abbiamo già installato una versione di DynamoRevit, quindi modificheremo il file esistente in modo che punti alla nuova build.

• Specificare il percorso del file DynamoRevitDS.dll all'interno di <Assembly>...</Assembly>.

In alternativa, possiamo fare in modo che il modulo aggiuntivo carichi il selettore di versione anziché un assieme specifico.

• Impostare il percorso del file <Assembly>...</Assembly> su DynamoRevitVersionSelector.dll.

• <FullClassName>...</FullClassName> specifica la classe di cui creare un'istanza dall'assieme a cui abbiamo puntato con il percorso dell'elemento assieme indicato sopra. Questa classe sarà il punto di ingresso per il modulo aggiuntivo.

Inoltre, dobbiamo rimuovere la cartella di Dynamo esistente fornita con Revit. A tale scopo, accedere a C:\\Program Files\Autodesk\Revit 2023\AddIns e rimuovere le due cartelle che contengono Dynamo - DynamoForRevit e DynamoPlayerForRevit. È possibile eliminarle o eseguirne il backup in una cartella separata se è necessario recuperare la cartella di Dynamo for Revit originale.

Il secondo passaggio consiste nell'aggiungere un percorso di file per gli assiemi di Dynamo Core al file Dynamo.config nella cartella bin di DynamoRevit. DynamoRevit li carica quando il modulo aggiuntivo viene aperto in Revit. Questo file .config consente di puntare il modulo aggiuntivo DynamoRevit a versioni diverse di Dynamo Core per lo sviluppo e la verifica delle modifiche sia in Dynamo Core che in DynamoRevit.

Il codice dovrebbe avere un aspetto simile al seguente:

• Aggiungere il percorso della directory della cartella bin a <add key/>.

Abbiamo clonato e creato Dynamo subito prima di questa simulazione per garantire che funzioni correttamente con DynamoRevit. Il percorso della directory punta a questa build.

Ora, quando si apre Revit, dovrebbe essere presente un modulo aggiuntivo Dynamo nella scheda Gestisci.

1. Selezionare Manage.

2. Fare clic sull'icona del modulo aggiuntivo Dynamo.

3. Un'istanza di DynamoRevit.

Se viene visualizzata una finestra di dialogo di errore che mostra gli assiemi mancanti, è probabile che si sia verificata una mancata corrispondenza tra le versioni di Dynamo Core create e quelle caricate in fase di esecuzione. Ad esempio, DynamoRevit con i pacchetti beta più recenti 2.0 di Dynamo Core non funzionerà se si tenta di avviarlo utilizzando i file .dll di Dynamo 1.3. Assicurarsi che entrambe i repository siano della stessa versione e che DynamoRevit stia eseguendo il pull di una versione corrispondente delle dipendenze NuGet. Questi sono definiti nel file package.json del repository di DynamoRevit.

Debug di DynamoRevit utilizzando Visual Studio

Nella sezione precedente, Compilazione di Dynamo dall'origine, abbiamo introdotto brevemente il debug in Visual Studio e come associare Visual Studio ad un processo. Utilizzando un'eccezione nel nodo Wall.ByCurveAndHeight come esempio, verrà illustrato come eseguire l'associazione ad un processo, impostare i punti di interruzione, eseguire il codice una riga alla volta e utilizzare lo stack di chiamate per determinare l'origine dell'eccezione. Questi strumenti di debug si applicano in genere ai workflow di sviluppo di file .net e sono utili per l'esplorazione al di fuori di questa guida.

• I punti di interruzione stabiliscono le righe del codice sorgente in cui l'applicazione verrà messa in pausa prima dell'esecuzione. Se un nodo causa l'arresto anomalo di DynamoRevit o restituisce un risultato imprevisto, è possibile aggiungere un punto di interruzione all'origine del nodo per mettere in pausa il processo, eseguire l'istruzione nel codice ed esaminare i valori attivi delle variabili fino a quando non viene individuata la causa del problema.

• L'esecuzione del codice una riga alla volta consente di spostarsi nel codice sorgente riga per riga. È possibile eseguire le funzioni una alla volta, eseguire l'istruzione in una chiamata di funzione o uscire dalla funzione attualmente in esecuzione.

• Lo stack di chiamate mostra la funzione che un processo è attualmente in esecuzione rispetto alle chiamate di funzione precedenti che hanno richiamato questa chiamata di funzione. Per visualizzare questa finestra, in Visual Studio è disponibile la finestra Call Stack. Ad esempio, se si raggiunge un'eccezione al di fuori del codice sorgente, è possibile visualizzare il percorso del codice chiamante nello stack di chiamate.

Il nodo Wall.ByCurveAndHeight genera un'eccezione quando viene fornito il valore PolyCurve come input curve con il messaggio: To BSPlineCurve Not Implemented. Con il debug si può capire perché esattamente il nodo non accetta questo tipo di geometria come input per il parametro curve. In questo esempio, si presuppone che DynamoRevit sia stato creato correttamente e possa essere eseguito come modulo aggiuntivo per Revit.

1. Il nodo Wall.ByCurveAndHeight che genera un'eccezione

Iniziare aprendo il file della soluzione DynamoRevit.All.sln, avviare Revit e avviare il modulo aggiuntivo DynamoRevit. Quindi, associare Visual Studio al processo di Revit con la finestra Attach to Process.

È necessario che Revit e DynamoRevit siano in esecuzione per essere mostrati come processo disponibile

1. Aprire la finestra Attach to Process selezionando Debug > Attach to Process....

2. Impostare Transport su Default.

3. Selezionare Revit.exe.

4. Selezionare Attach.

Con Visual Studio associato a Revit, aprire il codice sorgente Wall.ByCurveAndHeight in Wall.cs. È possibile trovare questa opzione in Solution Explorer in Libraries > RevitNodes > Elements nell'area Public static constructors del file. Impostare un punto di interruzione nel costruttore del tipo di muro in modo, che quando il nodo viene eseguito in Dynamo, il processo si interrompa e si possa eseguire ogni singola riga di codice. In genere, i costruttori di tipo zero-touch di Dynamo iniziano con By<parameters>.

1. Il file di classe con il costruttore per Wall.ByCurveAndHeight

2. Impostare un punto di interruzione facendo clic a sinistra del numero di riga o facendo clic con il pulsante destro del mouse sulla riga di codice e selezionare Breakpoint > Insert Breakpoint.

Con il punto di interruzione impostato, è necessario eseguire il processo attraverso la funzione Wall.ByCurveAndHeight. La funzione può essere eseguita nuovamente in Dynamo riconnettendo un filo ad una delle relative porte, il che forzerà la riesecuzione del nodo. Il punto di interruzione verrà rilevato in Visual Studio.

1. L'icona del punto di interruzione cambia quando viene rilevato

2. La finestra Call Stack che mostra il metodo successivo

Ora eseguire ogni riga del costruttore fino a quando non viene rilevata l'eccezione. Il codice evidenziato in giallo è l'istruzione successiva da eseguire.

1. Gli strumenti di debug per la navigazione nel codice

2. Premere Step Over per eseguire il codice evidenziato, quindi sospendere l'esecuzione dopo la restituzione della funzione.

3. L'istruzione successiva da eseguire è indicata dall'evidenziazione gialla e dalla freccia.

Se si continua a eseguire la funzione, si rileverà l'eccezione visualizzata nella finestra di DynamoRevit. Osservando la finestra Call Stack, si può vedere che l'eccezione è stata originariamente generata da un metodo denominato Autodesk.Revit.CurveAPIUtils.CreateNurbsCurve. Fortunatamente in questo caso l'eccezione è stata risolta e Dynamo non si è arrestato in modo anomalo. Il processo di debug ha fornito il contesto per il problema, portandoci a un altro metodo nel codice sorgente.

1. Quando si rileva l'istruzione che causa l'eccezione in Walls.cs, il processo di debug ci avvicina il più possibile alla causa del problema nel codice utente all'interno di ProtoToRevitCurve.cs.

2. L'istruzione che causa l'eccezione in ProtoToRevitCurve.cs

3. Nella finestra Call Stack, è possibile vedere che l'eccezione proviene da codice non utente.

4. Una finestra a comparsa che fornisce informazioni sull'eccezione

Questo processo può essere applicato a qualsiasi file di origine utilizzato. Se si sta sviluppando una libreria di nodi zero-touch per Dynamo Studio, è possibile aprire l'origine della libreria e associare un processo di Dynamo per eseguire il debug della libreria dei nodi. Anche se tutto funziona perfettamente, il debug è un ottimo modo per esplorare il codice e scoprire come funziona.

Pull dell'ultima build

Questo processo è quasi identico al pull delle modifiche per Dynamo, tranne per il fatto che è necessario verificare di trovarsi nel ramo corretto. Utilizzare il comando git branch nel repository di DynamoRevit per vedere quali rami sono disponibili localmente e quali sono attualmente estratti.

cd C:\Users\username\Documents\GitHub\DynamoRevit imposta la directory corrente sul repository di DynamoRevit. git branch verifica che ci troviamo nel ramo corretto, RC2.13.1_Revit2023. git pull origin RC2.13.1_Revit2023 esegue il pull delle modifiche dal ramo RC2.13.1_Revit2023 di origine remota.

L'origine punta semplicemente all'URL originale clonato.

Si desidera essere consapevoli del ramo in cui ci si trova attualmente e di quello da cui ci sta eseguendo il pull per evitare, ad esempio, di effettuare il pull delle modifiche da RC2.13.1_Revit2023 a Revit2018.

Come indicato in Creazione di Dynamo dall'origine, quando si è pronti per inviare una modifica al repository di DynamoRevit, è possibile creare una richiesta pull seguendo le linee guida del team di Dynamo riportate nella sezione Richieste pull.

Pubblicazione di un pacchetto

I pacchetti rappresentano un modo comodo per memorizzare e condividere i nodi con la comunità di Dynamo. Un pacchetto può contenere tutti gli elementi, dai nodi personalizzati creati nell'area di lavoro di Dynamo ai nodi derivati NodeModel. I pacchetti vengono pubblicati e installati utilizzando Package Manager. Oltre a questa pagina, la include una guida generale sui pacchetti.

Che cos'è Package Manager?

Dynamo Package Manager è un Registro di sistema del software (simile a npm) accessibile da Dynamo o in un browser Web. Package Manager include l'installazione, la pubblicazione, l'aggiornamento e la visualizzazione di pacchetti. Come npm, mantiene diverse versioni dei pacchetti. Inoltre, consente di gestire le dipendenze del progetto.

Nel browser, cercare i pacchetti e visualizzare le statistiche: .

• In Dynamo, Package Manager include i pacchetti di installazione, pubblicazione e aggiornamento.

1. Cercare i pacchetti in linea: Pacchetti > Ricerca pacchetti.

2. Visualizzare/Modificare i pacchetti installati: Pacchetti > Gestisci pacchetti.

3. Pubblicare un nuovo pacchetto: Pacchetti > Pubblica nuovo pacchetto.

Pubblicazione di un pacchetto

I pacchetti vengono pubblicati da Package Manager all'interno di Dynamo. Il processo consigliato consiste nel pubblicare localmente, verificare il pacchetto e quindi pubblicarlo in linea per condividerlo con la comunità. Utilizzando il case study NodeModel, verranno eseguiti i passaggi necessari per pubblicare il nodo RectangularGrid come pacchetto localmente e quindi in linea.

Avviare Dynamo e selezionare Pacchetti > Pubblica nuovo pacchetto... per aprire la finestra Pubblica un pacchetto.

1. Selezionare Aggiungi file per cercare i file da aggiungere al pacchetto.

2. Selezionare i due file .dll dal case study NodeModel.

3. Selezionare Ok.

Con i file aggiunti al contenuto del pacchetto, assegnare al pacchetto un nome, una descrizione e una versione. La pubblicazione di un pacchetto utilizzando Dynamo crea automaticamente un file pkg.json.

Un pacchetto pronto per essere pubblicato.

1. Fornire le informazioni richieste per nome, descrizione e versione.

2. Pubblicare facendo clic su Pubblica localmente e selezionare la cartella del pacchetto di Dynamo: AppData\Roaming\Dynamo\Dynamo Core\1.3\packages per rendere disponibile il nodo in Core. Pubblicare sempre localmente il pacchetto fino a quando non è pronto per la condivisione.

Dopo la pubblicazione di un pacchetto, i nodi saranno disponibili nella libreria di Dynamo nella categoria CustomNodeModel.

1. Il pacchetto appena creato nella libreria di Dynamo

Quando il pacchetto è pronto per la pubblicazione in linea, aprire Package Manager e scegliere Pubblica, quindi Pubblica in linea.

1. Per vedere come Dynamo ha formattato il pacchetto, fare clic sui tre punti verticali a destra di CustomNodeModel e scegliere Mostra directory principale.

2. Selezionare Pubblica, quindi Pubblica in linea nella finestra Pubblica un pacchetto di Dynamo.

3. Per eliminare un pacchetto, selezionare Elimina.

Come aggiornare un pacchetto

L'aggiornamento di un pacchetto è un processo simile alla pubblicazione. Aprire Package Manager, selezionare Pubblica versione... nel pacchetto che deve essere aggiornato e immettere una versione successiva.

1. Selezionare Pubblica versione... per aggiornare un pacchetto esistente con nuovi file nella directory principale, quindi scegliere se deve essere pubblicato localmente o in linea.

Client Web di Package Manager

Il client Web di Package Manager viene utilizzato esclusivamente per la ricerca e la visualizzazione dei dati relativi ai pacchetti, come ad esempio le versioni e le statistiche di download.

I nodi basati su NodeModel offrono una flessibilità e una potenza notevolmente superiori rispetto ai nodi zero-touch. In questo esempio, si porta il nodo griglia zero-touch al livello successivo aggiungendo un dispositivo di scorrimento integrato che imposta dimensioni casuali del rettangolo.

Il dispositivo di scorrimento consente di mettere in scala le celle rispetto alle relative dimensioni, in modo che l'utente non debba fornire un dispositivo di scorrimento con l'intervallo corretto.

Modello Model-View-Viewmodel

Ad un livello generale sono disponibili due parti per stabilire una relazione modello-vista in Dynamo:

• Una classe NodeModel per stabilire la logica di base del nodo (il "modello")

• Una classe INodeViewCustomization per personalizzare la modalità di visualizzazione di NodeModel (la "vista").

Gli oggetti NodeModel dispongono già di una relazione vista-modello associata (NodeViewModel), pertanto possiamo concentrarci solo sul modello e sulla vista per l'interfaccia utente personalizzata.

Come implementare NodeModel

I nodi NodeModel presentano diverse differenze significative rispetto ai nodi zero-touch, che verranno illustrate in questo esempio. Prima di passare alla personalizzazione dell'interfaccia utente, iniziamo costruendo la logica NodeModel.

1. Creare la struttura di progetto:

Un nodo NodeModel può chiamare solo funzioni, pertanto è necessario separare NodeModel e le funzioni in librerie diverse. Il modo standard per eseguire questa operazione per i pacchetti di Dynamo consiste nella creazione di progetti separati per ciascuno di essi. Iniziare creando una nuova soluzione per includere i progetti.

1. Selezionare File > New > Project.

2. Selezionare Other Project Types per visualizzare l'opzione Solution.

3. Selezionare Blank Solution.

4. Assegnare un nome alla soluzione CustomNodeModel.

5. Selezionare Ok.

Creare due progetti di libreria di classi C# nella soluzione: uno per le funzioni e uno per implementare l'interfaccia NodeModel.

1. Fare clic con il pulsante destro del mouse sulla soluzione e selezionare Add > New Project.

2. Scegliere Class Library.

3. Assegnare il nome CustomNodeModel.

4. Fare clic su Ok.

5. Ripetere la procedura per aggiungere un altro progetto denominato CustomNodeModelFunctions.

Successivamente, è necessario rinominare le librerie di classi create automaticamente e aggiungerne una al progetto CustomNodeModel. La classe GridNodeModel implementa la classe astratta NodeModel, la classe GridNodeView viene utilizzata per personalizzare la vista e GridFunction contiene eventuali funzioni che è necessario chiamare.

1. Aggiungere un'altra classe facendo clic con il pulsante destro del mouse sul progetto CustomNodeModel, selezionando Add > New Item... e scegliendo Class.

2. Nel progetto CustomNodeModel, sono necessarie le classi GridNodeModel.cs e GridNodeView.cs.

3. Nel progetto CustomNodeModelFunction, è necessaria una classe GridFunctions.cs.

Prima di aggiungere qualsiasi codice alle classi, aggiungere i pacchetti necessari per questo progetto. CustomNodeModel richiede ZeroTouchLibrary e WpfUILibrary e CustomNodeModelFunction richiede solo ZeroTouchLibrary. Si utilizzerà WpfUILibrary nella personalizzazione dell'interfaccia utente che verrà eseguita in seguito e si userà ZeroTouchLibrary per la creazione della geometria. I pacchetti possono essere aggiunti singolarmente per i progetti. Poiché questi pacchetti presentano dipendenze, Core e DynamoServices verranno installati automaticamente.

1. Fare clic con il pulsante destro del mouse su un progetto e selezionare Manage NuGet Packages.

2. Installare solo i pacchetti necessari per il progetto.

Visual Studio copierà i pacchetti NuGet a cui si fa riferimento nella directory della build. Questa opzione può essere impostata su False, in modo da non includere eventuali file non necessari nel pacchetto.

1. Seleziona i pacchetti NuGet di Dynamo.

2. Impostare Copy Local su False.

2. Ereditare la classe NodeModel

Come accennato in precedenza, l'aspetto principale che rende un nodo NodeModel diverso da un nodo zero-touch è la sua implementazione della classe NodeModel. Un nodo NodeModel richiede diverse funzioni di questa classe ed è possibile ottenerle aggiungendo :NodeModel dopo il nome della classe.

Copiare il seguente codice in GridNodeModel.cs.

È differente dai nodi zero-touch. Cerchiamo di capire cosa fa ogni parte.

• Specificare gli attributi del nodo, ad esempio NodeName, NodeCategory, InPortNames/OutPortNames, InPortTypes/OutPortTypes, InPortDescriptions/OutPortDescriptions.

• public class GridNodeModel : NodeModel è una classe che eredita la classe NodeModel da Dynamo.Graph.Nodes.

• public GridNodeModel() { RegisterAllPorts(); } è un costruttore che registra gli input e gli output del nodo.

• BuildOutputAst() restituisce un AST (albero della sintassi astratta), la struttura necessaria per la restituzione dei dati da un nodo NodeModel.

• AstFactory.BuildFunctionCall() chiama la funzione RectangularGrid da GridFunctions.cs.

• new Func<int, int, double, List<Rectangle>>(GridFunction.RectangularGrid) specifica la funzione e i relativi parametri.

• new List<AssociativeNode> { inputAstNodes[0], inputAstNodes[1], sliderValue }); mappa gli input del nodo ai parametri di funzione.

• AstFactory.BuildNullNode() crea un nodo nullo se le porte di input non sono connesse. Ciò consente di evitare la visualizzazione di un avviso sul nodo.

• RaisePropertyChanged("SliderValue") avvisa l'interfaccia utente quando il valore del dispositivo di scorrimento cambia.

• var sliderValue = AstFactory.BuildDoubleNode(SliderValue) crea un nodo nell'albero AST che rappresenta il valore del dispositivo di scorrimento.

• Modificare un input nella variabile sliderValue nella variabile functionCall new List<AssociativeNode> { inputAstNodes[0], sliderValue });.

3. Chiamare una funzione

Il progetto CustomNodeModelFunction verrà integrato in un assieme separato da CustomNodeModel in modo che possa essere chiamato.

Copiare il seguente codice in GridFunction.cs.

Questa classe di funzioni è molto simile al case study del nodo griglia zero-touch con una differenza:

• [IsVisibleInDynamoLibrary(false)] impedisce a Dynamo di "vedere" il seguente metodo e la seguente classe, poiché la funzione è già stata chiamata da CustomNodeModel.

Così come sono stati aggiunti i riferimenti per i pacchetti NuGet, CustomNodeModel dovrà fare riferimento a CustomNodeModelFunction per chiamare la funzione.

L'istruzione using per CustomNodeModel sarà inattiva fino a quando non si fa riferimento alla funzione.

1. Fare clic con il pulsante destro del mouse su CustomNodeModel e selezionare Add > Reference.

2. Scegliere Projects > Solution.

3. Selezionare CustomNodeModelFunction.

4. Fare clic su Ok.

4. Personalizzare la vista

Per creare un dispositivo di scorrimento, è necessario personalizzare l'interfaccia utente implementando l'interfaccia INodeViewCustomization.

Copiare il seguente codice in GridNodeView.cs.

• public class CustomNodeModelView : INodeViewCustomization<GridNodeModel> definisce le funzioni necessarie per personalizzare l'interfaccia utente.

Dopo aver impostato la struttura del progetto, utilizzare l'ambiente di progettazione di Visual Studio per creare un controllo utente e definirne i parametri in un file .xaml. Dalla casella degli strumenti, aggiungere un dispositivo di scorrimento a <Grid>...</Grid>.

1. Fare clic con il pulsante destro del mouse su CustomNodeModel e selezionare Add > New Item.

2. Selezionare WPF.

3. Assegnare un nome al controllo utente Slider.

4. Fare clic su Add.

Copiare il seguente codice in Slider.xaml.

• I parametri del controllo del dispositivo di scorrimento sono definiti nel file .xaml. Gli attributi Minimum e Maximum definiscono l'intervallo numerico di questo dispositivo di scorrimento.

• All'interno di <Grid>...</Grid> è possibile posizionare diversi controlli utente dalla casella degli strumenti di Visual Studio.

Quando è stato creato il file Slider.xaml, Visual Studio ha creato automaticamente un file C# denominato Slider.xaml.cs che inizializza il dispositivo di scorrimento. Modificare lo spazio dei nomi in questo file.

• Lo spazio dei nomi deve essere CustomNodeModel.CustomNodeModel.

GridNodeModel.cs definisce la logica di calcolo del dispositivo di scorrimento.

5. Configurazione come pacchetto

Prima di creare il progetto, il passaggio finale consiste nell'aggiungere un file pkg.json in modo che Dynamo possa leggere il pacchetto.

1. Fare clic con il pulsante destro del mouse su CustomNodeModel e selezionare Add > New Item.

2. Selezionare Web.

3. Selezionare JSON File.

4. Assegnare un nome al file pkg.json.

5. Fare clic su Add.

• Copiare il seguente codice in pkg.json.

• "name": determina il nome del pacchetto e il relativo gruppo nella libreria di Dynamo.

• "keywords": fornisce i termini di ricerca per la ricerca nella libreria di Dynamo.

• "node_libraries": [] indica le librerie associate al pacchetto.

  L'ultimo passaggio consiste nel creare la soluzione e pubblicarla come pacchetto di Dynamo. Per informazioni su come creare un pacchetto locale prima di pubblicarlo in linea e su come creare un pacchetto direttamente da Visual Studio, vedere il capitolo sull'installazione client dei pacchetti.

Introduzione:

Questa sezione contiene informazioni sui problemi che potrebbero verificarsi durante la migrazione di grafici, pacchetti e librerie a Dynamo 3.x.

Dynamo 3.0 è una release principale e alcune API sono state modificate o rimosse. La modifica più importante che probabilmente interesserà gli sviluppatori e gli utenti di Dynamo 3.x è il passaggio a .NET 8.

Dotnet/.NET è il runtime che attiva il linguaggio C# in cui viene scritto Dynamo. Abbiamo aggiornato l'ambiente passando ad una versione moderna di questo runtime insieme al resto dell'ecosistema Autodesk.

Per saperne di più, consultare il .

Compatibilità dei pacchetti

Utilizzo dei pacchetti di Dynamo 2.x in Dynamo 3.x

Poiché Dynamo 3.x viene ora eseguito nel runtime di .NET8, non è garantito che i pacchetti creati per Dynamo 2.x (utilizzando .NET 4.8) funzionino in Dynamo 3.x. Quando si tenta di scaricare un pacchetto in Dynamo 3.x pubblicato da una versione di Dynamo precedente alla 3.0, viene visualizzato un avviso che indica che il pacchetto proviene da una versione meno recente di Dynamo.

Ciò non significa che il pacchetto non funzionerà. È semplicemente un avviso che segnala problemi di compatibilità. In generale, è consigliabile verificare se è stata creata una versione più recente specificamente per Dynamo 3.x.

È inoltre possibile che questo tipo di avviso venga visualizzato nei file di registro di Dynamo al caricamento del pacchetto. Se tutto funziona correttamente, è possibile ignorarlo.

Utilizzo dei pacchetti di Dynamo 3.x in Dynamo 2.x

È molto improbabile che un pacchetto creato per Dynamo 3.x (utilizzando .NET 8) funzioni su Dynamo 2.x. Viene inoltre visualizzato un avviso quando si scaricano i pacchetti creati per le versioni più recenti di Dynamo mentre si utilizza una versione precedente.

Le estensioni sono un potente strumento di sviluppo nell'ecosistema di Dynamo. Consentono agli sviluppatori di gestire funzionalità personalizzate basate sulle interazioni e sula logica di Dynamo. Le estensioni possono essere suddivise in due categorie principali, ovvero estensioni ed estensioni delle viste. Come implica la denominazione, la framework dell'estensione della vista consente di estendere l'interfaccia utente di Dynamo registrando voci di menu personalizzate. Le estensioni standard funzionano in modo molto simile, meno l'interfaccia utente. Ad esempio, è possibile creare un'estensione che registra informazioni specifiche nella console di Dynamo. Questo scenario non richiede alcuna interfaccia utente personalizzata e pertanto potrebbe essere eseguito anche utilizzando un'estensione.

Case study dell'estensione

Seguendo l'esempio SampleViewExtension dal repository DynamoSamples su GitHub, illustreremo la procedura necessaria per creare una finestra non modale semplice che visualizzi i nodi attivi nel grafico in tempo reale. Per un'estensione della vista è necessario creare un'interfaccia utente per la finestra e associare i valori ad un modello di vista.

1. La finestra dell'estensione della vista è stata sviluppata seguendo l'esempio SampleViewExtension nel repository su GitHub.

Anche se costruiremo l'esempio da zero, è possibile anche scaricare e creare il repository DynamoSamples come riferimento.

Questa simulazione farà riferimento in modo specifico al progetto denominato SampleViewExtension disponibile in DynamoSamples/src/.

Come implementare un'estensione della vista

Un'estensione della vista è costituita da tre parti essenziali:

• Un assieme contenente una classe che implementa IViewExtension e una classe che crea un modello di vista

• Un file .xml che indica a Dynamo dove deve cercare questo assieme in fase di esecuzione e il tipo di estensione

• Un file .xaml che associa i dati alla visualizzazione grafica e determina l'aspetto della finestra

1. Creazione della struttura del progetto

Iniziare creando un nuovo progetto Class Library denominato SampleViewExtension.

1. Creare un nuovo progetto selezionando File > New > Project.

2. Selezionare Class Library.

3. Assegnare al progetto il nome SampleViewExtension.

4. Selezionare Ok.

In questo progetto, avremo bisogno di due classi. Una classe implementerà IViewExtension e un'altra che implementerà NotificationObject. IViewExtension conterrà tutte le informazioni su come l'estensione verrà distribuita, caricata, utilizzata come riferimento ed eliminata. NotificationObject fornirà notifiche per le modifiche in Dynamo e IDisposable. Quando si verifica una modifica, il conteggio verrà aggiornato di conseguenza.

1. Un file di classe denominato SampleViewExtension.cs che implementerà IViewExtension

2. Un file di classe denominato SampleWindowViewMode.cs che implementerà NotificationObject

Per utilizzare IViewExtension, è necessario il pacchetto NuGet WpfUILibrary. L'installazione di questo pacchetto comporta l'installazione automatica dei pacchetti Core, Services e ZeroTouchLibrary.

1. Selezionare WpfUILibrary.

2. Selezionare Install per installare tutti i pacchetti dipendenti.

2. Implementazione della classe IViewExtension

Dalla classe IViewExtension determineremo cosa succede quando Dynamo viene avviato, quando l'estensione viene caricata e quando Dynamo viene chiuso. Nel file della classe SampleViewExtension.cs, aggiungere il seguente codice:

La classe SampleViewExtension crea una voce di menu selezionabile per aprire la finestra e collegarla al modello di vista e alla finestra.

• La classe public class SampleViewExtension : IViewExtension SampleViewExtension ereditata dall'interfaccia IViewExtension fornisce tutto ciò che è necessario per creare la voce di menu.

• sampleMenuItem = new MenuItem { Header = "Show View Extension Sample Window" }; crea un elemento MenuItem e lo aggiunge al menu View.

1. La voce di menu

• sampleMenuItem.Click += (sender, args) attiva un evento che aprirà una nuova finestra quando si fa clic sulla voce di menu.

• MainGrid = { DataContext = viewModel } imposta il contesto dei dati per la griglia principale nella finestra, facendo riferimento a Main Grid nel file .xaml che creeremo.

• Owner = p.DynamoWindow imposta il proprietario della finestra a comparsa su Dynamo. Ciò significa che la nuova finestra dipende da Dynamo, pertanto azioni quali la riduzione a icona, l'ingrandimento e il ripristino di Dynamo faranno sì che la nuova finestra segua lo stesso funzionamento.

• window.Show(); visualizza la finestra in cui sono state impostate proprietà aggiuntive.

3. Implementazione del modello di vista

Ora che sono stati definiti alcuni parametri di base della finestra, verrà aggiunta la logica per rispondere a vari eventi correlati a Dynamo e verrà richiesto all'interfaccia utente di eseguire l'aggiornamento in base a tali eventi. Copiare il seguente codice nel file della classe SampleWindowViewModel.cs:

Questa implementazione della classe del modello di vista è in ascolto di CurrentWorkspaceModel e attiva un evento quando un nodo viene aggiunto o rimosso dall'area di lavoro. Ciò genera una modifica della proprietà che notifica all'interfaccia utente o agli elementi associati che i dati sono stati modificati e devono essere aggiornati. Viene chiamato il getter ActiveNodeTypes che chiama internamente una funzione helper aggiuntiva getNodeTypes(). Questa funzione esegue l'iterazione di tutti i nodi attivi nell'area di disegno, compila una stringa contenente i nomi di tali nodi e restituisce questa stringa al nostro binding nel file .xaml da visualizzare nella finestra a comparsa.

Con la logica di base dell'estensione definita, ora specificheremo i dettagli dell'aspetto della finestra con un file .xaml. Tutto ciò che server è una semplice finestra che visualizzi la stringa tramite l'associazione della proprietà ActiveNodeTypes in TextBlock Text.

1. Fare clic con il pulsante destro del mouse sul progetto e selezionare Add > New Item....

2. Selezionare il modello di controllo utente che verrà modificato per creare una finestra.

3. Assegnare un nome al nuovo file SampleWindow.xaml.

4. Selezionare Add.

Nel codice della finestra .xaml, dovremo associare SelectedNodesText ad un blocco di testo. Aggiungere il seguente codice a SampleWindow.xaml:

• Text="{Binding ActiveNodeTypes}" associa il valore della proprietà ActiveNodeTypes in SampleWindowViewModel.cs al valore TextBlock Text nella finestra.

Ora inizializzeremo la finestra di esempio nel file di backing .xaml C# SampleWindow.xaml.cs. Aggiungere il seguente codice a SampleWindow.xaml:

L'estensione della vista è ora pronta per essere creata e aggiunta a Dynamo. Dynamo richiede un file xml per registrare il nostro output .dll come estensione.

1. Fare clic con il pulsante destro del mouse sul progetto e selezionare Add > New Item....

2. Selezionare il file XML.

3. Assegnare un nome al file SampleViewExtension_ViewExtensionDefinition.xml.

4. Selezionare Add.

• Il nome del file segue lo standard di Dynamo per fare riferimento ad un assieme di estensione, come indicato di seguito: "extensionName"_ViewExtensionDefinition.xml

Nel file xml, aggiungere il seguente codice per indicare a Dynamo dove cercare l'assieme di estensione:

• In questo esempio, è stato creato l'assieme nella cartella di progetti di default di Visual Studio. Sostituire la destinazione <AssemblyPath>...</AssemblyPath> con la posizione dell'assieme.

L'ultimo passaggio consiste nel copiare il file SampleViewExtension_ViewExtensionDefinition.xml nella cartella viewExtensions di Dynamo, che si trova nella directory di installazione di Dynamo Core C:\Program Files\Dynamo\Dynamo Core\1.3\viewExtensions. È importante notare che sono presenti cartelle separate per extensions e viewExtensions. Il posizionamento del file xml nella cartella errata potrebbe causare errori di caricamento in fase di esecuzione.

1. Il file .xml copiato nella cartella viewExtensions di Dynamo

Questa è un'introduzione di base alle estensioni delle viste. Per un case study più sofisticato, vedere il pacchetto DynaShape, un progetto open source su GitHub. Il pacchetto utilizza un'estensione della vista che consente la modifica in tempo reale nella vista modello di Dynamo.

Se si stanno sviluppando assiemi da pubblicare come pacchetto per Dynamo, il progetto può essere configurato per raggruppare tutti i componenti di progetto necessari e inserirli in una struttura di directory compatibile con il pacchetto. Ciò consentirà di testare rapidamente il progetto come pacchetto e di simulare l'esperienza dell'utente.

Come creare direttamente un pacchetto nella cartella corrispondente

In Visual Studio sono disponibili due metodi per la creazione di un pacchetto:

• Aggiungere eventi post-compilazione tramite la finestra di dialogo Project Settings che utilizzano script xcopy o Python per copiare i file necessari

• Utilizzare la destinazione della build "AfterBuild" nel file .csproj per creare le operazioni di copia di file e directory.

"AfterBuild" è il metodo preferito per questi tipi di operazioni (e quello descritto in questo manuale), poiché non si basa sulla copia di file che potrebbe non essere disponibile nel computer di compilazione.

Copia di file di pacchetto con il metodo AfterBuild

Impostare la struttura delle directory nel repository in modo che i file di origine siano separati dai file di pacchetto. Utilizzando il case study CustomNodeModel, posizionare il progetto di Visual Studio e tutti i file associati in una nuova cartella src. Verranno memorizzati tutti i pacchetti generati dal progetto in questa cartella. La struttura delle cartelle dovrebbe ora essere simile alla seguente:

1. Spostare i file di progetto nella nuova cartella src

Sarà necessario verificare che la destinazione sia stata aggiunta al file CustomNodeModel.csproj (non ad un altro file di progetto) e che per il progetto non siano state definite impostazioni post-compilazione esistenti.

1. Posizionare la destinazione AfterBuild prima del tag </Project> finale.

Nella sezione <ItemGroup>, vengono definite diverse variabili per rappresentare tipi di file specifici. Ad esempio, la variabile Dll rappresenta tutti i file nella directory di output con estensione .dll.

L'operazione Copy consiste nel copiare tutti i file .dll in una directory, in particolare nella cartella del pacchetto in cui si sta eseguendo la compilazione.

I pacchetti di Dynamo in genere dispongono di una cartella dyf e extra per i nodi personalizzati di Dynamo e altri componenti di progetto, ad esempio le immagini. Per creare queste cartelle, è necessario utilizzare un'attività MakeDir. Questa operazione creerà una cartella se non esiste. È possibile aggiungere i file manualmente a questa cartella.

Se si crea il progetto, la cartella di progetto dovrebbe ora avere una cartella packages accanto alla cartella src creata in precedenza. All'interno della directory packages è presente una cartella contenente tutti gli elementi necessari per il pacchetto. È inoltre necessario copiare il file pkg.json nella cartella del pacchetto in modo che Dynamo sappia di caricare il pacchetto.

1. La nuova cartella del pacchetto creata dalla destinazione AfterBuild

2. La cartella src esistente con il progetto

3. Le cartelle dyf e extra create dalla destinazione AfterBuild

4. Copiare manualmente il file pkg.json.

Ora è possibile pubblicare il pacchetto utilizzando il gestore di pacchetti di Dynamo o copiarlo direttamente nella directory del pacchetto di Dynamo: <user>\AppData\Roaming\Dynamo\1.3\packages.

Dynamo dipende dalla creatività e dall'impegno della sua comunità e il team di Dynamo incoraggia i collaboratori ad esplorare le possibilità, a testare le idee e a coinvolgere la comunità per ottenere un feedback. Sebbene l'innovazione sia fortemente incoraggiata, le modifiche verranno unite solo se rendono Dynamo più facile da utilizzare e soddisfano le linee guida definite in questo documento. Le modifiche con vantaggi definiti in modo restrittivo non verranno unite.

Richieste pull previste

Il team di Dynamo prevede che le richieste pull seguano alcune linee guida:

• Rispettare gli e gli .

• Includere unit test durante l'aggiunta di nuove funzionalità.

• Quando si corregge un bug, aggiungere uno unit test che evidenzi come il funzionamento corrente sia compromesso.

• Mantenere la discussione concentrata su un solo problema. Creare un nuovo caso se si presenta un argomento nuovo o correlato.

E alcune linee guida su cosa non fare:

• Sorprenderci con grandi richieste pull. Invece, segnalare un problema e avviate una discussione in modo da concordare una direzione prima di investire una grande quantità di tempo.

• Eseguire il commit del codice che non si è scritto. Se si trova del codice che si ritiene appropriato aggiungere a Dynamo, segnalare un problema e avviare una discussione prima di procedere.

• Inviare richieste pull che modifichino le intestazioni o i file correlati alle licenze. Se si ritiene che ci sia un problema con tali richieste, segnalarlo e saremo lieti di discuterne.

• Aggiungere elementi all'API senza prima segnalare un problema e discuterne con noi.

Compilazione del modello di richiesta pull

Quando si invia una richiesta pull, utilizzare il . Prima di inviare la richiesta pull, assicurarsi che lo scopo sia chiaramente descritto e che tutte le dichiarazioni possano essere ritenute veritiere:

• Il codebase è in uno stato migliore dopo questa richiesta pull.

• È documentato in base agli .

• Il livello di test che questa richiesta pull include è appropriato.

• Le stringhe destinate all'utente, se presenti, vengono estratte nei file *.resx.

• Tutti test vengono superati utilizzando l'integrazione continua self-service.

• Istantanea delle modifiche apportate all'interfaccia utente, se presenti.

• Le modifiche all'API seguono il e sono registrate nel documento .

Il team di Dynamo assegnerà alla richiesta pull un revisore appropriato.

Processo di revisione delle richieste pull

Dopo aver inviato una richiesta pull, potrebbe essere necessario rimanere coinvolti nel processo di revisione. Si tenga conto dei seguenti criteri di revisione:

• Il team di Dynamo si riunisce una volta al mese per esaminare le richieste pull dalla meno recente a quella più recente.

• Se una richiesta pull rivista richiede modifiche da parte del proprietario, quest'ultimo ha 30 giorni per rispondere. Se la richiesta pull non ha rilevato alcuna attività entro la sessione successiva, verrà chiusa dal team o, a seconda della sua utilità, sarà gestita da un membro del team.

• Le richieste pull devono utilizzare il modello di default di Dynamo

• Le richieste pull che non dispongono dei modelli di Dynamo compilati completamente con tutte le dichiarazioni soddisfatte non verranno esaminate.

Selezione dei commit di DynamoRevit

Poiché sul mercato sono disponibili più versioni di Revit, potrebbe essere necessario selezionare le modifiche in specifici rami della release di DynamoRevit, in modo che versioni diverse di Revit possano usufruire delle nuove funzionalità. Durante il processo di revisione, i collaboratori saranno responsabili della selezione dei loro commit rivisti agli altri rami di DynamoRevit specificati dal team di Dynamo.

Estensioni come pacchetti

Panoramica

È possibile eseguire l'installazione client delle estensioni di Dynamo nel gestore di pacchetti come le normali librerie di nodi di Dynamo. Quando un pacchetto installato contiene un'estensione della vista, l'estensione viene caricata in fase di esecuzione al caricamento di Dynamo. È possibile controllare la console di Dynamo per verificare che l'estensione sia stata caricata correttamente.

Struttura di un pacchetto

La struttura di un pacchetto di estensione è la stessa di un normale pacchetto contenente...

Si supponga di aver già creato l'estensione; si avrà (almeno) un assieme .NET e un file manifesto. L'assieme deve contenere una classe che implementa IViewExtension o IExtension. Il file .XML manifesto indica a Dynamo la classe di cui creare un'istanza per avviare l'estensione. Affinché il gestore di pacchetti possa individuare correttamente l'estensione, il file manifesto deve corrispondere in modo preciso alla posizione e alla denominazione dell'assieme.

Posizionare eventuali file di assiemi nella cartella bin e il file manifesto nella cartella extra. In questa cartella è possibile inserire anche eventuali risorse aggiuntive.

Esempio di file .XML manifesto:

Caricamento

Una volta creata una cartella contenente le sottodirectory descritte in precedenza, è possibile eseguire il push (caricamento) nel gestore di pacchetti. Una cosa di cui tenere conto è che attualmente non è possibile pubblicare pacchetti da Dynamo Sandbox. Ciò significa che è necessario utilizzare DynamoRevit. Una volta all'interno di DynamoRevit, accedere a Pacchetti => Pubblica nuovo pacchetto. In questo modo, l'utente dovrà accedere all'Autodesk Account a cui desidera associare il pacchetto.

A questo punto dovrebbe comparire la normale finestra di pubblicazione del pacchetto, dove verranno compilati tutti i campi obbligatori relativi al pacchetto/all'estensione. Esiste un passaggio aggiuntivo molto importante che richiede di assicurarsi che nessuno dei file di assiemi sia contrassegnato come libreria di nodi. A tale scopo, fare clic con il pulsante destro del mouse sui file importati (la cartella del pacchetto creata in precedenza). Verrà visualizzato un menu contestuale che consente di selezionare (o deselezionare) questa opzione. Tutti gli assiemi dell'estensione dovrebbero essere deselezionati.

Prima di pubblicare in linea, si dovrebbe sempre pubblicare localmente per assicurarsi che tutto funzioni come previsto. Una volta verificato questo aspetto, si è pronti per l'attivazione selezionando Pubblica in linea.

Pull

Per verificare che il pacchetto sia stato caricato con successo, si dovrebbe essere in grado di cercarlo in base alla denominazione e alle parole chiave specificate nel passaggio di pubblicazione. Infine, è importante notare che le stesse estensioni richiederanno un riavvio di Dynamo prima di funzionare. In genere, queste estensioni richiedono parametri specificati all'avvio di Dynamo.

Se si cercano esempi su come sviluppare Dynamo, consultare le seguenti risorse:

Esempi di repository

Di seguito sono riportati alcuni esempi di modelli di Visual Studio che è possibile utilizzare per avviare un progetto personalizzato:

• : modello per i nodi zero-touch di base.

  • Restituire più output:

  • Utilizzare un oggetto geometria nativo da Dynamo:

  • Proprietà di esempio (nodo Query):

• : modelli per i nodi NodeModel di base e la personalizzazione della vista.

  • Modello NodeModel di base:

    • Definire gli attributi del nodo (nomi di input/output, descrizioni, tipi):

    • Restituire un nodo null se non sono presenti input:

    • Creare una chiamata di funzione:

  • Modello di personalizzazione della vista NodeModel di base: , , ,

    • Avvisare l'interfaccia utente che un elemento deve essere aggiornato:

    • Personalizzare NodeModel:

    • Definire gli attributi del dispositivo di scorrimento:

    • Determinare la logica di interazione per il dispositivo di scorrimento:

• : modelli per nodi zero-touch, interfaccia utente personalizzata, test ed estensioni delle viste.

  • • Creare un nodo dell'interfaccia utente personalizzato di base:

    • Creare un menu a discesa:

  • • Test di sistema:

    • Test ZeroTouch:

  • :

    • Esempio di nodi ZeroTouch, incluso uno che implementa IGraphicItem per influenzare il rendering della geometria:

    • Esempio di nodi ZeroTouch per colorare la geometria utilizzando IRenderPackage:

  • : un'implementazione IViewExtension che mostra una finestra non modale quando si fa clic sul relativo MenuItem.

• : modelli per lo sviluppo di pacchetti di Dynamo avanzati utilizzando NodeModel.

  • Esempi di Essentials:

  • Esempi di geometria:

  • Esempi di interfaccia utente:

Case study

Gli sviluppatori di terze parti hanno apportato contributi significativi ed entusiasmanti alla piattaforma, molti dei quali sono anche open source. I seguenti progetti sono esempi eccezionali di ciò che si può fare con Dynamo.

Ladybug è una libreria Python che consente di caricare, analizzare e modificare i file EPW (EneregyPlus Weather).

Honeybee è una libreria Python che consente di creare, eseguire e visualizzare i risultati della luce diurna (RADIANCE) e dell'analisi energetica (EnergyPlus/OpenStudio).

Bumblebee è un plug-in per l'interoperabilità di Excel e Dynamo (GPL).

Clockwork è una raccolta di nodi personalizzati per le attività correlate a Revit, nonché altri scopi quali la gestione degli elenchi, le operazioni matematiche, le operazioni di tipo stringa, le operazioni geometriche (principalmente caselle di delimitazione, mesh, piani, punti, superfici, UV e vettori) e la suddivisione in pannelli.

Introduzione:

Dynamo 2.0 è una release principale e alcune API sono state modificate o rimosse. Una delle modifiche più importanti che influiranno sugli autori di nodi e pacchetti è il passaggio al formato di file JSON.

In generale, gli autori dei nodi zero-touch dovranno fare poco o nulla per far funzionare i loro pacchetti nella versione 2.0.

I nodi dell'interfaccia utente e i nodi che derivano direttamente da NodeModel richiederanno più lavoro per l'esecuzione nella versione 2.x.

Anche gli autori di estensioni potrebbero dover apportare alcune modifiche, a seconda della quantità di API di Dynamo Core che utilizzano nelle loro estensioni.

Regole generali di creazione di pacchetti:

• Non aggregare i file .dll di Dynamo o DynamoRevit con il pacchetto. Questi file DLL verranno già caricati da Dynamo. Se si aggrega una versione diversa da quella caricata dall'utente (ad esempio si distribuisce Dynamo Core 1.3 ma l'utente sta eseguendo il pacchetto in Dynamo 2.0), si verificheranno inspiegabili bug di runtime. Ciò include file .dll come DynamoCore.dll, DynamoServices.dll, DSCodeNodes.dll e ProtoGeometry.dll.

• Non aggregare e distribuire newtonsoft.json.net con il pacchetto se è possibile evitarlo. Questo file .dll verrà caricato anche da Dynamo 2.x. Può verificarsi lo stesso problema descritto in precedenza.

• Non aggregare e distribuire CEFSharp con il pacchetto se è possibile evitarlo. Questo file .dll verrà caricato anche da Dynamo 2.x. Può verificarsi lo stesso problema descritto in precedenza.

• In generale, evitare di condividere le dipendenze con Dynamo o Revit se è necessario controllare la versione di tale dipendenza.

Problemi comuni:

1) All'apertura di un grafico, alcuni nodi presentano più porte con lo stesso nome, ma il grafico risultava corretto al momento del salvataggio. Questo problema può avere varie cause.

La causa principale comune è che il nodo è stato creato utilizzando un costruttore che ha ricreato le porte. Invece, avrebbe dovuto essere utilizzato un costruttore che ha caricato le porte. Questi costruttori sono generalmente contrassegnati [JsonConstructor]. Per alcuni esempi, vedere di seguito.

Ciò può verificarsi perché:

• Semplicemente non era presente un valore [JsonConstructor] corrispondente o non è stato trasferito il valore Inports e Outports dal file .dyn JSON.

• Sono state caricate due versioni di JSON.net nello stesso processo contemporaneamente, causando un errore di runtime del file.net, pertanto l'attributo [JsonConstructor] non può essere utilizzato correttamente per contrassegnare il costruttore.

• Il file DynamoServices.dll con una versione diversa da quella corrente di Dynamo è stato aggregato con il pacchetto e causa la mancata identificazione dell'attributo [MultiReturn] in fase di runtime del file .net, pertanto i nodi zero-touch contrassegnati con vari attributi non verranno applicati. Potrebbe verificarsi che un nodo restituisca un singolo output del dizionario anziché più porte.

2) I nodi risultano completamente mancanti durante il caricamento del grafico con alcuni errori nella console.

• Ciò potrebbe succedere se la deserializzazione non è riuscita per qualche motivo. È consigliabile serializzare solo le proprietà necessarie. È possibile utilizzare [JsonIgnore] in proprietà complesse che non è necessario caricare o salvare per ignorarle. Proprietà come function pointer, delegate, action, o event e così via non dovrebbero essere serializzate, perché di solito non vengono deserializzate e causano un errore di runtime.

Aggiornamento in profondità:

Nodi personalizzati 1.3 - > 2.0

Problemi noti:

• I commenti verranno convertiti in commenti di blocco anziché in commenti di riga.

• I nomi di tipo breve verranno sostituiti con nomi completi. Ad esempio, se non è stato specificato un tipo quando si carica nuovamente il nodo personalizzato, verrà visualizzato var[]..[], poiché questo è il tipo di default.

Nodi zero-touch 1.3 -> 2.0

• In Dynamo 2.0 i tipi di elenco e dizionario sono stati divisi e la sintassi per la creazione di elenchi e dizionari è stata modificata. Gli elenchi vengono inizializzati utilizzando [], mentre i dizionari usano {}. Se in precedenza si utilizzava l'attributo DefaultArgument per contrassegnare i parametri sui nodi zero-touch e si usava la sintassi dell'elenco per impostare come default un elenco specifico come someFunc([DefaultArgument("{0,1,2}")]), questo metodo non sarà più valido e sarà necessario modificare il frammento DesignScript per utilizzare la nuova sintassi di inizializzazione per gli elenchi.

• Come indicato in precedenza, non distribuire i file .dll di Dynamo con i pacchetti. (DynamoCore, DynamoServices e così via).

Nodi NodeModel 1.3 -> 2.0

I nodi NodeModel richiedono la maggior parte del lavoro per eseguire l'aggiornamento a Dynamo 2.x. A livello generale, sarà necessario implementare i costruttori che verranno utilizzati solo per caricare i nodi dal file JSON, oltre ai normali costruttori di NodeModel usati per creare nuove istanze dei tipi di nodi. Per differenziarli, contrassegnare i costruttori del tempo di caricamento con [JsonConstructor], che è un attributo di newtonsoft.Json.net.

Costruttori di file JSON

La modifica più comune necessaria per l'aggiornamento dei nodi derivati dalla classe di base NodeModel (o da altre classi di base di Dynamo Core, ad esempio DSDropDownBase) è la necessità di aggiungere un costruttore JSON alla classe.

Il costruttore senza parametri originale gestirà comunque l'inizializzazione di un nuovo nodo creato in Dynamo (ad esempio tramite la libreria). Il costruttore JSON è necessario per inizializzare un nodo deserializzato (caricato) da un file .dyn o .dyf salvato.

Il costruttore JSON è diverso dal costruttore di base in quanto contiene i parametri PortModel per inPorts e outPorts, forniti dalla logica di caricamento JSON. La chiamata per la registrazione delle porte per il nodo non è necessaria in questo caso, poiché esistono i dati nel file .dyn. Un esempio di costruttore JSON è simile al seguente:

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

Questa sintassi :base(Inports,outPorts){} chiama il costruttore di base nodeModel e vi trasferisce le porte deserializzate.

Non è necessario ripetere in questo costruttore qualsiasi logica speciale presente nel costruttore della classe che implica l'inizializzazione di dati specifici serializzati nel file .dyn (ad esempio, l'impostazione della registrazione della porta, della strategia di collegamento e così via), poiché questi valori possono essere letti dal file JSON.

Questa è la differenza principale tra il costruttore JSON e i costruttori non JSON per i nodi NodeModel. I costruttori JSON vengono richiamati quando si esegue il caricamento da un file e vengono trasferiti ad essi i dati caricati. È tuttavia necessario duplicare un'altra logica utente nel costruttore JSON (ad esempio, inizializzando i gestori eventi per il nodo o l'associazione).

Proprietà pubbliche e serializzazione

[JsonProperty(PropertyName = "InputValue")]

public DSColor DsColor {...

Convertitori:

Nota Se si crea una classe di convertitori JSON.net, Dynamo non dispone attualmente di un meccanismo che consente di inserirla nei metodi di caricamento e salvataggio. Pertanto, anche se si contrassegna la classe con l'attributo [JsonConverter], potrebbe non essere utilizzata; è invece possibile chiamare il convertitore direttamente nel setter o nel getter. //TODO need confirmation of this limitation. Any evidence is welcome.

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

public ConversionMetricUnit SelectedMetricConversion{...

Esclusione delle proprietà

Annullamento/Ripetizione

Come indicato sopra, in passato sono stati utilizzati metodi SerializeCore e DeserializeCore per salvare e caricare i nodi nel file .dyn del documento XML. Inoltre, sono stati utilizzati per salvare e caricare lo stato del nodo per l'annullamento/la ripetizione e lo sono ancora. Se si desidera implementare funzionalità complesse di annullamento/ripetizione per il nodo NodeModel dell'interfaccia utente, sarà necessario implementare questi metodi e serializzarli nell'oggetto documento XML fornito come parametro per questi metodi. Questo dovrebbe essere un caso di utilizzo raro, ad eccezione dei nodi complessi dell'interfaccia utente.

API delle porte di input e output

Un'occorrenza comune nei nodi NodeModel interessati dalle modifiche all'API 2.0 è la registrazione della porta nel costruttore del nodo. Esaminando gli esempi nel repository di Dynamo o DynamoSamples, si è notato in precedenza l'uso dei metodi InPortData.Add() o OutPortData.Add(). In precedenza, nell'API di Dynamo, le proprietà pubbliche InPortData e OutPortData erano contrassegnate come obsolete. Nella versione 2.0 queste proprietà sono state rimosse. Gli sviluppatori dovrebbero ora utilizzare i metodi InPorts.Add() e OutPorts.Add(). Inoltre, questi due metodi Add() hanno firme leggermente diverse:

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

e

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

Esempi:

Illustriamo ora l'aggiornamento di un nodo dell'interfaccia utente 1.3 a Dynamo 2.x.

Per caricare e salvare correttamente la classe nodeModel nella versione 2.0, è sufficiente aggiungere un attributo JsonConstructor per gestire il caricamento delle porte. Trasferire semplicemente le porte al costruttore di base; questa implementazione è vuota.

Nota Non chiamare RegisterPorts() o qualche variazione di tale valore nell'attributo JsonConstructor: per costruire nuove porte, verranno utilizzati gli attributi dei parametri di input e output nella classe di nodi. Non è questo il caso, poiché si desidera utilizzare le porte caricate che vengono trasferite al costruttore.

Di seguito è riportato un costruttore più complesso per un nodo dell'interfaccia utente:

Quando si aggiunge un costruttore JSON per il caricamento di questo nodo da un file, è necessario ricreare una parte di questa logica, ma si noti che non è incluso il codice che crea porte, imposta il collegamento o imposta i valori di default per le proprietà che è possibile caricare dal file.

Notare che altre proprietà pubbliche che sono state serializzate in JSON come ButtonText e WindowText non verranno aggiunte come parametri espliciti al costruttore; vengono impostate automaticamente da JSON.net utilizzando i setter per tali proprietà.

Esecuzione di script Python in nodi zero-touch (C#)

Se si ha familiarità con la scrittura di script in Python e si desidera ottenere più funzionalità dai nodi Python di Dynamo standard, è possibile utilizzare nodi zero-touch per creare nodi personalizzati. Iniziamo con un semplice esempio che ci consente di passare uno script Python come stringa ad un nodo zero-touch dove viene eseguito lo script e viene restituito un risultato. Questo case study si baserà sulle simulazioni e sugli esempi della sezione Per iniziare, a cui fare riferimento se si è completamente inesperti nella creazione di nodi zero-touch.

Nodo zero-touch che eseguirà una stringa di script Python

Motore Python

Questo nodo si basa su un'istanza del motore di scripting IronPython. A tale scopo, è necessario fare riferimento ad alcuni assiemi aggiuntivi. Per impostare un modello di base in Visual Studio, attenersi alla procedura descritta di seguito:

• Creare un nuovo progetto di classe di Visual Studio.

• Aggiungere un riferimento al file IronPython.dll situato in C:\Program Files (x86)\IronPython 2.7\IronPython.dll.

• Aggiungere un riferimento al file Microsoft.Scripting.dll situato in C:\Program Files (x86)\IronPython 2.7\Platforms\Net40\Microsoft.Scripting.dll.

• Includere le istruzioni IronPython.Hosting e Microsoft.Scripting.Hosting using nella classe.

• Aggiungere un costruttore vuoto privato per impedire l'aggiunta di un altro nodo alla libreria di Dynamo con il pacchetto.

• Creare un nuovo metodo che utilizzi una singola stringa come parametro di input.

• All'interno di questo metodo verrà creata l'istanza di un nuovo motore Python e verrà creato un ambito di script vuoto. Si può immaginare questo ambito come variabili globali all'interno di un'istanza dell'interprete Python.

• Quindi, chiamare Execute nel motore che trasferisce la stringa di input e l'ambito come parametri.

• Infine, recuperare e restituire i risultati dello script chiamando GetVariable nell'ambito e trasferendo il nome della variabile dallo script Python che contiene il valore che si sta tentando di restituire. Per ulteriori dettagli, vedere l'esempio seguente.

Il seguente codice fornisce un esempio per il passaggio menzionato sopra. La creazione della soluzione creerà un nuovo file .dll situato nella cartella bin del progetto. Ora è possibile importare il file .dll in Dynamo come parte di un pacchetto o accedendo a 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);
        }
    }
}

Lo script Python restituisce la variabile output, il che significa che è necessaria una variabile output nello script Python. Utilizzare questo script di esempio per verificare il nodo in Dynamo. Se si è mai utilizzato il nodo Python in Dynamo, quanto segue dovrebbe risultare familiare. Per ulteriori informazioni, consultare la sezione Python della Guida introduttiva.

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

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

Più output

Una limitazione dei nodi Python standard è che hanno una sola porta di output, pertanto, se si desidera restituire più oggetti, è necessario costruire un elenco e recuperare ogni oggetto incluso. Se si modifica l'esempio precedente per restituire un dizionario, si possono aggiungere tutte le porte di output desiderate. Per ulteriori informazioni sui dizionari, fare riferimento alla sezione Restituzione di più valori in Ulteriori informazioni sul concetto di zero-touch.

Questo nodo ci consente di restituire sia il volume del cuboide che il relativo baricentro.

Modifichiamo l'esempio precedente con questi passaggi:

• Aggiungere un riferimento a DynamoServices.dll da Gestione pacchetti NuGet.

• Oltre agli assiemi precedenti, includere System.Collections.Generic e Autodesk.DesignScript.Runtime.

• Modificare il tipo restituito nel metodo per restituire un dizionario che conterrà gli output.

• Ogni output deve essere recuperato singolarmente dall'ambito (si consideri la possibilità di impostare un ciclo semplice per gruppi più grandi di output).

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

È stata inoltre aggiunta un'altra variabile di output (output2) allo script Python di esempio. Tenere presente che queste variabili possono utilizzare qualsiasi convenzione di denominazione Python legale. L'output è stato utilizzato esclusivamente per maggiore chiarezza in questo esempio.

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)