Tutorial: Implementar una personalización de nivel de documento mediante un archivo de Windows Installer (2003 System)

Artículo
04/28/2010

Actualización: noviembre 2007

Se aplica a
La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados. Tipo de proyecto Proyectos de nivel de documento Versión de Microsoft Office Microsoft Office 2003 Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados.

Tipo de proyecto

Proyectos de nivel de documento

Versión de Microsoft Office

Microsoft Office 2003

Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

En este tutorial se muestra cómo crear un archivo de Microsoft Windows Installer (.msi) que se puede utilizar para implementar una personalización de nivel de documento. Para obtener más información sobre las personalizaciones de nivel de documento, vea Arquitectura de las personalizaciones de nivel de documento.

En este tutorial se muestran las tareas siguientes:

Crear un proyecto de instalación que se puede utilizar para generar un archivo de Windows Installer.
Modificar el proyecto de instalación para que el archivo de Windows Installer instale la solución de Visual Studio Tools para Office.
Agregar un paso al proyecto de instalación para que el archivo de Windows Installer edite el manifiesto de aplicación incrustado en el documento de la solución de Visual Studio Tools para Office.

Este tutorial supone que el equipo de destino ya tiene instalados los requisitos previos para ejecutar soluciones de Visual Studio Tools para Office. El archivo de Windows Installer que se genere no busca ni instala estos requisitos previos. Para obtener información sobre cómo instalar los requisitos previos, vea Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer. Para obtener información sobre los requisitos previos para ejecutar soluciones de Visual Studio Tools para Office, vea Cómo: Preparar equipos de usuarios finales para ejecutar soluciones de Office (2003 System).

Nota:
Antes de ejecutar la solución, se debe otorgar plena confianza a los ensamblados de soluciones de Visual Studio Tools para Office en la directiva de seguridad del usuario final. El archivo de Windows Installer que se genera en este tutorial no implementa la directiva de seguridad requerida para ejecutar la solución. Para obtener información sobre cómo agregar una acción personalizada para otorgar plena confianza al ensamblado de personalización, vea Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer. Para obtener información sobre la seguridad en las soluciones de Visual Studio Tools para Office, vea Requisitos de seguridad para ejecutar las soluciones de Office (2003 System) y Procedimientos recomendados sobre seguridad para soluciones de Office (2003 System). Para obtener información sobre el establecimiento de la directiva de seguridad en los equipos de los usuarios finales, vea Implementar la directiva de seguridad.

Antes de ejecutar la solución, se debe otorgar plena confianza a los ensamblados de soluciones de Visual Studio Tools para Office en la directiva de seguridad del usuario final. El archivo de Windows Installer que se genera en este tutorial no implementa la directiva de seguridad requerida para ejecutar la solución. Para obtener información sobre cómo agregar una acción personalizada para otorgar plena confianza al ensamblado de personalización, vea Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer. Para obtener información sobre la seguridad en las soluciones de Visual Studio Tools para Office, vea Requisitos de seguridad para ejecutar las soluciones de Office (2003 System) y Procedimientos recomendados sobre seguridad para soluciones de Office (2003 System). Para obtener información sobre el establecimiento de la directiva de seguridad en los equipos de los usuarios finales, vea Implementar la directiva de seguridad.

Requisitos previos

Necesita los componentes siguientes para completar este tutorial:

Visual Studio Tools para Office (componente opcional de Visual Studio 2008 Professional y Visual Studio Team System).
Microsoft Office Word 2003 o Microsoft Office Excel 2003.

Crear el proyecto

En este paso creará un proyecto de libro de Excel. Si desea ejecutar el tutorial con una solución existente de Word o Excel, comience este tutorial en la sección "Crear un proyecto de instalación" y reemplace el nombre del proyecto ExcelDeployment por el nombre de su proyecto en todos los ejemplos de códigos e instrucciones.

Para crear un nuevo proyecto

