Passo a passo: Criar a primeira personalização no nível de documento para ExcelWalkthrough: Create your first document-level customization for Excel

Este passo a passo introdutório mostra como criar uma personalização no nível de documento do Microsoft Office Excel.This introductory walkthrough shows you how to create a document-level customization for Microsoft Office Excel. Os recursos que você criar nesse tipo de solução estão disponíveis somente quando uma pasta de trabalho específica é aberta.The features that you create in this kind of solution are available only when a specific workbook is open. Você não pode usar uma personalização no nível de documento para fazer alterações em todo o aplicativo, por exemplo, exibindo uma nova guia de faixa de opções quando qualquer pasta de trabalho é aberta.You cannot use a document-level customization to make application-wide changes, for example, displaying a new Ribbon tab when any workbook is open.

Aplicável a: as informações neste tópico são aplicáveis aos projetos no nível de documento para Excel.Applies to: The information in this topic applies to document-level projects for Excel. Para obter mais informações, consulte recursos disponíveis por tipo de projeto e aplicativo do Office.For more information, see Features available by Office application and project type.

Esta explicação passo a passo ilustra as seguintes tarefas:This walkthrough illustrates the following tasks:

  • Criando um projeto de pasta de trabalho do Excel.Creating an Excel workbook project.

  • Adicionando texto a uma planilha que está hospedada no designer do Visual Studio.Adding text to a worksheet that is hosted in the Visual Studio designer.

  • Escrevendo código que usa o modelo de objeto do Excel para adicionar texto à planilha personalizada quando ele é aberto.Writing code that uses the object model of Excel to add text to the customized worksheet when it is opened.

  • Criando e executando o projeto para testá-lo.Building and running the project to test it.

  • Limpando o projeto concluído para remover arquivos de compilação desnecessárias e as configurações de segurança de seu computador de desenvolvimento.Cleaning up the completed project to remove unnecessary build files and security settings from your development computer.

    Note

    Seu computador pode mostrar diferentes nomes ou locais para alguns dos elementos de interface do usuário do Visual Studio nas instruções a seguir.Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. A edição do Visual Studio que você possui e as configurações que você usa determinam esses elementos.The Visual Studio edition that you have and the settings that you use determine these elements. Para obter mais informações, confira Personalizar o IDE.For more information, see Personalize the IDE.

Pré-requisitosPrerequisites

Você precisa dos seguintes componentes para concluir esta instrução passo a passo:You need the following components to complete this walkthrough:

Criar o projetoCreate the project

