Alessandro Del Sole's Blog

{ A programming space about Microsoft® .NET® }
posts - 1908, comments - 2047, trackbacks - 352

My Links

News

Your host

This is me! Questo spazio è dedicato a Microsoft® .NET®, di cui sono molto appassionato :-)

Cookie e Privacy

Disabilita cookie ShinyStat

Microsoft MVP

My MVP Profile

Microsoft Certified Professional

Microsoft Specialist

Xamarin Certified Mobile Developer

Il mio libro su VB 2015!

Pre-ordina il mio libro su VB 2015 Pre-ordina il mio libro "Visual Basic 2015 Unleashed". Clicca sulla copertina per informazioni!

Il mio libro su WPF 4.5.1!

Clicca sulla copertina per informazioni! E' uscito il mio libro "Programmare con WPF 4.5.1". Clicca sulla copertina per informazioni!

These postings are provided 'AS IS' for entertainment purposes only with absolutely no warranty expressed or implied and confer no rights.
If you're not an Italian user, please visit my English blog

Le vostre visite

I'm a VB!

Guarda la mia intervista a Seattle

Follow me on Twitter!

Altri spazi

GitHub
I miei progetti open-source su GitHub

Article Categories

Archives

Post Categories

Image Galleries

Privacy Policy

Leggi il capitolo 8 di esempio

8. Documentare i propri sorgenti

In questo capitolo impareremo a utilizzare i commenti XML nei programmi Visual Basic e a generare la guida specifica per il codice sorgente.

Sicuramente la maggior parte di voi, utilizzando Visual Studio 2005, avrà avuto la necessità di consultare la documentazione MSDN, per cercare informazioni su un determinato oggetto, su un determinato strumento o su un determinato frammento di codice.

Quando consultate la documentazione MSDN per Visual Studio, relativamente agli oggetti o ai loro membri, ogni pagina della guida mostra delle informazioni sul membro richiesto, secondo una particolare formattazione grafica. Inoltre, vengono mostrati il nome dell’oggetto, la sua descrizione, la sintassi per l’utilizzo a seconda del linguaggio utilizzato e collegamenti ad altri documenti correlati a quello in esame.

Soprattutto se sviluppate librerie di classi, potrebbe essere utile documentare le vostre classi nello stesso modo in cui sono documentate le librerie di classi del .NET Framework, automatizzando la procedura. Così non dovrete scrivere manualmente la documentazione di ogni singolo oggetto o membro di oggetto, ma potrete utilizzare strumenti in grado di effettuare il parsing del codice e generare una documentazione che abbia al tempo stesso la medesima formattazione grafica utilizzata per la libreria MSDN e le descrizioni del proprio codice.

In questo capitolo vedremo come utilizzare una nuova caratteristica del linguaggio Visual Basic: i commenti XML, che consentono di documentare il codice sorgente. Successivamente, vedremo come utilizzare un’applicazione di help authoring gratuita fornita da Microsoft, chiamata SandCastle, in grado di generare file della guida compilati sia in formato .chm (Help 1.x) sia in formato .HxS (Help 2.5) a partire dalla documentazione XML fornita a supporto del vostro codice sorgente. Ricorderete facilmente che la documentazione in formato .chm è stata trattata nel Capitolo 6, mentre la documentazione in formato .HxS è stata analizzata nel Capitolo 7.

L'utilizzo delle tecniche illustrate in questo capitolo si applica, in linea di massima, anche a Visual Studio Standard e Visual Basic Express, con l'unica eccezione illustrata nel paragrafo intitolato Generare la documentazione: Microsoft SandCastle.

Utilizzare i commenti XML

Valido anche per Visual Basic Express Edition.

Tra le molte novità introdotte con Visual Basic 2005, sia con riferimento all’IDE sia con riferimento al codice, una di particolare interesse riguarda la possibilità di utilizzare in modo nativo i commenti al codice in formato XML, a differenza di quanto avveniva nelle versioni precedenti dove l’aggiunta di commenti XML al proprio codice era possibile solo grazie all’installazione di componenti aggiuntivi esterni.

Perché i commenti XML?

A differenza dei normali commenti che eravate abituati a inserire all’interno del codice per renderlo più leggibile, i commenti in formato XML offrono alcune possibilità in più, poiché sono stati progettati per costituire la documentazione del codice, soprattutto quando create e distribuite librerie di classi.

Considerate, come esempio, proprio le librerie di classi che espongono classi, metodi o quant’altro. L’utilizzo di commenti XML a corredo di tali membri vi permetterà di visualizzare delle tooltip contenenti la descrizione del membro stesso, quando questo viene richiamato tramite l’Intellisense di Visual Studio, proprio come già avviene per i membri della libreria di classi base del .NET Framework.

Inoltre, potrete specificare al compilatore di Visual Basic di generare un file XML esterno, contenente tutta la documentazione relativa all’assembly, al fine di elaborarla tramite applicazioni di help authoring (come Microsoft SandCastle, trattata più avanti nel capitolo) e renderla così visualizzabile in un browser o in applicazioni come Microsoft Document Explorer.

