Compartir a través de

Combinación de personalizaciones de VBA y de nivel de documento

Puede usar 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 al código VBA en el documento desde el ensamblaje de personalización o configurar su proyecto para permitir que el código VBA en el documento llame al código en el ensamblaje de personalización.

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

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

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

Al ejecutar la solución, los controladores de eventos en VBA y el ensamblado de personalización detectan los eventos que se generan en el documento, y ambos conjuntos de código se ejecutan. No puede determinar de antemano qué código se ejecutará antes del otro; Debe determinarlo a través de las pruebas en cada caso individual. Puede obtener resultados inesperados si los dos conjuntos de código no se coordinan y prueban cuidadosamente.

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

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

  • Para Word, llame al método de la clase RunApplication.

  • Para Excel, llame al Run método de la Application clase .

    Para 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 que se van a pasar a la macro o función. El primer parámetro puede tener diferentes formatos para Word y Excel:

  • Para Word, el primer parámetro es una cadena que puede ser cualquier combinación de plantilla, módulo y nombre de macro. Si especifica el nombre del documento, el código solo puede ejecutar macros en documentos relacionados con el contexto actual, no en cualquier macro de cualquier documento.

  • Para Excel, el primer parámetro puede ser una cadena que especifica el nombre de la macro, un Range que indica dónde está la función o un identificador de registro para una función DLL (XLL) registrada. Si pasa una cadena, la cadena 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. En este ejemplo se supone que MyMacro se define en Sheet1.

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 el uso de la variable global missing en lugar de parámetros opcionales en Visual C#, vea Escribir código en soluciones de Office.

Invocar el código en las personalizaciones a nivel de documento desde VBA

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

  • Quiere ampliar el código VBA existente en un documento mediante características de una personalización de nivel de documento asociada al mismo documento.

  • Quiere que los servicios que desarrolle en una personalización de nivel de documento estén disponibles para los usuarios finales que pueden acceder a los servicios escribiendo código VBA en el documento.

    Las herramientas de desarrollo de Office en Visual Studio proporcionan una característica similar para los complementos de VSTO. Si va a desarrollar un complemento de VSTO, puede llamar al código en el complemento de VSTO desde otras soluciones de Microsoft Office. Para obtener más información, vea Llamar al código en complementos de VSTO desde otras soluciones de Office.

Nota:

Esta característica no se puede usar en proyectos de plantilla de Word. Solo se puede usar en proyectos de documento de Word, libro de Excel o plantilla de Excel.

Requisitos

Para poder habilitar el código VBA para llamar al ensamblado de personalización, el proyecto debe cumplir los siguientes requisitos:

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

    • Para Word: .docm o .doc

    • Para Excel: .xlsm, .xltm, .xlso .xlt

  • El documento ya debe contener un proyecto de VBA que tenga código VBA en él.

  • Se debe permitir que el código VBA del documento se ejecute sin pedir al usuario que habilite las macros. Puede confiar en el código de VBA para que se ejecute agregando la ubicación del proyecto de Office a la lista de ubicaciones de confianza en la configuración del Centro de confianza para Word o Excel.

  • El proyecto de Office debe contener al menos una clase pública que incluya uno o más miembros públicos que estén expuestos a VBA.

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

Permitir que el código VBA llame al ensamblado de personalización

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

  • Puede exponer miembros de una clase de elemento host en 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 todo el trabajo necesario para habilitar el código VBA para llamar a miembros de la clase.

  • Puede exponer miembros en cualquier clase pública de un proyecto de Visual C# o miembros de una clase de elemento que no sea host de un proyecto de Visual Basic a VBA. Esta opción le brinda mayor libertad para seleccionar las clases que expone a VBA, pero también requiere más pasos manuales.

    Para ello, debe realizar los siguientes pasos principales:

    1. Exponga la clase a COM.

    2. Invalide el método GetAutomationObject de una clase de elemento host en el proyecto para devolver una instancia de la clase que expone a VBA.

    3. Establezca la propiedad ReferenceAssemblyFromVbaProject de cualquier clase de elemento host del proyecto en True. Esto inserta la biblioteca de tipos del ensamblado de personalización en el ensamblado y agrega una referencia a 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 solo están disponibles en la ventana Propiedades en tiempo de diseño; no se pueden usar en tiempo de ejecución. Para ver las propiedades, abra el diseñador de un elemento host en Visual Studio. Para obtener más información sobre las tareas específicas que realiza Visual Studio al establecer estas propiedades, vea Tareas realizadas por las propiedades del elemento host.

Nota:

Si el libro o documento aún no contiene código VBA o si el código VBA del documento no es de confianza para ejecutarse, recibirá 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 en el documento en esta situación.

Utilice miembros en código VBA para invocar el ensamblado de personalización

Después de configurar el proyecto para permitir que el código VBA llame al ensamblado de personalización, Visual Studio agrega los siguientes miembros al proyecto de VBA en el 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 elemento host mediante la propiedad EnableVbaCallers, Visual Studio también agrega una propiedad denominada CallVSTOAssembly al módulo ThisDocument, ThisWorkbook, Sheet1, Sheet2 o Sheet3 en el proyecto de VBA.

    Puede usar la CallVSTOAssembly propiedad o el GetManagedClass método para acceder a los miembros públicos de la clase que ha expuesto al código VBA en el proyecto.

Nota:

Mientras desarrolla e implementa la solución, hay varias copias diferentes del documento donde puede agregar el código VBA. Para obtener más información, consulte Directrices para agregar código VBA al documento.

Usar la propiedad CallVSTOAssembly en un proyecto de Visual Basic

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

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

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

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

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

Uso del método GetManagedClass

