Exemplarische Vorgehensweise: Erstellen einer SharePoint-Projekterweiterung

Artikel
02/20/2013

Diese exemplarische Vorgehensweise veranschaulicht, wie eine Erweiterung für ein SharePoint-Projekt erstellt wird.Sie können eine Projekterweiterung verwenden, um auf Ereignisse auf Projektebene wie zu reagieren, wenn ein Projekt hinzugefügt, gelöscht oder umbenannt wurde.Sie können auch benutzerdefinierte Eigenschaften hinzufügen oder auf die Änderung eines Eigenschaftswerts reagieren.Im Gegensatz zu Projektelementerweiterungen können Projekterweiterungen einem bestimmten SharePoint-Projekttyp nicht zugeordnet werden.Wenn Sie eine Projekterweiterung erstellen, wird die Erweiterung bei jedem Öffnen eines SharePoint-Projekts in Visual Studio geladen.

In dieser exemplarischen Vorgehensweise erstellen wir eine benutzerdefinierte boolesche Eigenschaft, die jedem in Visual Studio erstellten SharePoint-Projekt hinzugefügt wird.Bei der Festlegung auf True wird dem Projekt von der neuen Eigenschaft ein Ressourcenordner für Bilder hinzugefügt oder zugewiesen.Bei der Festlegung auf False wird der Bilderordner ggf. entfernt.Weitere Informationen finden Sie unter Gewusst wie: Hinzufügen und Entfernen zugeordneter Ordner.

Diese exemplarische Vorgehensweise enthält die folgenden Aufgaben:

Erstellen einer Erweiterung Visual Studio für SharePoint-Projekte, mit der folgende Aufgaben ausgeführt werden können:
- Hinzufügen einer benutzerdefinierten Projekteigenschaft zum EigenschaftenfensterDie Eigenschaft gilt für jedes SharePoint-Projekt.
- Verwenden des SharePoint-Projektobjektmodells zum Hinzufügen eines zugeordneten Ordners zu einem Projekt
- Verwenden des Automatisierungsobjektmodells von Visual Studio zum Löschen eines zugeordneten Ordners aus dem Projekt
Erstellen eines Visual Studio-Erweiterungspakets (VSIX) zur Bereitstellung der Erweiterungsassembly der Projekteigenschaft
Debuggen und Testen der Projekteigenschaft

Vorbereitungsmaßnahmen

Zum Durchführen dieser exemplarischen Vorgehensweise werden auf dem Entwicklungscomputer die folgenden Komponenten benötigt:

Unterstützte Editionen von Microsoft Windows, SharePoint und Visual Studio.Weitere Informationen finden Sie unter Anforderungen für die Entwicklung von SharePoint-Lösungen.
Visual Studio SDK.In dieser exemplarischen Vorgehensweise wird die Vorlage VSIX Project im SDK verwendet, um ein VSIX-Paket zur Bereitstellung der Projekteigenschaftenerweiterung zu erstellen.Weitere Informationen finden Sie unter Erweitern der SharePoint-Tools in Visual Studio.

Erstellen der Projekte

Zum Abschließen dieser exemplarischen Vorgehensweise müssen Sie zwei Projekte erstellen:

Ein VSIX-Projekt für die Erstellung des VSIX-Pakets zum Bereitstellen der Projekterweiterung.
Ein Klassenbibliotheksprojekt, in das die Projekterweiterung implementiert wird.

Beginnen Sie mit der exemplarischen Vorgehensweise, indem Sie beide Projekte erstellen.

So erstellen Sie das VSIX-Projekt

Starten Sie Visual Studio.
Wählen Sie in der Menüleiste Datei, Neu, Projekt aus.

Im Dialogfeld Neues Projekt erweitern Sie die Visual C# oder Knoten Visual Basic, und wählen Sie dann den Knoten Erweiterungen aus.

Hinweis
Dieser Knoten ist nur verfügbar, wenn Sie das Visual Studio SDK installieren.Weitere Informationen finden Sie weiter oben in diesem Thema im Abschnitt zu den erforderlichen Komponenten.

am oberen Rand des Dialogfelds wählen Sie .NET Framework 4.5 in der Liste der Versionen von .NET Framework aus, und wählen Sie dann die Vorlage aus. VSIX-Projekt
Im Feld geben Sie NameProjectExtensionPackage ein und klicken Sie dann auf die Schaltfläche OK aus.

Das ProjectExtensionPackage Projekt wird in Projektmappen-Explorer.

So erstellen Sie das Erweiterungsprojekt

In Projektmappen-Explorer öffnen Sie das Kontextmenü für den Projektmappenknoten, wählen Sie Hinzufügen aus und wählen dann Neues Projekt aus.

