Débuter avec NAnt sous Visual Studio .NET - version C#

Il est parfois nécessaire de rendre un projet facilement distribuable et compilable sur tout système et indépendamment du logiciel qui l'a créé. En .NET, par exemple, lorsqu'un projet est réalisé, et que l'ont veut distribuer les sources rapidement, on se contente souvent de réaliser une archive incluant le fichier de projet du logiciel utilisé pour le développement qui référencie les sources.
Cependant, les outils permettant de travailler avec .NET sont de plus en plus nombreux, même si Visual Studio reste prédominant : Borland C# Builder, Delphi, SharpDevelop, MonoDevelop, Eclipse… Même la plateforme change : on peut réaliser des programmes en .NET avec le Framework .NET de Microsoft ou son portage libre Mono.
Pour certains projets, il peut donc être important d'unifier le mode de compilation et d'actions effectuées sur des sources. L'application NMake est une solution, mais le monde Java a apporté une innovation dans ce type de script en intégrant le XML. Cet outil, Ant, a été porté en .NET sous le nom de NAnt. Aujourd'hui la plupart des outils open source en .NET sont distribués avec un script NAnt.
Nous vous proposons, dans cet article, de réaliser pas à pas l'installation de NAnt sous Windows et de l'intégrer dans Visual Studio.

Pourquoi Visual Studio ? Il s'agit du logiciel le plus utilisé pour le développement .NET et l'acceptation de NAnt, qui apporte des fonctionnalités supplémentaires, sera facilitée si les développeurs sous Visual Studio l'utilisent. L'intégration doit donc être la plus souple possible sans devoir passer à chaque compilation par une ligne de commande.

