Il presente articolo è stato tradotto automaticamente.

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

Esigenze primarie

Documentare il codice con commenti XML

Lisa Feigenbaum

Questo articolo parte si basa su una versione preliminare di Visual Studio. Tutte le informazioni sono soggette a modifiche.

Contenuto

Introduzione a commenti XML
Personalizzazione dei commenti XML
La generazione di file di documentazione XML
Miglioramento di Visual Studio con i commenti XML
Vantaggi dell'aggiunta di commenti nome else del codice
Suggerimenti di .NET Framework
La generazione della documentazione Nicer
I commenti XML in Visual Studio 2010

Cercare un modo semplice ma efficacia per documentare il codice? I commenti XML forniscono una soluzione ottima. I commenti XML per Visual Basic prima sono stati introdotti in Visual Studio 2005. È possibile utilizzare per creare un file di documentazione per il progetto e fornire un'esperienza di ambiente di sviluppo completo per manualmente la colleghi o con altri utenti utilizzando il codice.

In questo articolo verranno presentati i commenti XML e viene illustrato come utilizzare tali. È possibile verranno analizzate modi in cui è possibile utilizzare i commenti XML per personalizzare l'ambiente di codifica e creare file di documentazione contenente commenti nel codice. È possibile inoltre illustreranno alcune funzionalità di Visual Studio futuri che verrà creata un'esperienza migliore anche per l'utilizzo di commenti XML nel codice.

Introduzione a commenti XML

I commenti XML possono essere utilizzati per documentare quasi tutte le definizioni, ad eccezione degli spazi dei nomi. Questa include tipi (classe, modulo, interfaccia, struttura, enum, delegato), i campi (Dim), proprietà (proprietà), eventi (eventi) e metodi (Declare Sub, Function, operatore).

I commenti XML sono inline inseriti, direttamente nel codice sorgente. Questo semplifica per mantenerle aggiornati come si evolve il codice. Per inserire un commento XML, digitare tre segni di virgolette sola (" ") immediatamente sopra la definizione, simile al seguente:

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

In alternativa, è possibile specificare anche ' "all'inizio della definizione di riga e premere INVIO. Visual Studio verrà inserita una struttura del commento XML per poter compilare.

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

Allo scopo di questo articolo HO utilizzato una funzione semplice con un parametro per illustrare la funzione commenti XML. La struttura XML varia in base alla definizione. Ad esempio, la struttura XML per una funzione include un elemento restituisce, mentre la struttura di un Sub non. Il numero di tag param per i metodi anche variano in base al numero di parametri.

Si noti che sebbene Visual Studio verrà inserita la struttura XML appropriata per la definizione e fornirà alcuni avvisi se il commento all'esterno di sincronizzazione, non correggerà automaticamente il commento per l'utente. Pertanto, verificare aggiornare il commento quando si modifica la definizione.

Dopo la struttura XML viene inserita, è possibile scheda tramite il contenuto wells per inserire i commenti. Visual Studio colorizes il contenuto XML nettamente dai tag. È inoltre possibile eliminare elementi se non è necessario, ad esempio l'elemento di note.

Infine, è possibile aggiungere elementi che non erano la struttura XML originale. Iniziare la digitazione un angolare sinistra (<), un elenco di tag comuni verrà visualizzati in un menu a comparsa IntelliSense come illustrato nella Nella figura 1 .

Figura 1 commento XML in IntelliSense

Il commento XML è possibile aggiungere qualsiasi codice XML valido. Un elenco di tag comuni è essere disponibile nell'articolo"Consigliato tag XML per i commenti relativi alla documentazione (Visual Basic)." Se il commento richiede troppo spazio, è possibile comprimere il riepilogo utilizzo il +/-controlli nel lato sinistro dell'editor di codice, come illustrato nella Nella figura 2 .

Nella figura 2 compresso di commento XML

Personalizzazione dei commenti XML

Nell'esempio precedente, apportate numerose modifiche alla struttura XML originale. Gli sviluppatori che utilizzano un ambiente aziendale potrebbe essere necessario modificare i commenti XML predefinito per identificare le indicazioni aziendale specifica. Per agevolare gli scenari, Visual Basic consente di personalizzare la struttura XML predefinito.

