ServerDocument.AddCustomization 方法 (String, String, Guid, Uri)

项目
05/20/2013

使用指定的文档、程序集名称、解决方案 ID 和部署清单，将自定义项附加到指定文档。

命名空间： Microsoft.VisualStudio.Tools.Applications
程序集： Microsoft.VisualStudio.Tools.Applications.ServerDocument（在 Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll 中）

语法

声明
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
)

参数

documentPath
类型：System.String
要附加自定义项的文档的完整路径。

assemblyName
类型：System.String
自定义项的程序集的完整路径。该路径必须在本地文件系统上或作为 UNC 共享；不能指定 HTTP 位置。

solutionId
类型：System.Guid
Visual Studio Tools for Office Runtime 用来标识解决方案的 GUID。

deploymentManifestUrl
类型：System.Uri
解决方案部署清单的 URL。

异常

异常	条件
ArgumentNullException	documentPath 或 assemblyName 为 nullnull 引用（在 Visual Basic 中为 Nothing）或为空。
FileNotFoundException	documentPath 或 assemblyName 引用的文件不存在。
DocumentAlreadyCustomizedException	documentPath 指定的文档已具有自定义项。
DocumentNotCustomizedException	documentPath 指定的文档损坏，或其权限受限制。
UnknownCustomizationFileException	Visual Studio Tools for Office Runtime 不支持 documentPath 指定的文档的文件扩展名。

备注

通过将 _AssemblyName 和 _AssemblyLocation 自定义文档属性添加到文档中，AddCustomization 方法可将指定的自定义项与文档相关联。这些属性确认文档具有自定义项，并指定部署清单的位置。在成功调用此方法之后，当用户下次打开指定文档时，运行时将尝试安装 Office 解决方案。有关自定义文档属性的更多信息，请参见自定义文档属性概述。

传递到 solutionID 参数的 GUID 在附加到文档的解决方案的应用程序清单中指定。必须传递在应用程序清单中的 vstov4:document 元素的 solutionId 特性中指定的同一个 GUID。有关更多信息，请参见Office 解决方案中的应用程序和部署清单和<document> 元素（Visual Studio 中的 Office 开发）。

如果您要从发布位置附加自定义项，请确保为 assemblyName 参数中的程序集指定正确的文件名。在发布 Office 解决方案时，复制到发布文件夹的程序集的文件扩展名为 .deploy。例如，如果程序集名称为 WordDocument1.dll，则发布文件夹中的程序集的文件名为 WordDocument1.dll.deploy。有关更多信息，请参见使用 ClickOnce 部署 Office 解决方案。

如果指定的文档不包含自定义项要求文档包含的控件，AddCustomization 方法仍然能够成功，但在用户打开文档时程序集加载会失败。

fileType 参数必须指定一个这样的文档：其文件扩展名被 Microsoft Office Word 和 Microsoft Office Excel 的文档级自定义项支持。您不能将自定义附加到以 Word XML 文档 (*xml) 或 Word 2003 XML 文档 (*xml) 文件格式保存的文档。有关支持的文件类型的更多信息，请参见文档级自定义项的体系结构。

示例

下面的代码示例使用 AddCustomization 方法将自定义项附加到指定文档。

此示例需要：

控制台应用程序项目或某些其他非 Office 项目。
对下列程序集的引用：
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll 和 Microsoft.VisualStudio.Tools.Applications.Runtime.dll (如果项目面向 .NET Framework 4 或 .NET Framework 4.5)。
  
  或
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll 和 Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll（如果该项目面向 .NET Framework 3.5）。

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 安全性

对直接调用方的完全信任。此成员不能由部分信任的代码使用。有关更多信息，请参见通过部分受信任的代码使用库。

请参见

参考

ServerDocument 类

AddCustomization 重载

Microsoft.VisualStudio.Tools.Applications 命名空间

其他资源

Office 解决方案中的应用程序和部署清单

使用 ClickOnce 部署 Office 解决方案