Cet article a fait l'objet d'une traduction automatique.

table.one { table-layout:fixed; width : 900px; } table.two { table-layout:fixed;width:900px; margin-bottom: 10px; } .tdwidth{ width:100px; }

Base Instincts

Documenter votre code avec les commentaires XML

Lisa Feigenbaum

Cet article est en partie basé sur une version préliminaire de Visual Studio. Toutes les informations sont sujets à modification.

Contenu

Notions fondamentales de commentaire XML
Personnalisation des commentaires XML
Génération du fichier de documentation XML
Amélioration de Visual Studio avec des commentaires XML
Les avantages de commentaires personne sinon de code
Astuces de .NET Framework
Génération de documentation mieux
Commentaires XML dans Visual Studio 2010

Recherchez un moyen simple mais efficace de votre code de document ? Commentaires XML fournissent une solution très. Commentaires XML pour Visual Basic ont été introduites dans Visual Studio 2005. Ils peuvent être utilisées pour créer un fichier de documentation pour le projet et fournir une expérience d'environnement de développement riche pour vous-même, vos collègues ou autres personnes utilisant votre code.

Dans cet article, je va vous présenter aux commentaires XML et vous expliquer comment les utiliser. J'AI découvrirez manières dans lequel commentaires XML peuvent être utilisés pour personnaliser votre environnement de codage et pour créer les fichiers de documentation à partir des commentaires dans votre code. Également j'expliquerai certaines fonctionnalités Visual Studio futures qui créera une expérience encore mieux pour manipuler des commentaires XML dans votre code.

Notions fondamentales de commentaire XML

Commentaires XML peuvent être utilisés pour documenter presque toutes les définitions sauf les espaces de noms. Cela comprend des types (classe, module, interface, structure, énumération, délégué), les champs (dimension), des propriétés (propriété), des événements (événement) et des méthodes (Sub, fonction, Declare, opérateur).

Commentaires XML sont insérée inline, directement dans votre code source. Cela facilite maintenir les à jour que le code évolue. Pour insérer un commentaire XML, tapez trois repères seule proposition de prix (« ») juste au-dessus de la définition, comme suit :