Innanzitutto, creare un nuovo file XML denominato VBXMLDoc.xml che include i modelli di commento predefinito. Un file di esempio è incluso nel download del codice per questo articolo. Salvare VBXMLDoc.xml nella posizione appropriata in base la versione di Windows e Visual Studio come illustrato nella Figura 3 . <user>In ogni caso, sostituire <utente> nel percorso con il proprio nome utente.

Visual Studio ha incorporati valori predefiniti per le bozze XML ottenere inseriti, ma quando VBXMLDoc.xml è presente all'avvio, Visual Studio saranno le definizioni XML dal file invece. La versione di VBXMLDoc.xml fornito nel download del codice contiene i tag predefiniti che in caso contrario vengono inseriti da Visual Studio. Per modificare le impostazioni predefinite, trovare il tipo di elemento di codice che si desidera e modificare gli elementi XML del file.

Ad esempio, è necessario modificare la struttura XML che Ottiene inserita per funzione. Nella figura 4 Mostra la predefinito e il voci personalizzate di una funzione. Gli elementi figlio dell'elemento modello rappresentano gli elementi XML che verranno inseriti nella struttura di commento XML. Gli elementi figlio dell'elemento CompletionList rappresentano i suggerimenti visualizzato in IntelliSense al digitare una parentesi di angolo sinistra (<) sopra una funzione.

Figura 4 tag XML per funzione

XML predefinito

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

XML personalizzati

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

Come si vede nella seconda parte della figura 4 , dopo aver apportato alcune personalizzazioni semplice. In primo luogo, rimosso l'elemento di note dai struttura predefinita e IntelliSense. Inoltre, aggiunto un elemento di autore struttura predefinita e IntelliSense e aggiunto un elemento della cronologia al IntelliSense.

A questo punto sarà necessario chiudere e riaprire Visual Studio per le modifiche in VBXMLDoc.xml ottenere prelevato. Dopo il riavvio, i commenti XML automaticamente inseriti di sopra funzione includerà un elemento di autore anziché note:

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

Sebbene sia possibile aggiungere elementi XML per il modello, non è possibile aggiungere i valori XML. Pertanto, è possibile rendere l'inserimento DELL'IDE <author> </author> per impostazione predefinita, ma non è possibile renderlo di inserimento di <author> Microsoft Corporation </author>.

La generazione di file di documentazione XML

Il compilatore Visual Basic genera un documento XML per l'assembly con tutti i commenti XML definiti nel codice. Il compilatore risolverà anche simboli utilizzati nell'cref, autorizzazione, e gli attributi di nome, come pure riferimenti ai file di includere gli elementi.

File generato non visualizza i membri commentati in modo gerarchico. Effetti, è un elenco semplice. Include una stringa ID univoca per ogni definizione che consente i commenti a cui mappare le definizioni nel codice (vedere la Figura 5 ). In questo caso, la stringa è M:RegLib.helpers.RegKeyExists(System.String). M è l'acronimo di metodo, RegLib.helpers specifica il percorso, RegKeyExists è il nome del metodo e il tipo di parametro System.String.

Nella figura 5 generati porzione del documento XML

<?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>

È possibile generare il file di documentazione XML utilizzando il compilatore della riga di comando o di interfaccia mediante Visual Studio. Se si compila con il compilatore della riga di comando, utilizzare le opzioni /doc o doc +. Che genererà un file XML con lo stesso nome e nello stesso percorso dell'assembly. Per specificare un nome di file diverso, utilizzare /doc:file.

Se si utilizza l'interfaccia di Visual Studio, c'è un'impostazione che determina se il file di documentazione XML viene generato. Per impostare, fare doppio clic sul progetto in Esplora soluzioni per aprire la finestra Progettazione progetti. Visualizzare la scheda compilazione. Cercare " XML genera file di documentazione " nella parte inferiore della finestra e assicurarsi che è selezionata. Per impostazione predefinita questa impostazione è su. Genera un file XML utilizzando lo stesso nome e percorso dell'assembly.

Mio esempio è un progetto di libreria di classi denominato RegLib, sarà l'assembly e file di documentazione XML RegLib.dll e RegLib.xml, rispettivamente. Il percorso in cui verrà creati è elencato nella casella di testo "generazione di percorso di output. Deve esistere una generazione esplicita per questi file da produrre.

Microsoft utilizza i commenti XML per generare la documentazione per tutti gli assembly Microsoft .NET Framework. I file vengono inseriti accanto alle DLL di documentazione XML sono documentare e corrispondono in nome.