La tecnologia Intellisense, infatti, permette di visualizzare informazioni essenziali circa l’utilizzo di un membro. La generazione di un file XML esterno permette, al contrario, di specificare commenti XML molto più dettagliati e di creare una vera e propria documentazione relativa al proprio assembly, che può essere richiamata e visualizzata in altri assembly come si vedrà meglio più avanti. All’utilizzo dei commenti XML è data importanza anche nelle linee guida per la scrittura del codice, che esamineremo nel Capitolo 10.

Per capire meglio l’utilità e l’importanza di questo tipo di commenti creeremo un progetto esempio, che sarà poi analizzato nel dettaglio.

Il primo commento XML

L’inserimento di un commento XML è molto semplice: è sufficiente posizionare il cursore sul primo rigo vuoto precedente alla dichiarazione del membro che desiderate commentare, per poi digitare tre volte il carattere di apostrofo.

Considerate la Figura 8.1 e il codice rappresentato.

Figura 8.1 - L'inserimento di un commento XML nel codice.

Il metodo ExtractFilename creato è semplicissimo, ma il codice non ha alcuna importanza: focalizzate l’attenzione per capire l’utilità dei commenti XML.

Come potete osservare, per l’inserimento di un commento XML dovete posizionarvi sul rigo precedente la definizione del metodo (o altro membro) e digitare i tre apostrofi. L’IDE inserisce automaticamente un blocco XML che descrive il contenuto del codice.

Inoltre, potete definire un commento XML come un insieme di alcuni tag, scritti nella sintassi <nometag> </nometag> tipica del linguaggio XML.

Osservate ora cosa accade se dall’editor del codice viene richiamato il metodo appena definito. L’Intellisense di Visual Studio, oltre a visualizzare il codice completo del metodo, mostrerà una tooltip in cui compare la descrizione specificata nel tag <summary> </summary> (Figura 8.2).

Figura 8.2 - L'Intellisense mostra la descrizione del metodo fornita tramite commenti XML.

Questa funzionalità è senza dubbio molto utile, soprattutto se sviluppate componenti piuttosto che applicazioni complete. Infatti, l’utente finale non dovrà ricordare a memoria cosa fa un determinato metodo o una certa proprietà, poiché l’Intellisense ne visualizzerà la definizione e la descrizione, da voi specificate a mezzo dei commenti XML.

Se sviluppate per hobby o per l’utilizzo del PC a casa, tutto ciò può ugualmente tornare utile. Ponendo il caso che abbiate realizzato un namespace contenente due classi, e che entrambe le classi implementino un metodo con lo stesso nome, la tooltip visualizzata nell’Intellisense vi aiuterà a non fare confusione.

Definire commenti XML complessi

L’esempio appena visto rappresenta, in effetti, un utilizzo minimo di tag in un commento XML, ma questi commenti possono essere in realtà molto più dettagliati e completi, grazie a un ricco set di tag appositamente definiti.

Alcuni di questi tag permettono, per esempio, di creare intere tabelle, di indicare che il testo digitato dev’essere identificato come codice e molto altro, e trovano il loro naturale utilizzo solo quando si decide di generare un file di documentazione XML esterno, in particolare quando si desidera che la documentazione XML del proprio assembly sia richiamata da altre applicazioni.

Prima di vedere qualche esempio di commenti XML più completi, osservate la Tabella 8.1, in cui vengono riassunti i principali tag che compongono un commento XML, con le relative descrizioni.

Nome elemento Descrizione
summary Descrive il contenuto del codice sorgente che segue e costituisce la “documentazione” del membro commentato
param name Indica un parametro richiesto dal metodo commentato. In un commento XML ci sono tanti elementi param name quanti parametri sono richiesti dal metodo
returns Descrive il valore restituito da una funzione
remarks Note aggiuntive
c Questo tag consente di inserire al suo interno del testo che deve essere riconosciuto e visualizzato come codice
code Permette di contrassegnare come codice il testo inserito al suo interno. Il codice può essere disposto su più righe
example Deve essere utilizzato congiuntamente al tag code e permette di specificare un esempio relativo a un’altra funzione presente nell’assembly
exception Consente di specificare un’eccezione (disponibile nell’ambito in cui si sviluppa) sollevata dal codice descritto. Si utilizza con l’attributo cref
include Permette di richiamare un file XML esterno contenente la documentazione e di farvi riferimento tramite i tag obbligatori: file (indica il nome del file XML), path (indica il percorso del file), ID (identificatore del tag da richiamare), name (identificatore del nome del tag da richiamare)
list

Permette di creare una tabella. La struttura è la seguente:

<list type="tipo">

<listheader>

<term>termine</term>

<description>descrizione</description>

</listheader>

<item>

<term>termine</term>

<description>descrizione</description>

</item>

</list>

Dove: type indica il tipo di elenco (bullet = puntato, number = numerato, table = tabella), term indica un termine da definire (solo se type = table), description indica un elemento dell’elenco (solo se type = bullet o number)

