ServerDocument.AddCustomization-Methode (String, String, Guid, Uri)

Artikel
08/10/2011

Fügt mithilfe von Assemblynamen, Projektmappen-ID und Bereitsstellungsmanifest eine Anpassung an das angegebene Dokument an.

Namespace: Microsoft.VisualStudio.Tools.Applications
Assembly: Microsoft.VisualStudio.Tools.Applications.ServerDocument (in Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll)

Syntax

'Declaration
Public Shared Sub AddCustomization ( _
    documentPath As String, _
    assemblyName As String, _
    solutionId As Guid, _
    deploymentManifestUrl As Uri _
)

public static void AddCustomization(
    string documentPath,
    string assemblyName,
    Guid solutionId,
    Uri deploymentManifestUrl
)

Parameter

documentPath
Typ: System.String
Der vollständige Pfad des Dokuments, an das Sie eine Anpassung anfügen möchten.

assemblyName
Typ: System.String
Der vollständige Pfad der Assembly für die Anpassung.Der Pfad muss sich auf dem lokalen Dateisystem oder einer UNC-Freigabe befinden. Es können keine HTTP-Speicherorte angegeben werden.

solutionId
Typ: System.Guid
Eine GUID, die von Visual Studio Tools for Office-Laufzeit zum Identifizieren der Projektmappe verwendet wird.

deploymentManifestUrl
Typ: System.Uri
Die URL des Bereitstellungsmanifests für die Projektmappe.

Ausnahmen

Ausnahme	Bedingung
ArgumentNullException	documentPath oder assemblyName hat den Wert nullNULL-Verweis (Nothing in Visual Basic) oder ist leer.
FileNotFoundException	documentPath oder assemblyName verweist auf eine Datei, die nicht vorhanden ist.
DocumentAlreadyCustomizedException	Das in documentPath angegebene Dokument verfügt bereits über eine Anpassung.
DocumentNotCustomizedException	Das in documentPath angegebene Dokument ist fehlerhaft oder verfügt über eingeschränkte Berechtigungen.
UnknownCustomizationFileException	Das in documentPath angegebene Dokument hat eine Dateinamenerweiterung, die nicht von Visual Studio Tools for Office-Laufzeit unterstützt wird.

Hinweise

Die AddCustomization-Methode ordnet dem Dokument die angegebene Anpassung zu, indem dem Dokument die angepassten Eigenschaften _AssemblyName und _AssemblyLocation zugeordnet werden. Diese Eigenschaften erkennen, dass das Dokument über eine -Anpassung verfügt, und geben den Speicherort des Bereitstellungsmanifests an. Nachdem diese Methode erfolgreich aufgerufen wurde, versucht die Laufzeit beim nächsten Öffnen des angegebenen Dokuments durch einen Benutzer, die Office-Projektmappe zu installieren. Weitere Informationen über angepasste Dokumenteigenschaften finden Sie unter Übersicht über benutzerdefinierte Dokumenteigenschaften.

Die GUID, die Sie an den solutionID-Parameter übergeben, wird im Anwendungsmanifest der Projektmappe angegeben, die Sie an das Dokument anfügen. Sie müssen dieselbe GUID übergeben, die im solutionId-Attribut des vstov4:document-Elements im Anwendungsmanifest angegeben ist. Weitere Informationen finden Sie unter Anwendungs- und Bereitstellungsmanifeste in Office-Projektmappen und <document>-Element (Office-Entwicklung in Visual Studio).

Wenn Sie eine Anpassung aus einem Veröffentlichungsort anfügen, müssen Sie sicherstellen, dass Sie den richtigen Dateinamen für die Assembly im assemblyName-Parameter angeben. Wenn Sie eine Office-Projektmappe veröffentlichen, weist die Assembly, die in den Veröffentlichungsordner kopiert wird, die Dateinamenerweiterung .deploy auf. Wenn der Assemblyname beispielsweise WordDocument1.dll lautet, dann erhält die Datei der Assembly im Veröffentlichungsordner den Namen WordDocument1.dll.deploy. Weitere Informationen finden Sie unter Veröffentlichen von Office-Lösungen.

