ServerDocument.AddCustomization Method

Reference

Definition

Namespace:: Microsoft.VisualStudio.Tools.Applications

Assembly:: Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Overloads

AddCustomization(String, Uri)	Attaches a customization to the specified document by using the specified assembly name and deployment manifest.
AddCustomization(String, String, Guid, Uri)	Attaches a customization to the specified document by using the specified document, assembly name, solution ID, and deployment manifest.
AddCustomization(String, String, Guid, Uri, Boolean, String[])

AddCustomization(String, Uri)

Attaches a customization to the specified document by using the specified assembly name and deployment manifest.

public:
 static void AddCustomization(System::String ^ documentPath, Uri ^ deploymentManifestUrl);

public static void AddCustomization (string documentPath, Uri deploymentManifestUrl);

static member AddCustomization : string * Uri -> unit

Public Shared Sub AddCustomization (documentPath As String, deploymentManifestUrl As Uri)

Parameters

documentPath: String

The full path of the document to which you want to attach a customization.

deploymentManifestUrl: Uri

The URL of the deployment manifest for the solution.

Exceptions

ArgumentNullException

documentPath or deploymentManifestUrl is null or empty.

ArgumentException

deploymentManifestUrl does not specify an absolute URL.

FileNotFoundException

documentPath or deploymentManifestUrl refers to a file that does not exist.

DocumentAlreadyCustomizedException

The document specified by documentPath already has a customization.

InvalidManifestException

The deployment manifest specified by deploymentManifestUrl is not a valid deployment manifest.

DocumentNotCustomizedException

The document specified by documentPath is corrupt, or has restricted permissions.

UnknownCustomizationFileException

The document specified by documentPath has a file name extension that is not supported by the Visual Studio Tools for Office runtime.

Examples

The following code example uses the AddCustomization method to attach a customization to the specified document.

This example requires:

A console application project or some other non-Office project.
References to the following assemblies:
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.dll (if the project targets the .NET Framework 4 or the .NET Framework 4.5).
  
  or
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (if the project targets the .NET Framework 3.5).
Imports (for Visual Basic) or using (for C#) statements for Microsoft.VisualStudio.Tools.Applications and Microsoft.VisualStudio.Tools.Applications.Runtime namespaces at the top of your code file.

private void AddCustomizationUsingDocumentPath(string documentPath, 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, 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);
    }
}

Private Sub AddCustomizationUsingDocumentPath(ByVal documentPath As String, _
    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, 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

Remarks

The AddCustomization method associates the specified customization with the document by adding the _AssemblyName and _AssemblyLocation custom document properties to the document. These properties identify that the document has a customization and specify the location of the deployment manifest. After this method is successfully called, the next time a user opens the specified document, the runtime will attempt to install the Office solution. For more information about the custom document properties, see Custom Document Properties Overview.

If the specified document does not contain a control that the customization expects the document to have, the AddCustomization method will succeed, but the assembly will fail to load when the user opens the document.

The fileType parameter must specify a document that has a file name extension that is supported for document-level customizations. You cannot attach a customization to a document that is saved in the Word XML Document (*xml) or Word 2003 XML Document (*xml) file formats. For more information about the supported file types, see Architecture of Document-Level Customizations.

Applies to

AddCustomization(String, String, Guid, Uri)

Attaches a customization to the specified document by using the specified document, assembly name, solution ID, and deployment manifest.

public:
 static void AddCustomization(System::String ^ documentPath, System::String ^ assemblyName, Guid solutionId, Uri ^ deploymentManifestUrl);

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

static member AddCustomization : string * string * Guid * Uri -> unit

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

Parameters

documentPath: String

The full path of the document to which you want to attach a customization.

assemblyName: String

The full path of the assembly for the customization. The path must be on the local file system or a UNC share; you cannot specify an HTTP location.

solutionId: Guid

A GUID that the Visual Studio Tools for Office runtime uses to identify the solution.

deploymentManifestUrl: Uri

The URL of the deployment manifest for the solution.

Exceptions

ArgumentNullException

documentPath or assemblyName is null or empty.

FileNotFoundException

documentPath or assemblyName refers to a file that does not exist.

DocumentAlreadyCustomizedException

The document specified by documentPath already has a customization.

DocumentNotCustomizedException

The document specified by documentPath is corrupt, or has restricted permissions.

UnknownCustomizationFileException

The document specified by documentPath has a file name extension that is not supported by the Visual Studio Tools for Office runtime.

Examples

The following code example uses the AddCustomization method to attach a customization to the specified document.

This example requires:

A console application project or some other non-Office project.
References to the following assemblies:
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.dll (if the project targets the .NET Framework 4 or the .NET Framework 4.5).
  
  or
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (if the project targets the .NET Framework 3.5).

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);
    }
}

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

Remarks

The AddCustomization method associates the specified customization with the document by adding the _AssemblyName and _AssemblyLocation custom document properties to the document. These properties identify that the document has a customization and specify the location of the deployment manifest. After this method is successfully called, the next time a user opens the specified document, the runtime attempts to install the Office solution. For more information about the custom document properties, see Custom Document Properties Overview.

The GUID that you pass to the solutionID parameter is specified in the application manifest of the solution that you are attaching to the document. You must pass the same GUID that is specified in the solutionId attribute of the vstov4:document element in the application manifest. For more information, see Application and Deployment Manifests in Office Solutions and <document> Element.

If you are attaching a customization from a publish location, make sure that you specify the correct file name for the assembly in the assemblyName parameter. When you publish an Office solution, the assembly that is copied to the publish folder has the .deploy file name extension. For example, if the assembly name is WordDocument1.dll, the file name of the assembly in the publish folder is WordDocument1.dll.deploy. For more information, see Deploying an Office Solution by Using ClickOnce.

The fileType parameter must specify a document that has a file name extension that is supported for document-level customizations for Microsoft Office Word and Microsoft Office Excel. You cannot attach a customization to a document that is saved in the Word XML Document (*xml) or Word 2003 XML Document (*xml) file formats. For more information about the supported file types, see Architecture of Document-Level Customizations.

Applies to

AddCustomization(String, String, Guid, Uri, Boolean, String[])

public:
 static void AddCustomization(System::String ^ documentPath, System::String ^ assemblyName, Guid solutionId, Uri ^ deploymentManifestUrl, bool runAsLocal, [Runtime::InteropServices::Out] cli::array <System::String ^> ^ % nonpublicCachedDataMembers);

public static void AddCustomization (string documentPath, string assemblyName, Guid solutionId, Uri deploymentManifestUrl, bool runAsLocal, out string[] nonpublicCachedDataMembers);

static member AddCustomization : string * string * Guid * Uri * bool * String[] -> unit

Public Shared Sub AddCustomization (documentPath As String, assemblyName As String, solutionId As Guid, deploymentManifestUrl As Uri, runAsLocal As Boolean, ByRef nonpublicCachedDataMembers As String())

Parameters

documentPath: String

assemblyName: String

solutionId: Guid

deploymentManifestUrl: Uri

runAsLocal: Boolean

nonpublicCachedDataMembers: String[]

Applies to

Partager via

ServerDocument.AddCustomization Method

Definition

Overloads

AddCustomization(String, Uri)

Parameters

Exceptions

Examples

Remarks

Applies to

AddCustomization(String, String, Guid, Uri)

Parameters

Exceptions

Examples

Remarks

Applies to

AddCustomization(String, String, Guid, Uri, Boolean, String[])

Parameters

Applies to

Ressources supplémentaires