param Permette di aggiungere una struttura al testo del commento e va utilizzato nei tag summary, remarks, returns
paramref Indica che una data parola corrisponde a uno dei parametri del metodo cui il commento XML si riferisce
permission Unitamente all’attributo cref permette di specificare le modalità di accesso a un determinato membro
see Permette di specificare nel testo un collegamento ad altra documentazione
seealso Consente di specificare che il testo debba essere incluso in una sezione di tipo Vedere anche
typeparam Unitamente all’attributo name, consente di definire che un parametro è di un determinato tipo
value Si utilizza per commentare le proprietà Property..End Property, descrivendone il valore

Tabella 8.1 - Descrizione degli elementi utilizzabili nei commenti XML.

Come si è detto, la maggior parte dei tag elencati ha senso se generate un file XML esterno per documentare il vostro codice sorgente. Questo perché potreste voler creare documentazione dall’aspetto professionale tramite appositi programmi di help authoring (come vedremo tra breve), con colorazione diversa per il codice rispetto al testo normale, tabelle, sezioni Vedere anche e molto altro.

L’Intellisense di Visual Studio, infatti, si limita a visualizzare una tooltip con pochi elementi, come per esempio il contenuto dei tag <summary>, <returns>, <example>, nonostante riconosca e accetti tutti i tag visti nella tabella.

Per avvisare il compilatore che volete generare un file XML esterno contenente la documentazione dei sorgenti ci sono due possibilità:

· utilizzare l’opzione /doc del compilatore a riga di comando di Visual Basic;

· aprire la finestra delle proprietà del progetto. Potete attivare tale finestra facendo doppio clic sull’elemento My Project nella finestra Esplora soluzioni o con il comando Proprietà progetto del menu Progetto. Una volta aperta la finestra sarà sufficiente fare clic sulla casella Genera documentazione XML (non si applica a Visual Basic Express Edition, che crea il file XML per default).

Dopo questa breve parentesi possiamo tornare ad affrontare il discorso sull’ inserimento dei tag XML nei commenti. Sarà ancora l’inesauribile Intellisense a suggerire quali tag potete inserire in una determinata posizione del commento non appena premete il tasto < di inizio tag (Figura 8.3).

Figura 8.3 - L'Intellisense di Visual Studio mostra quali elementi potete inserire nei commenti XML.

A questo punto possiamo passare alla pratica, analizzando come utilizzare i commenti XML in una libreria di classi creata per l’occasione.

Una libreria di classi di esempio

Valido anche per Visual Basic Express Edition.

Sorgente di esempio: Capitolo 8\MyXmlComments.

Create una nuova libreria di classi, con il consueto comando Nuovo progetto del menu File.

La libreria di classi sarà piuttosto semplice. Si occuperà di creare una lista di impiegati aziendali.

Pertanto implementeremo:

1. una struttura che contiene i dati di un impiegato, come il cognome, il nome, l’età e il ruolo occupato;

2. una collection per memorizzare l’elenco degli impiegati;

3. una proprietà che restituisce il numero degli impiegati;

4. un metodo per l’aggiunta di un nuovo impiegato alla collection.

A ogni membro della classe aggiungeremo dei commenti XML dettagliati.

Per comodità osserveremo le singole porzioni di codice con i relativi commenti che verranno poi analizzati. Questo è il codice relativo alla struttura Impiegato:

Public Class Class1

''' <summary>

''' Contiene le informazioni relative ad un singolo impiegato

''' Viene istanziata nella sub <c>NuovoImpiegato</c>

''' Contiene 4 elementi:

''' <list type="bullet">

''' <item>Cognome, di tipo <c>String</c></item>

''' <item>Nome, di tipo <c>String</c></item>

''' <item>Età, di tipo <c>Short</c></item>

''' <item>Ruolo, di tipo <c>String</c></item>

''' </list>

''' </summary>

''' <remarks></remarks>

Public Structure Impiegato

Public Cognome As String

Public Nome As String

Public Età As Short

Public Ruolo As String

End Structure

La struttura Impiegato è dichiarata pubblica, in quanto avrà visibilità all’esterno dell’assembly. Contiene quattro membri pubblici, di cui tre sono stringhe (Cognome, Nome, Ruolo) e uno di tipo Short (Età).

Il tag <summary> contiene una breve descrizione della struttura. Al suo interno il tag <c> permette di specificare che NuovoImpiegato deve essere visualizzato come codice.

Il tag <list> crea un elenco puntato (type = “Bullet”) dei quattro membri (tag <item>) appartenenti alla struttura.

Vengono poi dichiarati gli oggetti che occorrono: un oggetto generico MieiImpiegati che conterrà l’elenco degli impiegati e un oggetto Persona che rappresenta un singolo impiegato a cui assegnare i valori succitati.

''' <remarks><seealso cref="Persona"/></remarks>

Public Shared MieiImpiegati As New List(Of Impiegato)

''' <summary>

''' Vedere quanto descritto per la struttura<see cref="Impiegato"/>

''' </summary>

Public Shared Persona As Impiegato

