Procedura dettagliata: creazione di un'estensione di progetto SharePoint

Articolo
02/18/2013

Questa procedura dettagliata illustra come creare un'estensione per i progetti SharePoint.È possibile utilizzare un'estensione di progetto per rispondere a eventi a livello di progetto come quando un progetto viene aggiunta, eliminazione, o viene rinominato.È inoltre possibile aggiungere proprietà personalizzate o rispondere a un evento di modifica di un valore di proprietà.A differenza delle estensioni di elemento di progetto, le estensioni di progetto non possono essere associate a un particolare tipo di progetto SharePoint.Quando si crea un'estensione di progetto, questa viene caricata quando si apre in Visual Studio un qualsiasi tipo di progetto SharePoint.

In questa procedura dettagliata si creerà una proprietà booleana personalizzata che viene aggiunta a qualsiasi progetto SharePoint creato in Visual Studio.Quando impostata su True, la nuova proprietà aggiunge o associa al progetto una cartella di risorse denominata Images.Quando impostata su False, la cartella Images viene rimossa, se esiste.Per ulteriori informazioni, vedere Procedura: aggiungere e rimuovere cartelle mappate.

In questa procedura dettagliata vengono illustrate le attività seguenti:

Creazione di un'estensione di Visual Studio per progetti SharePoint che eseguono le operazioni seguenti:
- Aggiunta di una proprietà di progetto personalizzata alla finestra Proprietà.La proprietà si applica a qualsiasi progetto SharePoint.
- Utilizzo del modello a oggetti del progetto SharePoint per aggiungere a un progetto una cartella mappata.
- Utilizzo del modello a oggetti di automazione di Visual Studio (DTE) per eliminare una cartella mappata dal progetto.
Compilazione di un pacchetto Visual Studio Extension (VSIX) per l'assembly dell'estensione della proprietà di progetto.
Debug e test della proprietà di progetto.

Prerequisiti

Per completare la procedura dettagliata, nel computer di sviluppo devono essere presenti i componenti elencati di seguito:

Edizioni supportate di Microsoft Windows, SharePoint e Visual Studio.Per ulteriori informazioni, vedere Requisiti per lo sviluppo di soluzioni SharePoint.
Campo Visual Studio SDK.In questa procedura dettagliata viene utilizzato il modello VSIX Project di SDK per creare un pacchetto VSIX allo scopo di distribuire l'estensione della proprietà di progetto.Per ulteriori informazioni, vedere Estensione degli strumenti di SharePoint in Visual Studio.

Creazione dei progetti

Per completare questa procedura dettagliata è necessario creare due progetti:

Un progetto VSIX per creare il pacchetto VSIX allo scopo di distribuire l'estensione di progetto.
Un progetto Libreria di classi che implementa l'estensione di progetto.

Iniziare la procedura dettagliata creando i progetti.

Per creare il progetto VSIX

Avviare Visual Studio.
Sulla barra dei menu, scegliere Il file, Nuova, Project.
Nella finestra di dialogo Nuovo progetto, espandere i nodi Visual Basic o Visual C# quindi selezionare il nodo Extensibility.

[!NOTA]

Questo nodo è disponibile solo se si installa Visual Studio SDK.Per ulteriori informazioni, vedere la sezione precedente relativa ai prerequisiti.
Nella parte superiore della finestra di dialogo, scegliere .NET Framework 4.5 nell'elenco delle versioni di.NET Framework e quindi scegliere il modello Progetto VSIX.
Nella casella Nome, immettere ProjectExtensionPackagequindi scegliere il pulsante OK.

Il progetto ProjectExtensionPackage visualizzato in Esplora soluzioni.

Per creare il progetto di estensione

In Esplora soluzioni, aprire il menu di scelta rapida del nodo della soluzione, scegliere Aggiungiquindi scegliere Nuovo progetto.

[!NOTA]