Falls ein von der Anpassung erwartetes Steuerelement nicht im angegebenen Dokument enthalten ist, wird zwar die AddCustomization-Methode erfolgreich ausgeführt, aber beim Öffnen des Dokuments durch den Benutzer wird die Assembly nicht geladen.

Der fileType-Parameter muss ein Dokument mit einer Dateinamenerweiterung angeben, das Anpassungen auf Dokumentebene für Microsoft Office Word und Microsoft Office Excel unterstützt. Sie können keine Anpassung an ein Dokument anfügen, das im Word-XML-Dokument- (*.xml) oder Word 2003-XML-Dokument-(*.xml)-Dateiformat gespeichert wird. Weitere Informationen zu den unterstützten Dateitypen finden Sie unter Architektur von Anpassungen auf Dokumentebene.

Beispiele

Im folgenden Codebeispiel wird die AddCustomization-Methode verwendet, um eine Anpassung an das angegebene Dokument anzuhängen.

Für dieses Beispiel sind erforderlich:

Ein Konsolenanwendungsprojekt oder ein anderes Nicht-Office-Projekt.
Verweise auf die folgenden Assemblys:
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll und Microsoft.VisualStudio.Tools.Applications.Runtime.dll (wenn das Projekt auf .NET Framework 4 abzielt)
  
  oder
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll und Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (wenn das Projekt auf .NET Framework 3.5 abzielt).

Private Sub AddCustomizationUsingAssemblyPath(ByVal documentPath As String, _
    ByVal assemblyName As String, ByVal solutionID As Guid, ByVal deployManifestPath As String)
    Dim runtimeVersion As Integer = 0

    Try
        ' Make sure that this document does not yet have any Visual Studio Tools 
        ' for Office customizations.
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
        If runtimeVersion = 0 Then
            Dim deploymentManifestUri As New Uri(deployManifestPath)
            ServerDocument.AddCustomization(documentPath, assemblyName, solutionID, deploymentManifestUri)
            MessageBox.Show("The document was successfully customized.")
        Else
            System.Windows.Forms.MessageBox.Show("The document is already customized.")
        End If

    Catch ex As System.IO.FileNotFoundException
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.")
    Catch ex As UnknownCustomizationFileException
        System.Windows.Forms.MessageBox.Show("The specified document has a file " & _
            "extension that is not supported by Visual Studio Tools for Office.")
    Catch ex As DocumentNotCustomizedException
        System.Windows.Forms.MessageBox.Show("The document could not be customized." & _
        vbLf & ex.Message)
    End Try
End Sub

private void AddCustomizationUsingAssemblyPath(string documentPath, string assemblyName, 
    Guid solutionID, string deployManifestPath)
{
    int runtimeVersion = 0;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);

        // Make sure that this document does not yet have any Visual Studio Tools 
        // for Office customizations.
        if (runtimeVersion == 0)
        {
            Uri deploymentManifestUri = new Uri(deployManifestPath);
            ServerDocument.AddCustomization(documentPath, assemblyName, solutionID, deploymentManifestUri);
            MessageBox.Show("The document was successfully customized.");
        }
        else
        {
            System.Windows.Forms.MessageBox.Show("The document is already customized.");
        }
    }
    catch (System.IO.FileNotFoundException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.");
    }
    catch (UnknownCustomizationFileException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document has a file " +
            "extension that is not supported by Visual Studio Tools for Office.");
    }
    catch (DocumentNotCustomizedException ex)
    {
        System.Windows.Forms.MessageBox.Show("The document could not be customized.\n" +
            ex.Message);
    }
}

.NET Framework-Sicherheit

Volle Vertrauenswürdigkeit für den unmittelbaren Aufrufer. Dieser Member kann von nur teilweise vertrauenswürdigem Code nicht verwendet werden. Weitere Informationen finden Sie unter Verwenden von Bibliotheken aus teilweise vertrauenswürdigem Code.