De plus, NAnt, ce n'est pas que de la compilation. Voici quelques tâches que NAnt peut réaliser :
- compilation de sources C#, VB.NET, J#… et prise en compte des assemblies associées ;
- création, suppression, copie de répertoires, de fichiers ;
- exécution de programmes externes ;
- utilisation de NUnit (pour les tests unitaires) ;
- lire et écrire dans la base de registre ;
- envoyer des emails (pour avertir de la fin d'une compilation par exemple) ;
- utiliser CVS ;
- réaliser des archives ;
- lire et écrire du XML avec Xpath ;
- etc.

La configuration utilisée pour ce tutoriel est :
- Windows XP Pro SP1 ;
- Visual Studio .NET 2003.

Dans cette partie, nous allons rendre Nant utilisable via des lignes de commandes.

Rendez-vous sur http://nant.sourceforge.net/ et téléchargez la dernière version de Nant (0.85 RC3 au moment d'écrire cet article).
Décompressez l'archive récupérée dans le répertoire de votre choix. Nous supposerons que le répertoire de Nant choisi est « C:\Program Files.ant\ ».

Définissons le répertoire « nant\bin » dans la variable d'environnement « Path » du système afin que l'exécutable « Nant.exe » soit reconnu indépendamment de son répertoire d'installation.

Allez dans le panneau de configuration et ouvrez « Système » puis dans l'onglet « Avancé », cliquez sur le bouton « Variables d'environnement ».

Dans la partie « Variables système », cherchez la variable « Path » et cliquez sur « Éditer ».
Dans la zone « Valeur de variable », ajouter (surtout ne rien supprimer), la chaîne suivante : « ;C:\Program Filesant\bin » à adapter selon le répertoire choisi à l'installation.
Validez ensuite les modifications.

Ouvrez une console DOS.
Tapez à l'invite DOS, la commande suivante : « nant -help ».

Si la version de Nant apparaît avec des informations sur les commandes possibles, alors NAnt est bien installé.

Dans la suite de cet article, nous allons détailler l'utilisation Nant avec Visual Studio.

Cependant, pour une utilisation en ligne de commande, la procédure est la suivante :
- créer un script Nant avec une extension .build ;
- créer au moins un fichier source (*.cs) ;
- se placer, via une fenêtre DOS, dans le répertoire contenant les fichiers ;
- tapez « nant » pour une utilisation de la tâche par défaut ;
- tapez « nant nomtarget » pour l'exécution précise d'une tâche (voir partie 3).

Copiez le fichier : « C:\Program Filesant \schemaant.xsd » dans le répertoire « C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\schemas\xml\ ».

Vous devrez peut être adapter les chemins selon votre version de Nant et le répertoire d'installation de Visual Studio .NET. Cette copie permettra dans la partie 3 de permettre la complétion automatique lors de l'édition du fichier de script Nant.

Configurons Visual Studio pour exécuter Nant directement par son interface avec une icône ou un raccourci clavier.

Ouvrez Visual Studio.
Choisissez dans la barre de menu : « Outils > Outils externes… ».
Cliquez sur le bouton « Ajouter ».
Indiquez les valeurs suivantes :
- Titre : Nant ;
- Commande : nant (il est important que l'étape 1 ait été bien réalisée, sinon indiquez le chemin de l'outil en entier) ;
- Répertoire initial : $(ProjectDir) (Répertoire du projet) ;
- Cochez uniquement « Fermer en quittant ».
Mémorisez la position dans la liste « Contenu du menu » de la ligne que vous avez créée. Dans mon cas, c'est la 8e.
Cliquez sur « OK ». Si un message d'alerte apparaît vous proposant de modifier la commande apparaît, répondez « Non ».

Associons NAnt à un raccourci clavier.

Allez dans « Outils > Personnaliser » et cliquez sur « Clavier… ».
Sélectionnez la ligne Outils.CommandeExterne8.
Associez à la ligne le raccourci clavier que vous souhaitez, « CTRL+F8 » par exemple. Veillez à ne pas choisir un raccourci déjà pris et à cliquer sur le bouton « Assigner ».
Si une alerte apparaît vous proposant de créer un nouveau schéma, répondez « Oui » et donnez-lui le nom que vous souhaitez.

Associons NAnt à un bouton de la barre d'outils.

Retournez ou restez dans « Outils > Personnaliser ».
Dans l'onglet « Barre d'outils », faites « Nouvelle… » et choisissez comme nom « Nant ». Une petite zone de barre d'outils flottante devrait apparaître.
Allez dans l'onglet « Commandes », choisissez la catégorie « Outils ».
Dans la zone « Commandes », glissez déposez dans la zone flottante la ligne « Commande externe 8 ».
Cliquez sur « Modifier la sélection > Nom » et donnez comme nom : « Nant Build ». Choisissez une icône si vous le souhaitez.

Glissez déposez la zone flottante où vous le souhaitez dans la barre d'outils.
Cliquez sur Fermer dans la fenêtre « Personnaliser ».

À ce stade, nous pouvons appeler Nant en appuyant sur « CTRL+F8 » ou en cliquant su l'icône « Nant Build ».
Créons maintenant notre premier script.

Pour le premier projet, nous allons réaliser un simple HelloWorld en mode console et son script de build afin de comprendre les bases de NAnt.

Créez un nouveau projet Visual C# du type « Application console » avec comme nom « MonHelloWorld ».
Placez, dans la méthode Main() de Class1.cs, le code suivant et enregistrez :

[STAThread]
static void Main(string[] args)
{
    Console.WriteLine("Hello World !");
    Console.ReadLine(); // Permet d'empêcher la fermeture de la fenêtre DOS
}

Ajoutez, à partir de Visual Studio, un nouveau fichier texte à la racine du projet et appelez le « MonHelloWorld.build ». L'extension du fichier est importante à respecter, le nom ne l'est pas.

À cette étape, le projet doit ressembler à ça :

Faites un clic droit sur le fichier MonHelloWord.build puis « Ouvrir avec… ».
Choisissez « Éditeur HTML/XML » et cliquez sur le bouton « Par défaut » puis « Ouvrir ».
Tous les fichiers « *.build » seront donc ouverts automatiquement par l'éditeur xml intégré.

Dans le fichier MonHelloWorld.build, placez le contenu xml suivant :

<?xml version="1.0"?>
<project name="Mon Hello World" default="execute" basedir="." xmlns="http://nant.sf.net/release/0.85-rc3/nant.xsd">
    <description>Un Hello World pour tester NAnt.</description>
    <property name="debug" value="true" overwrite="false" />
    <property name="output" value="build" overwrite="false" />
    <property name="exename" value="Class1.exe" overwrite="false" />
    <target name="clean" description="Suppression du répertoire \build">
        <delete dir="${output}" failonerror="false" />
    </target>
    <target name="build" description="Compilation de la source" depends="clean">
        <mkdir dir="${output}" failonerror="false" />
        <csc target="exe" output="${output}\${exename}" debug="${debug}">
            <sources>
                <include name="Class1.cs" />
            </sources>
        </csc>
    </target>
    <target name="execute" description="Exécution du programme" depends="build">
        <exec program="${output}\${exename}" />
    </target>
</project>

Le fichier se découpe en cinq parties principales.

1) L'entête qui indique le type du fichier et quelques éléments de définition :