Miglioramento di Visual Studio con i commenti XML

Molte funzionalità di Visual Studio consente di utilizzare i commenti XML per fornire un'esperienza migliore per l'utilizzo di membri. Poiché il compilatore Visual Basic è sempre in esecuzione in background, Visual Studio può utilizzare i commenti XML come sono creati, senza una generazione esplicita.

La posizione più componenti in cui vengono utilizzati i commenti XML è IntelliSense. Il contenuto di riepilogo dal commento XML viene visualizzato nella descrizione comandi. Viene utilizzato il metodo, IntelliSense visualizza anche il contenuto di parametro in ciò che viene chiamato una descrizione comandi della Guida in linea di parametro (vedere la Figura 6 ).

Nella figura 6 parametro Guida descrizione comandi mediante il commento XML

I membri nel Visualizzatore oggetti di esplorazione è un'esperienza molto migliorata con i commenti XML. Visualizzatore oggetti vengono visualizzati riepilogo, param, reso, note, typeparam e i commenti di eccezione quando sono presenti (vedere la Figura 7 ). Progettazione classi, visualizzazione classi e Banco di test inoltre utilizzare i commenti XML quando sono disponibili.

Nella figura 7 Visualizzatore oggetti utilizzando i commenti XML

Vantaggi dell'aggiunta di commenti nome else del codice

Versioni precedenti illustrato come personalizzare l'esperienza di Visual Studio per una funzione mediante l'aggiunta di commenti XML alla relativa definizione. Per i membri definiti in assembly a cui viene fatto riferimento, tuttavia, non è pratico seguire lo stesso processo quanto non è necessariamente accesso all'origine. Fortunatamente, è un altro processo (commenti riguardanti anche XML) che è possibile utilizzare per i membri a cui viene fatto riferimento.

C'è una differenza chiave. Per i membri nella soluzione corrente, le funzionalità di Visual Studio utilizzare in una rappresentazione in memoria dei commenti XML in base all'origine. In questo caso, il file di documentazione XML è puramente un output e anche non desidera essere generato per utilizzare le funzioni di Visual Studio. Invece, nel caso di assembly a cui viene fatto riferimento, i file di documentazione XML vengono letti come input e influenzano il comportamento nell'ambiente di codifica.

Vediamo un esempio. Verrà crea un nuovo progetto e fare riferimento all'assembly che HO creato precedente (RegLib.dll). File di documentazione XML generato (RegLib.xml) deve trovarsi accanto all'assembly e disponga lo stesso nome. È possibile accedere al metodo RegKeyExists dal progetto corrente, viene visualizzato in IntelliSense. Tuttavia, È possibile modificare l'aspetto.

È possibile aprire RegLib.xml comandi e modificare il contenuto di riepilogo "determina se la chiave del Registro di sistema esiste". Si verifica immediatamente l'aggiornamento e alla successiva che è possibile accedere al membro in IntelliSense, è possibile vedere il nuovo testo nella descrizione comandi (vedere la Nella figura 8 ).

Nella figura 8 descrizione comandi di IntelliSense

Suggerimenti di .NET Framework

.NET Framework è un altro esempio di assembly che si fa riferimento dal progetto. Si consideri Microsoft.VisualBasic.dll, compare cui file di documentazione XML:

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

Aprire il file XML ed esaminare i commenti XML. Esistono alcuni elementi XML interessanti in tale posizione. Ad esempio Filterpriority determina come un membro viene visualizzata IntelliSense di Visual Basic. Il valore 1 significa che dovrebbe apparire nella scheda Common, 2 indica che deve essere visualizzato nella scheda tutte e 3 indica che deve essere nascosta da IntelliSense completamente. Filterpriority questo membro è impostata su 1, quindi viene visualizzato in comuni. È possibile modificare facilmente il valore filterpriority a 2 e salvare il file XML in modo che il membro venga visualizzato nella scheda Tutto.

Si noti che, prima di modificare i file di documentazione XML di .NET Framework, è costituito buona norma creare una copia preventivamente. Sarà inoltre necessario aprire i file in un'applicazione che dispone di privilegi elevati. Visual Studio è un'opzione valida poiché conserva il formato di file.