Relativamente all’oggetto MieiImpiegati abbiamo definito un commento XML inserendo un tag <remarks> per specificare delle note sull’utilizzo dell’oggetto stesso. Il tag <seealso>, unitamente all’attributo cref seguito dal segno di = e dal nome dell’oggetto, definisce una sezione Vedere anche, ossia comunica all’utente che è opportuno leggere anche la descrizione relativa all’oggetto Persona. Ciò implica che l’oggetto cui si fa riferimento tramite l’attributo cref debba essere stato dichiarato e commentato nella classe.

Il commento all’oggetto Persona, invece, all’interno del tag <summary> riporta anche un tag <see>. Questo tag, unitamente all’attributo cref seguito dal segno di = e dal nome dell’oggetto, comunica all’utente che per ricevere informazioni sull’oggetto Persona si deve fare riferimento alla documentazione dell’oggetto Impiegato.

Come accennato in precedenza, la libreria di classi deve implementare una proprietà chiamata Counter che tenga il conto degli impiegati. La definiamo come segue:

''' <summary>

''' Restituisce il totale degli oggetti di tipo Impiegato

''' </summary>

''' <value>Totale degli oggetti di tipo Impiegato</value>

''' <returns>Short</returns>

Public Shared ReadOnly Property Counter() As Short

Get

   Return MieiImpiegati.Count

End Get

End Property

La proprietà è di sola lettura, dal momento che non dev’essere modificabile dall’utente.

L’oggetto MieiImpiegati implementa una proprietà Count che contiene il totale degli elementi in esso contenuti.

L’istruzione Return comunica così all’utente il numero totale degli impiegati finora aggiunti.

Con riferimento ai commenti XML osserviamo quanto segue:

1. il tag <summary> fornisce una descrizione sulle funzionalità della proprietà;

2. il tag <value> viene utilizzato per la prima volta nel progetto, in quanto è possibile specificarlo solo per descrivere il valore restituito da proprietà di tipo Property..End Property. Come potete vedere osservando il codice, questo tag comunica all’utente che la proprietà restituisce il totale degli oggetti di tipo Impiegato;

3. il tag <returns>, da ultimo, specifica il tipo di dato restituito dalla proprietà.

Ci occuperemo ora di definire un metodo chiamato NuovoImpiegato che aggiunga un nuovo impiegato all’elenco. Ecco il codice:

''' <summary>

''' Aggiunge un nuovo impiegato alla collection

''' <example>

''' Istanziare così la struttura <c>Impiegato</c>:

''' <code>

''' Persona = New Impiegato

''' </code>

''' </example>

''' </summary>

''' <exception cref="ArgumentException">

''' Sollevata quando <paramref name="Età"/> non è un intero

''' </exception>

''' <param name="Cognome"></param>

''' <param name="Nome"></param>

''' <param name="Età"></param>

''' <param name="Ruolo"></param>

''' <remarks>

''' Passare alla sub i 4 parametri corrispondenti ai membri della struttura <c>Impiegato</c>

'''</remarks>

Public Shared Sub NuovoImpiegato(ByVal Cognome As String, ByVal Nome As String, ByVal Età As Short, ByVal Ruolo As String)

   Persona = New Impiegato

   With Persona

         .Cognome = Cognome

        .Nome = Nome

        .Età = Età

        .Ruolo = Ruolo

   End With

   MieiImpiegati.Add(Persona)

   Persona = Nothing

End Sub

End Class

Il codice relativo al metodo è decisamente semplice. La Sub NuovoImpiegato necessita di quattro parametri: Cognome, Nome, Ruolo di tipo stringa ed Età di tipo Short.

Il corpo del metodo è così realizzato:

1. si istanzia un nuovo oggetto Persona di tipo Impiegato;

2. il blocco With..End With assegna a ogni membro della struttura Persona il corrispondente argomento passato al metodo;

3. l’oggetto Persona creato poco prima rappresenta un singolo impiegato. Quest’ultimo viene aggiunto all’oggetto MieiImpiegati tramite il metodo Add;

4. viene eliminato il contenuto dell’oggetto Persona per liberare risorse non più utilizzate, dal momento che ormai l’impiegato è stato aggiunto all’elenco.

L’utilizzo dell’istruzione Shared permetterà di richiamare il metodo e gli elementi a esso correlati senza dover creare un’istanza della classe.

Alcune considerazioni circa i commenti XML:

· come è ormai noto il tag <summary> contiene una descrizione delle funzionalità del metodo creato;

· all’interno del tag <summary> è stato inserito un tag <example>, correlato a un tag <code>. Essi, insieme, mostrano all’utente un esempio di come utilizzare il codice. Questo esempio viene visualizzato anche dall’Intellisense di Visual Studio quando si richiama il metodo;

· il tag <c> nella prima riga dell’esempio consente di contrassegnare come codice il testo Impiegato;

· il tag <exception> seguito dall’attributo cref comunica all’utente che può verificarsi un’eccezione di tipo ArgumentException qualora il parametro Età non sia un intero; è grazie al tag <paramref>, seguito dall’attributo name, che si fa riferimento al parametro desiderato;

· i quattro tag <param>, seguiti dall’attributo name, elencano tutti gli argomenti di cui necessita il metodo;

· il tag <remarks> fornisce note aggiuntive sull’uso del metodo, contrassegnando come codice, tramite il tag <c> nidificato, il testo Impiegato.

