Intégration de Visual Studio (MSBuild)

Article
08/21/2008

Mise à jour : novembre 2007

Visual Studio 2005 héberge MSBuild pour charger et générer des projets managés. Dans la mesure où MSBuild est responsable du projet, la plupart des projets au format MSBuild peuvent être utilisés sans problème dans Visual Studio, même si le projet a été créé par un outil différent et possède un processus de génération personnalisé.

Cette rubrique décrit des aspects spécifiques de l'hébergement de MSBuild dans Visual Studio qui doivent être pris en compte lors de la personnalisation des projets et des fichiers .targets que vous souhaitez charger et générer dans Visual Studio. Vous serez ainsi assuré que les fonctionnalités Visual Studio, telles qu'IntelliSense et le débogage fonctionnent pour votre projet personnalisé.

Extensions de nom de fichier projet

MSBuild.exe reconnaît n'importe quelle extension de nom de fichier projet correspondant au modèle . *proj. En revanche, Visual Studio reconnaît uniquement un sous-ensemble de ces extensions, lesquelles déterminent le système de projet spécifique au langage qui chargera le projet. Visual Studio ne possède pas de système de projet basé sur MSBuild, indépendant du langage.

Par exemple, le système de projet Visual C# charge des fichiers .csproj, mais Visual Studio n'est pas en mesure de charger un fichier .xxproj. Un fichier projet pour les fichiers sources dans un langage arbitraire doit utiliser la même extension que les fichiers projet Visual Basic, Visual C# ou Visual J# pour être chargés dans Visual Studio.

Noms de cibles connus

Lorsque vous cliquez sur la commande Générer dans Visual Studio, la cible par défaut est exécutée dans le projet. Dans de nombreux cas, cette cible est également nommée Build. La sélection de la commande Régénérer ou Nettoyer entraîne une tentative d'exécution d'une cible du même nom dans le projet. Un clic sur Publier se traduit par l'exécution d'une cible nommée PublishOnly dans le projet.

Configurations et plates-formes

Les configurations sont représentées dans les projets MSBuild par des propriétés regroupées dans un élément PropertyGroup qui contient un attribut Condition. Visual Studio examine ces conditions pour créer une liste de configurations de projet et de plates-formes à afficher. Pour réussir à extraire cette liste, les conditions doivent avoir un format similaire à ce qui suit :

Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' "
Condition=" '$(Configuration)' == 'Release' " 
Condition=" '$(Something)|$(Configuration)|$(SomethingElse)' == 'xxx|Debug|yyy' "

À cette fin, Visual Studio examine les conditions définies sur les éléments PropertyGroup, ItemGroup, Import, property et item.

Actions de génération supplémentaires

Visual Studio vous permet de modifier le nom de la collection d'éléments d'un fichier dans un projet avec la propriété Action de génération de la fenêtre Propriétés des fichiers. Les noms des collections d'éléments Compile, EmbeddedResource, Content et None sont toujours répertoriés dans ce menu ainsi que tous les autres noms de collections d'éléments figurant déjà dans votre projet. Pour garantir la disponibilité de tous les noms de collections d'éléments personnalisées dans ce menu, vous pouvez ajouter les noms à une collection d'éléments nommée AvailableItemName. Par exemple, en ajoutant ce qui suit à votre fichier projet, le type personnalisé JScript est ajouté à ce menu pour tous les projets qui l'importent :

<ItemGroup>
    <AvailableItemName Include="JScript"/>
</ItemGroup>

Remarque :
Certains noms de collections d'éléments sont spécifiques à Visual Studio, mais ne sont pas répertoriés dans cette liste déroulante.

Compilateurs in-process

Lorsque c'est possible, Visual Studio tente d'utiliser les versions in-process des compilateurs Visual Basic ou Visual C# pour améliorer les performances. Pour un fonctionnement correct, les conditions suivantes doivent être respectées :

