Como usar argumentos nomeados e opcionais na programação do Office

Argumentos nomeados e argumentos opcionais melhoram a conveniência, a flexibilidade e a legibilidade na programação em C#. Além disso, esses recursos facilitam muito o acesso a interfaces COM, como as APIs de automação do Microsoft Office.

Importante

O VSTO (Visual Studio Tools for Office) depende do .NET Framework. Os suplementos COM também podem ser escritos com o .NET Framework. Os suplementos do Office não podem ser criados com o .NET Core e o .NET 5+, as versões mais recentes do .NET. Isso ocorre porque o .NET Core/.NET 5+ não pode trabalhar em conjunto com o .NET Framework no mesmo processo e pode levar a falhas de carregamento de suplementos. Você pode continuar a usar o .NET Framework para escrever suplementos VSTO e COM para o Office. A Microsoft não atualizará o VSTO ou a plataforma de suplemento COM para usar o .NET Core ou o .NET 5+. Você pode aproveitar o .NET Core e o .NET 5+, incluindo o ASP.NET Core, para criar o lado do servidor dos Suplementos Web do Office.

No exemplo a seguir, o método ConvertToTable tem 16 parâmetros que representam características de uma tabela, como número de colunas e linhas, formatação, bordas, fontes e cores. Todos os 16 parâmetros são opcionais, porque na maioria das vezes você não deseja especificar valores específicos para todos eles. No entanto, sem argumentos nomeados e opcionais, você deve fornecer um valor ou um valor de espaço reservado. Com argumentos nomeados e opcionais, você especifica valores apenas para os parâmetros necessários para seu projeto.

Tem de ter o Microsoft Office Word instalado no computador para concluir estes procedimentos.

Nota

Seu computador pode mostrar nomes ou locais diferentes para alguns dos elementos da interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você tem e as configurações que você usa determinam esses elementos. Para obter mais informações, consulte Personalizando o IDE.

Criar um novo aplicativo de console

Inicie o Visual Studio. No menu Arquivo, aponte para Novo e selecione Projeto. No painel Categorias de Modelos , expanda C# e selecione Windows. Examine na parte superior do painel Modelos para certificar-se de que o .NET Framework 4 aparece na caixa Estrutura de Destino . No painel Modelos, selecione Aplicativo de console. Digite um nome para seu projeto no campo Nome . Selecione OK. O novo projeto aparece no Gerenciador de Soluções.

Adicionar uma referência

No Gerenciador de Soluções, clique com o botão direito do mouse no nome do projeto e selecione Adicionar Referência. A caixa de diálogo Adicionar referência é exibida. Na página .NET, selecione Microsoft.Office.Interop.Word na lista Nome do componente. Selecione OK.

Adicionar necessário usando diretivas

No Gerenciador de Soluções, clique com o botão direito do mouse no arquivo Program.cs e selecione Exibir Código. Adicione as seguintes using diretivas à parte superior do arquivo de código:

using Word = Microsoft.Office.Interop.Word;

Exibir texto em um documento do Word

Program Na classe em Program.cs, adicione o seguinte método para criar um aplicativo do Word e um documento do Word. O método Add tem quatro parâmetros opcionais. Este exemplo usa seus valores padrão. Portanto, nenhum argumento é necessário na declaração de chamada.

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    wordApp.Visible = true;
    // docs is a collection of all the Document objects currently
    // open in Word.
    Word.Documents docs = wordApp.Documents;

    // Add a document to the collection and name it doc.
    Word.Document doc = docs.Add();
}

Adicione o seguinte código no final do método para definir onde exibir o texto no documento e qual texto exibir:

// Define a range, a contiguous area in the document, by specifying
// a starting and ending character position. Currently, the document
// is empty.
Word.Range range = doc.Range(0, 0);

// Use the InsertAfter method to insert a string at the end of the
// current range.
range.InsertAfter("Testing, testing, testing. . .");

Executar a aplicação

Adicione a seguinte instrução ao Main:

DisplayInWord();

Pressione CTRL+F5 para executar o projeto. É apresentado um documento do Word que contém o texto especificado.

Alterar o texto para uma tabela

Use o ConvertToTable método para incluir o texto em uma tabela. O método tem 16 parâmetros opcionais. O IntelliSense inclui parâmetros opcionais entre parênteses, conforme mostrado na ilustração a seguir.

Os argumentos nomeados e opcionais permitem especificar valores apenas para os parâmetros que você deseja alterar. Adicione o seguinte código ao final do método DisplayInWord para criar uma tabela. O argumento especifica que as vírgulas na cadeia de caracteres de texto separam range as células da tabela.

// Convert to a simple table. The table will have a single row with
// three columns.
range.ConvertToTable(Separator: ",");

Pressione CTRL+F5 para executar o projeto.

Experimente outros parâmetros

Altere a tabela para que ela tenha uma coluna e três linhas, substitua a última linha pela DisplayInWord instrução a seguir e digite CTRL+F5.

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

Especifique um formato predefinido para a tabela, substitua a última linha pela DisplayInWord instrução a seguir e digite CTRL+F5. O formato pode ser qualquer uma das constantes WdTableFormat .

range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
    Format: Word.WdTableFormat.wdTableFormatElegant);

Exemplo

O código a seguir inclui o exemplo completo:

using System;
using Word = Microsoft.Office.Interop.Word;

namespace OfficeHowTo
{
    class WordProgram
    {
        static void Main(string[] args)
        {
            DisplayInWord();
        }

        static void DisplayInWord()
        {
            var wordApp = new Word.Application();
            wordApp.Visible = true;
            // docs is a collection of all the Document objects currently
            // open in Word.
            Word.Documents docs = wordApp.Documents;

            // Add a document to the collection and name it doc.
            Word.Document doc = docs.Add();

            // Define a range, a contiguous area in the document, by specifying
            // a starting and ending character position. Currently, the document
            // is empty.
            Word.Range range = doc.Range(0, 0);

            // Use the InsertAfter method to insert a string at the end of the
            // current range.
            range.InsertAfter("Testing, testing, testing. . .");

            // You can comment out any or all of the following statements to
            // see the effect of each one in the Word document.

            // Next, use the ConvertToTable method to put the text into a table.
            // The method has 16 optional parameters. You only have to specify
            // values for those you want to change.

            // Convert to a simple table. The table will have a single row with
            // three columns.
            range.ConvertToTable(Separator: ",");

            // Change to a single column with three rows..
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1);

            // Format the table.
            range.ConvertToTable(Separator: ",", AutoFit: true, NumColumns: 1,
                Format: Word.WdTableFormat.wdTableFormatElegant);
        }
    }
}