Come potete vedere, l’utilizzo di commenti XML permette di documentare in maniera efficiente e organizzata il codice sorgente. Per renderci conto nel dettaglio del perché del lavoro svolto, creeremo una piccola applicazione Windows Forms che utilizza la libreria di classi appena creata e ci soffermeremo su alcuni peculiari aspetti, in particolare cosa viene mostrato dall’Intellisense di Visual Studio.

Dal menu File selezionate il comando Aggiungi|Nuovo progetto, al fine di aggiungere una nuova applicazione alla soluzione. Selezionate l’icona relativa alle applicazioni per Windows e assegnate al nuovo progetto il nome XmlCommentsDemo. Facendo clic su OK, il nuovo progetto viene aggiunto alla soluzione.

Questo semplice progetto dimostrativo aggiungerà due nuovi impiegati alla lista, mostrerà il totale degli impiegati e infine mostrerà il nome e il cognome di ogni impiegato.

La prima operazione da compiere è aggiungere un riferimento alla libreria di classi. Pertanto dovete aprire la finestra delle proprietà del progetto, facendo clic su My Project in Esplora soluzioni, oppure tramite il comando Proprietà progetto del menu Progetto.

A questo punto selezionate la scheda Riferimenti, quindi fate clic sul pulsante Aggiungi. Apparirà così la finestra Aggiungi riferimento. Poiché la libreria di classi che occorre è un progetto della medesima soluzione, dovete spostarvi nella scheda Progetti e selezionare il progetto MyXmlComments.

Fate clic su OK, per assegnare il riferimento al progetto e tornare all’editing.

Dalla finestra Esplora soluzioni fate clic su Form1 per passare alla visualizzazione del codice, tramite l’apposito pulsante presente sempre in Esplora soluzioni. Inserite il seguente codice:

Imports MyXmlComments.Class1

Public Class Form1

Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load

     NuovoImpiegato("Del Sole", "Alessandro", 29, "Contabile")

     NuovoImpiegato("Verdi", "Mario", 42, "Generico")

     MsgBox("Totale nuovi impiegati: " & MyXmlComments.Class1.Counter.ToString)

     For i As Short = 0 To MyXmlComments.Class1.Counter - 1

         MsgBox("Nome: " & MyXmlComments.Class1.MieiImpiegati.Item(i).Nome & ", Cognome: " & _ MyXmlComments.Class1.MieiImpiegati.Item(i).Cognome)

     Next

End Sub

End Class

La direttiva Imports permette di abbreviare il codice per richiamare il metodo NuovoImpiegato.

Nell’evento Load della classe Form1 vengono aggiunti due impiegati alla lista mediante il metodo NuovoImpiegato, appartenente alla libreria di classi che abbiamo creato in precedenza e referenziato nel progetto.

Successivamente viene mostrato il totale degli impiegati utilizzando la proprietà Counter (notate la conversione in stringa tramite il metodo .ToString).

Infine, grazie a un ciclo For..Next, vengono mostrati il nome e il cognome di ciascun impiegato presente nella lista, richiamando i singoli elementi (item) dell’oggetto MieiImpiegati. Per ognuno di questi elementi abbiamo scelto di recuperare il nome e il cognome, ma voi potrete anche decidere di richiamare l’età e il ruolo occupato, ovviamente.

L’applicazione è così completata e pronta per l’esecuzione. In questa sede, però, il nostro scopo principale è quello di analizzare cosa succede mentre viene inserito il codice, sulla base dei commenti XML che sono stati specificati precedentemente nella libreria di classi.

La Figura 8.4 mostra cosa accade mentre richiamate il metodo NuovoImpiegato.

Figura 8.4 - L'intervento dell'Intellisense quando viene richiamato il metodo NuovoImpiegato.

L’Intellisense visualizza le indicazioni descritte nei commenti XML: in particolare, la descrizione sulle funzionalità del metodo (fornita dal tag <summary>) e l’esempio relativo alla creazione di una nuova istanza dell’oggetto Persona (dato dall’unione dei tag <example> e <code>).

Ora potete capire perché in precedenza abbiamo affermato che l’utilizzo di alcuni tag ha senso solo quando desiderate generare documentazione XML in un file esterno. L’Intellisense, infatti, mostra il contenuto solo di alcuni dei tag che sono stati elencati. Ciò è comunque utile per descrivere quanto più possibile le modalità di utilizzo dei metodi e, più in generale, dei membri di una classe.

Per esempio, utilizzando la proprietà Counter della libreria di classi l'Intellisense ne mostra la descrizione (Figura 8.5).

Figura 8.5 - L'intervento dell'Intellisense quando utilizzate la proprietà Counter.

In ultima analisi, osservate quanto viene visualizzato nell’Intellisense in relazione all’oggetto MieiImpiegati (Figura 8.6).

In effetti non compare alcuna descrizione aggiuntiva rispetto alla dichiarazione dell’oggetto. Se riguardate il codice relativo ai commenti XML utilizzati per l’oggetto MieiImpiegati, vi sarà facile constatare che è stata specificata solo una sezione Vedere anche, tramite un tag <seealso> che però non viene mostrato nell’Intellisense, poiché è logicamente utile solo qualora si generi un file XML esterno.