Hinweis
In Visual Basic-Projekten wird der Projektmappenknoten in Projektmappen-Explorer, wenn das Kontrollkästchen Projektmappe immer anzeigen in General, Projects and Solutions, Options Dialog Box ausgewählt ist.

Im Dialogfeld Neues Projekt erweitern Sie die Visual C# oder Knoten Visual Basic, und wählen Sie dann Fenster aus.
am oberen Rand des Dialogfelds wählen Sie .NET Framework 4.5 in der Liste der Versionen von .NET Framework aus, und wählen Sie dann die Klassenbibliothek Projektvorlage aus.
Im Feld geben Sie NameProjectExtension ein und klicken Sie dann auf die Schaltfläche OK aus.

Visual Studio fügt das Projekt ProjectExtension zur aktuellen Projektmappe hinzu und öffnet die Class1-Codedatei.
Löschen Sie die Class1-Codedatei aus dem Projekt.

Konfigurieren des Projekts

Bevor Sie Code zum Erstellen der Projekterweiterung schreiben, fügen Sie dem Erweiterungsprojekt Codedateien und Assemblyverweise hinzu.

So konfigurieren Sie das Projekt

Fügen Sie eine Codedatei hinzu, die CustomProperty zum Namen trägt.
Öffnen Sie das Kontextmenü für das ProjectExtension Projekt, und wählen Sie dann Verweis hinzufügen aus.
Im Dialogfeld Verweis-Manager – CustomProperty wählen Sie den Knoten Framework aus, und wählen Sie dann das Kontrollkästchen neben den System.ComponentModel.Compositions- und System.Windows.Forms aus.
Wählen Sie den Knoten aus Erweiterungen, aktivieren Sie das Kontrollkästchen neben den Microsoft.VisualStudio.SharePoint- und EnvDTE-Assemblys aus, und wählen Sie dann die Schaltfläche OK aus.
In Projektmappen-ExplorerVerweise unter dem Ordner für das Projekt ProjectExtension, wählen Sie EnvDTE aus.
Ändern Sie im Fenster Eigenschaften den Wert der Eigenschaft Interoptypen einbetten in False.

Definieren der neuen SharePoint-Projekteigenschaft

Erstellen Sie eine Klasse, die die Projekterweiterung und das Verhalten der neuen Projekteigenschaft definiert.Zur Definition der neuen Projekterweiterung wird von der Klasse die ISharePointProjectExtension-Schnittstelle implementiert.Implementieren Sie diese Schnittstelle, wenn Sie eine Erweiterung für ein SharePoint-Projekt erstellen möchten.Fügen Sie der Klasse auch ExportAttribute hinzu.Anhand dieses Attributs kann Visual Studio die ISharePointProjectExtension-Implementierung erkennen und laden.Übergeben Sie den ISharePointProjectExtension-Typ an den Konstruktor des Attributs.

So definieren Sie die neue SharePoint-Projekteigenschaft

Fügen Sie folgenden Code in die CustomProperty-Codedatei ein.

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;

        }
    }
}

Erstellen der Lösung

Erstellen Sie als Nächstes die Lösung, um sicherzustellen, dass sie ohne Fehler kompiliert wird.

So erstellen Sie die Projektmappe

Klicken Sie auf der Menüleiste wählen Sie Erstellen, Projektmappe erstellen aus.

Erstellen eines VSIX-Pakets zur Bereitstellung der Projekteigenschaftenerweiterung

Zur Bereitstellung der Projekterweiterung verwenden Sie das VSIX-Projekt in der Lösung, um ein VSIX-Paket zu erstellen.Konfigurieren Sie zuerst das VSIX-Paket, indem Sie die im VSIX-Projekt enthaltene Datei "source.extension.vsixmanifest" ändern.Erstellen Sie anschließend das VSIX-Paket, indem Sie die Lösung erstellen.

So erstellen und konfigurieren Sie das VSIX-Paket

In Projektmappen-Explorer öffnen Sie das Kontextmenü für die source.extension.vsixmanifest-Datei, und wählen Sie dann die Schaltfläche Öffnen aus.

Visual Studio öffnet die Datei im Manifest-Designer.Die Informationen, die auf der Registerkarte Metadaten auch angezeigt wird, werden in Erweiterungen und Updates. Alle VSIX-Pakete benötigen die Datei " extension.vsixmanifest ".Weitere Informationen zu dieser Datei finden Sie unter VSIX-Erweiterungs-Schemareferenz.
Im Feld geben Sie ProduktnameBenutzerdefinierte Projekteigenschaft ein.
Im Feld geben Sie AutorContoso ein.
Im Feld geben Sie BeschreibungEine benutzerdefinierte SharePoint-Projekteigenschaft, die die Zuordnung des Imageressourcenordners dem Projekt umschaltet ein.
Wählen Sie die Registerkarte Objekte aus, und wählen Sie dann die Schaltfläche Neu aus.

