Tutorial: Crear la primera personalización en el nivel de documento para ExcelWalkthrough: Create your first document-level customization for Excel

Este tutorial introductorio muestra cómo crear una personalización de nivel de documento para Microsoft Office Excel.This introductory walkthrough shows you how to create a document-level customization for Microsoft Office Excel. Las características que se crean en este tipo de solución solo están disponibles cuando se abre un libro concreto.The features that you create in this kind of solution are available only when a specific workbook is open. No se puede usar una personalización de nivel de documento para realizar cambios en toda la aplicación, por ejemplo para mostrar una nueva pestaña de la cinta de opciones cuando se abre un libro.You cannot use a document-level customization to make application-wide changes, for example, displaying a new Ribbon tab when any workbook is open.

Aplicación: la información de este tema se aplica a los proyectos de nivel de documento de Excel.Applies to: The information in this topic applies to document-level projects for Excel. Para obtener más información, consulte características disponibles por tipo de aplicación y el proyecto de Office.For more information, see Features available by Office application and project type.

En este tutorial se muestran las tareas siguientes:This walkthrough illustrates the following tasks:

  • Crear un proyecto de libro de Excel.Creating an Excel workbook project.

  • Agregar texto a una hoja de cálculo que se hospeda en el diseñador de Visual Studio.Adding text to a worksheet that is hosted in the Visual Studio designer.

  • Escribir código que usa el modelo de objetos de Excel para agregar texto a la hoja de cálculo personalizada cuando se abre.Writing code that uses the object model of Excel to add text to the customized worksheet when it is opened.

  • Compilar y ejecutar el proyecto para probarlo.Building and running the project to test it.

  • Limpiar el proyecto completado para quitar los archivos de compilación innecesarios y la configuración de seguridad del equipo de desarrollo.Cleaning up the completed project to remove unnecessary build files and security settings from your development computer.

    Nota

    Es posible que tu equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos.The Visual Studio edition that you have and the settings that you use determine these elements. Para obtener más información, consulte personalizar el IDE.For more information, see Personalize the IDE.

Requisitos previosPrerequisites

Necesita los componentes siguientes para completar este tutorial:You need the following components to complete this walkthrough:

Crear el proyectoCreate the project