Figura 8.6 - L'intervento dell'Intellisense quando viene utilizzato l'oggetto MieiImpiegati.

Salvate il progetto ed eseguitelo, premendo F5. Una Messagebox informerà dell’aggiunta di due nuovi impiegati. Chiudete l’applicazione e poi Visual Studio.

In questa sezione avete così imparato a conoscere i commenti XML, a utilizzarli e soprattutto avete capito perché sono così utili e importanti rispetto ai commenti normali, che per anni sono stati utilizzati nelle versioni precedenti di Visual Basic.

Le sezioni successive mostreranno come conseguire in pratica un altro degli scopi dei commenti XML: la creazione di documentazione compilata per i vostri file sorgenti, tramite un’apposita applicazione gratuita di help authoring quale Microsoft SandCastle.

Generare la documentazione: Microsoft SandCastle

Microsoft SandCastle è un’applicazione gratuita di help authoring, in grado di generare file della guida compilati sia in formato .chm sia in formato .HxS, a partire dalla documentazione XML generata dal compilatore Visual Basic.

SandCastle è stato progettato per .NET 2.0 e si propone come strumento di creazione di documentazione per librerie di classi gestite. È utilizzato dalla stessa Microsoft per documentare i propri sorgenti.

SandCastle è uno strumento utilizzabile esclusivamente dalla riga di comando e può essere scaricato da Internet sia come parte del Visual Studio 2005 SDK (per il quale potete consultare il Capitolo 3) sia singolarmente, all’indirizzo:

http://www.microsoft.com/downloads/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

Al momento della stesura di questo libro l’ultima release disponibile è la December 2006 Community Technology Preview. Ovviamente, qualora abbiate precedentemente installato Visual Studio 2005 SDK, non serve scaricare e installare separatamente SandCastle. Potete utilizzare SandCastle anche se avete solo Visual Basic Express. Sarete però limitati alla sola creazione di file dell'Help 1.x in formato .chm, mentre non sarete in grado di generare documentazione in formato Help 2.5 (file .HxS) poiché non potrete installare il relativo compilatore, incluso nel Visual Studio 2005 SDK e installabile separatamente con Visual Studio Standard.

Utilizzo di SandCastle

Microsoft SandCastle è uno strumento di indubbia utilità, ma ha un difetto: non è dotato di interfaccia grafica ed è utilizzabile solo dalla riga di comando; inoltre, la sintassi per l’utilizzo dalla riga di comando è complessa, sia da comprendere sia da utilizzare.

Fortunatamente in internet è possibile reperire alcune interfacce grafiche per SandCastle, gratuite ed estremamente funzionali. Nel corso dei successivi paragrafi, pertanto, impareremo a generare la documentazione per i nostri sorgenti utilizzando un’interfaccia grafica chiamata SandCastle HelpFile Builder, evitando di utilizzare le operazioni di generazione dalla riga di comando che, come detto, sono estremamente complesse e possono portare confusione. Uno strumento grafico consente invece, con pochi clic del mouse, di ottenere il risultato desiderato in maniera più proficua e precisa.

Installazione e localizzazione di SandCastle

Microsoft SandCastle può essere scaricato all’indirizzo internet segnalato in precedenza o come parte integrante del Visual Studio 2005 SDK (solo a partire dalla versione 4.0). Qualora venga installato Visual Studio 2005 SDK, SandCastle si trova nella directory C:\Programmi\Visual Studio 2005 SDK\anno.mese\VisualStudioIntegration\Tools\Sandcastle, dove mese.anno indicano il periodo di rilascio del Visual Studio 2005 SDK; qualora sia stato installato separatamente, viene normalmente installato in C:\Programmi\SandCastle.

È importante ricordare che SandCastle è sì in grado di generare documentazione in formato compilato .chm o .HxS, ma non è un compilatore. Esso utilizza i compilatori Microsoft per generare la documentazione; pertanto, per utilizzare SandCastle è necessario avere installato Microsoft HTML Help Workshop (per quanto riguarda la guida compilata in formato .chm) e il Visual Studio 2005 SDK (che contiene il compilatore per la guida in formato .HxS).

Cenni sull’utilizzo dalla riga di comando

Allo stato attuale, SandCastle viene distribuito come strumento utilizzabile dalla riga di comando, anche se per le versioni future sono previste interfacce grafiche integrate.

Due sono i file da eseguire per generare la documentazione, MRefBuilder.exe e BuildAssembler.exe. L’utilizzo di questi strumenti non è affatto semplice e immediato, pertanto in questo libro non tratteremo l’uso di SandCastle tramite riga di comando, bensì solo tramite un’interfaccia grafica esterna, come vedremo a breve. Per maggiori informazioni su come utilizzare SandCastle in questa modalità potete visitare il Blog dedicato, all’indirizzo:

https://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx

Utilizzo di un’interfaccia grafica per SandCastle: SandCastle HelpFile Builder

