Aller plus loin avec le Zero-Touch

Après avoir appris à créer un projet Zero-Touch, nous pouvons approfondir les spécificités de la création d’un nœud en parcourant l’exemple ZeroTouchEssentials sur Dynamo Github.

Nœuds Zero-Touch

De nombreux nœuds standard de Dynamo sont essentiellement des nœuds Zero-Touch, comme la plupart des nœuds Math, Color et DateTime ci-dessus.

Pour commencer, téléchargez le projet ZeroTouchEssentials à partir de l’emplacement suivant : https://github.com/DynamoDS/ZeroTouchEssentials

Dans Visual Studio, ouvrez le fichier solution ZeroTouchEssentials.sln et générez la solution.

ZeroTouchEssentials dans Visual Studio

Le fichier ZeroTouchEssentials.cs contient toutes les méthodes que vous allez importer dans Dynamo.

Ouvrez Dynamo et importez le ZeroTouchEssentials.dll pour obtenir les nœuds que vous allez référencer dans les exemples suivants.

Les exemples de code sont tirés de ZeroTouchEssentials.cs et correspondent généralement à ce dernier. La documentation XML a été supprimée pour préserver la concision, et chaque exemple de code créera le nœud figurant dans l’image ci-dessus.

Valeur d’entrée par défaut

Dynamo prend en charge la définition de valeurs par défaut pour les ports d’entrée d’un nœud. Ces valeurs par défaut seront fournies au nœud si les ports ne sont pas connectés. Les valeurs par défaut sont exprimées à l’aide du mécanisme C# qui spécifie les arguments facultatifs dans le Guide de programmation C#. Les valeurs par défaut sont spécifiées de la manière suivante :

• Définissez les paramètres de la méthode à une valeur par défaut : 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;
        }
    }
}

Valeur par défaut

1. La valeur par défaut s’affiche lorsque vous passez le curseur sur le port d’entrée du nœud.

Renvoyer plusieurs valeurs

Le renvoi de plusieurs valeurs est un peu plus complexe que la création de plusieurs entrées et devra être renvoyé à l’aide d’un dictionnaire. Les entrées du dictionnaire deviennent des ports sur le côté sortie du nœud. Les ports de retour multiples peuvent être créés de la manière suivante :

• ajoutez using System.Collections.Generic; pour utiliser Dictionary<> ;

• ajoutez using Autodesk.DesignScript.Runtime; pour utiliser l’attribut MultiReturn. Cela fait référence à « DynamoServices.dll » du package DynamoServices NuGet ;

• ajoutez l’attribut [MultiReturn(new[] { "string1", "string2", ... more strings here })] à la méthode. Les chaînes font référence aux clés du dictionnaire et deviendront les noms des ports de sortie ;

• renvoyez un Dictionary<> de la fonction dont les clés correspondent aux noms des paramètres dans l’attribut : 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) }
            };
        }
    }
}

Référez-vous à cet exemple de code dans ZeroTouchEssentials.cs

Un nœud qui renvoie plusieurs sorties.

Sorties multiples

1. Notez que deux ports de sortie sont désormais nommés en fonction des chaînes que nous avons saisies pour les clés du dictionnaire.

Documentation, info-bulles et recherche

Il est recommandé d’ajouter de la documentation aux nœuds Dynamo pour décrire la fonction du nœud, les entrées, les sorties, les balises de recherche, etc. Cela se fait par le biais de balises de documentation XML. Pour créer de la documentation XML, procédez de la manière suivante :

• tout texte de commentaire précédé de trois barres obliques est considéré comme de la documentation ;

  • par exemple : /// Documentation text and XML goes here

• après les trois barres obliques, créez des balises XML au-dessus des méthodes que Dynamo lira lors de l’importation du fichier .dll ;

  • par exemple : /// <summary>...</summary>

• activez la documentation XML dans Visual Studio en sélectionnant Project > Project Properties > Build et en cochant la case XML documentation file.

Générer un fichier XML

1. Visual Studio générera un fichier XML à l’emplacement spécifié.

Les types de balises sont les suivants :

• /// <summary>...</summary> est la documentation principale de votre nœud et apparaît sous forme d’infobulle au-dessus de votre nœud dans la barre latérale de recherche gauche ;

• /// <param name="inputName">...</param> créera une documentation pour des paramètres d’entrée spécifiques ;

• /// <returns>...</returns> créera une documentation pour un paramètre de sortie ;

• /// <returns name = "outputName">...</returns> créera une documentation pour plusieurs paramètres de sortie ;

• /// <search>...</search> fera correspondre votre nœud à des résultats de recherche basés sur une liste séparée par des virgules. Par exemple, si nous créons un nœud qui subdivise un maillage, nous pouvons ajouter des balises telles que « maillage », « subdivision » et « catmull-clark ».

L’exemple suivant présente un nœud avec des descriptions d’entrée et de sortie, ainsi qu’un résumé qui s’affichera dans la bibliothèque.

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

Reportez-vous à cet exemple de code dans ZeroTouchEssentials.cs.

