Procédure pas à pas : création d'une extension de projet SharePoint

Article
08/10/2011

Cette procédure pas à pas illustre la création d'une extension pour les projets SharePoint. Vous pouvez utiliser une extension de projet pour répondre aux événements de niveau projet, par exemple lorsqu'un projet est ajouté ou supprimé, ou que son nom est modifié. Vous pouvez également ajouter des propriétés personnalisées ou répondre lorsqu'une valeur de propriété change. Contrairement aux extensions d'élément de projet, les extensions de projet ne peuvent pas être associées à un type de projet SharePoint particulier. Lorsque vous créez une extension de projet, celle-ci est chargée dès l'ouverture d'un projet SharePoint dans Visual Studio.

Dans cette procédure pas à pas, vous créez une propriété booléenne personnalisée qui est ajoutée à tout projet SharePoint créé dans Visual Studio. Lorsqu'elle a la valeur True, la nouvelle propriété ajoute ou mappe un dossier ressource Images à votre projet. Lorsqu'elle a la valeur False, le dossier Images est supprimé, s'il existe. Pour plus d'informations, consultez Comment : ajouter et supprimer des dossiers mappés.

Cette procédure pas à pas présente les tâches suivantes :

Création d'une extension Visual Studio, pour les projets SharePoint, qui effectue les opérations suivantes :
- Ajoute une propriété de projet personnalisée à la fenêtre Propriétés. La propriété s'applique à tout projet SharePoint.
- Utilise le modèle d'objet du projet SharePoint pour ajouter un dossier mappé à un projet.
- Utilise le modèle objet Automation principal (DTE) dans Visual Studio pour supprimer un dossier mappé du projet.
Génération d'un package VSIX (Visual Studio Extension) Visual Studio pour déployer l'assembly d'extension de la propriété du projet.
Débogage et test de la propriété du projet.

Composants requis

Vous avez besoin des composants suivants sur l'ordinateur de développement pour terminer cette procédure pas à pas :

Éditions de Microsoft Windows, SharePoint et Visual Studio prises en charge. Pour plus d'informations, consultez Configuration requise pour développer des solutions SharePoint.
Kit de développement logiciel (SDK) Visual Studio 2010. Cette procédure pas à pas se base sur le modèle Projet VSIX dans le SDK pour créer un package VSIX nécessaire au déploiement de l'extension de propriété du projet. Pour plus d'informations, consultez Extension des outils SharePoint dans Visual Studio.

Création du projet

Pour exécuter cette procédure pas à pas, vous devez créer deux projets :

Un projet VSIX pour créer le package VSIX afin de déployer l'extension de projet.
Un projet de bibliothèque de classes qui implémente l'extension de projet.

Démarrez la procédure pas à pas en créant les projets.

Pour créer le projet VSIX

Démarrez Visual Studio.
Dans le menu Fichier, pointez sur Nouveau, puis cliquez sur Projet.
Dans la boîte de dialogue Nouveau projet, développez les nœuds Visual C# ou Visual Basic, puis cliquez sur le nœud Extensibilité.

Notes

Le nœud Extensibilité est disponible uniquement si vous installez le Kit de développement logiciel (SDK) Visual Studio 2010. Pour plus d'informations, consultez la section des composants requis plus haut dans cette rubrique.
Dans la zone de liste déroulante en haut de la boîte de dialogue, sélectionnez .NET Framework 4. Les extensions des outils SharePoint nécessitent des fonctionnalités dans cette version du .NET Framework.
Cliquez sur le modèle Projet VSIX.
Dans la zone de texte Nom, tapez ProjectExtensionPackage.
Cliquez sur OK.

Visual Studio ajoute le projet ProjectExtensionPackage à l'Explorateur de solutions.

Pour créer le projet d'extension

Cliquez avec le bouton droit sur le nœud de la solution dans l'Explorateur de solutions, cliquez sur Ajouter, puis sur Nouveau projet.

Notes