Cree un proyecto de libro de Excel con el nombre ExcelDeployment, utilizando la plantilla de proyecto para Office 2003.

En el asistente, seleccione Crear un nuevo documento. Para obtener más información, vea Cómo: Crear proyectos de Visual Studio para Office.

Visual Studio abre el nuevo libro de Excel en el diseñador y agrega el proyecto ExcelDeployment al Explorador de soluciones.

Agregar código subyacente al libro

El proyecto necesita código para comprobar que la solución está funcionando al abrir el documento. Para este tutorial, agregue un cuadro de mensaje al controlador de eventos Startup del libro.

Para agregar un cuadro de mensaje a un evento de inicialización

En el Explorador de soluciones, haga clic con el botón secundario del mouse en ThisWorkbook.vb o ThisWorkbook.cs y, a continuación, haga clic en Ver código en el menú de acceso directo.

Agregue el código siguiente al controlador de eventos Startup de la clase ThisWorkbook para que aparezca un cuadro de mensaje durante la inicialización.

Private Sub ThisWorkbook_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
    Handles Me.Startup

    MessageBox.Show("The workbook is deployed successfully.")
End Sub

private void ThisWorkbook_Startup(object sender, System.EventArgs e)
{
    MessageBox.Show("The workbook is deployed successfully.");
}

Presione F5 para ejecutar el proyecto.

Se inicia Excel y aparece el cuadro de mensaje.
Cierre el cuadro de mensaje.
Salga de Excel.

Crear un proyecto de instalación

Los proyectos de instalación proporcionan archivos y código que puede compilar para crear un archivo de Windows Installer para la solución. Para obtener más información, vea Proyectos de instalación.

Para crear un proyecto de instalación para la solución

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el nodo de la solución.
En el menú de acceso directo, elija Agregar y haga clic en Nuevo proyecto.

Aparecerá el cuadro de diálogo Agregar nuevo proyecto.
En el panel Tipos de proyecto, expanda el nodo Otros tipos de proyectos y seleccione Instalación e implementación.
En el panel Plantillas, seleccione Proyecto de instalación.
Dé al proyecto el nombre ExcelSetup.
Haga clic en Aceptar.

El proyecto de instalación aparecerá en el Explorador de soluciones. De manera predeterminada, el archivo de Windows Installer, que se generará mediante este proyecto de instalación, incluye un cuadro de diálogo que permite al usuario final especificar la ubicación de instalación de la solución. Para obtener más información, vea Carpeta de instalación (Cuadro de diálogo de la interfaz de usuario).

Agregar el libro y el ensamblado de la solución al proyecto de instalación

El resultado primario del proyecto ExcelDeployment consta del libro y el ensamblado de la solución. Agregue estos componentes al proyecto de instalación.

Para agregar el documento y el ensamblado al proyecto de instalación

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el nodo del proyecto ExcelSetup.
Elija Ver en el menú de acceso directo y, a continuación, haga clic en Sistema de archivos.
En el panel izquierdo, haga clic con el botón secundario del mouse en Carpeta de la aplicación.
En el menú de acceso directo, elija Agregar y haga clic en Resultados del proyecto.
Seleccione ExcelDeployment en el cuadro Proyecto.
Seleccione Resultado principal en la lista de tipos de resultados.
Haga clic en Aceptar.

El resultado del proyecto y las dependencias aparecen en el panel derecho.
En el Explorador de soluciones, expanda Dependencias detectadas, bajo el nodo del proyecto ExcelSetup.
Haga clic con el botón secundario del mouse en todas las dependencias, salvo en Microsoft .NET Framework y haga clic en Excluir en el menú de acceso directo.

Crear un proyecto de acción personalizada

Las acciones personalizadas son una característica de Windows Installer. Puede utilizarlas para ejecutar código al final del proceso de instalación para llevar a cabo acciones que no se pueden hacer durante la instalación. Para obtener más información, vea Acciones personalizadas.

