ServerDocument.AddCustomization Method (String, Uri)
Attaches a customization to the specified document by using the specified assembly name and deployment manifest.
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, _
deploymentManifestUrl As Uri _
)
public static void AddCustomization(
string documentPath,
Uri deploymentManifestUrl
)
Parameters
documentPath
Type: System.StringThe full path of the document to which you want to attach a customization.
deploymentManifestUrl
Type: System.UriThe URL of the deployment manifest for the solution.
Exceptions
| Exception | Condition |
|---|---|
| ArgumentNullException | documentPath or deploymentManifestUrl is nulla null reference (Nothing in Visual Basic) 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. |
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.
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 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
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);
}
}
.NET Framework Security
- Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.