Nei progetti Visual Basic, il nodo della soluzione viene visualizzato in Esplora soluzioni solo se la casella di controllo Mostra sempre soluzione è selezionata in General, Projects and Solutions, Options Dialog Box.
Nella finestra di dialogo Nuovo progetto, espandere i nodi Visual Basic o Visual C# quindi scegliere Finestre.
Nella parte superiore della finestra di dialogo, scegliere .NET Framework 4.5 nell'elenco delle versioni di.NET Framework e quindi scegliere il modello di progetto Libreria di classi.
Nella casella Nome, immettere ProjectExtensionquindi scegliere il pulsante OK.

Visual Studio aggiunge il progetto ProjectExtension alla soluzione e apre il file di codice predefinito Class1.
Eliminare il file di codice Class1 dal progetto.

Configurazione del progetto

Prima di scrivere il codice per creare l'estensione di progetto, aggiungere al progetto di estensione file di codice e riferimenti all'assembly.

Per configurare il progetto

Aggiungere un file di codice denominato CustomProperty al progetto ProjectExtension.
Aprire il menu di scelta rapida del progetto ProjectExtension quindi scegliere Aggiungi riferimento.
Nella finestra di dialogo Gestione riferimenti – CustomProperty, selezionare il nodo Framework quindi selezionare la casella di controllo accanto agli assembly System.Windows.Forms e System.ComponentModel.Composition.
Scegliere il nodo Estensioni, selezionare la casella di controllo accanto agli assembly EnvDTE e Microsoft.VisualStudio.SharePoint quindi scegliere il pulsante OK.
In Esplora soluzioni, nella cartella Riferimenti per il progetto ProjectExtension, scegliere EnvDTE.
Nella finestra Proprietà, modificare la proprietà Incorpora tipi di interoperabilità in False.

Definizione della nuova proprietà di progetto SharePoint

Creare una classe che definisce l'estensione di progetto e il comportamento della nuova proprietà di progetto.Per definire la nuova estensione di progetto, la classe implementa l'interfaccia ISharePointProjectExtension.Implementare questa interfaccia ogni volta che si desidera definire un'estensione di un progetto SharePoint.Inoltre, aggiungere l'oggetto ExportAttribute alla classe.Questo attributo consente a Visual Studio di individuare e caricare l'implementazione di ISharePointProjectExtension.Passare il tipo ISharePointProjectExtension al costruttore dell'attributo.

Per definire la nuova proprietà di progetto SharePoint

Incollare il codice seguente nel file di codice 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;

        }
    }
}

Compilazione della soluzione

A questo punto occorre compilare la soluzione per garantire che non vi siano errori di compilazione.

Per compilare la soluzione

Sulla barra dei menu, scegliere Compilazione, Compila soluzione.

Creazione di un pacchetto VSIX per distribuire l'estensione della proprietà di progetto

Per distribuire l'estensione di progetto, utilizzare il progetto VSIX nella soluzione per creare un pacchetto VSIX.Anzitutto, configurare il pacchetto VSIX modificando il file source.extension.vsixmanifest incluso nel progetto VSIX.Successivamente, creare il pacchetto VSIX compilando la soluzione.

Per configurare e creare il pacchetto VSIX

In Esplora soluzioni, aprire il menu di scelta rapida per il file source.extension.vsixmanifest quindi scegliere il pulsante Apri.

Visual Studio apre il file nella finestra di progettazione del manifesto.Le informazioni visualizzate nella scheda Metadati vengono visualizzati anche in Estensioni e aggiornamenti. Tutti i pacchetti VSIX richiedono il file extension.vsixmanifest.Per ulteriori informazioni su questo file, vedere Informazioni di riferimento sullo schema dell'estensione VSIX.
Nella casella Nome prodotto, immettere Proprietà di progetto personalizzata.
Nella casella Autore, immettere Contoso.
Nella casella Descrizione, immettere Una proprietà di progetto personalizzata di SharePoint che passa il mapping della cartella di risorse denominata images al progetto.
Scegliere la scheda Asset quindi scegliere il pulsante Nuova.

