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

Article
02/19/2013

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 au niveau de le projet par exemple lorsqu'un projet est ajouté, supprimé, renommé ou.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 Visual Studio.Cette procédure pas à pas se base sur le modèle Projet VSIX dans le Kit de développement logiciel (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 la barre de menus, sélectionnez Fichier, Nouveau, Projet.
Dans la boîte de dialogue Nouveau projet , développez les nœuds Visual C# ou Visual Basic , puis sélectionnez le nœud Extensibilité .

[!REMARQUE]

Ce nœud est disponible uniquement si vous installez le kit de développement Visual Studio.Pour plus d'informations, consultez la section des composants requis plus haut dans cette rubrique.
En haut de la boîte de dialogue, choisissez .NET Framework 4,5 dans la liste des versions du .NET Framework, puis choisissez le modèle projet VSIX .
Dans la zone Nom , entrez ProjectExtensionPackage, puis choisissez le bouton OK .

Le projet ProjectExtensionPackage apparaît dans Explorateur de solutions.

Pour créer le projet d'extension

Dans Explorateur de solutions, ouvrez le menu contextuel du nœud de solution, choisissez Ajouter, puis choisissez Nouveau projet.

[!REMARQUE]

Dans les projets d' Visual Basic , le nœud de la solution s'affiche dans Explorateur de solutions uniquement si la case à cocher Toujours solution show est sélectionnée dans General, Projects and Solutions, Options Dialog Box.
Dans la boîte de dialogue Nouveau projet , développez les nœuds Visual C# ou Visual Basic , puis choisissez Fenêtres.
En haut de la boîte de dialogue, choisissez .NET Framework 4,5 dans la liste des versions du .NET Framework, puis choisissez le modèle de projet Bibliothèque de classes .
Dans la zone Nom , entrez ProjectExtension, puis choisissez le bouton 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 fichier de code nommé CustomProperty au projet ProjectExtension.
Ouvrez le menu contextuel du projet ProjectExtension , puis choisissez Ajouter une référence.
Dans la boîte de dialogue gestionnaire de référence – CustomProperty , sélectionnez le nœud framework , puis activez la case à cocher en regard de les assemblys System.ComponentModel.Composition et System.Windows.Forms.
Sélectionnez le nœud Extensions , activez la case à cocher en regard de les assemblys Microsoft.VisualStudio.SharePoint et EnvDTE, puis choisissez le bouton OK .
Dans Explorateur de solutions, sous le dossier Références pour le projet ProjectExtension , choisissez 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

Collez le code suivant dans le fichier de code CustomProperty.

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 la barre de menus, sélectionnez Générer, 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 Explorateur de solutions, ouvrez le menu contextuel du fichier source.extension.vsixmanifest, puis choisissez le bouton Ouvrir .

Visual Studio ouvre le fichier dans le concepteur de manifestes.Les informations qui s'affichent dans l'onglet métadonnées également s'affichent dans Extensions et mises à jour. Tous les packages VSIX requièrent le fichier extension.vsixmanifest.Pour plus d'informations sur ce fichier, consultez Référence de schéma d'extensions VSIX.
Dans la zone nom de produit , entrez Propriété de projet personnalisée.
Dans la zone Author , entrez Contoso.
Dans la zone Description , entrez Une propriété personnalisée de projet SharePoint qui bascule le mappage du dossier ressource images au projet.
Sélectionnez l'onglet Composants , puis choisissez le bouton Nouveau .

La boîte de dialogue ajoutez le nouveau ressource s'affiche.
Dans la liste Type , choisissez Microsoft.VisualStudio.MefComponent.

[!REMARQUE]

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.
Dans la liste Source , sélectionnez la case d'option un projet dans la solution actuelle .
Dans la liste Projet , choisissez ProjectExtension.

Cette valeur identifie le nom de l'assembly que vous générez dans le projet.
Choisissez OK pour fermer la boîte de dialogue ajoutez le nouveau ressource .
Dans la barre de menus, sélectionnez Fichier, Enregistrer tout lorsque vous avez terminé, puis fermez le concepteur de manifestes.
Dans la barre de menus, sélectionnez Générer, Générer la solution, puis vérifiez que le projet se compile sans erreurs.
Dans Explorateur de solutions, ouvrez le menu contextuel du projet ProjectExtensionPackage , puis choisissez le bouton Ouvrir le dossier dans l'Explorateur de fichiers .
Dans Explorateur de fichiers, ouvrez le dossier de sortie de la génération pour le projet ProjectExtensionPackage, puis vérifiez que le répertoire contient 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 tester la nouvelle extension de propriété de projet dans une instance expérimentale de Visual Studio.Cette instance d' Visual Studio est créée lorsque vous exécutez un projet VSIX ou tout autre projet d'extensibilité.Après avoir mis au point le projet, vous pouvez installer l'extension sur votre système puis continuer à le déboguer et 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, puis ouvrez la solution ProjectExtensionPackage.
Démarrez une version debug de votre projet soit en choisissant la clé F5 ou, dans la barre de menus, choisissant Déboguer, Démarrer le débogage.

Visual Studio installe l'extension dans %UserProfile%\AppData\Local\Microsoft\VisualStudio\11.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 pour une solution de batterie, puis utilisez les valeurs par défaut pour les autres valeurs dans l'assistant.
1. Dans la barre de menus, sélectionnez Fichier, Nouveau, Projet.
2. En haut de la boîte de dialogue Nouveau projet , choisissez .NET Framework 3.5 dans la liste des versions du .NET Framework.
  
  Les extensions d'outils SharePoint nécessitent des fonctionnalités dans cette version de .NET Framework.
3. Sous le nœud Modèles , développez le nœud Visual C# ou Visual Basic , sélectionnez le nœud SharePoint , puis sélectionnez le nœud 2010 .
4. Sélectionnez le modèle Projet SharePoint 2010 , puis entrez ModuleTest comme nom de votre projet.
Dans Explorateur de solutions, sélectionnez le nœud de projet ModuleTest .

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 cette propriété par True.

Un dossier ressource Images est ajouté au projet SharePoint.
Remplacez la valeur de cette propriété à False.

Si vous choisissez le bouton oui dans la boîte de dialogue Supprimez le dossier images ? , le dossier ressource images est supprimé du projet SharePoint.
Fermez l'instance expérimentale de Visual Studio.