Para usar el método global GetManagedClass, pase el objeto VBA que corresponde a la clase de elemento host que contiene la sobrescritura del método GetAutomationObject. A continuación, use el objeto devuelto para tener acceso a la clase que ha expuesto a VBA.

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

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

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

GetManagedClass(pdispInteropObject Object) As Object

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

Directrices para agregar código VBA al documento

Existen varias copias distintas del documento donde puede agregar código VBA que invoca la personalización a nivel de documento.

A medida que desarrolla y prueba la solución, puede escribir código VBA en el documento que se abre mientras depura o ejecuta el proyecto en Visual Studio (es decir, el documento en la carpeta de salida de compilación). Sin embargo, cualquier código de VBA que agregue a este documento se sobrescribirá la próxima vez que compile el proyecto, ya que Visual Studio reemplaza el documento en la carpeta de salida de compilación por una copia del documento desde la carpeta principal del proyecto.

Si desea guardar el código VBA que agregue al documento durante la depuración o ejecución de la solución, copie el código VBA en el documento de la carpeta del proyecto. Para obtener más información sobre el proceso de compilación, vea Compilar soluciones de Office.

Cuando esté listo para implementar la solución, hay tres ubicaciones principales de documentos en las que puede agregar el código VBA.

En la carpeta del proyecto en el ordenador de desarrollo

Esta ubicación es conveniente si tiene control completo sobre el código VBA en el documento y el código de personalización. Dado que el documento está en el equipo de desarrollo, puede modificar fácilmente el código VBA si cambia el código de personalización. El código de VBA que agregue a esta copia del documento permanece en el documento al compilar, depurar y publicar la solución.

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

Precaución

Si agrega código VBA que se ejecuta cuando se abre el documento, en raras ocasiones este código podría dañar el documento o impedir que se abra en el diseñador.

En la carpeta de publicación o instalación

En algunos casos, puede ser adecuado agregar el código VBA al documento en la carpeta de publicación o instalación. Por ejemplo, puede elegir esta opción si el código VBA está escrito y probado por un desarrollador diferente en un equipo que no tiene Instalado Visual Studio.

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

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

En el equipo del usuario final

Si los usuarios finales son desarrolladores de VBA que llaman a los servicios que usted proporciona en la personalización a nivel de documento, puede indicarles cómo llamar a su código utilizando la propiedad CallVSTOAssembly o el método GetManagedClass en sus copias del documento. Al publicar actualizaciones en la solución, no se sobrescribirá el código VBA del documento del equipo del usuario final, ya que las actualizaciones de publicación no modifican el documento.

Tareas realizadas por las propiedades del elemento host

Al usar las propiedades EnableVbaCallers y ReferenceAssemblyFromVbaProject , Visual Studio realiza diferentes conjuntos de tareas.

EnableVbaCallers

Al establecer 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 host.

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

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

    Al volver a establecer la propiedad EnableVbaCallers en False, Visual Studio realiza las siguientes tareas:

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

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

    Nota:

    Visual Studio no establece automáticamente la propiedad ReferenceAssemblyFromVbaProject de nuevo a False. Puede establecer esta propiedad en False manualmente mediante la ventana Propiedades .

ReferenceAssemblyFromVbaProject

Cuando la propiedad ReferenceAssemblyFromVbaProject de cualquier elemento host de 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 inserta la biblioteca de tipos en el ensamblado.

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

    • Biblioteca de tipos para su ensamblaje de personalización.

    • Biblioteca de tipos de motores de ejecución de Microsoft Visual Studio Tools para Office 9.0. Esta biblioteca de tipos se incluye en el entorno de ejecución de Visual Studio Tools para Office.

    Cuando la propiedad ReferenceAssemblyFromVbaProject se vuelve a establecer en False, Visual Studio realiza las siguientes tareas:

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

  4. Quita la biblioteca de tipos incrustada del ensamblado.

Troubleshoot

En la tabla siguiente se enumeran algunos errores comunes y sugerencias para corregir los errores.

Error Suggestion
Después de establecer la propiedad EnableVbaCallers o ReferenceAssemblyFromVbaProject , un mensaje de error indica que el documento no contiene un proyecto de VBA o que no tiene permiso para acceder al proyecto de VBA en el documento. Asegúrese de que el documento del proyecto contiene al menos una macro de VBA, el proyecto de VBA tiene suficiente confianza para ejecutarse y el proyecto de VBA no está protegido por una contraseña.
Después de establecer la propiedad EnableVbaCallers o ReferenceAssemblyFromVbaProject , un mensaje de error indica que falta o está dañada la GuidAttribute declaración. Asegúrese de que la GuidAttribute declaración se encuentra en el archivo AssemblyInfo.cs o AssemblyInfo.vb del proyecto y que este atributo está establecido en un GUID válido.
Después de establecer la propiedad EnableVbaCallers o ReferenceAssemblyFromVbaProject, un mensaje de error indica que el número de versión especificado por AssemblyVersionAttribute no es válido. Asegúrese de que la AssemblyVersionAttribute declaración en el archivo AssemblyInfo.cs o AssemblyInfo.vb del 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 AssemblyVersionAttribute clase .
Después de cambiar el nombre del ensamblado de personalización, el código VBA que llama al ensamblado de personalización deja de funcionar. Si cambia el nombre del ensamblado de personalización después de exponerlo al código VBA, se interrumpe el vínculo entre el proyecto VBA del documento y el ensamblado de personalización. Para corregir este problema, cambie la propiedad ReferenceFromVbaAssembly del proyecto a False y, a continuación, vuelva a True y reemplace las referencias al nombre del ensamblado antiguo en el código VBA por el nuevo nombre de ensamblado.

Contenido relacionado

  • Last updated on