Combinar personalizaciones de VBA y de nivel de documento

Artículo
02/19/2013

Puede utilizar código de Visual Basic para Aplicaciones (VBA) en un documento que forme parte de una personalización de nivel de documento para Microsoft Office Word o Microsoft Office Excel.Puede llamar a código de VBA del documento desde el ensamblado de personalización o puede configurar el proyecto para permitir que código de VBA del documento llame a código del ensamblado de personalización.

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

Comportamiento del código de VBA en una personalización de nivel de documento

Al abrir su proyecto en Visual Studio, el documento se abre en modo de diseño.El código de VBA no se ejecuta cuando el documento está en modo de diseño, por lo que puede trabajar en el documento y en el código sin ejecutar el código de VBA.

Cuando ejecuta la solución, los controladores de eventos de VBA y del ensamblado de personalización recogen los eventos provocados en el documento y se ejecutan ambos conjuntos de código.No es posible conocer de antemano qué código se ejecutará antes que el otro, por lo que deberá determinarlo probando cada caso en particular.Puede obtener resultados inesperados si no se coordinan y prueban cuidadosamente ambos conjuntos de código.

Llamar a código de VBA desde el ensamblado de personalización

Puede llamar a macros de documentos de Word y a macros y funciones de libros de Excel.Para ello, utilice uno de los métodos siguientes:

En Word, llame al método Run de la clase Microsoft.Office.Interop.Word.Application.
En Excel, llame al método Run de la clase Microsoft.Office.Interop.Excel.Application.

En cada método, el primer parámetro identifica el nombre de la macro o función a la que desea llamar y los parámetros opcionales restantes especifican los parámetros para pasar a la macro o función.El primer parámetro puede tener formatos diferentes para Word y Excel:

En Word, el primer parámetro es una cadena que puede ser cualquier combinación de nombre de plantilla, módulo y macro.Si especifica el nombre del documento, el código sólo podrá ejecutar las macros de documentos relacionados con el contexto actual. no simplemente cualquier macro en cualquier documento.
En Excel, el primer parámetro puede ser una cadena que especifica el nombre de la macro, Range que indica dónde se encuentra la función o un identificador de registro de una función DLL registrada (XLL).Si pasa una cadena, ésta se evaluará en el contexto de la hoja activa.

En el ejemplo de código siguiente se muestra cómo llamar a una macro denominada MyMacro desde un proyecto de nivel de documento para Excel.Este ejemplo supone que MyMacro está definida en Sheet1.

Globals.Sheet1.Application.Run("MyMacro")

Globals.Sheet1.Application.Run("MyMacro", missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing, 
    missing, missing, missing, missing, missing, missing);

[!NOTA]

Para obtener información sobre cómo utilizar la variable missing global en lugar de los parámetros opcionales en Visual C#, vea Escribir código en soluciones de Office.

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

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.

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, vea 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 host del proyecto para devolver una instancia de la clase que expone 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 Compilar 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 compile, 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 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:

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.

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

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 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:

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 Runtime de Microsoft Visual Studio Tools para Office.

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

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.

Vea también

Compartir a través de