Notez que le code de cet exemple de nœud contient :

1. un résumé du nœud ;

2. une description d’entrée ;

3. une description de sortie.

Objets

Dynamo ne possède pas de mot-clé new, les objets doivent donc être construits à l’aide de méthodes de construction statiques. Les objets sont construits de la façon suivante :

• rendez le constructeur interne internal ZeroTouchEssentials() à moins de devoir le faire autrement ;

• construisez l’objet avec une méthode statique telle que public static ZeroTouchEssentials ByTwoDoubles(a, b).

Remarque : Dynamo utilise le préfixe « By » pour indiquer qu’une méthode statique est un constructeur, et bien que cela soit optionnel, l’utilisation de « By » aidera votre bibliothèque à mieux s’adapter au style existant de 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);
        }
    }
}

Reportez-vous à cet exemple de code dans ZeroTouchEssentials.cs.

Une fois que le .dll ZeroTouchEssentials a été importé, un nœud ZeroTouchEssentials sera présent dans la bibliothèque. Cet objet peut être créé en utilisant le nœud ByTwoDoubles.

Nœud ByTwoDoubles

Utiliser des types de géométrie Dynamo

Les bibliothèques Dynamo peuvent utiliser les types de géométrie Dynamo en entrée et créer de nouvelles géométries en sortie. Les types de géométrie sont créés de la manière suivante :

• Référencez « ProtoGeometry.dll » dans le projet en incluant using Autodesk.DesignScript.Geometry; au début de votre fichier C# et en ajoutant le package NuGet ZeroTouchLibrary au projet.

• Important : gérez les ressources de géométrie qui ne sont pas renvoyées par vos fonctions. Reportez-vous à la section Instructions using/dispose ci-dessous.

Remarque : les objets de géométrie Dynamo sont utilisés comme tout autre objet transmis aux fonctions.

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

Reportez-vous à cet exemple de code dans ZeroTouchEssentials.cs.

Un nœud qui obtient la longueur d’une courbe et la double.

Entrée de la courbe

1. Ce nœud accepte un type de géométrie Courbe comme entrée.

Instructions using/dispose

Les ressources de géométrie qui ne sont pas renvoyées par les fonctions devront être gérées manuellement à moins que vous n’utilisiez Dynamo version 2.5 ou ultérieure. Dans Dynamo 2.5 et versions ultérieures, les ressources de géométrie sont gérées en interne par le système. Toutefois, vous devrez peut-être supprimer la géométrie manuellement si vous avez un cas d’utilisation complexe ou si vous devez réduire la mémoire à un moment précis. Le moteur Dynamo traitera toutes les ressources de géométrie qui sont renvoyées par des fonctions. Les ressources de géométrie qui ne sont pas renvoyées peuvent être traitées manuellement de l’une des manières suivantes :

• Avec une instruction using :

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

  L’instruction using est décrite ici.

  Reportez-vous à la rubrique Améliorations apportées à la stabilité de la géométrie Dynamo pour en savoir plus sur les nouvelles fonctions de stabilité introduites dans Dynamo 2.5.

• Avec les appels dispose manuels :

  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;

Migrations

Lors de la publication d’une nouvelle version d’une bibliothèque, les noms des nœuds peuvent changer. Les changements de nom peuvent être spécifiés dans un fichier migrations afin que les graphiques générés sur des versions antérieures d’une bibliothèque continuent à fonctionner correctement lorsqu’une mise à jour est effectuée. Les migrations sont implémentées de la manière suivante :

• créez un fichier .xml dans le même dossier que le .dll au format suivant : « BaseDLLName ».Migrations.xml ;

• dans le .xml, créez un seul élément <migrations>...</migrations> ;

• dans l’élément migrations, créez <priorNameHint>...</priorNameHint> éléments pour chaque changement de nom ;

• pour chaque changement de nom, fournissez un élément <oldName>...</oldName> et <newName>...</newName>.

Fichier migrations

1. Cliquez avec le bouton droit de la souris et sélectionnez Add > New Item

2. Choisissez XML File

3. Pour ce projet, nous nommerons le fichier migrations ZeroTouchEssentials.Migrations.xml

Cet exemple de code indique à Dynamo que tout nœud nommé GetClosestPoint est désormais nommé ClosestPointTo.

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

Reportez-vous à cet exemple de code dans ProtoGeometry.Migrations.xml.

Génériques

Zero-Touch ne prend pas en charge l’utilisation de génériques pour l’instant. Ils peuvent être utilisés, mais pas dans le code importé directement lorsque le type n’est pas défini. Les méthodes, propriétés ou classes génériques qui ne possèdent pas le type défini ne peuvent pas être exposées.

Dans l’exemple ci-dessous, un nœud Zero-Touch de type T ne sera pas importé. Si le reste de la bibliothèque est importé dans Dynamo, il y aura des exceptions de type manquant.

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

L’utilisation d’un type générique avec le type défini dans cet exemple est importée dans Dynamo.

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