Une cible du projet doit comporter une tâche nommée Csc (pour les projets Visual C#) ou Vbc (pour les projets Visual Basic)
Le paramètre UseHostCompilerIfAvailable de la tâche doit avoir la valeur true.
Seules les valeurs de paramètre prises en charge doivent être spécifiées. Tous les paramètres spécifiés pour la tâche sont pris en charge par le compilateur in-process, mais certaines valeurs de paramètre ne sont pas prises en charge. Les valeurs suivantes des paramètres de tâche Csc ne sont pas prises en charge par le compilateur in-process Visual C# :
- NoConfig : les valeurs vides et false ne sont pas prises en charge.
- ResponseFiles : les valeurs non vides ne sont pas prises en charge.
- AdditionalLibPaths : les valeurs non vides ne sont pas prises en charge.
- AddModules : les valeurs non vides ne sont pas prises en charge.
- CodePage : les valeurs non nulles ne sont pas prises en charge.
- GenerateFullPaths : true n'est pas pris en charge.
- LinkResources : les valeurs non vides ne sont pas prises en charge.

Si ces conditions ne sont pas respectées, le projet compilera à l'aide du compilateur de ligne de commande au lieu du compilateur in-process.

IntelliSense au moment du design

Pour bénéficier de la prise en charge d'IntelliSense dans Visual Studio avant la génération d'un assembly de sortie, les conditions suivantes doivent être respectées :

Il doit exister une cible nommée Compile.
La cible Compile ou l'une de ses dépendances doit appeler la tâche du compilateur du projet, par exemple Csc ou Vbc.
La cible Compile ou l'une de ses dépendances doit faire en sorte que le compilateur reçoive tous les paramètres nécessaires à IntelliSense, en particulier toutes les références.
Les conditions répertoriées dans la section « Compilateurs in-process » doivent être respectées.

Création de solutions

Dans Visual Studio, l'ordre des générations de projet et du fichier solution est contrôlé par Visual Studio lui-même. Lors de la génération d'une solution avec msbuild.exe à partir de la ligne de commande, MSBuild analyse le fichier solution et classe les générations de projet. Dans les deux cas, les projets sont générés individuellement en fonction de l'ordre des dépendances et les références entre projets ne sont pas parcourues. En revanche, lors de la génération de projets individuels avec msbuild.exe, les références entre projets sont parcourues.

Lors de la génération dans Visual Studio, la propriété $(BuildingInsideVisualStudio) a la valeur true. Vous pouvez l'utiliser dans vos fichiers projet ou .targets pour que la génération se comporte différemment.

Affichage des propriétés et des éléments

Visual Studio reconnaît certains noms et valeurs de propriété. Par exemple, la présence de la propriété suivante dans un projet entraîne l'affichage de Application Windows dans la zone Type d'application du Concepteur de projets.

<OutputType>WinExe</OutputType>

La valeur de la propriété peut être modifiée dans le Concepteur de projets et enregistrée dans le fichier projet. Si une telle propriété est affectée d'une valeur non valide lors d'une modification manuelle, Visual Studio affiche un avertissement lors du chargement du projet et remplace la valeur non valide par une valeur par défaut.

Visual Studio reconnaît les valeurs par défaut de certaines propriétés. Ces propriétés ne sont pas rendues persistantes dans le fichier projet sauf si elles possèdent des valeurs non définies par défaut.

Les propriétés portant des noms arbitraires ne sont pas affichées dans Visual Studio. Pour modifier des propriétés arbitraires dans Visual Studio, vous devez ouvrir le fichier projet dans l'Éditeur XML et les modifier manuellement. Pour plus d'informations, consultez Comment : modifier des fichiers projet.

Les éléments définis dans le projet avec des noms de collections d'éléments arbitraires sont affichés par défaut dans l'Explorateur de solutions sous leur nœud de projet. Pour masquer un élément, attribuez la valeur false aux métadonnées Visible. Par exemple, l'élément suivant participera au processus de génération, mais ne s'affichera pas dans l'Explorateur de solutions.

<ItemGroup>
    <IntermediateFile Include="cache.temp">
        <Visible>false</Visible>
    </IntermediateFile>
</ItemGroup>

Les éléments déclarés dans les fichiers importés dans le projet ne sont pas affichés par défaut. Les éléments créés pendant le processus de génération ne sont jamais affichés dans l'Explorateur de solutions.

Conditions appliquées aux éléments et aux propriétés

Pendant une génération, toutes les conditions sont respectées pleinement.

Lors de la détermination des valeurs de propriétés à afficher, les propriétés que Visual Studio considère comme dépendantes de la configuration sont évaluées différemment des propriétés considérées comme indépendantes de la configuration. Pour les propriétés dépendantes de la configuration, Visual Studio définit les propriétés Configuration et Platform de la façon appropriée et indique à MSBuild de réévaluer le projet. Pour les propriétés indépendantes de la configuration, le mode d'évaluation des conditions n'est pas déterminé.

Lorsqu'il faut déterminer l'affichage de l'élément dans l'Explorateur de solutions, les expressions conditionnelles associées à des éléments sont toujours ignorées.

Débogage

Pour rechercher et lancer l'assembly de sortie ainsi qu'attacher le débogueur, Visual Studio a besoin des propriétés OutputPath, AssemblyName et OutputType correctement définies. Il ne sera pas possible d'attacher le débogueur si le processus de génération n'a pas donné lieu à la génération d'un fichier .pdb par le compilateur.

Exécution des cibles au moment du design

Visual Studio tente d'exécuter des cibles portant certains noms lorsqu'il charge un projet. Il s'agit notamment des cibles Compile, ResolveAssemblyReferences, ResolveCOMReferences, GetFrameworkPaths et CopyRunEnvironmentFiles. Visual Studio exécute ces cibles afin que le compilateur puisse être initialisé pour fournir IntelliSense, que le débogueur puisse être initialisé et que les références affichées dans Explorateur de solutions puissent être résolues. En l'absence de ces cibles, le projet se charge et effectue une génération correcte, mais l'expérience au moment du design dans Visual Studio ne sera pas complètement fonctionnelle.

Modification des fichiers projet dans Visual Studio

Lorsqu'il est nécessaire de modifier directement un projet MSBuild, vous pouvez ouvrir le fichier projet dans l'Éditeur XML de Visual Studio. Pour plus d'informations, consultez Comment : modifier des fichiers projet.

IntelliSense et validation

Lors de l'utilisation de l'Éditeur XML pour modifier des fichiers projet, IntelliSense et la validation sont pilotés par les fichiers de schéma MSBuild. Ceux-ci sont installés par Visual Studio dans le cache de schémas, qui figure dans le dossier [emplacement d'installation de Visual Studio ]\Xml\Schemas.

Les types MSBuild principaux sont définis dans Microsoft.Build.Core.xsd et les types communs utilisés par Visual Studio sont définis dans Microsoft.Build.CommonTypes.xsd. Pour personnaliser les schémas afin de disposer de la validation et IntelliSense pour les noms de collections d'éléments personnalisés, les propriétés et les tâches, vous pouvez modifier Microsoft.Build.xsd ou créer votre propre schéma incluant les schémas CommonTypes ou Core. Si vous créez votre propre schéma, vous devez indiquer à l'Éditeur XML de l'utiliser à l'aide de la fenêtre Propriétés.

Modification de fichiers projet chargés

Visual Studio met en cache le contenu des fichiers projet et des fichiers importés par les fichiers projet. Si vous modifiez un fichier projet chargé, Visual Studio vous invite automatiquement à recharger le projet afin que les modifications soient appliquées. Toutefois, si vous modifiez un fichier importé par un projet chargé, aucune invite de rechargement ne s'affiche et vous devez décharger et recharger manuellement le projet pour que les modifications prennent effet.

Groupes de sortie

Plusieurs cibles définies dans Microsoft.Common.targets possèdent des noms se terminant par OutputGroups ou OutputGroupDependencies. Visual Studio appellent ces cibles pour obtenir des listes spécifiques de sorties de projet. Ainsi, la cible SatelliteDllsProjectOutputGroup crée une liste de tous les assemblys satellites créés par une génération. Ces groupes de sorties sont utilisés par des fonctionnalités, telles que la publication, le déploiement et les références entre projets. Les projets qui ne les définissent pas seront chargés et générés dans Visual Studio, mais il se peut que certaines fonctionnalités ne fonctionnent pas correctement.

Résolution de référence

La résolution des références est le processus consistant à utiliser des éléments de référence stockés dans un fichier projet pour localiser les véritables assemblys. Visual Studio doit déclencher la résolution de références pour afficher les propriétés détaillées de chaque référence dans la fenêtre Propriétés. La liste suivante décrit les trois types de références et leur mode de résolution.

Références d'assembly :

Le système de projet appelle une cible avec le nom connu ResolveAssemblyReferences. Cette cible doit produire des éléments avec le nom de collection d'éléments ReferencePath. Chacun de ces éléments doit avoir une spécification d'élément (la valeur de l'attribut Include d'un élément) qui contient le chemin d'accès complet à la référence. Les éléments doivent avoir toutes les métadonnées des éléments d'entrée passés en plus des nouvelles métadonnées suivantes :
- CopyLocal, indiquant si l'assembly doit être copié dans le dossier de sortie ; la valeur peut être true ou false.
- OriginalItemSpec, contenant la spécification d'élément d'origine de la référence.
- ResolvedFrom, défini à la valeur "{TargetFrameworkDirectory }" s'il a été résolu à partir du répertoire .NET Framework.
Références COM :

Le système de projet appelle une cible avec le nom connu ResolveCOMReferences. Cette cible doit produire des éléments avec le nom de collection d'éléments ComReferenceWrappers. Chacun de ces éléments doit posséder une spécification d'élément qui contient le chemin d'accès complet à l'assembly d'interopérabilité pour la référence COM. Les éléments doivent avoir toutes les métadonnées des éléments d'entrée passés, en plus de nouvelles métadonnées portant le nom CopyLocal, qui indiquent si l'assembly doit être copié dans le dossier de sortie ; la valeur peut être true ou false.
Références natives

Le système de projet appelle une cible avec le nom connu ResolveNativeReferences. Cette cible doit produire des éléments avec le nom de collection d'éléments NativeReferenceFile. Les éléments doivent avoir toutes les métadonnées des éléments d'entrée passés, en plus d'une nouvelle métadonnée nommée OriginalItemSpec, contenant la spécification d'élément d'origine de la référence.