SandCastle HelpFile Builder è un’interfaccia grafica gratuita, progettata per utilizzare le funzionalità di Microsoft SandCastle tramite un’applicazione Windows Forms, in modo da semplificare la creazione di documentazione compilata tramite l’uso del mouse, di pulsanti e di quant’altro possa rendere semplice e intuitivo l’utilizzo di SandCastle, senza dover ricorrere alla riga di comando.

In internet è possibile trovare diverse interfacce grafiche gratuite per SandCastle. Qui utilizzeremo SandCastle HelpFile Builder, poiché il relativo progetto è ospitato su CodePlex (http://www.codeplex.com), il sito di Microsoft dedicato ai progetti open source.

SandCastle HelpFile Builder è stato realizzato da Eric WoodRuff, del quale è possibile visitare il sito internet personale all’indirizzo: http://www.EWoodruff.us.

Come abbiamo detto, SandCastle HelpFile Builder è gratuito e ospitato su CodePlex. L’indirizzo esatto per scaricarlo è il seguente: http://www.codeplex.com/SHFB. Trattandosi di un progetto open source potete scaricare anche il codice sorgente, disponibile in linguaggio Visual C#. Una volta installato, potete eseguire SandCastle HelpFile Builder (Figura 8.7) tramite l’apposito collegamento creato nel menu Start|Programmi.

Figura 8.7 - La schermata di avvio di SandCastle HelpFile Builder.

Utilizzare SandCastle HelpFile Builder è piuttosto semplice. È sufficiente specificare l’assembly da documentare (e il relativo file XML generato dal compilatore), impostare le principali proprietà nella finestra delle proprietà del progetto sottostante e infine avviare la generazione. Nel prossimo paragrafo vedremo in dettaglio come utilizzare con semplicità questo strumento.

Generazione di un file della guida di esempio

Sorgente di esempio: Capitolo 8\Progetto SandCastle.

Il primo passo da seguire per documentare un assembly è quello di creare un nuovo progetto. SandCastle HelpFile Builder è in grado di creare tre tipologie di progetti:

· nuovo progetto vuoto;

· nuovo progetto basato su una soluzione di Visual Studio;

· nuovo progetto basato su un progetto di Ndoc.

Creare un progetto importando una soluzione di Visual Studio può esservi utile se non avete a disposizione l’assembly compilato, anche se questa è una possibilità piuttosto remota.

Vedremo ora come creare un progetto per documentare la libreria di classi di esempio creata nelle sezioni dedicate all’aggiunta di commenti XML al codice, ossia il progetto MyXmlComments.

In primo luogo è necessario comunicare a SandCastle HelpFile Builder l’assembly da documentare, tramite il pulsante Add. Nella finestra di dialogo, selezionate dapprima la cartella contenente la libreria MyXmlComments.dll, quindi selezionate questo file e fate clic su OK. Come potete notare, nella casella contenente l’assembly da documentare viene aggiunto automaticamente anche il file della documentazione XML.

Il passaggio successivo è quello di impostare le principali proprietà del progetto, che influenzeranno il contenuto del file della guida compilato. Tenete presente che SandCastle HelpFile Builder consente di impostare moltissime proprietà, molte delle quali possono essere lasciate invariate. In questo libro tratteremo le proprietà più importanti, mentre per le altre potete consultare la documentazione dell’applicazione. In ogni caso, selezionando col mouse ogni singola proprietà, ne verrà mostrata una breve descrizione nell’area inferiore dell’applicazione.

Per prima cosa bisogna impostare la proprietà HelpFileFormat, che consente di stabilire il tipo di output (Help 1.x, Help 2.5, pagine HTML per siti web). Ipotizzate di voler generare un file .chm, pertanto selezionate il valore HtmlHelp1x.

Quindi, nel campo relativo alla proprietà CopyrightText, digitate il testo Alessandro Del Sole, tutti i diritti riservati (potete sostituire ovviamente il mio nome con il vostro). Tale proprietà specifica del testo che verrà visualizzato a piè di pagina nelle note di copyright. Potete anche specificare un sito internet per le indicazioni sul copyright, utilizzando la proprietà CopyrightHRef.

Successivamente, nel campo della proprietà FeedbackEMailAddress digitate il vostro indirizzo di posta elettronica, che verrà visualizzato a piè di pagina unitamente alle note sul copyright.

Digitate il testo Documentazione per la libreria MyXmlComments nel campo della proprietà HelpTitle, che consente di specificare un titolo per la documentazione. Nel campo relativo alla proprietà HtmlHelpName digitate MyXmlComments. Questa proprietà permette di specificare il nome del file di output e non deve contenere né l’estensione né il percorso.

Nella casella combinata relativa alla proprietà Language selezionate la lingua italiana, mentre, tramite la casella combinata relativa alla proprietà PresentationStyle, selezionate lo stile VS2005. Questa proprietà, come si può intuire, permette di selezionare il layout grafico che dovrà assumere il file compilato.

Infine, nella casella combinata di cui alla proprietà SyntaxFilters, selezionate Visual Basic.

Il gruppo di proprietà denominato Paths raggruppa le proprietà relative ai percorsi dei compilatori, di SandCastle e dell’output del progetto. Non è necessario specificare il percorso dei compilatori e di SandCastle a meno che non sia l’applicazione a richiederlo. Per quanto riguarda l’output del progetto, potete liberamente decidere di selezionare un percorso diverso da quello proposto. In questo esempio lasciate inalterato il percorso prestabilito.

L’ultima impostazione avviene selezionando il pulsante Namespaces, posto in alto a destra. Ciò consente di specificare una descrizione per ogni namespace all’interno dell’assembly. Quando si fa clic su tale pulsante, viene mostrata una finestra di dialogo che elenca tutti i namespace appartenenti all’assembly e ai quali è possibile assegnare una descrizione. Fate clic sul namespace MyXmlComments in modo da selezionare la relativa casella di controllo e, nella casella di testo sottostante, digitate il testo Contiene classi e membri per la gestione di impiegati aziendali. Tale descrizione apparirà nella guida compilata.

Infine, per avviare la generazione della documentazione è sufficiente utilizzare il comando Build Project del menu Documentation. Tenete presente che il processo di generazione della documentazione può essere molto lungo, quindi non vi preoccupate se occorrono diversi minuti prima che lo stesso sia concluso. Durante la generazione, SandCastle HelpFileBuilder mostra i log delle operazioni nell’area inferiore dell’applicazione.

Un suggerimento: se all’avvio della generazione viene visualizzato un errore del tipo BUILD FAILED: Riferimento non impostato su un’istanza di un oggetto, è necessario impostare manualmente il percorso di SandCastle. Se questo non risolve il problema, provate a scaricare una versione più recente di SandCastle.

In generale, quando si verificano errori utilizzando SandCastle HelpFile Builder e si utilizza il run-time di SandCastle fornito con Visual Studio 2005 SDK, è possibile che l’interfaccia grafica e il run-time stesso non siano compatibili. Il problema si risolve, normalmente, scaricando e installando SandCastle nell’edizione separata dall’SDK, ricordando di specificare il nuovo percorso relativo agli eseguibili di SandCastle stesso.

Al termine della generazione, potrete visualizzare il file della guida compilato e osservare come il codice sorgente sia stato documentato secondo il classico stile della documentazione di Microsoft Visual Studio (Figura 8.8).

Figura 8.8 - La documentazione finale per il sorgente compilata.

Con pochi passaggi, poco sforzo e un paio di strumenti gratuiti è possibile creare una ricca e funzionale documentazione per le proprie librerie di classi.

Scegliere la modalità più appropriata per documentare il proprio codice

La domanda che probabilmente vi sarete posti alla fine della lettura di questo capitolo riguarda la differenza tra la documentazione generata da SandCastle e quella prodotta tramite le altre applicazioni di help authoring esaminate nei Capitoli 6 e 7 e l’opportunità di scegliere l’una o l’altra applicazione (e conseguentemente il tipo di file compilato).

Sebbene non sia possibile stabilire un rigido standard, si possono elencare alcune considerazioni:

· l’utilizzo di SandCastle è opportuno esclusivamente quando dovete documentare del codice sorgente, in particolare quando progettate librerie di classi destinate a sviluppatori, per le quali, grazie ai commenti XML, potete automatizzare la produzione di documentazione contenente la descrizione degli oggetti, dei membri e del relativo utilizzo. Il tipo di output (.chm o .HxS) dipende dalla vostra volontà di rendere disponibile la documentazione a tutti o solo a coloro che hanno Visual Studio 2005 (ricordate che con l’avvento di .NET non è necessario avere Visual Studio per scrivere programmi);

· la produzione di help compilato in formato .chm è opportuna quando realizzate un’ampia gamma di applicazioni, prevalentemente Windows Forms, per le quali è necessario realizzare un tipo di documentazione stand-alone, in grado di essere visualizzata da tutti tramite l’apposito servizio del sistema operativo. Questo tipo di documentazione non richiede la presenza di Visual Studio 2005 e continua a essere l’unica piattaforma Microsoft ufficiale per lo sviluppo di documentazione. I file .chm possono essere visualizzati su qualsiasi computer, anche da coloro che non hanno Visual Studio, pertanto è indicata per applicazioni non destinate a sviluppatori;

· l’utilizzo di InnovaSys HelpStudio Lite è consigliabile quando sviluppate applicazioni destinate a sviluppatori, in quanto la documentazione .HxS così generata può essere visualizzata solo tramite il visualizzatore di Visual Studio (Microsoft Document Explorer). A differenza di quanto avviene con SandCastle, HelpStudio Lite è un editor visuale, che traduce quanto progettato dall’utente in formato HTML e pertanto consente di sfruttare la potenza tipica di questo linguaggio (pensate, per esempio, alla possibilità di inserire video, audio e immagini nei documenti creati). Questo tipo di documentazione non necessita di commenti XML all’interno del codice. È preferibile con le librerie di classi ma può essere prodotta anche per applicazioni di altro genere, tenendo sempre conto del fatto che questo tipo di help compilato richiede la presenza di Visual Studio sulla macchina che lo esegue.

Print | posted on domenica 17 giugno 2007 14:08 |

Powered by:
Powered By Subtext Powered By ASP.NET