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

Artículo
08/10/2011

Asocia una personalización al documento especificado utilizando el documento, el nombre de ensamblado, el identificador de solución y el manifiesto de implementación indicados.

Espacio de nombres: Microsoft.VisualStudio.Tools.Applications
Ensamblado: Microsoft.VisualStudio.Tools.Applications.ServerDocument (en Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll)

Sintaxis

'Declaración
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
Ruta de acceso completa del documento al que desea asociar una personalización.

assemblyName
Tipo: System.String
Ruta de acceso completa del ensamblado de la personalización.La ruta de acceso debe estar en el sistema de archivos local o en un recurso compartido UNC; no se puede especificar una ubicación HTTP.

solutionId
Tipo: System.Guid
GUID que Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office usa para identificar la solución.

deploymentManifestUrl
Tipo: System.Uri
Dirección URL del manifiesto de implementación para la solución.

Excepciones

Excepción	Condición
ArgumentNullException	documentPath o assemblyName es nullreferencia null (Nothing en Visual Basic) o está vacío.
FileNotFoundException	documentPath o assemblyName hace referencia a un archivo que no existe.
DocumentAlreadyCustomizedException	El documento especificado por documentPath ya tiene una personalización.
DocumentNotCustomizedException	El documento especificado por documentPath está dañado o tiene permisos restringidos.
UnknownCustomizationFileException	El documento especificado por documentPath tiene una extensión de nombre de archivo que no es compatible con Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office.

Comentarios

Para asociar la personalización especificada al documento, el método AddCustomization agrega las propiedades de documento personalizado _AssemblyName y _AssemblyLocation al documento. Estas propiedades identifican que el documento tiene una personalización y especifica la ubicación del manifiesto de implementación. Después de llamar a este método correctamente, la siguiente vez que el usuario abra el documento especificado, el motor en tiempo de ejecución intentará instalar la solución de Office. Para obtener más información sobre las propiedades de documentos personalizados, vea Información general sobre propiedades personalizadas del documento.

El GUID que se pasa al parámetro solutionID se especifica en el manifiesto de aplicación de la solución que se está asociando al documento. Debe pasar el mismo GUID que se especificó en el atributo solutionId del elemento vstov4:document del manifiesto de aplicación. Para obtener más información, vea Manifiestos de implementación y aplicación en soluciones de Office y <document> (Elemento, Desarrollo de Office en Visual Studio).

Si está asociando una personalización desde una ubicación de publicación, asegúrese de que especifica el nombre de archivo correcto para el ensamblado en el parámetro assemblyName. Cuando publique una solución de Office, el ensamblado que se copia a la carpeta de publicación tendrá la extensión de nombre de archivo .deploy. Por ejemplo, si el nombre del ensamblado es DocumentoWord1.dll, el nombre de archivo del ensamblado que se encuentra en la carpeta de publicación es DocumentoWord1.dll.deploy. Para obtener más información, vea Publicar soluciones de Office.

Si el documento especificado no contiene ninguno de los controles que la personalización esperaba que tuviera, el método AddCustomization se ejecuta correctamente, pero el ensamblado no podrá cargarse cuando el usuario abra el documento.

El parámetro fileType debe especificar un documento que tiene una extensión de nombre de archivo que se admite para las personalizaciones de nivel de documento para Microsoft Office Word y Microsoft Office Excel. No puede adjuntar una personalización a un documento que está guardado en el documento XML de Word (* xml) o en formatos de archivo del documento XML de Word 2003 (* xml). Para obtener más información sobre los tipos de archivos compatibles, vea Arquitectura de las personalizaciones de nivel de documento.

Ejemplos

En el ejemplo de código siguiente se usa el método AddCustomization para adjuntar una personalización al documento especificado.

Este ejemplo necesita:

Un proyecto de aplicación de consola o algún otro proyecto que no es de Office.
Referencias a los siguientes ensamblados:
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll y Microsoft.VisualStudio.Tools.Applications.Runtime.dll (si el destino del proyecto es .NET Framework 4).
  
  O bien
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (si el proyecto está dirigido 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);
    }
}

Seguridad de .NET Framework

Plena confianza para el llamador inmediato. Un código de confianza parcial no puede utilizar este miembro. Para obtener más información, vea Utilizar bibliotecas de código que no es de plena confianza.