Para crear un proyecto de acción personalizada

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el nodo de la solución.
En el menú de acceso directo, elija Agregar y haga clic en Nuevo proyecto.

Aparecerá el cuadro de diálogo Agregar nuevo proyecto.
En el panel Tipos de proyecto, expanda el nodo del lenguaje de programación y seleccione Windows.
En el panel Plantillas, seleccione Biblioteca de clases.
Dé al proyecto el nombre ExcelCustomAction.
Haga clic en Aceptar.

El nuevo proyecto aparecerá en el Explorador de soluciones.
En el Explorador de soluciones, haga clic con el botón secundario del mouse en Class1.vb o Class1.cs en el proyecto ExcelCustomAction y, a continuación, haga clic en Eliminar. Este archivo no es necesario para este tutorial.

Crear una acción personalizada que edite el manifiesto de aplicación

Anteriormente en este tutorial, cuando ejecutó el proyecto al presionar F5, el proceso de generación editó el manifiesto de aplicación incrustado en el libro, para indicar la ruta de acceso relativa del ensamblado. Si el libro y el ensamblado permanecen en la misma carpeta después de la instalación, entonces no será necesario modificar el manifiesto de aplicación incrustado y puede pasar por alto esta sección. Sin embargo, si desea habilitar al usuario para que mueva el libro a otra carpeta después de instalar la solución, debe editar el manifiesto de aplicación para que indique la ruta de acceso completa del ensamblado.

Debe actualizar el manifiesto de aplicación incrustado en el documento de la solución de Visual Studio Tools para Office, ejecutando una acción personalizada después de la instalación, ya que la ubicación del ensamblado de la solución no se conoce hasta que el usuario la especifica durante la instalación. Edite el manifiesto de aplicación incrustado utilizando la clase ServerDocument. Para utilizar la clase ServerDocument en el proyecto de instalación, agregue código a una clase Installer dentro del proyecto de acción personalizada.

Para crear una acción personalizada que edite el manifiesto de aplicación

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el proyecto ExcelCustomAction.
En el menú de acceso directo, elija Agregar y haga clic en Nuevo elemento.

Aparecerá el cuadro de diálogo Agregar nuevo elemento.
Seleccione Clase del instalador y dé a la clase el nombre ManifestEditor.
Agregue una referencia al ensamblado Microsoft.VisualStudio.Tools.Applications.Runtime para el proyecto ExcelCustomAction.
En el Explorador de soluciones, haga clic con el botón secundario del mouse en el archivo ManifestEditor.cs o ManifestEditor.vb y, a continuación, haga clic en Ver código.

Agregue la instrucción Imports o using a la parte superior del archivo de código.

Imports Microsoft.VisualStudio.Tools.Applications.Runtime

using Microsoft.VisualStudio.Tools.Applications.Runtime;

Copie el código siguiente en la clase ManifestEditor.

Este código reemplaza al método Install, que se utiliza para realizar acciones de instalación personalizadas. El código establece la ubicación de instalación especificada por el usuario en la propiedad AssemblyPath. La ruta de acceso de la instalación especificada por el usuario y los nombres del documento y del ensamblado se obtienen de la propiedad Parameters.

Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary)
    UpdateApplicationManifest()
    MyBase.Install(stateSaver)
End Sub

Private Sub UpdateApplicationManifest()

    ' Get the parameters passed to the task.
    Dim targetDir As String = Me.Context.Parameters("targetdir")
    Dim documentName As String = Me.Context.Parameters("documentname")
    Dim assemblyName As String = Me.Context.Parameters("assemblyname")

    ' Get the application manifest from the document.
    Dim documentPath As String = System.IO.Path.Combine(targetDir, documentname)
    Dim serverDocument1 As ServerDocument = New ServerDocument(documentPath, _
            System.IO.FileAccess.ReadWrite)

    Try
        Dim appManifest1 As AppManifest = serverDocument1.AppManifest
        Dim assemblyPath As String = System.IO.Path.Combine(targetDir, assemblyName)
        appManifest1.Dependency.AssemblyPath = assemblyPath
        serverDocument1.Save()

    Finally
        If Not serverDocument1 Is Nothing Then
            serverDocument1.Close()
        End If
    End Try