Das Dialogfeld wird angezeigt. Neue Anlage hinzufügen

In der Liste wählen Sie TypMicrosoft.VisualStudio.MefComponent aus.

Hinweis
Dieser Wert entspricht dem MEFComponent-Element in der Datei "extension.vsixmanifest".Von diesem Element wird der Name einer Erweiterungsassembly im VSIX-Paket angegeben.Weitere Informationen finden Sie unter MEFComponent Element.

In der Liste Quelle wählen Sie das Optionsfeld Ein Projekt in der aktuellen Projektmappe.
In der Liste wählen Sie ProjektProjectExtension aus.

Dieser Wert bestimmt den Namen der Assembly, die Sie im Projekt erstellen.
Wählen Sie OKNeue Anlage hinzufügen, um das Dialogfeld zu schließen.
Klicken Sie auf der Menüleiste wählen Sie Datei, wenn Sie Alle speichern Ende, und schließen Sie dann den Manifest-Designer.
Klicken Sie auf der Menüleiste wählen Sie Erstellen, Projektmappe erstellen aus, und überprüfen Sie, dass das Projekt ohne Fehler kompiliert wird.
In Projektmappen-Explorer öffnen Sie das Kontextmenü für das ProjectExtensionPackage Projekt, und wählen Sie die Schaltfläche Ordner in Datei-Explorer öffnen aus.
In Explorer öffnen Sie den Buildausgabeordner für das ProjectExtensionPackage-Projekt, und überprüfen Sie, ob der Ordner eine Datei enthält, die ProjectExtensionPackage.vsix ".

Standardmäßig ist der Buildausgabeordner derOrdner "\bin\Debug" im Ordner mit der Projektdatei.

Testen der Projekteigenschaft

Sie sind nun bereit, die benutzerdefinierte Projekteigenschaft testen.Es ist am einfachsten, die neue Projekteigenschaftenerweiterung in einer experimentellen Instanz von Visual Studio zu debuggen und zu testen.Diese Instanz von Visual Studio wird erstellt, wenn Sie ein VSIX oder eines anderen Erweiterungsprojekts.Nachdem Sie das Projekt debuggen, können Sie die Erweiterung auf dem System installieren und anschließend fortfahren, um es in einer regulären Instanz von Visual Studio zu debuggen und zu testen.

So debuggen und testen Sie die Erweiterung in einer experimentellen Instanz von Visual Studio

Starten Sie neu Visual Studio mit Administratorrechten, und öffnen Sie dann die öffnen.
Starten Sie einen Debugbuild des Projekts entweder, indem Sie die F5 Schlüssel oder, auf der Menüleiste auswählen und Debuggen, Debuggen starten auswählen.

Visual Studio installiert die Erweiterung in %UserProfile%\AppData\Local\Microsoft\VisualStudio\11.0Exp\Extensions\Contoso\Custom Project Property\1.0 und startet eine experimentelle Instanz von Visual Studio.
Klicken Sie in der experimentellen Instanz von Visual Studio, erstellen Sie ein SharePoint-Projekt für eine Farmlösung, und verwenden Sie die Standardwerte für die anderen Werte im Assistenten.
1. Wählen Sie in der Menüleiste Datei, Neu, Projekt aus.
2. Neues Projekt am oberen Rand des Dialogfelds wählen Sie .NET Framework 3.5 in der Liste der Versionen von .NET Framework aus.
  
  SharePoint-Toolerweiterungen benötigen Funktionen in dieser Version .NET Framework.
3. Vorlagen unter dem Knoten erweitern Sie den Visual C# oder Knoten Visual Basic, wählen Sie den Knoten SharePoint aus, und wählen Sie dann den Knoten 2010 aus.
4. Wählen Sie die SharePoint 2010-Projekt Vorlage aus, und geben Sie dann ModuleTest als Namen des Projekts ein.
In Projektmappen-Explorer wählen Sie den ModuleTest Projektknoten aus.

Ein neue benutzerdefinierte Eigenschaft zur Zuweisung des Bilderordners wird im Fenster Eigenschaften mit dem Standardwert False angezeigt.
Ändern Sie den Wert dieser Eigenschaft auf True.

Dem SharePoint-Projekt wird ein Ressourcenordner für Bilder hinzugefügt.
Ändern Sie den Wert dieser Eigenschaft zurück zu False.

Wenn Sie die Schaltfläche Ja im Dialogfeld Löschen Sie den Ordner Images? auswählen, wird der Ressourcenordner für Bilder aus dem SharePoint-Projekt gelöscht.
Schließen Sie die experimentelle Instanz von Visual Studio.