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

Artigo
08/01/2011

Anexa uma personalização no documento especificado usando o documento especificado, o nome de assembly, identificação da solução e 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 ao qual você deseja anexar uma personalização.

assemblyName
Tipo: System.String
O caminho completo do assembly para a personalização.O caminho deve estar no sistema de arquivos local ou em um compartilhamento UNC; é possível especificar uma localização HTTP.

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

deploymentManifestUrl
Tipo: System.Uri
A URL do manifesto da implantação da solução.

Exceções

Exceção	Condição
ArgumentNullException	documentPathor assemblyName is nulluma referência nula (Nothing no Visual Basic) or empty.
FileNotFoundException	documentPathou assemblyName se refere a um arquivo que não existe.
DocumentAlreadyCustomizedException	O documento especificado pelo documentPath já tem uma personalização.
DocumentNotCustomizedException	O documento especificado pelo documentPath está corrompido, ou tem permissões restritas.
UnknownCustomizationFileException	O documento especificado por documentPath tem uma extensão de nome de arquivo que não é suportada pelo Visual Studio Tools for Office runtime.

Comentários

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

O GUID que você passar para o solutionID parâmetro é especificado no manifesto do aplicativo da solução que você está anexando ao documento. Você deve passar o mesmo GUID que é especificado na solutionId atributo o vstov4:document elemento no manifesto do aplicativo. For more information, see Manifestos de aplicativo e implantação em soluções do Office and <document> Elemento (desenvolvimento do Office em Visual Studio).

Se você estiver anexando uma personalização de um local de publicação, certifique-se de que você especifique o nome de arquivo correto para o assembly no assemblyName parâmetro. Quando você publica uma solução Office, o assembly que é copiado para a pasta de publicação tem a extensão de nome de arquivo. Deploy. Por exemplo, se o nome do assembly for WordDocument1.dll, o nome do arquivo do assembly na pasta publicar é WordDocument1.dll.deploy. For more information, see Soluções do Office de publicação.

Se o documento especificado não contém um controle que a personalização espera que o documento para que, a AddCustomization método terá êxito, mas o assembly não será carregado quando o usuário abre o documento.

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

Exemplos

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

This example requires:

Um projeto de aplicativo de console ou algum outro projeto de não-Office.
Referências aos assemblies seguintes:
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll e Microsoft.VisualStudio.Tools.Applications.Runtime.dll (se os destinos do projeto de .NET Framework 4).
  
  or
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll e Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (se os destinos do projeto a.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.