Compartir a través de

Llamar a código de VBA en personalizaciones de nivel de documento

  • Artículo

Puede configurar un proyecto de nivel de documento para Word o Excel de forma que el código de Visual Basic para Aplicaciones (VBA) del documento pueda llamar al código del ensamblado de personalización. Esto resulta útil en los escenarios siguientes:

  • Si desea extender el código de VBA existente de un documento utilizando las características de una personalización de nivel de documento que esté asociada al mismo documento.

  • Si desea que los servicios que desarrolla con una personalización de nivel de documento estén a disposición de los usuarios finales que pueden obtener acceso a estos servicios escribiendo código de VBA en el documento.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de documento para las siguientes aplicaciones: Excel 2007 y Excel 2010; Word 2007 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

Las herramientas de desarrollo de Office en Visual Studio proporcionan una característica similar para los complementos de nivel de aplicación. Si está desarrollando un complemento, puede llamar al código del complemento desde otras soluciones de Microsoft Office. Para obtener más información, consulte Llamar a código en complementos de nivel de aplicación desde otras soluciones de Office.

Nota

Esta característica no se puede usar en los proyectos de plantilla de Word. Sólo se puede utilizar en proyectos de documentos de Word, libros de Excel o plantillas de Excel.

Requisitos

Antes de poder permitir que el código de VBA llame a miembros del ensamblado de personalización, el proyecto debe cumplir los siguientes requisitos:

  • El documento debe tener una de las extensiones de nombre de archivo siguientes:

    • Para Word: .docm o .doc

    • En Excel: .xlsm, .xltm, .xls o .xlt

  • El documento debe contener con anterioridad un proyecto de VBA que tenga código de VBA.

  • El código de VBA del documento debe poder ejecutarse sin que se le pregunte al usuario si desea habilitar las macros. Puede confiar en que el código de VBA se ejecute si agrega la ubicación del proyecto de Office a la lista de ubicaciones de confianza en las opciones del Centro de confianza de Word o Excel.

  • El proyecto de Office debe contener por lo menos una clase pública que tenga uno o varios de los miembros públicos que está exponiendo a VBA.

    Puede exponer métodos, propiedades y eventos a VBA. La clase que exponga puede ser una clase de elemento de host (como ThisDocument en Word o ThisWorkbook y Sheet1 en Excel) u otra clase que defina en el proyecto. Para obtener más información acerca de los elementos de host, vea Información general sobre elementos y controles Host.

Permitir que el código de VBA llame a miembros del ensamblado de personalización

Hay dos maneras diferentes en las que puede exponer los miembros de un ensamblado de personalización al código de VBA del documento:

  • Puede exponer miembros de una clase de elemento de host de un proyecto de Visual Basic a VBA. Para ello, establezca la propiedad EnableVbaCallers del elemento host en True en la ventana Propiedades mientras el elemento host (es decir, el documento, la hoja de cálculo o el libro) está abierto en el diseñador. Visual Studio realiza automáticamente todas las tareas necesarias para que el código de VBA pueda llamar a los miembros de la clase.

  • Puede exponer los miembros de cualquier clase pública de un proyecto de Visual C# o los miembros de una clase de elemento no hospedado de un proyecto de Visual Basic a VBA. Esta opción le da más libertad para elegir qué clases va a exponer a VBA, pero también requiere más pasos manuales.

    Para ello, debe realizar los pasos principales que se detallan a continuación:

    1. Exponga la clase a COM.

    2. Invalide el método GetAutomationObject de una clase de elemento de host de su proyecto para devolver una instancia de la clase que está exponiendo a VBA.

    3. Establezca la propiedad ReferenceAssemblyFromVbaProject de cualquier clase de elemento de host del proyecto en True. Esto incrusta la biblioteca de tipos del ensamblado de personalización en el ensamblado y agrega una referencia de la biblioteca de tipos al proyecto de VBA del documento.

Para obtener instrucciones detalladas, vea Cómo: Exponer código a VBA en un proyecto de Visual Basic y Cómo: Exponer código a VBA en un proyecto de Visual C#.