Dans les projets Visual Basic, le nœud de la solution s'affiche dans l'Explorateur de solutions à condition d'avoir activé la case à cocher Toujours afficher la solution dans la Général, Projets et solutions, boîte de dialogue Options.
Dans la boîte de dialogue Nouveau projet, développez le nœud Visual C# ou Visual Basic, puis cliquez sur Fenêtres.
Dans la zone de liste déroulante en haut de la boîte de dialogue, sélectionnez .NET Framework 4.
Sélectionnez le modèle de projet Bibliothèque de classes.
Dans la zone Nom, tapez ProjectExtension.
Cliquez sur OK.

Visual Studio ajoute le projet ProjectExtension à la solution et ouvre le fichier de code Class1 par défaut.
Supprimez le fichier de code Class1 du projet.

Configuration du projet

Avant d'écrire le code pour créer l'extension de projet, ajoutez les fichiers de code et les références d'assembly au projet d'extension.

Pour configurer le projet

Ajoutez un nouveau fichier de code nommé CustomProperty au projet ProjectExtension.
Dans le menu Projet, cliquez sur Ajouter une référence.
Sous l'onglet .NET, appuyez sur CTRL et cliquez sur les assemblys suivants, puis cliquez sur OK :
- Microsoft.VisualStudio.SharePoint
- System.ComponentModel.Composition
- System.Windows.Forms
- EnvDTE
Dans l'Explorateur de solutions, sous le dossier Références du projet ProjectExtension, cliquez sur EnvDTE.
Dans la fenêtre Propriétés, affectez à la propriété Incorporer les types d'interopérabilité la valeur False.

Définition de la nouvelle propriété de projet SharePoint

Créez une classe qui définit l'extension de projet et le comportement de la nouvelle propriété de projet. Pour définir la nouvelle extension de projet, la classe implémente l'interface ISharePointProjectExtension. Implémentez cette interface chaque fois que vous souhaitez définir une extension pour un projet SharePoint. En outre, ajoutez l'attribut ExportAttribute à la classe. Cet attribut permet à Visual Studio de découvrir et de charger votre implémentation ISharePointProjectExtension. Communiquez le type ISharePointProjectExtension au constructeur de l'attribut.

Pour définir la nouvelle propriété de projet SharePoint

Double-cliquez sur le fichier de code CustomProperty pour le modifier, s'il n'est pas déjà ouvert.

Collez le code suivant dans le fichier.

Imports System
Imports System.Linq
Imports System.ComponentModel
Imports System.ComponentModel.Composition
Imports System.Windows.Forms
Imports Microsoft.VisualStudio.SharePoint
Imports EnvDTE

