Verwenden von benannten und optionalen Argumenten in der Office-Programmierung

Benannte und optionale Argumente optimieren die Zweckmäßigkeit, die Flexibilität und die Lesbarkeit in der C#-Programmierung. Diese Funktionen erleichtern zusätzlich den Zugriff auf COM-Schnittstellen wie etwa die Automatisierungs-APIs in Microsoft Office.

Wichtig

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 und höher erstellt werden, den neuesten Versionen von .NET. Dies liegt daran, dass .NET Core/.NET 5 und höher nicht mit .NET Framework im selben Prozess zusammenarbeiten und daher 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 und höher zu verwenden. Sie können .NET Core und .NET 5 und höher nutzen, einschließlich ASP.NET Core, um die Serverseite von Office Web-Add-Ins zu erstellen.

In folgendem Beispiel hat die Methode ConvertToTable 16 Parameter, die Eigenschaften einer Tabelle repräsentieren, wie z.B. die Zeilen- und Spaltenanzahl, das Format, die Rahmen, Schriftarten und Farben. Alle 16 Parameter sind optional, weil Sie oftmals keine bestimmten Werte für sie festlegen möchten. Ohne benannte und optionale Argumente müssen Sie jedoch einen Wert oder einen Platzhalterwert angeben. Mit benannten und optionalen Argumenten geben Sie nur für die Parameter Werte an, die für Ihr Projekt erforderlich sind.

Microsoft Office Word muss auf Ihrem Computer installiert sein, damit Sie diesen Vorgang abschließen können.

Hinweis

Auf Ihrem Computer werden möglicherweise andere Namen oder Speicherorte für die Benutzeroberflächenelemente von Visual Studio angezeigt als die in den folgenden Anweisungen aufgeführten. Diese Elemente sind von der jeweiligen Visual Studio-Version und den verwendeten Einstellungen abhängig. Weitere Informationen finden Sie unter Personalisieren 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 den Eintrag C#, und wählen Sie dann Windows. Sehen Sie am oberen Rand des Bereichs Vorlagen nach, um sicherzustellen, dass .NET Framework 4 im Feld Zielframework angezeigt wird. Wählen Sie im Bereich Vorlagen die Option Konsolenanwendung aus. Geben Sie einen Namen für das Projekt im Feld Name ein. Klicken Sie auf OK. Das neue Projekt wird im Projektmappen-Explorer angezeigt.

Hinzufügen eines Verweises

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

Hinzufügen erforderlicher using-Anweisungen

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

using Word = Microsoft.Office.Interop.Word;

Anzeigen von Text in einem Word-Dokument

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

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

Fügen Sie den folgenden Code am Ende der Methode hinzu, um zu definieren, wo der Text im Dokument angezeigt werden und um welchen Text es sich dabei handeln 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 mit dem angegebenen Text wird angezeigt.

Ä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 Klammern ein, wie in folgender Abbildung veranschaulicht.

Benannte und optionale Argumente ermöglichen es Ihnen, nur Werte für die Parameter anzugeben, die Sie auch ändern möchten. Fügen Sie den folgenden Code am Ende der DisplayInWord-Methode hinzu, um eine Tabelle zu erstellen. Das Argument gibt an, dass die Kommas in der Textzeichenfolge in range die Zelle 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 nur noch eine Spalte und drei Zeilen hat, ersetzen Sie die letzte Zeile in DisplayInWord durch folgende Anweisung, und geben Sie dann STRG+F5 ein.

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

Um ein vordefiniertes Format für die Tabelle anzugeben, ersetzen Sie die letzte Zeile in DisplayInWord durch folgende Anweisung, und geben Sie dann STRG+F5 ein. Das Format kann jede 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();
            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);
        }
    }
}