Las propiedades EnableVbaCallers y ReferenceAssemblyFromVbaProject sólo están disponibles en la ventana Propiedades en tiempo de diseño, y no se pueden utilizar en tiempo de ejecución. Para ver las propiedades, abra el diseñador de un elemento de host en Visual Studio. Para obtener más información sobre las tareas específicas que Visual Studio realiza cuando se establecen estas propiedades, vea Tareas realizadas por las propiedades del elemento host.

Nota

Si el libro o el documento aún no contiene código de VBA o si no se confía en el código de VBA del documento para su ejecución, aparecerá un mensaje de error al establecer la propiedad EnableVbaCallers o ReferenceAssemblyFromVbaProject en True. Esto se debe a que Visual Studio no puede modificar el proyecto de VBA del documento cuando se da esta situación.

Utilizar miembros del código de VBA para llamar a miembros del ensamblado de personalización

Después de configurar el proyecto de modo que el código de VBA pueda llamar al ensamblado de personalización, Visual Studio agrega los miembros siguientes al proyecto de VBA del documento:

  • Para todos los proyectos, Visual Studio agrega un método global denominado GetManagedClass.

  • Para los proyectos de Visual Basic en los que se exponen miembros de una clase de elementos host mediante la propiedad EnableVbaCallers, Visual Studio también agrega una propiedad denominada CallVSTOAssembly al módulo ThisDocument, ThisWorkbook, Sheet1, Sheet2 o Sheet3 del proyecto de VBA.

Puede utilizar la propiedad CallVSTOAssembly o el método GetManagedClass para obtener acceso a los miembros públicos de la clase expuesta al código de VBA en el proyecto.

Nota

Mientras desarrolla e implementa su solución, hay varias copias diferentes del documento en las que puede agregar el código de VBA. Para obtener más información, vea Instrucciones para agregar código de VBA al documento.

Utilizar la propiedad CallVSTOAssembly en un proyecto de Visual Basic

Utilice la propiedad CallVSTOAssembly para tener acceso a los miembros públicos que agregó a la clase de elemento de host. Por ejemplo, la siguiente macro de VBA llama a un método denominado MyVSTOMethod que se define en la clase Sheet1 en un proyecto de libro de Excel.

Sub MyMacro()
    Sheet1.CallVSTOAssembly.MyVSTOMethod()
End Sub

Esta propiedad representa una manera más práctica de llamar al ensamblado de personalización que usar directamente el método GetManagedClass. CallVSTOAssembly devuelve un objeto que representa la clase de elementos host que se ha expuesto a VBA. Los miembros y parámetros de método del objeto devuelto aparecen en IntelliSense.

La propiedad CallVSTOAssembly tiene una declaración similar al código siguiente. En este código se presupone que la clase de elemento de host Sheet1 de un proyecto de libro de Excel denominado ExcelWorkbook1 se ha expuesto a VBA.

Property Get CallVSTOAssembly() As ExcelWorkbook1.Sheet1
    Set CallVSTOAssembly = GetManagedClass(Me)
End Property

Utilizar el método GetManagedClass

Para utilizar el método GetManagedClass global, pase el objeto de VBA que se corresponde con la clase de elemento de host que contiene la invalidación del método GetAutomationObject. A continuación, utilice el objeto devuelto para tener acceso a la clase que expuso a VBA.

Por ejemplo, la siguiente macro de VBA llama a un método denominado MyVSTOMethod que se define en la clase de elemento de host Sheet1 de un proyecto de libro de Excel denominado ExcelWorkbook1.

Sub CallVSTOMethod
    Dim VSTOSheet1 As ExcelWorkbook1.Sheet1
    Set VSTOSheet1 = GetManagedClass(Sheet1)
    VSTOSheet1.MyVSTOMethod
End Sub

El método GetManagedClass tiene la declaración siguiente.

GetManagedClass(pdispInteropObject Object) As Object