Para crear un nuevo proyecto de libro de Excel en Visual StudioTo create a new Excel workbook project in Visual Studio

  1. Inicie Visual StudioVisual Studio.Start Visual StudioVisual Studio.

  2. En el menú Archivo , elija Nuevoy haga clic en Proyecto.On the File menu, point to New, and then click Project.

  3. En el panel de plantillas, expanda Visual C# o Visual Basicy luego expanda Office/SharePoint.In the templates pane, expand Visual C# or Visual Basic, and then expand Office/SharePoint.

  4. En el nodo Office/SharePoint expandido, seleccione el nodo Complementos de Office .Under the expanded Office/SharePoint node, select the Office Add-ins node.

  5. En la lista de plantillas de proyecto, elija un proyecto de complemento de VSTO de Excel.In the list of project templates, choose an Excel VSTO Add-in project.

  6. En el nombre , escriba FirstWorkbookCustomization.In the Name box, type FirstWorkbookCustomization.

  7. Haga clic en Aceptar.Click OK.

    Se abre el Asistente para proyectos de Visual Studio Tools para Office .The Visual Studio Tools for Office Project Wizard opens.

  8. Seleccione crear un nuevo documentoy haga clic en Aceptar.Select Create a new document, and click OK.

    • Visual StudioVisual Studio crea el FirstWorkbookCustomization del proyecto y agrega los siguientes archivos al proyecto. creates the FirstWorkbookCustomization project, and adds the following files to the project.

    • FirstWorkbookCustomizationxlsx: representa el libro de Excel en el proyecto.FirstWorkbookCustomization.xlsx - Represents the Excel workbook in the project. Contiene todas las hojas de cálculo y los gráficos.Contains all the worksheets and charts.

    • Sheet1 (.vb para Visual Basic o .cs para Visual C#): una hoja de cálculo que proporciona la superficie de diseño y el código de la primera hoja de cálculo del libro.Sheet1 (.vb file for Visual Basic or .cs file for Visual C#) - A worksheet that provides the design surface and the code for the first worksheet in the workbook. Para obtener más información, consulte elemento host Worksheet.For more information, see Worksheet host item.

    • Sheet2 (.vb para Visual Basic o .cs para Visual C#)-hoja de cálculo que proporciona la superficie de diseño y el código para la segunda hoja de cálculo del libro.Sheet2 (.vb file for Visual Basic or .cs file for Visual C#) - A worksheet that provides the design surface and the code for the second worksheet in the workbook.

    • Sheet3 (.vb para Visual Basic o .cs para Visual C#)-hoja de cálculo que proporciona la superficie de diseño y el código para la tercera hoja de cálculo del libro.Sheet3 (.vb file for Visual Basic or .cs file for Visual C#) - A worksheet that provides the design surface and the code for the third worksheet in the workbook.

    • ThisWorkbook (.vb para Visual Basic o .cs para Visual C#): contiene la superficie de diseño y el código para las personalizaciones de nivel de libro.ThisWorkbook (.vb file for Visual Basic or .cs file for Visual C#) - Contains the design surface and the code for workbook-level customizations. Para obtener más información, consulte elemento host Workbook.For more information, see Workbook host item.

      El archivo de código Sheet1 se abre automáticamente en el diseñador.The Sheet1 code file is opened automatically in the designer.

Cierre y vuelva a abrir hojas de cálculo en el diseñadorClose and reopen worksheets in the designer

Puede volver a abrir el libro o la hoja de cálculo si los cierra deliberada o accidentalmente en el diseñador mientras está desarrollando el proyecto.If you deliberately or accidentally close a workbook or a worksheet in the designer while you are developing your project, you can reopen it.

Para cerrar y volver a abrir una hoja de cálculo en el diseñadorTo close and reopen a worksheet in the designer

  1. Cierre el libro, haga clic en el cerrar botón (X) de la ventana del diseñador.Close the workbook by clicking the Close button (X) for the designer window.

  2. En el Explorador de soluciones, haga clic en el Sheet1 archivo de código y haga clic en Diseñador de vistas.In Solution Explorer, right-click the Sheet1 code file, and click View Designer.

    - o -- or -

    En el Explorador de soluciones, haga doble clic en el Sheet1 archivo de código.In Solution Explorer, double-click the Sheet1 code file.

Agregar texto a una hoja de cálculo en el diseñadorAdd text to a worksheet in the designer

Puede diseñar la interfaz de usuario de la personalización modificando la hoja de cálculo que está abierta en el diseñador.You can design the user interface (UI) of your customization by modifying the worksheet that is open in the designer. Por ejemplo, puede agregar texto a las celdas, aplicar fórmulas o agregar controles de Excel.For example, you can add text to cells, apply formulas, or add Excel controls. Para obtener más información sobre cómo usar el diseñador, vea proyectos de Office en el entorno de Visual Studio.For more information about how to use the designer, see Office projects in the Visual Studio environment.

Para agregar texto a la hoja de cálculo mediante el diseñadorTo add text to a worksheet by using the designer

  1. En la hoja de cálculo que está abierto en el diseñador, seleccione la celda A1y, a continuación, escriba el texto siguiente.In the worksheet that is open in the designer, select cell A1, and then type the following text.

    Este texto se agregó mediante el diseñador.This text was added by using the designer.

Advertencia

Si agrega esta línea de texto a la celda A2, se sobrescribirá otro código en este ejemplo.If you add this line of text to cell A2, it will be overwritten by other code in this example.

Agregar texto a una hoja de cálculo mediante programaciónAdd text to a worksheet programmatically

A continuación, agregue código al archivo de código Sheet1.Next, add code to the Sheet1 code file. El nuevo código usa el modelo de objetos de Excel para agregar una segunda línea de texto al libro.The new code uses the object model of Excel to add a second line of text to the workbook. De forma predeterminada, el archivo de código Sheet1 contiene el siguiente código generado:By default, the Sheet1 code file contains the following generated code:

  • Una definición parcial de la clase Sheet1, que representa el modelo de programación de la hoja de cálculo y proporciona acceso al modelo de objetos de Excel.A partial definition of the Sheet1 class, which represents the programming model of the worksheet and provides access to the object model of Excel. Para obtener más información, elemento host Worksheet y información general sobre el modelo de objetos de Word.For more information, Worksheet host item and Word object model overview. El resto de la clase Sheet1 se define en un archivo de código oculto que no se debe modificar.The remainder of the Sheet1 class is defined in a hidden code file that you should not modify.

  • Los controladores de eventos Sheet1_Startup y Sheet1_Shutdown.The Sheet1_Startup and Sheet1_Shutdown event handlers. Se llama a estos controladores de eventos cuando Excel carga y descarga la personalización.These event handlers are called when Excel loads and unloads your customization. Use estos controladores de eventos para inicializar la personalización cuando se cargue y para limpiar los recursos que usa la personalización cuando se descargue.Use these event handlers to initialize your customization when it is loaded, and to clean up resources used by your customization when it is unloaded. Para obtener más información, consulte eventos en proyectos de Office.For more information, see Events in Office projects.

Para agregar una segunda línea de texto a la hoja de cálculo mediante códigoTo add a second line of text to the worksheet by using code

  1. En el Explorador de soluciones, haga clic en Sheet1y, a continuación, haga clic en ver código.In Solution Explorer, right-click Sheet1, and then click View Code.

    El archivo de código se abre en Visual Studio.The code file opens in Visual Studio.

  2. Reemplace el controlador de eventos Sheet1_Startup por el siguiente código:Replace the Sheet1_Startup event handler with the following code. Cuando se abre Sheet1, este código agrega una segunda línea de texto a la hoja de cálculo.When Sheet1 is opened, this code adds a second line of text to the worksheet.

    private void Sheet1_Startup(object sender, System.EventArgs e)
    {
        Microsoft.Office.Tools.Excel.NamedRange nr =
            this.Controls.AddNamedRange(this.Range["A2"], "NamedRange1");
        nr.Value2 = "This text was added by using code";
    }
    
    Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
        Dim nr As Microsoft.Office.Tools.Excel.NamedRange = _
            Me.Controls.AddNamedRange(Me.Range("A2"), "NamedRange1")
        nr.Value2 = "This text was added by using code"
    End Sub
    

El proyecto de pruebaTest the project

Para probar el libroTo test your workbook

  1. Presione F5 para compilar y ejecutar el proyecto.Press F5 to build and run your project.

    Al compilar el proyecto, el código se compila en un ensamblado que está asociado al libro.When you build the project, the code is compiled into an assembly that is associated with the workbook. Visual Studio coloca una copia del libro y el ensamblado en la carpeta de resultados de compilación del proyecto y establece la configuración de seguridad en el equipo de desarrollo para permitir que se ejecute la personalización.Visual Studio puts a copy of the workbook and the assembly in the build output folder for the project, and it configures the security settings on the development computer to enable the customization to run. Para obtener más información, consulte soluciones de Office de compilación.For more information, see Build Office solutions.

  2. En el libro, compruebe que ve el texto siguiente.In the workbook, verify that you see the following text.

    Este texto se agregó mediante el diseñador.This text was added by using the designer.

    Este texto se agregó mediante código.This text was added by using code.

  3. Cierre el libro.Close the workbook.

Limpiar el proyectoClean up the project

Cuando termine de desarrollar un proyecto, debe quitar los archivos de la carpeta de resultados de compilación y la configuración de seguridad creada por el proceso de compilación.When you finish developing a project, you should remove the files in the build output folder and the security settings created by the build process.

Para limpiar el proyecto completado en el equipo de desarrolloTo clean up the completed project on your development computer

  1. En el menú Crear de Visual Studio, haga clic en Limpiar solución.In Visual Studio, on the Build menu, click Clean Solution.

Pasos siguientesNext steps

Ahora que ha creado una personalización de nivel de documento básico para Excel, en los siguientes temas obtendrá más información sobre cómo desarrollar personalizaciones:Now that you have created a basic document-level customization for Excel, you can learn more about how to develop customizations from these topics:

Vea tambiénSee also

Información general sobre el desarrollo de soluciones de Office (VSTO) Office solutions development overview (VSTO)
Soluciones de Excel Excel solutions
Programar personalizaciones de nivel de documento Program document-level customizations
Información general sobre el modelo de objetos de Excel Excel object model overview
Automatizar Excel usando objetos extendidos Automate Excel by using extended objects
Personalización de la interfaz de usuario de Office Office UI customization
Compilar soluciones de Office Build Office solutions
Implementar una solución de Office Deploy an Office solution
Introducción a las plantillas de proyecto de OfficeOffice project templates overview