Come usare argomenti denominati e facoltativi nella programmazione di Office

Gli argomenti denominati e gli argomenti facoltativi migliorano praticità, flessibilità e leggibilità nella programmazione C#. Queste funzionalità, poi, semplificano notevolmente l'accesso alle interfacce COM, quali le API di automazione di Microsoft Office.

Importante

VSTO (Visual Studio Tools per Office) si basa su .NET Framework. Anche i componenti aggiuntivi COM possono essere scritti con .NET Framework. Non è possibile creare componenti aggiuntivi per Office con .NET Core e .NET 5+, le versioni più recenti di .NET. Ciò è dovuto al fatto che .NET Core/.NET 5+ non può funzionare insieme a .NET Framework nello stesso processo e può causare errori di caricamento dei componenti aggiuntivi. È possibile continuare a usare .NET Framework per scrivere VSTO e i componenti aggiuntivi COM per Office. Microsoft non aggiornerà VSTO o la piattaforma dei componenti aggiuntivi COM per l'uso di .NET Core o .NET 5+. È possibile utilizzare .NET Core e .NET 5+, incluso ASP.NET Core, per creare il lato server dei componenti aggiuntivi Web di Office.

Nell'esempio seguente, il metodo ConvertToTable dispone di 16 parametri che rappresentano le caratteristiche di una tabella, ad esempio il numero di colonne e di righe, la formattazione, i bordi, i tipi di carattere e i colori. I 16 parametri sono tutti facoltativi, perché nella maggior parte dei casi non si vogliono specificare particolari valori per tutti. Tuttavia, senza argomenti denominati e facoltativi, è necessario specificare un valore o un valore segnaposto. Con gli argomenti denominati e facoltativi si specificano valori solo per i parametri obbligatori per il progetto.

Per eseguire queste procedure, Microsoft Office Word deve essere installato.

Nota

I nomi o i percorsi visualizzati per alcuni elementi dell'interfaccia utente di Visual Studio nelle istruzioni seguenti potrebbero essere diversi nel computer in uso. La versione di Visual Studio in uso e le impostazioni configurate determinano questi elementi. Per altre informazioni, vedere Personalizzazione dell'IDE.

Creare un nuovo progetto di applicazione console

Avviare Visual Studio. Scegliere Nuovo dal menu Filee quindi selezionare Progetto. Nel riquadro Categorie modelli espandere C# e quindi selezionare Windows. Verificare che nella parte superiore del riquadro Modelli sia visualizzato .NET Framework 4 nella casella Framework di destinazione. Nel riquadro modelli selezionare Applicazione console. Digitare un nome per il progetto nel campo Nome. Seleziona OK. Il nuovo progetto verrà visualizzato in Esplora soluzioni.

Aggiungere un riferimento

In Esplora soluzionifare clic con il pulsante destro del mouse sul nome del progetto, quindi scegliere Aggiungi riferimento. Verrà visualizzata la finestra di dialogo Aggiungi riferimento. Nella pagina .NET selezionare Microsoft.Office.Interop.Word nell'elenco Nome componente. Seleziona OK.

Aggiungere le direttive using necessarie

In Esplora soluzionifare clic con il pulsante destro del mouse sul file Program.cs, quindi selezionare Visualizza codice. Aggiungere le direttive using seguenti all'inizio del file di codice:

using Word = Microsoft.Office.Interop.Word;

Visualizzare il testo in un documento di Word

Nella classe Program in Program.cs aggiungere il metodo seguente per creare un'applicazione di Word e un documento di Word. Il metodo Add dispone di quattro parametri facoltativi. Questo esempio usa i relativi valori predefiniti. Non sono pertanto necessari argomenti nell'istruzione di chiamata.

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

Aggiungere il codice seguente alla fine del metodo per definire il punto in cui visualizzare del testo nel documento e quale testo visualizzare:

// 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. . .");

Eseguire l'applicazione

Aggiungere a Main l'istruzione riportata di seguito:

DisplayInWord();

Premere CTRL+F5 per eseguire il progetto. Verrà visualizzato un documento di Word contenente il testo specificato.

Convertire il testo in una tabella

Usare il metodo ConvertToTable per racchiudere il testo in una tabella. Il metodo presenta 16 parametri facoltativi. IntelliSense racchiude tra parentesi quadre i parametri facoltativi, come mostrato nell'immagine seguente. I valori predefiniti di Type.Missing sono il nome semplice di System.Type.Missing.

Gli argomenti denominati e facoltativi consentono di specificare valori esclusivamente per i parametri che si vogliono modificare. Aggiungere il codice seguente alla fine del metodo DisplayInWord per creare una tabella. L'argomento indica che le virgole nella stringa di testo in range separano le celle della tabella.

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

Premere CTRL+F5 per eseguire il progetto.

Sperimentare nell’uso di altri parametri

Modificare la tabella in modo che contenga una colonna e tre righe, sostituire l'ultima riga in DisplayInWord con l'istruzione seguente, quindi premere CTRL+F5.

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

Specificare un formato predefinito per la tabella, sostituire l'ultima riga in DisplayInWord con l'istruzione seguente, quindi premere CTRL+F5. Il formato può corrispondere a qualsiasi costante WdTableFormat.

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

Esempio

Il codice seguente include l'esempio 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);
        }
    }
}