Este método devuelve un objeto que representa la clase que se expuso a VBA. Los miembros y parámetros de método del objeto devuelto aparecen en IntelliSense.

Instrucciones para agregar código de VBA al documento

Hay varias copias diferentes del documento a las que se puede agregar código de VBA que llama a la personalización de nivel de documento.

Cuando desarrolle y pruebe su solución, puede escribir código de VBA en el documento que se abre mientras depura o ejecuta su proyecto en Visual Studio (es decir, el documento de la carpeta de resultados de la compilación). Sin embargo, todo el código de VBA que agregue a este documento se sobrescribirá la próxima vez que genere el proyecto, ya que Visual Studio reemplaza el documento de la carpeta de resultados de la compilación con una copia del documento de la carpeta de proyecto principal.

Si desea guardar el código de VBA que agregue al documento mientras depura o ejecuta la solución, copie el código de VBA en el documento de la carpeta de proyecto. Para obtener más información sobre el proceso de compilación, vea Información general acerca del proceso de compilación de soluciones de Office.

Cuando esté a punto para implementar la solución, habrá tres principales ubicaciones de documento en las que podrá agregar el código de VBA.

En la carpeta de proyecto del equipo de desarrollo

Esta ubicación resulta cómoda si tiene control absoluto sobre el código de VBA del documento y el código de personalización. Dado que el documento se encuentra en el equipo de desarrollo, podrá modificar fácilmente el código de VBA si cambia el código de personalización. El código de VBA que agregue a esta copia del documento permanecerá en el documento cuando genere, depure y publique su solución.

No puede agregar el código de VBA al documento mientras esté abierto en el diseñador. Debe cerrar primero el documento en el diseñador y, a continuación, abrir directamente el documento en Word o Excel.

Nota de precauciónPrecaución

En raras ocasiones, al agregar código de VBA para que se ejecute cuando el documento está abierto, este código podría dañar el documento o impedir que se abriera en el diseñador.

En la carpeta de publicación o instalación

En algunos casos, puede resultar conveniente agregar el código de VBA al documento en la carpeta de publicación o instalación. Es posible, por ejemplo, que elija esta opción si otro desarrollador escribe y prueba el código de VBA en un equipo que no tiene instalado Visual Studio.

Si los usuarios instalan directamente la solución desde la carpeta de publicación, debe agregar el código de VBA al documento cada vez que publique la solución. Visual Studio sobrescribe el documento en la ubicación de la publicación cuando se publica la solución.

Si los usuarios instalan la solución desde una carpeta de instalación que es diferente de la carpeta de publicación, puede evitarse tener que agregar el código de VBA en el documento cada vez que publique la solución. Cuando una actualización de la publicación esté lista para pasarla de la carpeta de publicación a la carpeta de instalación, copie todos los archivos en la carpeta de instalación salvo el documento.

En el equipo del usuario final

Si los usuarios finales son desarrolladores de VBA que llaman a los servicios que se proporcionan en la personalización de nivel de documento, puede indicarles cómo deben llamar al código usando la propiedad CallVSTOAssembly o el método GetManagedClass en sus copias del documento. Cuando publique actualizaciones para la solución, el código de VBA del documento que se encuentra en el equipo del usuario final no se sobrescribirá, ya que las actualizaciones de la publicación no modifican el documento.

Tareas realizadas por las propiedades del elemento host

Cuando se utilizan las propiedades EnableVbaCallers y ReferenceAssemblyFromVbaProject, Visual Studio realiza diferentes conjuntos de tareas.

EnableVbaCallers

Cuando se establece la propiedad EnableVbaCallers de un elemento host en True en un proyecto de Visual Basic, Visual Studio realiza las tareas siguientes:

  1. Agrega los atributos ComClassAttribute y ComVisibleAttribute a la clase de elemento de host.

  2. Invalida el método GetAutomationObject de la clase de elemento de host.

  3. Establece la propiedad ReferenceAssemblyFromVbaProject del elemento host en True.