Namespace Contoso.SharePointProjectExtensions.MapImagesFolder

    ' Export attribute: Enables Visual Studio to discover and load this extension.
    ' MapImagesFolderProjectExtension class: Adds a new Map Images Folder property to any SharePoint project.
    <Export(GetType(ISharePointProjectExtension))> _
    Public Class MapImagesFolderProjectExtension
        Implements ISharePointProjectExtension

        Public Sub Initialize(ByVal projectService As ISharePointProjectService) Implements ISharePointProjectExtension.Initialize
            AddHandler projectService.ProjectPropertiesRequested, AddressOf Me.projectService_ProjectPropertiesRequested
        End Sub

        Private Sub projectService_ProjectPropertiesRequested(ByVal sender As Object, ByVal e As SharePointProjectPropertiesRequestedEventArgs)
            Dim propertiesObject As CustomProjectProperties = Nothing

            ' If the properties object already exists, get it from the project's annotations.
            If False = e.Project.Annotations.TryGetValue(propertiesObject) Then
                ' Otherwise, create a new properties object and add it to the annotations.
                propertiesObject = New CustomProjectProperties(e.Project)
                e.Project.Annotations.Add(propertiesObject)
            End If

            e.PropertySources.Add(propertiesObject)
        End Sub
    End Class

    Public Class CustomProjectProperties
        Private sharePointProject As ISharePointProject = Nothing
        Private Const MapImagesFolderPropertyDefaultValue As Boolean = False
        Private Const MapImagesFolderPropertyId = "ContosoMapImagesFolderProperty"

        Public Sub New(ByVal myProject As ISharePointProject)
            sharePointProject = myProject
        End Sub

        ' Represents the new boolean property MapImagesFolder.
        ' True = Map an Images folder to the project if one does not already exist; otherwise, do nothing.
        ' False = Remove the Images folder from the project, if one exists; otherwise, do nothing.
        <DisplayName("Map Images Folder")> _
        <DescriptionAttribute("Specifies whether an Images folder is mapped to the SharePoint project.")> _
        <DefaultValue(MapImagesFolderPropertyDefaultValue)> _
        Public Property MapImagesFolder As Boolean
            Get
                Dim propertyStringValue As String = String.Empty

                ' Try to get the current value from the .user file; if it does not yet exist, return a default value.
                If Not sharePointProject.ProjectUserFileData.TryGetValue(MapImagesFolderPropertyId, propertyStringValue) Then
                    Return MapImagesFolderPropertyDefaultValue
                Else
                    Return CBool(propertyStringValue)
                End If
            End Get

            Set(ByVal value As Boolean)
                If value Then
                    If Not ImagesMappedFolderInProjectExists(sharePointProject) Then
                        ' An Images folder is not mapped to the project, so map one.
                        Dim mappedFolder As IMappedFolder = sharePointProject.MappedFolders.Add(MappedFolderType.Images)
                        sharePointProject.ProjectService.Logger.WriteLine( _
                            mappedFolder.Name & " mapped folder added to the project.", LogCategory.Status)
                    End If
                ElseIf (ImagesMappedFolderInProjectExists(sharePointProject) AndAlso UserSaysDeleteFile()) Then
                    ' An Images folder is mapped to the project and the user wants to remove it.
                    DeleteFolder()
                End If

                sharePointProject.ProjectUserFileData(MapImagesFolderPropertyId) = value.ToString()
            End Set
        End Property

        Private Function ImagesMappedFolderInProjectExists(ByVal sharePointProject As ISharePointProject) As Boolean
            Dim returnValue As Boolean = False
            For Each folder As IMappedFolder In sharePointProject.MappedFolders
                ' Check to see if an Images folder is already mapped.
                If (folder.FolderType = MappedFolderType.Images) Then
                    returnValue = True
                End If
            Next
            Return returnValue
        End Function

        Private Function UserSaysDeleteFile() As Boolean
            ' Ask the user whether they want to delete the Images folder.
            Dim returnValue As Boolean = False
            If (MessageBox.Show("Do you want to delete the Images folder from the project?", _
                "Delete the Images folder?", MessageBoxButtons.YesNo) = DialogResult.Yes) Then
                returnValue = True
            End If
            Return returnValue
        End Function

        Private Sub DeleteFolder()
            ' The Visual Studio DTE object model is required to delete the mapped folder.
            Dim dteProject As EnvDTE.Project = _
                sharePointProject.ProjectService.Convert(Of ISharePointProject, EnvDTE.Project)(sharePointProject)
            Dim targetFolderName As String = _
                sharePointProject.MappedFolders.First(Function(mf) mf.FolderType = MappedFolderType.Images).Name
            Dim mappedFolderItem As EnvDTE.ProjectItem = dteProject.ProjectItems.Item(targetFolderName)
            mappedFolderItem.Delete()

            sharePointProject.ProjectService.Logger.WriteLine("Mapped Folder " & _
                targetFolderName & " deleted", LogCategory.Status)
        End Sub
    End Class
End Namespace

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.ComponentModel;
using System.ComponentModel.Composition;
using System.Windows.Forms;
using Microsoft.VisualStudio.SharePoint;
using EnvDTE;

// Adds a new property called MapImagesFolder to any SharePoint project.
// When MapImagesFolder is set to true, the Image folder is mapped to the project.
// When MapImagesFolder is set to false, the Image folder is deleted from the project.
namespace SP_Project_Extension
{
    // Export attribute: Enables Visual Studio to discover and load this extension.
    [Export(typeof(ISharePointProjectExtension))]

