Focus sur les documents

---

Mise à jour : 21 novembre 2024

Travailler avec des identifiants de documents (DocumentId)

Chaque document est distingué par un identifiant dont le type est DocumentId L'identifiant peut être vide et sa propriété IsEmpty renverra donc true. De plus, le document en cours d'édition est retourné par la propriété EditedDocument et peut être vide.

Il est donc possible de récupérer le document en cours d'édition et de vérifier qu'il n'est pas vide avant de commencer toute modification.

Les identifiants des documents correspondent à des révisions mineures spécifiques des objets PDM. Il est possible de trouver un DocumentId à partir d'objets PDM et vice versa, comme décrit dans le diagramme ci-dessous :

• Pour ouvrir un document, il suffit d'appeler la méthode TopSolidHost.Documents.Open et de lui communiquer le DocumentId.
• Pour enregistrer un document, il faut utiliser la méthode TopSolidHost.Documents.Save et renseigner le DocumentId.
• Pour fermer un document, il faut utiliser la méthode TopSolidHost.Documents.Close qui prend comme argument le DocumentId, et deux booléens pour demander respectivement à l'utilisateur de confirmer la fermeture et si le document doit être sauvegardé.

Voici un morceau de code qui vous permet d'ouvrir, de sauvegarder et de fermer le document rempli par n'importe quel DocumentId "docId" :

TopSolidHost.Documents.Open(ref docId);
TopSolidHost.Documents.Save(docId);
TopSolidHost.Documents.Close(docId,false,false);

---

Modification des documents : StartModification et EndModification

Votre application peut s'interfacer avec TopSolid pour extraire des informations et modifier ses données. Si des modifications sont nécessaires, l'application doit en informer TopSolid au préalable. Cela se fait en appelant TopSolidHost.Application.StartModification avant d'effectuer des modifications et TopSolidHost.Application.EndModification une fois les modifications terminées.

Note

StartModification peut échouer si TopSolid est dans un état inaccessible. Par exemple, cela peut arriver si l'utilisateur est en train d'éditer une fonction du menu. Votre application doit gérer ce scénario de manière appropriée.

Si StartModification réussit, TopSolid devient indisponible pour l'utilisateur jusqu'à ce que EndModification soit appelé. Si l'appel à EndModification n'a pas lieu, TopSolid restera bloqué, ce qui obligera l'utilisateur à mettre fin au processus et à perdre potentiellement toutes les modifications non sauvegardées. Pour éviter cela, il est essentiel de toujours appeler EndModification.

Pour se prémunir contre les problèmes liés à StartModification et EndModification, nous recommandons d'implémenter un bloc try/catch. Placez le StartModification et la logique de modification dans le bloc try et assurez-vous que EndModification est appelé à la fois dans les blocs try et catch. Cela permet de s'assurer qu'en cas d'erreur, le contrôle est correctement rendu à l'utilisateur. La structure recommandée est la suivante :

try
{
	//Start modification
    TopSolidHost.Application.StartModification("My Action", false);
    
    // Your modification code here
    
	//End modification (if success)
    TopSolidHost.Application.EndModification(true, true);
}
catch (Exception ex)
{
    // Handle exception here
    TopSolidHost.Application.EndModification(false, false);
}

---

Focus sur EnsureIsDirty

Pour s'assurer qu'un document est modifiable, vous devez utiliser la méthode TopSolidHost.Documents.EnsureIsDirty, qui référence le DocumentId du document à modifier. Si cette méthode renvoie true, le document est éditable, ce qui vous permet de procéder aux modifications tout en minimisant le risque d'erreurs.

Cependant, il faut savoir que cette méthode peut échouer dans certains scénarios, par exemple lorsqu'un utilisateur quitte le coffre-fort du document. Dans ce cas, une nouvelle révision est créée, ce qui entraîne un changement de l'identifiant du document (DocumentId). Cela souligne l'importance de la validation de l'état du document et de la gestion des erreurs potentielles lorsque l'on travaille avec des révisions de documents.

Warning

Les débutants négligent souvent la méthode EnsureIsDirty. Si vous rencontrez un problème et que vous vous retrouvez dans le bloc catch, vérifiez que vous n'avez pas oublié d'appeler la méthode EnsureIsDirty. Cette simple étape permet d'éviter les erreurs et de s'assurer que le document a été correctement validé avant de tenter de le modifier.