Método ServerDocument.AddCustomization (String, String, Guid, Uri)

Artigo
05/21/2013

Anexar uma personalização documento especificado usando o documento, o nome do assembly, a identificação de solução, e especificados o manifesto de implantação.

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

Sintaxe

'Declaração
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
)

Parâmetros

documentPath
Tipo: System.String
O caminho completo do documento a que você deseja anexar uma personalização.

assemblyName
Tipo: System.String
O caminho completo do conjunto para personalização.O caminho deve estar no sistema de arquivos local ou em um compartilhamento UNC; você não pode especificar um local HTTP.

solutionId
Tipo: System.Guid
Um GUID que Visual Studio Tools for Office Runtime usa para identificar a solução.

deploymentManifestUrl
Tipo: System.Uri
O URL de manifesto de implantação para a solução.

Exceções

Exceção	Condição
ArgumentNullException	documentPath ou assemblyName são nulluma referência nula (Nothing no Visual Basic) ou vazio.
FileNotFoundException	documentPath ou assemblyName referem-se a um arquivo que não existe.
DocumentAlreadyCustomizedException	O documento especificado por documentPath já tiver uma personalização.
DocumentNotCustomizedException	O documento especificado por documentPath estiver corrompida, ou restringiu permissões.
UnknownCustomizationFileException	O documento especificado por documentPath possui uma extensão de nome de arquivo que não é suportada por Visual Studio Tools for Office Runtime.

Comentários

O método de AddCustomization associa a personalização especificada com o documento adicionando propriedades personalizadas do documento de _AssemblyName e de _AssemblyLocation ao documento.Essas propriedades que identificam o documento tem uma personalização e especifique o local do manifesto de implantação.Após esse método é chamado com êxito, a próxima vez que um usuário abre o documento especificado, o tempo de execução tentar instalar a solução do Office.Para obter mais informações sobre propriedades personalizadas do documento, consulte Visão geral sobre propriedades de documento personalizado.

Um GUID que você passa para o parâmetro de solutionID é especificado no manifesto do aplicativo de solução que você está anexando ao documento.Você deve passar o mesmo que é especificado no atributo de solutionId do elemento de vstov4:document no manifesto do aplicativo.Para obter mais informações, consulte Manifestos de aplicativo e implantação em soluções do Office e <document> Elemento (desenvolvimento do Office em Visual Studio).

Se você estiver anexar uma personalização de um local de publicação, certifique-se que você especifica o nome de arquivo correto para o assembly no parâmetro de assemblyName .Quando você publica uma solução do Office, o assembly que é copiado para a pasta publicar tem a extensão de nome de arquivo .deploy.Por exemplo, se o nome do assembly é WordDocument1.dll, o nome de arquivo do assembly na pasta publicação é WordDocument1.dll.deploy.Para obter mais informações, consulte Implantando uma solução do Office usando o ClickOnce.

Se o documento especificado não contém um controle que personalização espera ter o documento, o método de AddCustomization funcionará com, mas o assembly não carregará quando o usuário abre o documento.

O parâmetro de fileType deve especificar um documento que tem uma extensão de nome de arquivo que é suportada para personalizações da nível do Microsoft Office Word e Microsoft Office Excel.Você não pode anexar uma personalização um documento que é salvo no documento XML (*xml Word) ou exprimir formatos de arquivo 2003 do documento XML (*xml).Para obter mais informações sobre tipos de arquivo suportados, consulte o Arquitetura de personalizações em nível de documento.

Exemplos

O exemplo de código a seguir usa o método de AddCustomization para anexar uma personalização documento especificado.

Este exemplo requer:

Um projeto de aplicativo do console ou qualquer outro projeto do Office não.
Referências para os seguintes conjuntos de módulos (assemblies):
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll e Microsoft.VisualStudio.Tools.Applications.Runtime.dll (se o projeto utiliza .NET Framework 4 ou .NET Framework 4.5).
  
  ou
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll e Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (se o projeto utiliza o .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);
    }
}

Segurança do .NET Framework

Confiança total para o chamador imediato. O membro não pode ser usado por código parcialmente confiável. Para obter mais informações, consulte Usando bibliotecas de código parcialmente confiáveis.