    // Defines a new custom project property that applies to any SharePoint project.
    public class SPProjectExtension : ISharePointProjectExtension
    {
        // Implements ISharePointProjectService.Initialize, which determines the behavior of the new property.
        public void Initialize(ISharePointProjectService projectService)
        {
            // Handle events for when a project property is changed.
            projectService.ProjectPropertiesRequested +=
                new EventHandler<SharePointProjectPropertiesRequestedEventArgs>(projectService_ProjectPropertiesRequested);
        }

        void projectService_ProjectPropertiesRequested(object sender, SharePointProjectPropertiesRequestedEventArgs e)
        {
            // Add a new property to the SharePoint project.
            e.PropertySources.Add((object)new ImagesMappedFolderProperty(e.Project));
        }
    }

    public class ImagesMappedFolderProperty
    {
        ISharePointProject sharePointProject = null;
        public ImagesMappedFolderProperty(ISharePointProject myProject)
        {
            sharePointProject = myProject;
        }
        static bool MapFolderSetting = false;

        [DisplayName("Map Images Folder")]
        [DescriptionAttribute("Specifies whether an Images folder is mapped to the SharePoint project.")]
        public bool MapImagesFolder
        // Represents the new boolean property MapImagesFolder.
        // True = Map an Images folder to the project if one does not already exist; otherwise, do nothing.
        // False = Remove the Images folder from the project, if one exists; otherwise, do nothing.
        {
            get
            {
                // Get the current property value.
                return MapFolderSetting;
            }
            set
            {
                if (value)
                {
                    if (!ImagesMappedFolderInProjectExists(sharePointProject))
                    {
                        // An Images folder is not mapped to the project, so map one.
                        IMappedFolder mappedFolder1 = sharePointProject.MappedFolders.Add(MappedFolderType.Images);
                        // Add a note to the logger that a mapped folder was added.
                        sharePointProject.ProjectService.Logger.WriteLine("Mapped Folder added:" + mappedFolder1.Name, LogCategory.Status);
                    }
                }
                else
                {
                    if (ImagesMappedFolderInProjectExists(sharePointProject) && UserSaysDeleteFile())
                    {
                        // An Images folder is mapped to the project and the user wants to remove it.
                        // The Visual Studio DTE object model is required to delete the mapped folder.
                        // Reference the Visual Studio DTE model, get handles for the SharePoint project and project items.
                        EnvDTE.Project dteProject = sharePointProject.ProjectService.Convert<ISharePointProject, EnvDTE.Project>(sharePointProject);
                        string targetFolderName = sharePointProject.MappedFolders.First(mf => mf.FolderType == MappedFolderType.Images).Name;
                        EnvDTE.ProjectItem mappedFolderItem = dteProject.ProjectItems.Item(targetFolderName);
                        mappedFolderItem.Delete();
                        sharePointProject.ProjectService.Logger.WriteLine("Mapped Folder " + targetFolderName + " deleted", LogCategory.Status);
                    }
                }
                MapFolderSetting = value;
            }

        }

        private bool ImagesMappedFolderInProjectExists(ISharePointProject sharePointProject)
        {
            bool retVal = false;
            foreach (IMappedFolder folder in sharePointProject.MappedFolders)
            {
                // Check to see if an Images folder is already mapped.
                if (folder.FolderType == MappedFolderType.Images)
                    retVal = true;
            }
            return retVal;
        }

        private bool UserSaysDeleteFile()
        {
            // Prompt the user whether they want to delete the Images folder.
            bool retVal = false;
            if (MessageBox.Show("Do you want to delete the Images folder from the project?", "Delete the Images folder?", MessageBoxButtons.YesNo) == DialogResult.Yes)
            {
                retVal = true;
            }
            return retVal;

        }
    }
}

Génération de la solution

Ensuite, générez la solution afin de garantir sa compilation sans erreur.

Pour générer la solution

Dans le menu Générer, cliquez sur Générer la solution.

Création d'un package VSIX pour déployer l'extension de propriété de projet

Pour déployer l'extension de projet, utilisez le projet VSIX dans votre solution pour créer un package VSIX. En premier lieu, configurez le package VSIX en modifiant le fichier source.extension.vsixmanifest qui est inclus dans le projet VSIX. Ensuite, créez le package VSIX en générant la solution.