End Sub

// Override the Install method to update the customization location
// in the application manifest.
public override void Install(System.Collections.IDictionary stateSaver)
{
    UpdateApplicationManifest();
    base.Install(stateSaver);
}

// Update the application manifest according to the the install location.
private void UpdateApplicationManifest()
{
    // Get the parameters passed to the task.
    string targetDir = this.Context.Parameters["targetdir"];
    string documentName = this.Context.Parameters["documentname"];
    string assemblyName = this.Context.Parameters["assemblyname"];

    // Get the application manifest from the document.
    string documentPath = System.IO.Path.Combine(targetDir, documentName);
    ServerDocument serverDocument1 = new ServerDocument(documentPath,
        System.IO.FileAccess.ReadWrite);

    try
    {
        AppManifest appManifest1 = serverDocument1.AppManifest;
        string assemblyPath = System.IO.Path.Combine(targetDir, assemblyName);
        appManifest1.Dependency.AssemblyPath = assemblyPath;
        serverDocument1.Save();
    }
    finally
    {
        if (serverDocument1 != null)
        {
            serverDocument1.Close();
        }
    }
}

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el proyecto ExcelCustomAction y, a continuación, haga clic en Generar.

Agregar la acción personalizada al proyecto de instalación

Ahora puede habilitar el archivo Windows Installer para que ejecute la acción personalizada que edita el manifiesto de aplicación. Para ello, agregue el resultado principal del proyecto ExcelCustomAction al proyecto de instalación.

Para agregar el resultado primario del proyecto de acción personalizada al proyecto de instalación

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el nodo del proyecto ExcelSetup.
En el menú de acceso directo, elija Ver y, a continuación, haga clic en Acciones personalizadas.
En el Editor de acciones personalizadas, haga clic con el botón secundario del mouse en el nodo Instalar y haga clic en Agregar acción personalizada.
En el cuadro Buscar en, seleccione Carpeta de la aplicación y, a continuación, haga clic en Agregar resultado.
Seleccione ExcelCustomAction en el cuadro Proyecto.
Seleccione Resultado principal en la lista de tipos de resultado y, a continuación, haga clic en Aceptar.
Compruebe que Resultado principal de ExcelCustomAction (activo) se haya agregado a la lista de resultados primarios del proyecto de instalación y, a continuación, haga clic en Aceptar.
En el Editor de acciones personalizadas, expanda el nodo Instalar.
Haga clic con el botón secundario del mouse en Resultado principal de ExcelCustomAction (activo) y, a continuación, en Ventana Propiedades.
En la ventana Propiedades, establezca la propiedad CustomActionData en la siguiente cadena.
```
/targetdir="[TARGETDIR]\" /documentname="ExcelDeployment.xls" /assemblyname="ExcelDeployment.dll"
```
Para obtener información sobre la propiedad CustomActionData, vea CustomActionData (Propiedad).
En el Explorador de soluciones, haga clic con el botón secundario del mouse en el proyecto ExcelSetup y, a continuación, haga clic en Generar.

Probar el proyecto

Ahora, puede probar el proyecto para asegurarse de que la solución esté instalada cuando ejecute el archivo de Windows Installer en el equipo de desarrollo.

Para probar el proyecto

En el Explorador de soluciones, haga clic con el botón secundario del mouse en el proyecto ExcelSetup y, a continuación, haga clic en Ejecutar.
Siga las instrucciones del asistente de configuración y especifique una carpeta de instalación en el equipo de desarrollo.
Abra el libro de Excel en la carpeta de instalación.
Confirme que aparece el cuadro de mensaje.

Vea también

Compartir a través de