Para criar um novo projeto de pasta de trabalho do Excel no Visual StudioTo create a new Excel workbook project in Visual Studio

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

  2. No menu Arquivo, aponte para Novo e clique em Projeto.On the File menu, point to New, and then click Project.

  3. No painel de modelos, expanda Visual c# ou Visual Basice, em seguida, expanda Office/SharePoint.In the templates pane, expand Visual C# or Visual Basic, and then expand Office/SharePoint.

  4. Sob o expandida Office/SharePoint nó, selecione o suplementos do Office nó.Under the expanded Office/SharePoint node, select the Office Add-ins node.

  5. Na lista de modelos de projeto, escolha um projeto de suplemento do VSTO do Excel.In the list of project templates, choose an Excel VSTO Add-in project.

  6. No nome , digite FirstWorkbookCustomization.In the Name box, type FirstWorkbookCustomization.

  7. Clique em OK.Click OK.

    O Visual Studio Tools for Office Project Wizard é aberta.The Visual Studio Tools for Office Project Wizard opens.

  8. Selecione criar um novo documentoe clique em Okey.Select Create a new document, and click OK.

    • Visual StudioVisual Studio cria o FirstWorkbookCustomization de projeto e adiciona os seguintes arquivos ao projeto. creates the FirstWorkbookCustomization project, and adds the following files to the project.

    • FirstWorkbookCustomization. xlsx - representa a pasta de trabalho do Excel no projeto.FirstWorkbookCustomization.xlsx - Represents the Excel workbook in the project. Contém todas as planilhas e gráficos.Contains all the worksheets and charts.

    • Sheet1 (. vb arquivo para o Visual Basic ou CS arquivo para o Visual C#)-uma planilha que fornece a superfície de design e o código para a primeira planilha na pasta de trabalho.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 obter mais informações, consulte item de host da planilha.For more information, see Worksheet host item.

    • Planilha2 (. vb arquivo para o Visual Basic ou CS arquivo para o Visual C#)-uma planilha que fornece a superfície de design e o código para a segunda planilha na pasta de trabalho.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 arquivo para o Visual Basic ou CS arquivo para o Visual C#)-uma planilha que fornece a superfície de design e o código para a terceira planilha na pasta de trabalho.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 arquivo para o Visual Basic ou CS arquivo para o Visual C#)-contém a superfície de design e o código para personalizações no nível de pasta de trabalho.ThisWorkbook (.vb file for Visual Basic or .cs file for Visual C#) - Contains the design surface and the code for workbook-level customizations. Para obter mais informações, consulte item de host da pasta de trabalho.For more information, see Workbook host item.

      O arquivo de código Sheet1 é aberto automaticamente no designer.The Sheet1 code file is opened automatically in the designer.

Feche e reabra a planilhas no designerClose and reopen worksheets in the designer

Se você deliberadamente ou acidentalmente fechar uma pasta de trabalho ou em uma planilha no designer enquanto você estiver desenvolvendo seu projeto, você poderá reabri-lo.If you deliberately or accidentally close a workbook or a worksheet in the designer while you are developing your project, you can reopen it.

Fechar e reabrir uma planilha no designerTo close and reopen a worksheet in the designer

  1. Feche a pasta de trabalho clicando o fechar botão (X) para a janela do designer.Close the workbook by clicking the Close button (X) for the designer window.

  2. Na Gerenciador de soluções, com o botão direito do Sheet1 arquivo de código e, em seguida, clique em View Designer.In Solution Explorer, right-click the Sheet1 code file, and click View Designer.

    - ou -- or -

    Na Gerenciador de soluções, clique duas vezes o Sheet1 arquivo de código.In Solution Explorer, double-click the Sheet1 code file.

Adicionar texto a uma planilha no designerAdd text to a worksheet in the designer

Você pode criar a interface do usuário (UI) de sua personalização modificando a planilha que está aberta no designer.You can design the user interface (UI) of your customization by modifying the worksheet that is open in the designer. Por exemplo, você pode adicionar texto às células, aplicar fórmulas ou adicionar controles do Excel.For example, you can add text to cells, apply formulas, or add Excel controls. Para obter mais informações sobre como usar o designer, consulte projetos do Office no ambiente do Visual Studio.For more information about how to use the designer, see Office projects in the Visual Studio environment.

Para adicionar texto a uma planilha usando o designerTo add text to a worksheet by using the designer

  1. Na planilha que está aberta no designer, selecione a célula A1e, em seguida, digite o texto a seguir.In the worksheet that is open in the designer, select cell A1, and then type the following text.

    Este texto foi adicionado usando o designer.This text was added by using the designer.

Warning

Se você adicionar essa linha de texto para a célula A2, ele será substituído por outro código neste exemplo.If you add this line of text to cell A2, it will be overwritten by other code in this example.

Adicionar texto a uma planilha programaticamenteAdd text to a worksheet programmatically

Em seguida, adicione código ao arquivo de código Sheet1.Next, add code to the Sheet1 code file. O novo código usa o modelo de objeto do Excel para adicionar uma segunda linha de texto para a pasta de trabalho.The new code uses the object model of Excel to add a second line of text to the workbook. Por padrão, o arquivo de código Sheet1 contém o seguinte código gerado:By default, the Sheet1 code file contains the following generated code:

  • Uma definição parcial do Sheet1 classe, que representa o modelo de programação da planilha e fornece acesso ao modelo de objeto do 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 obter mais informações, item de host da planilha e visão geral do modelo de objeto Word.For more information, Worksheet host item and Word object model overview. O restante do Sheet1 classe é definida em um arquivo de código oculto que você não deve modificar.The remainder of the Sheet1 class is defined in a hidden code file that you should not modify.

  • O Sheet1_Startup e Sheet1_Shutdown manipuladores de eventos.The Sheet1_Startup and Sheet1_Shutdown event handlers. Esses manipuladores de eventos são chamados quando o Excel carrega e descarrega sua personalização.These event handlers are called when Excel loads and unloads your customization. Use esses manipuladores de eventos para inicializar sua personalização quando ele for carregado e para limpar os recursos usados pela sua personalização quando ela for descarregada.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 obter mais informações, consulte eventos em projetos do Office.For more information, see Events in Office projects.

Para adicionar uma segunda linha de texto na planilha usando códigoTo add a second line of text to the worksheet by using code

  1. Na Gerenciador de soluções, clique com botão direito Sheet1e, em seguida, clique em Exibir código.In Solution Explorer, right-click Sheet1, and then click View Code.

    Abre o arquivo de código no Visual Studio.The code file opens in Visual Studio.

  2. Substitua o Sheet1_Startup manipulador de eventos com o código a seguir.Replace the Sheet1_Startup event handler with the following code. Quando Sheet1 é aberto, esse código adiciona uma segunda linha de texto na planilha.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
    

O projeto de testeTest the project

Para testar a sua pasta de trabalhoTo test your workbook

  1. Pressione F5 para compilar e executar seu projeto.Press F5 to build and run your project.

    Quando você compila o projeto, o código é compilado em um assembly que está associado com a pasta de trabalho.When you build the project, the code is compiled into an assembly that is associated with the workbook. Visual Studio coloca uma cópia da pasta de trabalho e o assembly na pasta de saída de compilação para o projeto, e ele define as configurações de segurança no computador de desenvolvimento para habilitar a personalização executar.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 obter mais informações, consulte soluções do Office compilar.For more information, see Build Office solutions.

  2. Na pasta de trabalho, verifique se o texto a seguir.In the workbook, verify that you see the following text.

    Este texto foi adicionado usando o designer.This text was added by using the designer.

    Este texto foi adicionado por meio de código.This text was added by using code.

  3. Feche a pasta de trabalho.Close the workbook.

Limpar o projetoClean up the project

Quando você concluir o desenvolvimento de um projeto, você deve remover os arquivos na pasta de saída de compilação e as configurações de segurança criadas pelo processo de compilação.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 limpar o projeto concluído no computador de desenvolvimentoTo clean up the completed project on your development computer

  1. No Visual Studio, sobre o construir menu, clique em limpar solução.In Visual Studio, on the Build menu, click Clean Solution.

Próximas etapasNext steps

Agora que você criou uma personalização no nível de documento básica para Excel, você pode aprender mais sobre como desenvolver as personalizações com estes tópicos:Now that you have created a basic document-level customization for Excel, you can learn more about how to develop customizations from these topics:

Consulte tambémSee also

Visão geral de desenvolvimento de soluções do Office (VSTO) Office solutions development overview (VSTO)
Soluções do Excel Excel solutions
Personalizações em nível de documento do programa Program document-level customizations
Visão geral do modelo de objeto do Excel Excel object model overview
Automatizar o Excel usando objetos estendidos Automate Excel by using extended objects
Personalização da interface do usuário do Office Office UI customization
Compilar soluções do Office Build Office solutions
Implantar uma solução do Office Deploy an Office solution
Visão geral de modelos de projeto do OfficeOffice project templates overview