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#. Inoltre, queste funzionalità facilitano notevolmente l'accesso alle interfacce COM, ad esempio le API di automazione di Microsoft Office.

Importante

VSTO (Visual Studio Tools per Office) si basa su .NET Framework. I componenti aggiuntivi COM possono anche 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 componenti aggiuntivi VSTO e COM per Office. Microsoft non aggiornerà VSTO o la piattaforma del componente aggiuntivo COM per l'uso di .NET Core o .NET 5+. È possibile sfruttare i vantaggi di .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 ha 16 parametri che rappresentano le caratteristiche di una tabella, ad esempio il numero di colonne e righe, la formattazione, i bordi, i tipi di carattere e i colori. Tutti i 16 parametri sono facoltativi, perché nella maggior parte dei casi non si vogliono specificare valori specifici per tutti. Tuttavia, senza argomenti denominati e facoltativi, è necessario specificare un valore o un valore segnaposto. Con argomenti denominati e facoltativi, è possibile specificare i valori solo per i parametri necessari per il progetto.

Per completare queste procedure, è necessario che Nel computer sia installato Microsoft Office Word.

Annotazioni

Il computer potrebbe visualizzare nomi o percorsi diversi per alcuni degli elementi dell'interfaccia utente di Visual Studio nelle istruzioni seguenti. L'edizione di Visual Studio disponibile e le impostazioni usate determinano questi elementi. Per altre informazioni, vedere Personalizzazione dell'IDE.

Creare una nuova applicazione console

Avvia Visual Studio. Scegliere Nuovo dal menu Filee quindi selezionare Progetto. Nel riquadro Categorie modelli espandere C#, quindi selezionare Windows. Cercare nella parte superiore del riquadro Modelli per assicurarsi che .NET Framework 4 appaia 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 soluzioni fare clic con il pulsante destro del mouse sul nome del progetto e quindi scegliere Aggiungi riferimento. Viene 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 soluzioni fare clic con il pulsante destro del mouse sul file Program.cs e quindi scegliere Visualizza codice. Aggiungere le direttive seguenti using all'inizio del file di codice:

using Word = Microsoft.Office.Interop.Word;

Visualizzare il testo in un documento di Word

Program Nella classe in Program.cs aggiungere il metodo seguente per creare un'applicazione Word e un documento di Word. Il metodo Add ha quattro parametri facoltativi. In questo esempio vengono usati i valori predefiniti. Pertanto, nell'istruzione chiamante non sono necessari argomenti.

Annotazioni

Per evitare problemi di threading e intervallo COM che possono causare eccezioni come "Il filtro dei messaggi indica che l'applicazione è occupata" (HRESULT 0x8001010A), l'applicazione Word viene mantenuta invisibile durante le operazioni e resa visibile solo dopo il completamento di tutte le operazioni.

static void DisplayInWord()
{
    var wordApp = new Word.Application();
    // Keep Word invisible during operations to avoid COM threading issues
    wordApp.Visible = false;
    // 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();
    
    // Make Word visible after operations are complete
    wordApp.Visible = true;
}

Aggiungere il codice seguente alla fine del metodo per definire dove visualizzare il testo nel documento e il testo da 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

Aggiungi la seguente istruzione a Main:

DisplayInWord();

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

Modificare il testo in una tabella

Utilizzare il ConvertToTable metodo per racchiudere il testo in una tabella. Il metodo ha 16 parametri facoltativi. IntelliSense racchiude i parametri facoltativi tra parentesi quadre, come illustrato nella figura seguente. I valori predefiniti di Type.Missing sono il nome semplice per System.Type.Missing.

Gli argomenti denominati e facoltativi consentono di specificare valori solo per i parametri da modificare. Aggiungere il codice seguente alla fine del metodo DisplayInWord per creare una tabella. L'argomento specifica 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 altri parametri

Modificare la tabella in modo che contenga una colonna e tre righe, sostituire l'ultima riga in DisplayInWord con l'istruzione seguente e quindi digitare 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 e quindi digitare CTRL+F5. Il formato può essere una delle costanti 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();
            // Keep Word invisible during operations to avoid COM threading issues
            wordApp.Visible = false;
            // 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);

            // Make Word visible after all operations are complete
            wordApp.Visible = true;
        }
    }
}