<?xml version="1.0"?>
<project name="Mon Hello World" default="execute" basedir="." xmlns="http://nant.sf.net/schemas/nant-0.85.win32.net-1.0.xsd">
    <description>Un Hello World pour tester NAnt.</description>

default="execute"
Permet d'indiquer que la tâche (target) « execute » sera exécutée par défaut si aucun paramètre n'est passé au programme « nant.exe » (ce qui sera notre cas).

xmlns=« http://nant.sf.net/release/0.85-rc3/nant.xsd »
L'ajout de cette chaîne ainsi que la copie du fichier xsd dans le répertoire dédié de Visual Studio permet d'activer la complétion des tags xml lors de l'édition du fichier xml de script Nant (ici MyHelloWorld.build)

basedir="."
Indique que le répertoire de base sera le même que celui dans lequel s'exécute le script. Ici, il s'agit de notre répertoire projet.

2) L'initialisation des propriétés

<property name="debug" value="true" overwrite="false" />
<property name="output" value="build" overwrite="false" />
<property name="exename" value="Class1.exe" overwrite="false" />

Il s'agit d'une sorte de déclaration de constantes où la valeur sera accessible par ${nomProperty}
- debug à true indiquera que la compilation se fait en mode Debug
- output à build indiquera que le répertoire où seront placés les fichiers générés sera « .\build\ »
- exename à Class1.exe indiquera que l'exécutable devra être nommé « Class1.exe »

Seules, ces propriétés n'ont aucun intérêt, elles doivent ensuite être utilisées dans le reste du script.

3) Les tâches du script

<target name="clean" description="Suppression du répertoire \build">
    <delete dir="${output}" failonerror="false" />
</target>
<target name="build" description="Compilation de la source" depends="clean">
    <mkdir dir="${output}" failonerror="false" />
    <csc target="exe" output="${output}\${exename}" debug="${debug}">
        <sources>
            <include name="Class1.cs" />
        </sources>
    </csc>
</target>
<target name="execute" description="Exécution du programme" depends="build">
    <exec program="${output}\${exename}" />
</target>

Trois tâches sont proposées ici, chaque tâche est définie par un nœud <target /> :
- clean : la suppression du répertoire de build ;
- build : la compilation des sources après avoir recréé le répertoire de build ;
- execute : on exécute le Class1.exe généré.

Pour ordonner les tâches, placer les <target /> dans l'ordre d'exécution ne sert à rien. Il faut définir des dépendances : « execute » ne peut être lancé que si « build » est terminé et « build » ne peut être lancé que si « clean » est terminé. Les attributs « depends » dans les nœuds <target /> permettent d'imposer cette règle.
On comprend ainsi la raison de lancer « execute » en premier puisque lui-même appellera les tâches dont il dépend.

Pour finir, appuyez sur « CTRL+F8 » ou sur l'icône « Nant Build » et vérifiez que tout fonctionne bien dans la fenêtre DOS qui se lance. Logiquement un répertoire « build » a dû être créé à la racine de votre projet (visible via l'explorateur windows).

Juste optionnellement, et pour fournir un exemple supplémentaire qui permet de montrer l'intérêt de NAnt pour certaines tâches, voici un target vous permettant de sauvegarder à chaque appel le contenu du répertoire du projet dans un fichier zip à la date et l'heure de l'exécution.

<property name="backupdir" value="backup" overwrite="false" />
<target name="backup" description="Création de la sauvegarde">
    <mkdir dir="${backupdir}" unless="${directory::exists(backupdir)}" />
    <tstamp property="builddate" pattern="yyyyMMdd_HHmm" />
    <zip zipfile="${backupdir}\${builddate}_MonHelloWorld.zip">
        <fileset basedir=".">
            <include name="*.*" />
        </fileset>
    </zip>
</target>

http://nant.sourceforge.net/ : Site du projet NAnt.
http://nantcontrib.sourceforge.net/ : Site du projet NAntContrib qui ajoute de nombreuses fonctionnalités à la version NAnt de base.
http://nantrunner.sourceforge.net/ : Site de NAntRunner, un Addin pour Visual Studio .NET permettant d'utiliser NAnt efficacement.