Cuando se establece de nuevo la propiedad EnableVbaCallers en False, Visual Studio realiza las siguientes tareas:

  1. Quita los atributos ComClassAttribute y ComVisibleAttribute de la clase ThisDocument.

  2. Quita el método GetAutomationObject de la clase de elemento de host.

    Nota

    Visual Studio no restablece automáticamente la propiedad ReferenceAssemblyFromVbaProject en False. Puede establecer esta propiedad en False manualmente en la ventana Propiedades.

ReferenceAssemblyFromVbaProject

Cuando la propiedad ReferenceAssemblyFromVbaProject de un elemento host en un proyecto de Visual Basic o Visual C# se establece en True, Visual Studio realiza las siguientes tareas:

  1. Genera una biblioteca de tipos para el ensamblado de personalización e incrusta la biblioteca de tipos en el ensamblado.

  2. Agrega una referencia a las bibliotecas de tipos siguientes en el proyecto de VBA del documento:

    • La biblioteca de tipos para el ensamblado de personalización.

    • La biblioteca de tipos del Motor de ejecución de Microsoft Visual Studio Tools para Office 9.0. Esta biblioteca de tipos está incluida en el Motor en tiempo de ejecución de Microsoft Visual Studio Tools para Office.

Cuando se establece de nuevo la propiedad ReferenceAssemblyFromVbaProject en False, Visual Studio realiza las siguientes tareas:

  1. Quita las referencias de la biblioteca de tipos del proyecto de VBA del documento.

  2. Quita la biblioteca de tipos incrustada del ensamblado.

Solución de problemas

En la tabla siguiente se muestran algunos errores comunes y algunas sugerencias para corregir estos errores.

Error

Sugerencia

Después de definir la propiedad EnableVbaCallers o ReferenceAssemblyFromVbaProject, aparece un mensaje de error en el que se indica que el documento no contiene ningún proyecto de VBA o que no tiene permiso para obtener acceso al proyecto de VBA del documento.

Asegúrese de que el documento del proyecto contiene al menos una macro de VBA, de que el proyecto de VBA tiene la confianza suficiente para ejecutarse y de que el proyecto de VBA no está protegido mediante contraseña.

Después de establecer la propiedad EnableVbaCallers o ReferenceAssemblyFromVbaProject, aparece un mensaje de error en el que se indica que falta la declaración GuidAttribute o está dañada.

Asegúrese de que la declaración GuidAttribute se encuentra en el archivo AssemblyInfo.cs o AssemblyInfo.vb de su proyecto y de que este atributo está establecido en un GUID válido.

Después de establecer la propiedad EnableVbaCallers o ReferenceAssemblyFromVbaProject, aparece un mensaje de error en el que se indica que el número de versión especificado por AssemblyVersionAttribute no es válido.

Asegúrese de que la declaración AssemblyVersionAttribute del archivo AssemblyInfo.cs o AssemblyInfo.vb de su proyecto está establecida en un número de versión de ensamblado válido. Para obtener información sobre los números de versión de ensamblado válidos, vea la clase AssemblyVersionAttribute.

Después de cambiar el nombre del ensamblado de personalización, el código de VBA que llama a miembros del ensamblado de personalización deja de funcionar.

Si cambia el nombre del ensamblado de personalización después de exponerlo a código de VBA, el vínculo entre el proyecto de VBA del documento y el ensamblado de personalización se rompe. Para corregir este problema, cambie la propiedad ReferenceFromVbaAssembly de su proyecto a False y vuelva a establecerla en True; a continuación, reemplace todas las referencias al nombre de ensamblado anterior que haya en el código de VBA por el nuevo nombre de ensamblado.

Vea también

Tareas

Cómo: Exponer código a VBA en un proyecto de Visual Basic

Cómo: Exponer código a VBA en un proyecto de Visual C#

Tutorial: Llamar a código de VBA en un proyecto de Visual Basic

Tutorial: Llamar a código de VBA en un proyecto de Visual C#

Conceptos

Publicar soluciones de Office

Otros recursos

Combinar personalizaciones de VBA y de nivel de documento

Programar personalizaciones de nivel de documento