Verwenden von benannten und optionalen Argumenten in der Office-Programmierung

Benannte Argumente und optionale Argumente verbessern die Benutzerfreundlichkeit, Flexibilität und Lesbarkeit bei der C#-Programmierung. Darüber hinaus erleichtern diese Features den Zugriff auf COM-Schnittstellen wie die Microsoft Office-Automatisierungs-APIs erheblich.

Von Bedeutung

VSTO (Visual Studio Tools for Office) basiert auf .NET Framework. COM-Add-Ins können auch mit .NET Framework geschrieben werden. Office-Add-Ins können nicht mit .NET Core und .NET 5+ erstellt werden, die neuesten Versionen von .NET. Dies liegt daran, dass .NET Core/.NET 5+ nicht mit .NET Framework im selben Prozess zusammenarbeiten kann und zu Add-In-Ladefehlern führen kann. Sie können .NET Framework weiterhin zum Schreiben von VSTO- und COM-Add-Ins für Office verwenden. Microsoft aktualisiert VSTO oder die COM-Add-In-Plattform nicht, um .NET Core oder .NET 5+ zu verwenden. Sie können .NET Core und .NET 5+ nutzen, einschließlich ASP.NET Core, um die Serverseite von Office Web-Add-Ins zu erstellen.

Im folgenden Beispiel weist die Methode ConvertToTable 16 Parameter auf, die Merkmale einer Tabelle darstellen, z. B. Anzahl von Spalten und Zeilen, Formatierung, Rahmen, Schriftarten und Farben. Alle 16 Parameter sind optional, da Sie meistens keine bestimmten Werte für alle angeben möchten. Ohne benannte und optionale Argumente müssen Sie jedoch einen Wert oder einen Platzhalterwert angeben. Bei benannten und optionalen Argumenten geben Sie werte nur für die parameter an, die für Ihr Projekt erforderlich sind.

Sie müssen Microsoft Office Word auf Ihrem Computer installiert haben, um diese Verfahren ausführen zu können.

Hinweis

Auf Ihrem Computer werden möglicherweise unterschiedliche Namen oder Speicherorte für einige der Visual Studio-Benutzeroberflächenelemente in den folgenden Anweisungen angezeigt. Die Visual Studio-Edition, über die Sie verfügen, und die Einstellungen, die Sie verwenden, bestimmen diese Elemente. Weitere Informationen finden Sie unter Personalisierung der IDE.

Erstellen einer neuen Konsolenanwendung

Starten Sie Visual Studio. Zeigen Sie im Menü Datei auf Neu, und klicken Sie dann auf Projekt. Erweitern Sie im Bereich "Vorlagenkategorien " C#, und wählen Sie dann Windows aus. Suchen Sie oben im Vorlagenbereich , um sicherzustellen, dass .NET Framework 4 im Feld "Zielframework " angezeigt wird. Wählen Sie im Bereich "Vorlagen" die Option "Konsolenanwendung" aus. Geben Sie im Feld "Name " einen Namen für Ihr Projekt ein. Wählen Sie OK aus. Das neue Projekt wird im Projektmappen-Explorer angezeigt.

Hinzufügen eines Verweises

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Namen Ihres Projekts, und wählen Sie dann "Verweis hinzufügen" aus. Das Dialogfeld Verweis hinzufügen wird angezeigt. Wählen Sie auf der .NET-Seite"Microsoft.Office.Interop.Word " in der Liste "Komponentenname " aus. Wählen Sie OK aus.

Hinzufügen erforderlicher using-Anweisungen

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Program.cs Datei, und wählen Sie dann "Code anzeigen" aus. Fügen Sie die folgenden using Direktiven am Anfang der Codedatei hinzu:

using Word = Microsoft.Office.Interop.Word;

Anzeigen von Text in einem Word-Dokument

Fügen Sie in der Program Klasse in Program.cs die folgende Methode hinzu, um eine Word-Anwendung und ein Word-Dokument zu erstellen. Die Add-Methode verfügt über vier optionale Parameter. In diesem Beispiel werden die Standardwerte verwendet. Deshalb sind in der aufrufenden Anweisung keine Argumente erforderlich.

Hinweis

Um COM-Threading- und Timing-Probleme zu vermeiden, die Ausnahmen wie "Der Nachrichtenfilter hat angegeben, dass die Anwendung ausgelastet ist" (HRESULT 0x8001010A) verursachen können, wird die Word-Anwendung während der Vorgänge unsichtbar gehalten und erst sichtbar gemacht, nachdem alle Vorgänge abgeschlossen sind.

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

Fügen Sie am Ende der Methode den folgenden Code hinzu, um zu definieren, wo Text im Dokument angezeigt werden soll und welcher Text angezeigt werden soll:

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

Ausführen der Anwendung

Fügen Sie die folgende Anweisung in Main hinzu:

DisplayInWord();

Drücken Sie STRG+F5 , um das Projekt auszuführen. Ein Word-Dokument wird angezeigt, das den angegebenen Text enthält.

Ändern von Text in eine Tabelle

Verwenden Sie die ConvertToTable Methode, um den Text in eine Tabelle einzuschließen. Die Methode verfügt über 16 optionale Parameter. IntelliSense schließt optionale Parameter in eckige Klammern ein, wie in der folgenden Abbildung dargestellt. Die Standardwerte von Type.Missing sind der einfache Name für System.Type.Missing.

Benannte und optionale Argumente ermöglichen ihnen die Angabe von Werten nur für die Parameter, die Sie ändern möchten. Fügen Sie am Ende der Methode DisplayInWord den folgenden Code hinzu, um eine Tabelle zu erstellen. Das Argument gibt an, dass die Kommas in der Textzeichenfolge in range die Zellen der Tabelle trennen.

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

Drücken Sie STRG+F5 , um das Projekt auszuführen.

Experimentieren mit anderen Parametern

Ändern Sie die Tabelle so, dass sie eine Spalte und drei Zeilen enthält, ersetzen Sie die letzte Zeile in DisplayInWord der folgenden Anweisung, und geben Sie dann STRG+F5 ein.

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

Geben Sie ein vordefiniertes Format für die Tabelle an, ersetzen Sie die letzte Zeile in DisplayInWord der folgenden Anweisung, und geben Sie dann STRG+F5 ein. Das Format kann eine der WdTableFormat-Konstanten sein.

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

Beispiel

Der folgende Code enthält das vollständige Beispiel:

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