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

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 y versiones especificados de Visual Studio Tools para Office de Microsoft Office. Tipo de proyecto Proyectos de nivel de documento Versión de Microsoft Office Microsoft Office System 2007 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 y versiones especificados de Visual Studio Tools para Office de Microsoft Office.

Tipo de proyecto

Proyectos de nivel de documento

Versión de Microsoft Office

Microsoft Office System 2007

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

Puede configurar un proyecto de nivel de documento para Word 2007 o Excel 2007 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 solución de Visual Studio Tools para Office que esté asociada al mismo documento.
Si desea hacer que los servicios que desarrolla con Visual Studio Tools para Office estén a disposición de los usuarios finales que pueden obtener acceso a estos servicios escribiendo código de VBA en el documento.

Visual Studio Tools para Office también proporciona 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 Visual Studio Tools para Office a la lista de ubicaciones de confianza en las opciones del Centro de confianza de Word o Excel.
El proyecto de Visual Studio Tools para 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 de la clase de elemento de host en True. Visual Studio Tools para Office realiza automáticamente todas las tareas necesarias para permitir que el código de VBA llame 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 realiza Visual Studio Tools para Office 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 Tools para Office 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 su proyecto para permitir que el código de VBA llame a elementos del ensamblado de personalización, Visual Studio Tools para Office agrega los miembros siguientes al proyecto de VBA del documento:

En todos los proyectos, Visual Studio Tools para Office agrega un método global denominado GetManagedClass.
En los proyectos de Visual Basic en los que se exponen miembros de una clase de elemento de host mediante la propiedad EnableVbaCallers, Visual Studio Tools para Office agrega también una propiedad denominada CallVSTOAssembly en el 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 que se expuso al código de VBA en el proyecto de Visual Studio Tools para Office.

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 constituye un mecanismo más conveniente para llamar a los miembros del ensamblado de personalización que utilizar directamente el método GetManagedClass. CallVSTOAssembly devuelve un objeto que representa la clase de elemento de host que expuso 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 en las que se puede agregar código de VBA que llama a miembros de la personalización de Visual Studio Tools para Office.

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 conveniente si tiene control absoluto sobre el código de VBA del documento y el código de personalización de Visual Studio Tools para Office. 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.

Precaució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 opte por esta opción si otro programador escribe y prueba el código de VBA en un equipo que no tiene Visual Studio Tools para Office instalado.

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 programadores de VBA que están llamando a miembros de los servicios que se proporcionan en la personalización de Visual Studio Tools para Office, puede indicarles cómo deben llamar a su código utilizando 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 utiliza las propiedades EnableVbaCallers y ReferenceAssemblyFromVbaProject, Visual Studio Tools para Office realiza conjuntos diferentes de tareas.

EnableVbaCallers

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

Agrega los atributos ComClassAttribute y ComVisibleAttribute a la clase de elemento de host.
Invalida el método GetAutomationObject de la clase de elemento de host.
Establece la propiedad ReferenceAssemblyFromVbaProject del elemento host en True.

Al establecer la propiedad EnableVbaCallers de nuevo en False, Visual Studio Tools para Office realiza las tareas siguientes:

Quita los atributos ComClassAttribute y ComVisibleAttribute de la clase ThisDocument.

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

Nota:
Visual Studio Tools para Office no establece automáticamente la propiedad ReferenceAssemblyFromVbaProject de nuevo en False. Puede establecer esta propiedad en False manualmente en la ventana Propiedades.

ReferenceAssemblyFromVbaProject

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

Genera una biblioteca de tipos para el ensamblado de personalización e incrusta la biblioteca de tipos en el ensamblado.
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 de tiempo de ejecución de Visual Studio Tools para Office.

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

Quita las referencias de la biblioteca de tipos del proyecto de VBA del documento.
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.