'''
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Sinon, vous pouvez également taper « » au début de la définition de ligne et les appuyez sur ENTRÉE. Visual Studio pour insérer un squelette du commentaire XML pour pouvoir renseigner.

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <remarks></remarks>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Le but de cet article, J'AI utilisé une fonction simple avec un paramètre pour illustrer la fonctionnalité commentaires XML. Le squelette XML varie selon la définition. Par exemple, le squelette XML pour une fonction comprend un élément renvoie, tandis que le squelette d'une sous-routine ne. Le nombre de balises param pour les méthodes varie également en fonction du nombre de paramètres.

Notez que bien que Visual Studio insère le squelette XML approprié pour la définition et vous fournira une les avertissements si le commentaire obtient les de synchronisation, il pas corrige automatiquement le commentaire pour vous. Par conséquent, veillez à mettre à jour du commentaire au fur et à mesure que vous apportez des modifications à la définition.

Une fois le squelette XML est inséré, vous pouvez tabulation via les groupes de contenu pour insérer vos commentaires. Visual Studio colorie le contenu XML très depuis les balises. Vous pouvez également supprimer des éléments si vous avez n'est pas besoin, telles que l'élément Remarques.

Enfin, vous pouvez ajouter des éléments qui se trouvaient pas dans le squelette XML d'origine. Que vous amorcez la saisie d'un chevron gauche (<), une liste des balises courantes apparaît dans un menu contextuel IntelliSense comme illustré dans la figure 1 .

Figure 1 commentaires XML dans IntelliSense

Vous pouvez ajouter n'importe quel code XML valide sur le commentaire XML. Une liste de balises utilisées se trouve dans l'article »Recommandée balises XML pour les commentaires de documentation (Visual Basic)." Si le commentaire occupe trop d'espace, vous pouvez la réduire à la synthèse la +/-contrôles sur le côté gauche de l'éditeur de code, comme illustré dans La figure 2 .

La figure 2 réduit les commentaires XML

Personnalisation des commentaires XML

Dans l'exemple précédent, J'AI effectuer des modifications pour le squelette XML d'origine. Développeurs travaillent dans un environnement d'entreprise devrez peut-être modifier les commentaires XML par défaut en fonction de leurs instructions d'entreprise spécifique. Pour vous aider avec ces scénarios, Visual Basic permet de personnaliser le squelette XML par défaut.

Tout d'abord, créez un nouveau fichier XML nommé VBXMLDoc.xml qui inclut vos modèles de commentaire par défaut. Un exemple de fichier est inclu dans le téléchargement de code de cet article. Enregistrer VBXMLDoc.xml à l'emplacement approprié basé sur votre version de Windows et Visual Studio, comme illustré figure 3 . <user>Dans chaque cas, remplacez <utilisateur> dans le chemin d'accès par votre propre nom d'utilisateur.

Visual Studio a intégré par défaut pour les skeletons XML qui obtenir insérées, mais lorsque VBXMLDoc.xml est présent au démarrage, Visual Studio utiliseront les définitions XML contenu de ce fichier au lieu de cela. La version de VBXMLDoc.xml fournies dans le téléchargement de code contient les balises par défaut qui serait autrement être insérés par Visual Studio. Pour modifier les paramètres par défaut, le type d'élément de code que vous êtes intéressé par et modifier les éléments XML dans le fichier.

Par exemple, modifions le squelette XML qui obtient inséré pour la fonction. figure 4 illustre par défaut les entrées personnalisées pour une fonction. Enfants de l'élément de modèle représentent les éléments XML qui sont insérées dans le squelette de commentaire XML. Enfants de l'élément CompletionList représentent les suggestions qui apparaîtront dans IntelliSense lors de taper un crochet angle gauche (<) au-dessus d'une fonction.

Figure 4 balises XML de fonction

Par défaut XML

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <remarks/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <remarks/>
    <returns/>
    <summary/>
  </CompletionList>
</CodeElement>

XML personnalisé

<CodeElement type="Function">
  <Template>
    <summary/>
    <param/>
    <returns/>
    <author/>
  </Template>
  <CompletionList>
    <exception cref=""/>
    <include file="" path=""/>
    <param name=""/>
    <permission cref=""/>
    <returns/>
    <summary/>
    <author/>
    <history/>
  </CompletionList>
</CodeElement>

Comme vous pouvez le voir dans la deuxième partie de la figure 4 , J'AI apporté quelques personnalisations simples. Tout d'abord, J'AI supprimé l'élément de notes dans le squelette par défaut et IntelliSense. En outre, vous avez ajouté un élément author au squelette par défaut et IntelliSense, et J'AI ajouté un élément d'historique dans IntelliSense.

À ce stade vous devrez peut-être fermer et rouvrir Visual Studio pour les les modifications dans VBXMLDoc.xml à obtenir récupérées. Après avoir redémarré, les commentaires XML automatiquement insérées au-dessus de fonction inclut un élément author au lieu de notes :

''' <summary>
''' 
''' </summary>
''' <param name="regKey"></praram>
''' <returns></returns>
''' <author></author>
Function RegKeyExists(ByVal regKey As String) As Boolean
  Dim exists As Boolean = False
  Try
...

Bien qu'il soit possible d'ajouter éléments XML pour le modèle, il n'est pas possible d'ajouter des valeurs XML. Par conséquent, vous pouvez apporter l'insertion IDE <author> </author> par défaut, mais il n'est pas possible faciliter l'insertion de <author> Microsoft Corporation </author>.

Génération du fichier de documentation XML

Le compilateur Visual Basic produit un document XML de votre assembly avec tous les commentaires XML définies dans le code. Le compilateur résolve également symboles utilisés dans cref, autorisation, et les attributs de nom, ainsi que les références de fichier dans incluent des éléments.

Le fichier généré n'est pas afficher les membres de votre commentées hiérarchiquement. Au lieu de cela, il est une liste plate. Il inclut une chaîne D'ID unique pour chaque définition de qui permet les commentaires à mapper à leurs définitions dans le code (voir figure 5 ). Dans ce cas, la chaîne est M:RegLib.Helpers.RegKeyExists(System.String). MESURE est l'acronyme de méthode, RegLib.Helpers spécifie le chemin d'accès, RegKeyExists est le nom de la méthode et System.String le type de paramètre.

La figure 5 génération XML document extrait

<?xml version="1.0" ?>
<doc>
<assembly>
<name>RegLib</name>
</assembly>
<members>
...
<member name="M:RegLib.Helpers.RegKeyExists(System.String)">
  <summary>Determines whether a specific registry key exists.</summary>
  <param name="regKey">Name or path of the registry key.</param>
  <returns>True if the registry key exists; otherwise, False.</returns>
  <author>Microsoft Corporation</author>
</member>
...
</members>
</doc>

Vous pouvez générer le fichier de documentation XML en utilisant l'une au compilateur de ligne de commande ou à l'aide de la Visual Studio d'interface. Si vous êtes compiler avec le compilateur de ligne de commande, utilisez /doc options ou doc. +. Qui va générer un fichier XML par le même nom et le même chemin que l'assembly. Pour spécifier un nom de fichier différent, utilisez /doc:file.

Si vous utilisez l'interface Visual Studio, il n'y a un paramètre qui détermine si le fichier de documentation XML est généré. Pour définir les il, double-cliquez sur mon projet dans Explorateur de solutions pour ouvrir le Concepteur de projets. Accédez à l'onglet compiler. Rechercher « générer XML fichier de documentation » en bas de la fenêtre et assurez-vous qu'il est activée. Par défaut, ce paramètre est de. Il génère un fichier XML utilisant le même nom et chemin d'accès en tant que l'assembly.

Mon exemple est un projet de bibliothèque de classes appelé RegLib, de sorte que l'assembly et le fichier de documentation XML soit RegLib.dll et RegLib.xml, respectivement. Le chemin d'accès où elles seront créées est répertoriée dans la zone « Chemin de sortie version ». Il doit y avoir une version explicite de ces fichiers à produire.

Microsoft utilise des commentaires XML pour générer la documentation pour tous les assemblys Microsoft .NET Framework. La documentation XML fichiers sont placés en regard des dll document, et qu'ils correspondent dans nom.

Amélioration de Visual Studio avec des commentaires XML

De nombreuses fonctionnalités de Visual Studio utiliser commentaires XML pour fournir une meilleure expérience pour travailler avec des membres. Car le compilateur Visual Basic est toujours en cours d'exécution en arrière-plan, Visual Studio peut consommer des commentaires XML qu'ils sont créés, sans nécessiter une version explicite.

L'endroit plus courants où les commentaires XML sont utilisées est IntelliSense. Le contenu résumé dans le commentaire XML apparaît dans l'info-bulle. Comme la méthode est utilisée, IntelliSense affiche également le contenu param dans ce que l'on appelle une info-bulle Aide paramètre (voir figure 6 ).

La figure 6 paramètre Aide info-bulle à l'aide commentaires XML

Exploration des membres dans l'Explorateur d'objets est une expérience beaucoup améliorée avec des commentaires XML. Explorateur d'objets affiche résumé, param, retour, notes, typeparam et commentaires exception lorsqu'il existent (voir figure 7 ). Classe Designer, Affichage de classes et banc de test d'objets utilisent également commentaires XML lorsqu'elles sont disponibles.

La figure 7 Explorateur d'objets à l'aide des commentaires XML

Les avantages de commentaires personne sinon de code

J'AI illustré précédemment comment personnaliser l'expérience de Visual Studio pour une fonction en ajoutant des commentaires XML à sa définition. Pour les membres définis dans les assemblys référencés, toutefois, il n'est pas pratique de suivent le même processus puisque vous n'est pas nécessairement avez accès à la source. Heureusement, il est un processus différent (commentaires XML également impliquant) que vous pouvez utiliser pour les membres référencés !

Il existe une différence clée. Pour les membres de la solution actuelle, les fonctionnalités de Visual Studio fonctionnent par rapport à une représentation en mémoire des commentaires XML basés sur la source. Dans ce cas, le fichier de documentation XML est purement une sortie et n'est pas même besoin d'être générées pour les fonctionnalités de Visual Studio à utiliser. D'autre part, dans le cas des assemblys référencés, les fichiers de documentation XML sont lus comme entrées et influencent le comportement dans l'environnement de codage.

Examinons un exemple. Je vais créer un nouveau projet et référencer l'assembly que J'AI créé antérieure (RegLib.dll). Le fichier de documentation XML généré (RegLib.xml) doit être placé en regard de l'assembly et doit avoir le même nom. Si j'accéder à la méthode RegKeyExists depuis le projet actuel, il apparaîtra dans IntelliSense. Cependant, je peut modifier son apparence.

Ouverture RegLib.xml et modifier le contenu résumé à « détermine si la clé de Registre existe ». La mise à jour se produit immédiatement, et la prochaine fois que j'accéder le membre dans IntelliSense, je vois le nouveau texte dans l'info-bulle (voir La figure 8 ).

La figure 8 info-bulle IntelliSense

Astuces de .NET Framework

Le .NET Framework est un autre exemple d'assemblys vous faire référence à partir de vos projets. Tenez compte des Microsoft.VisualBasic.dll, dont fichier de documentation XML se trouve bien ici :

C:\Windows\Microsoft.NET\Framework\v2.0.50727\en\Microsoft.VisualBasic.xml 

Ouvrir le fichier XML et examiner les commentaires XML. Il existe des éléments XML intéressants que vous trouverez dans cet emplacement. Par exemple, Filterpriority détermine comment un membre s'affiche dans Visual Basic, IntelliSense. Une valeur de 1 signifie qu'il doit apparaître dans l'onglet Common, 2 signifie qu'il doit apparaître dans l'onglet toutes et 3 signifie qu'il doit être masqué dans IntelliSense complètement. Filterpriority ce membre est défini sur 1: il apparaîtra en commun. Vous pourriez facilement modifier la valeur filterpriority à 2 et enregistrez le fichier XML pour le membre apparaît dans l'onglet toutes.

Notez que, avant de modifier les fichiers de documentation .NET Framework XML, il est judicieux de créer une copie au préalable. Vous devez également ouvrir les fichiers dans une application disposant de privilèges élevés. Visual Studio est une bonne option car elle conserve le format de fichier.

Vous pouvez utiliser la méthodologie décrite dans cette section pour influencer les membres dans un assembly référencé, tant que vous avez accès à son fichier de documentation XML ou vous pouvez créer un s'il n'existe pas. Pour influencer le filterpriority d'un membre défini dans l'assembly actuel, utilisez l'attribut System.ComponentModel.EditorBrowsable.

Un autre élément intéressant est le jeu d'autorisations. Cet élément indique dans quelles circonstances le membre est accessible. Le contenu de l'élément fait référence à la type System.Security.Permissions.SecurityPermission.

Nous allons inférieur notre niveau d'autorisation en cours et voir effet cela a notre accès aux FileWidth. Créer une console ou application Windows. Cliquez sur mes programmes dans Explorateur de solutions pour ouvrir le Concepteur de projets. Sélectionnez l'onglet Sécurité, puis vérifiez « activer les paramètres de sécurité ClickOnce » et « Ceci est une application de confiance partielle ».

À ce stade les autorisations requises ne sont pas disponibles, donc FileWidth et neighboring membres deviennent grisé arrière et inaccessible dans IntelliSense. Cette fonctionnalité de Visual Basic s'appelle IntelliSense dans la zone. L'info-bulle indique le type d'autorisation est requis pour utiliser le membre.

Vous pouvez ajouter des éléments jeu d'autorisations à fichiers de documentation XML membre et spécifiez l'autorisation appropriée.

Génération de documentation mieux

Le code XML généré par le compilateur Visual Basic est lisible, mais pas le plus convivial. Un certain nombre d'outils ont été créé pour créer les mieux documentation aspect qui est plus facile de naviguer.

Le premier outil est appelé Sandcastle, développé par Microsoft. Après l'installation Sandcastle, collecter les assemblys qui vous sont documenter, leurs dépendances et leurs fichiers de documentation XML. Copiez tous les documents dans le dossier d'installation vSandcastle (généralement C:\Program Files\Sandcastle\Examples\sandcastle).

Ouvrez une invite de commande avec des privilèges élevés et naviguez vers le même répertoire, puis exécutez cette commande :

build_Sandcastle.bat prototype <your assembly name without the file extension>

Répertoires et fichiers sont générés par cette opération.Ouvrez le répertoire .chm, puis ouvrez le fichier .chm à l'intérieur.Il doit ressembler à l'aide à la figure 9 .

La figure 9 Sandcastle .chm sortie

L'outil offre un certain nombre d'autre sortie formats autres que. chm.Pour plus d'informations et autres annonces sur Sandcastle, Veuillez regarder le blog àblogs.msdn.com/Sandcastle.

NDocest un autre outil populaire que vous pourriez envisager d'utiliser, ou vous pouvez utiliser les puissantes fonctionnalités XML dans Visual Basic 9 pour écrire votre propre outil personnalisé !

Commentaires XML dans Visual Studio 2010

Hâte, il existe de nouvelles possibilités pour la façon dont vous pouvez interagir avec les commentaires XML dans le code.L'éditeur Visual Studio 2010 est réécrite de manière à l'aide de Windows Presentation Foundation (WPF) et permet de visualisations riches.L'éditeur met à jour également impliqué déplacer vers un nouveau système de composant, le géré d'extensibilité Framework (MEF), qui facilite beaucoup enregistrer des compléments dans Visual Studio.la figure 10 illustre un exemple d'une visionneuse de commentaire XML a été construit sur le nouvel éditeur et le composant de modèle.

La figure 10 Observateur de commentaire XML de Visual Studio 2010

Cliquant sur le bouton dans les coin supérieur droit de commutateurs l'affichage entre le contrôle WPF et le XML d'origine.Le contrôle WPF fournit certainement une quantité vue plus clair.Il tire également parti des fonctionnalités WPF tels que dégradés et les bords arrondis.WPF permet d'inclure les images ou vidéos, également !Il s'agit certainement une zone riche pour les compléments tiers tirer parti de dans la version de Visual Studio 2010.

Veuillez envoyer vos questions et commentaires àl'adresse instinct@microsoft.com.

Lisa Feigenbaum est le responsable de programme Microsoft pour la communauté Visual Basic.Elle a été membre de l'équipe Visual Basic depuis 2004.Avant son rôle actuel, Lisa était responsable de programme pour le Visual Basic Editor et le débogueur, travailler sur les fonctionnalités, telles que IntelliSense, Modifier-et-Continuer et extraits de code.Vous trouverez Jeff à divers américainet conférences internationales et de groupes d'utilisateurs, regardez son webcasts Channel 9, ou lire ses messages sur le blog équipe Visual Basic àhttps://blogs.msdn.com/vbteam .