Pour configurer et créer le package VSIX

Dans l'Explorateur de solutions, double-cliquez sur le fichier source.extension.vsixmanifest.

Visual Studio ouvre le fichier dans l'éditeur de manifeste. Cet éditeur fournit une UI que vous pouvez utiliser pour modifier le XML dans le manifeste. Ces informations s'affichent ultérieurement dans le Gestionnaire d'extensions. Le fichier extension.vsixmanifest est requis par tous les packages VSIX. Pour plus d'informations sur ce fichier, consultez VSIX Extension Schema Reference.
Dans la zone Nom du produit, tapez Propriété de projet personnalisée.
Dans la zone Auteur, tapez Contoso.
Dans la zone Description, tapez Propriété de projet SharePoint personnalisée qui bascule le mappage du dossier ressource Images dans le projet.
Dans la section Contenu de l'éditeur, cliquez sur le bouton Ajouter du contenu.
Sélectionnez Composant MEF dans la zone déroulante Sélectionnez un type de contenu.

Notes

Cette valeur correspond à l'élément MEFComponent dans le fichier extension.vsixmanifest. Cet élément spécifie le nom d'un assembly d'extension dans le package VSIX. Pour plus d'informations, consultez MEFComponent Element (VSX Schema).
Dans la section Sélectionner une source, cliquez sur Projet , puis sélectionnez ProjextExtension dans la zone déroulante.

Cette valeur identifie l'assembly que vous générez dans le projet.
Lorsque vous avez terminé, cliquez sur OK pour fermer la boîte de dialogue Ajouter du contenu.
Lorsque vous avez terminé, cliquez sur Enregistrer tout dans le menu Fichier, puis fermez le concepteur de manifestes.
Dans le menu Générer, cliquez sur Générer la solution. Assurez-vous que le projet se compile sans erreurs.
Cliquez sur le projet ProjectExtensionPackage dans l'Explorateur de solutions, cliquez sur le bouton Afficher tous les fichiers, puis ouvrez le dossier de sortie de la génération pour le projet ProjectExtensionPackage. Ce dossier doit maintenant contenir un fichier nommé ProjectExtensionPackage.vsix.

Par défaut, le dossier de sortie de la génération est le dossier .. \bin\Debug sous le dossier qui contient votre fichier projet.

Test de la propriété de projet

Vous êtes maintenant prêt à tester la propriété de projet personnalisée. Il est plus facile de déboguer et de tester la nouvelle extension de propriété de projet dans une instance expérimentale de Visual Studio. Il s'agit de l'instance de Visual Studio créée lorsque vous exécutez un projet VSIX ou un autre projet d'extensibilité. Après avoir débogué le projet, vous pouvez installer l'extension sur votre système, puis continuer à le déboguer et à le tester dans une instance normale de Visual Studio.

Pour déboguer et tester l'extension dans une instance expérimentale de Visual Studio

Redémarrez Visual Studio avec les informations d'identification d'administration et ouvrez la solution ProjectExtensionPackage.
Appuyez sur F5 pour démarrer une version Debug de votre projet.

Visual Studio installe l'extension du projet %UserProfile%\AppData\Local\Microsoft\VisualStudio\10.0Exp\Extensions\Contoso\Custom Project Property\1.0 et démarre une instance expérimentale de Visual Studio.
Dans l'instance expérimentale de Visual Studio, créez un projet SharePoint de solution de batterie, tel qu'un Module. Utilisez les valeurs par défaut pour les autres valeurs dans l'Assistant.
Dans l'Explorateur de solutions, cliquez sur le nœud du projet.

Une nouvelle propriété personnalisée Map Images Folder s'affiche dans la fenêtre Propriétés avec False comme valeur par défaut.
Remplacez la valeur de Map Images Folder par True.

Un dossier ressource Images est ajouté au projet SharePoint.
Remplacez la valeur de Map Images Folder par False.

Le dossier ressource Images est supprimé du projet SharePoint.
Fermez l'instance expérimentale de Visual Studio.