La finestra di dialogo Aggiungi nuovo asset visualizzato.
Nell'elenco Tipo, scegliere Microsoft.VisualStudio.MefComponent.

[!NOTA]

Questo valore corrisponde all'elemento MEFComponent del file extension.vsixmanifest.Questo elemento specifica il nome di un assembly dell'estensione nel pacchetto VSIX.Per ulteriori informazioni, vedere MEFComponent Element.
Nell'elenco Alimentazione, scegliere il pulsante di opzione Progetto nella soluzione corrente.
Nell'elenco Project, scegliere ProjectExtension.

Questo valore identifica il nome dell'assembly che si compila il progetto.
Scegliere OK per chiudere la finestra di dialogo Aggiungi nuovo asset.
Sulla barra dei menu, scegliere Il file, Salva tutto quando si completa e chiudere la finestra di progettazione del manifesto.
Sulla barra dei menu, scegliere Compilazione, Compila soluzionequindi assicurarsi che il progetto venga compilato senza errori.
In Esplora soluzioni, aprire il menu di scelta rapida del progetto ProjectExtensionPackage e scegliere il pulsante Apri cartella in Esplora file.
In Esplora file, aprire la cartella di output di compilazione per il progetto ProjectExtensionPackage e verificare che la cartella contiene un file denominato ProjectExtensionPackage.vsix.

Per impostazione predefinita, la cartella dell'output di compilazione è ..\bin\Debug sotto la cartella che contiene il file di progetto.

Test della proprietà di progetto

È ora possibile testare la proprietà di progetto personalizzata.È più facile eseguire il debug e il test della nuova estensione di proprietà di progetto in un'istanza sperimentale Visual Studio.Questa istanza Visual Studio viene creata quando si esegue un progetto VSIX o altro progetto di estensibilità.Dopo aver eseguito il debug del progetto, è possibile installare l'estensione nel sistema e quindi continuare a eseguire il debug e il test in un'istanza normale Visual Studio.

Per eseguire il debug e il test dell'estensione in un'istanza sperimentale di Visual Studio

Riavviare Visual Studio con credenziali amministrative e aprire la soluzione ProjectExtensionPackage.
Avviare una compilazione di debug del progetto scegliendo la chiave F5 o, sulla barra dei menu, scegliente Debug, Avvia debug.

Visual Studio i file di estensione vengono installati in %UserProfile% \ AppData \ local \ Microsoft \ VisualStudio \ 11.0Exp \ extensions \ Contoso \ project property \ 1,0 e viene avviata un'istanza sperimentale Visual Studio.
Nell'istanza sperimentale Visual Studio, creare un progetto SharePoint per una soluzione farm e utilizzare i valori predefiniti per gli altri valori nella procedura guidata.
1. Sulla barra dei menu, scegliere Il file, Nuova, Project.
2. Nella parte superiore della finestra di dialogo Nuovo progetto, scegliere .NET Framework 3.5 nell'elenco delle versioni di.NET Framework.
  
  Le estensioni degli strumenti di SharePoint richiedono alcune funzionalità di questa versione .NET Framework.
3. Nel nodo Modelli, espandere il nodo Visual Basic o Visual C#, selezionare il nodo SharePoint quindi selezionare il nodo 2010.
4. Scegliere il modello Progetto SharePoint 2010 quindi immettere ModuleTest come nome del progetto.
In Esplora soluzioni, selezionare il nodo del progetto ModuleTest.

Una nuova proprietà personalizzata denominata Map Images Folder verrà visualizzata nella finestra Proprietà con il valore predefinito False.
Modificare il valore di questa proprietà su True.

Una cartella di risorse denominata Images verrà aggiunta al progetto SharePoint.
Modificare il valore di questa proprietà su False.

Se si sceglie il pulsante Sì nella finestra di dialogo Eliminare la cartella Immagini?, la cartella di risorse denominata images verrà eliminato dal progetto SharePoint.
Chiudere l'istanza sperimentale di Visual Studio.