Cet article de blog pour développeurs d’Autodesk®, rédigé par Naveen Kumar, présente un guide détaillé sur le stockage extensible (Extensible Storage ou ES) dans l’API Revit®. L’auteur explique que l’ES permet aux développeurs d’attacher des données structurées personnalisées aux éléments Revit®, agissant de manière similaire aux paramètres normaux lors de la synchronisation avec le modèle central dans un environnement de travail partagé.
L’article insiste sur les meilleures pratiques de performance, recommandant de garder les données petites et structurées pour éviter de ralentir le modèle. Une section importante est dédiée à la prévention des conflits de schémas, qui se produisent lorsque des add-ins différents utilisent le même GUID pour des définitions de schémas différentes, conseillant d’attribuer un nouveau GUID lors de la mise à jour d’un schéma existant.
Enfin, il est souligné que le stockage extensible n’est pas inclus dans la conversion SVF et n’apparaît donc pas dans l’Autodesk® Viewer.
Comprendre le Stockage Extensible dans Revit® : Un Aperçu Conceptuel
Introduction : Au-delà des Paramètres Standards
Lorsque vous développez des solutions pour Revit®, vous vous heurtez rapidement aux limites des paramètres standards. Comment stocker des données complexes, des configurations spécifiques à votre application ou des métadonnées qui n’ont pas leur place dans un simple champ de texte ou un nombre ? C’est ici qu’intervient le Stockage Extensible (Extensible Storage).
Pour comprendre ce concept, utilisons une analogie simple. Imaginez qu’un élément Revit® (comme un mur ou une porte) est un classeur. Les paramètres standards sont comme des étiquettes pré-imprimées sur ce classeur : « Matériau », « Hauteur », « Coût ». Vous pouvez remplir les valeurs, mais vous ne pouvez pas changer la nature des étiquettes. Le Stockage Extensible, quant à lui, est comme attacher une pochette de rangement personnalisée à ce même classeur. Vous seul décidez de la taille de la pochette, du nombre de compartiments qu’elle contient et du type d’informations que vous y placez, qu’il s’agisse de listes de pièces, de dates de maintenance ou de configurations complexes.
Cet aperçu vous guidera à travers les composants clés du Stockage Extensible, son comportement dans un environnement collaboratif et les bonnes pratiques essentielles pour l’utiliser de manière efficace et sécurisée.
1. Qu’est-ce que le Stockage Extensible ? Les Composants Clés
Le Stockage Extensible repose sur deux concepts fondamentaux qui fonctionnent en tandem : l’Entité et le Schéma.
1.1. L’Entité : Votre Conteneur de Données Personnalisées
L’Entité (Entity) est l’objet de données que vous attachez à un élément Revit®. C’est le « contenu » que vous placez dans votre pochette de rangement personnalisée. Une Entité peut contenir une information simple, comme une chaîne de caractères, ou des données bien plus structurées, comme des listes d’identifiants d’éléments ou des cartes de valeurs.
1.2. Le Schéma : Le Plan de Votre Conteneur
Chaque Entité doit obligatoirement suivre une structure prédéfinie, appelée Schéma (Schema). Le Schéma est le plan directeur de votre conteneur de données.
Pour reprendre notre analogie, si l’Entité est un formulaire que vous avez rempli, le Schéma est le modèle de formulaire vierge. Il définit précisément quels champs existent (par exemple, « Nom du Fabricant », « Date d’Installation », « Liste des Pièces de Rechange ») et quel type de données chaque champ peut accepter (texte, nombre, identifiant d’élément, etc.). Sans Schéma, Revit® ne saurait pas comment interpréter les données de votre Entité.
1.3. L’Identifiant Unique (GUID) : L’ADN de Votre Schéma
Chaque Schéma doit posséder un identifiant unique au monde, appelé GUID (Globally Unique Identifier). Ce GUID est l’équivalent d’un numéro de série unique qui garantit que votre structure de données ne peut être confondue avec aucune autre.
L’importance de ce GUID est capitale. C’est grâce à lui que Revit® identifie sans la moindre ambiguïté la structure de vos données. Une mauvaise gestion des GUID est la source principale de conflits entre différents compléments (add-ins), car Revit® ne peut pas charger en mémoire deux Schémas différents qui prétendent avoir la même identité.
Maintenant que nous maîtrisons ces composants fondamentaux et le rôle critique du GUID, voyons comment ils se comportent concrètement dans un projet Revit®.
2. Le Stockage Extensible en Pratique : Comportement et Implications
2.1. Le Travail Collaboratif (Worksharing)
L’une des plus grandes forces du Stockage Extensible est son intégration transparente dans l’environnement de travail collaboratif de Revit®. La modification d’une Entité sur un élément se comporte exactement comme la modification d’un paramètre standard.
Le processus se déroule en trois étapes clés :
- Modification : Pour ajouter, modifier ou supprimer une Entité sur un élément, Revit® doit d’abord « emprunter » cet élément. Si un autre utilisateur le possède déjà, vous devrez lui en demander l’accès.
- Synchronisation : Lorsque vous synchronisez avec le modèle central, toutes les modifications apportées à vos Entités sont envoyées et intégrées au modèle central.
- Mise à jour : Les autres utilisateurs reçoivent les Entités mises à jour lorsqu’ils rechargent les dernières modifications depuis le modèle central.
En résumé, vous pouvez utiliser le Stockage Extensible en toute confiance dans un environnement partagé, car il respecte les mêmes règles de propriété et de synchronisation que les données natives de Revit®.
2.2. La Stabilité lors des Mises à Jour de Revit®
Une autre question essentielle est la pérennité des données. La bonne nouvelle est que le Stockage Extensible est conçu pour être durable : il survit aux mises à jour entre les versions majeures de Revit®. Vos données personnalisées ne seront pas perdues lorsque vous migrerez un projet de Revit® 2024 à Revit® 2025, par exemple.
Il convient toutefois de rester prudent : bien que les données soient préservées, des conflits de Schéma peuvent toujours survenir si votre add-in ou un autre utilise un GUID déjà présent en mémoire avec une définition différente. De plus, l’API elle-même peut évoluer dans les futures versions.
Comprendre ce comportement est essentiel, mais pour éviter les problèmes, il est encore plus important de maîtriser les bonnes pratiques.
3. Les Pièges à Éviter et les Bonnes Pratiques
Utiliser le Stockage Extensible est puissant, mais cette puissance exige de la rigueur pour ne pas nuire à la performance du modèle ou créer des conflits.
3.1. Priorité n°1 : La Performance du Modèle
La taille et la structure des données que vous stockez ont un impact direct sur la performance de Revit®. Des données volumineuses ou mal structurées peuvent ralentir considérablement le modèle.
Voici trois conseils fondamentaux pour préserver la performance :
- Gardez les données petites : Il n’y a pas de limite stricte, mais des données volumineuses attachées à de nombreux éléments ralentiront les temps de sauvegarde, de synchronisation et d’ouverture du projet. Le « pourquoi » est simple : Revit® doit charger et traiter ces données à chaque opération.
- Structurez intelligemment : Évitez de stocker toutes vos informations dans une seule grande chaîne de caractères (comme un JSON). Privilégiez l’utilisation de plusieurs champs avec des types de données primitifs (texte, nombre, etc.). Cela permet à Revit® d’accéder à une information spécifique plus rapidement, sans avoir à analyser l’intégralité de la chaîne.
- Utilisez les
ElementIdsavec modération : Stocker des références à d’autres éléments via leurElementIdest très utile. Cependant, Revit® doit effectuer un traitement supplémentaire pour gérer ces liens (par exemple, lors de la copie ou de la suppression d’éléments). Un nombre excessif d’ElementIdsdans une seule Entité peut donc entraîner des ralentissements.
3.2. Le Risque Majeur : Les Conflits entre Add-ins
Le problème le plus grave que vous pouvez rencontrer est un conflit de Schéma. Cela se produit lorsque deux Schémas partagent le même GUID mais ont des définitions qui diffèrent sur l’un des points suivants : le nom du Schéma, le nombre de champs, les définitions des champs, le VendorId, le GUID de l’application, ou les niveaux d’accès en lecture/écriture.
La raison technique est cruciale à comprendre : les Schémas sont chargés dans la mémoire de la session Revit® en cours, et non stockés dans le document lui-même. Par conséquent, si vous ouvrez un modèle qui contient un Schéma, puis un autre modèle (dans la même session) qui utilise le même GUID avec une autre définition, Revit® lèvera une erreur de conflit. Un piège classique pour les développeurs débutants est de copier un exemple de code trouvé en ligne et de modifier sa définition de Schéma, mais en oubliant de générer un nouveau GUID.
Pour garantir la stabilité de votre add-in et sa cohabitation avec d’autres, suivez cette procédure pour mettre à jour un Schéma :
Comment Mettre à Jour un Schéma en Toute Sécurité
| Étape | Action Requise |
|---|---|
| 1. Créer une Nouvelle Identité | Attribuez un nouveau GUID à votre Schéma mis à jour. N’essayez jamais de modifier un Schéma existant en gardant le même GUID. |
| 2. Gérer la Transition | Mettez à jour votre code pour qu’il soit capable de lire les données de l’ancien Schéma (s’il existe) et de les écrire dans le nouveau Schéma. |
| 3. Planifier la Suppression | Une fois que vous êtes certain que les données ont été migrées vers le nouveau Schéma, prévoyez une logique pour supprimer l’Entité de l’ancien Schéma afin de nettoyer le modèle. |
Avertissement sur le travail collaboratif : La migration de données (étape 2) est une modification d’élément. Elle déclenche donc un « emprunt » de cet élément, comme vu précédemment. Évitez absolument d’automatiser cette migration lors d’événements comme l’ouverture (DocumentOpened) ou la sauvegarde (DocumentSaved) du document. Une telle automatisation peut « emprunter » des centaines d’éléments sans aucune action de l’utilisateur, créant des blocages et des conflits de permissions majeurs pour les autres membres de l’équipe.
3.3. Une Limite Fondamentale : La Visibilité des Données
Il est essentiel de comprendre que les données du Stockage Extensible sont privées et non visibles en dehors de votre add-in. Elles sont conçues pour être lues et écrites via l’API Revit®, et uniquement par une application qui connaît leur Schéma.
Cette nature privée a deux conséquences majeures :
- Les données n’apparaissent pas dans l’Autodesk® Viewer (
Forge Viewer / APS Viewer). La raison est technique : le processus de conversion qui génère les fichiers pour la visionneuse (SVF) ne charge aucun add-in et ne peut donc pas exécuter le code nécessaire pour lire et exporter vos données privées. - Les données ne sont pas accessibles via les API de paramètres standards. Vous ne pouvez pas lire une Entité comme vous liriez un paramètre de texte normal.
Si vous avez besoin d’exploiter ces données dans la visionneuse, vous devrez implémenter une stratégie d’exportation séparée (par exemple, vers un fichier JSON externe ou un service de métadonnées personnalisé).
4. Conclusion : Les Leçons à Retenir
Le Stockage Extensible est un outil indispensable pour tout développeur Revit® qui souhaite dépasser les fonctionnalités de base. Il offre une flexibilité immense pour attacher des données structurées et intelligentes aux éléments d’un modèle. Cependant, cette flexibilité s’accompagne de responsabilités : la performance, la stabilité et la compatibilité.
Pour un nouvel apprenant, voici les quatre points essentiels à mémoriser :
- Comportement familier : En mode collaboratif, le Stockage Extensible se comporte comme les paramètres standards, respectant les règles d’emprunt et de synchronisation.
- La performance avant tout : La taille et la structure de vos données sont cruciales. Gardez vos données légères et bien organisées pour ne pas ralentir le modèle.
- Le GUID est sacré : Une gestion rigoureuse et unique des GUID est obligatoire pour éviter les conflits dévastateurs entre add-ins. Ne réutilisez jamais un GUID pour un Schéma différent.
- Des données privées : N’oubliez jamais que vos données ne seront pas visibles dans l’Autodesk® Viewer ou accessibles via les API de paramètres. Planifiez des exports alternatifs si ces données doivent être exploitées sur d’autres plateformes.