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.

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.

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 valores padrão de Type.Missing são o nome simples para System.Type.Missing.

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);
        }
    }
}