È possibile utilizzare la metodologia descritta in questa sezione per influenzare i membri di un assembly a cui viene fatto riferimento, a condizione che il file di documentazione XML sarà possibile accedere o crearne uno se non esiste. Per influenzare filterpriority di un membro definito nell'assembly corrente, utilizzare l'attributo System.ComponentModel.EditorBrowsable.

Un altro elemento interessante è PermissionSet. Questo elemento specifica le condizioni il membro è accessibile. Il contenuto dell'elemento si intende il tipo di System.Security.Permissions.SecurityPermission.

Si inferiore il livello di autorizzazione corrente e verificare quale effetto produce l'accesso ai FileWidth. Creare una console o applicazioni Windows. Fare clic su programmi personali in Esplora soluzioni per aprire la finestra Progettazione progetti. Selezionare la scheda Protezione, quindi controllare "attiva le impostazioni di protezione ClickOnce" e "questa è un'applicazione parzialmente attendibile."

A questo punto autorizzazioni necessari non sono disponibili, in modo FileWidth e adiacenti membri diventano inattiva e non accessibile in IntelliSense. Questa funzionalità di Visual Basic è denominata IntelliSense in zona. La descrizione comando indica che per utilizzare il membro è necessario il tipo di autorizzazione.

È possibile aggiungere elementi PermissionSet a file di documentazione XML membro e specificare le autorizzazioni appropriate.

La generazione della documentazione Nicer

Il codice XML generato dal compilatore Visual Basic è leggibile, ma non il più semplice. Sono stati creati numerosi strumenti per creare documentazione aspetto nicer passare facilmente.

Viene chiamato lo strumento primo Sandcastle, sviluppato da Microsoft. Dopo aver installato Sandcastle, raccogliere gli assembly che si documentando, le relative dipendenze e i file di documentazione XML. Copiare tutti i materiali nella cartella di installazione vSandcastle (in genere c:\Programmi\Microsoft Files\Sandcastle\Examples\sandcastle.

Aprire un prompt dei comandi con privilegi elevati e spostarsi nella directory stessa, quindi eseguire il comando:

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

Verranno generati dall'operazione di directory e file. Aprire la directory chm e quindi aprire il file con estensione chm all'interno. Consigliabile simile la Guida nella Figura 9 .

Nella Figura 9 chm Sandcastle output

Lo strumento offre una serie di altri formati di output diverso. chm. Per ulteriori informazioni e annunci ulteriormente in Sandcastle, controllare il blog in blogs.msdn.com/Sandcastle.

NDoc è un altro strumento comune che è possibile utilizzare oppure è impossibile utilizzare le potenti funzionalità XML in Visual Basic 9 per scrivere il proprio strumento personalizzato.

I commenti XML in Visual Studio 2010

Ricerca in avanti, esistono nuove possibilità per il modo in cui è possibile interagire con i commenti XML nel codice. L'editor di Visual Studio 2010 viene riscritto utilizzando Windows Presentation Foundation (WPF) e consente di effetti grafici RTF. L'editor Aggiorna inoltre coinvolti spostare in un nuovo sistema componente il gestito extensibility Framework (MEF), che rende molto più semplice registrare il componente aggiuntivo con Visual Studio. Nella figura 10 viene illustrato un esempio di un visualizzatore di commento XML è stato creato in primo piano nuovo editor e del modello di componenti.

Nella figura 10 Visualizzatore di commento XML in Visual Studio 2010

Facendo clic sul pulsante di opzioni di angolo superiore destro la visualizzazione tra il controllo WPF e il codice XML originale. Il controllo WPF fornisce certamente una quantità visualizzazione più chiara. Inoltre sfrutta funzionalità WPF, ad esempio sfumature e bordi arrotondamento. WPF rende possibile includere immagini o video, troppo. Sarà sicuramente un'area formattata per terze parti i componenti aggiuntivi sfruttare nella versione di Visual Studio 2010.

Inviare domande e commenti instinct@Microsoft.com.

Lisa Feigenbaum è il Program Manager Microsoft per la community di Visual Basic. Un membro del team Visual Basic ha trascorso dall'2004. Prima il ruolo corrente, Davide è Program Manager per l'editor di Visual Basic e debugger, lavorando funzionalità quali IntelliSense, Modifica e -continua e frammenti di codice. È possibile trovare Lisa in diversi stati uniti e conferenze internazionale e gruppi utenti, guardare il webcast di Channel 9 o leggere il post nel blog di team VB in https://blogs.msdn.com/vbteam.