Exemplarische Vorgehensweise: Office-Programmierung in C#

C# bietet Features, die die Microsoft Office-Programmierung verbessern. Zu nützlichen C#-Funktionen gehören benannte und optionale Argumente und Rückgabewerte des Typs dynamic. Bei der COM-Programmierung können Sie das ref-Schlüsselwort weglassen und Zugriff auf indizierte Eigenschaften erhalten.

Beide Sprachen ermöglichen das Einbetten von Typinformationen, wodurch Assemblys bereitgestellt werden können, die mit COM-Komponenten interagieren, ohne primäre Interop-Assemblys (PIAs) auf dem Computer des Benutzers bereitzustellen. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Einbetten von Typen aus verwalteten Assemblys.

Diese exemplarische Vorgehensweise veranschaulicht diese Funktionen im Kontext der Office-Programmierung, aber viele dieser Funktionen sind auch bei der allgemeinen Programmierung nützlich. In der exemplarischen Vorgehensweise verwenden Sie eine Excel-Add-In-Anwendung, um eine Excel-Arbeitsmappe zu erstellen. Als nächstes erstellen Sie ein Word-Dokument, das einen Link zur Arbeitsmappe enthält. Zum Schluss sehen Sie, wie Sie die PIA-Abhängigkeit aktivieren und deaktivieren können.

Voraussetzungen

Auf Ihrem Computer müssen Microsoft Office Excel und Microsoft Office Word oder neuere Versionen installiert sein, um diese exemplarische Vorgehensweise ausführen zu können.

Einrichten einer Excel-Add-In-Anwendung

1. Starten Sie Visual Studio.
2. Zeigen Sie im Menü Datei auf Neu, und klicken Sie dann auf Projekt.
3. Erweitern Sie im Bereich Installierte Vorlagen den Bereich C#, erweitern Sie Office, und wählen Sie dann das Versionsjahr des Office-Produkts aus.
4. Wählen Sie im Bereich Vorlagen die Option Excel <Version> Add-In aus.
5. Sehen Sie am oberen Rand des Bereichs Vorlagen nach, um sicherzustellen, dass .NET Framework 4 oder eine höhere Version im Feld Zielframework angezeigt wird.
6. Geben Sie, wenn gewünscht, einen Namen für das Projekt in das Feld Name ein.
7. Klicken Sie auf OK.
8. Das neue Projekt wird im Projektmappen-Explorer angezeigt.

Hinzufügen von Verweisen

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektnamen, und wählen Sie dann Verweis hinzufügen aus. Das Dialogfeld Verweis hinzufügen wird angezeigt.
2. Wählen Sie auf der Registerkarte Assemblys die Option Microsoft.Office.Interop.Excel, Version <version>.0.0.0 (einen Schlüssel für die Versionsnummer des Office-Produkts finden Sie unter Microsoft Versions (in englischer Sprache)), in der Liste Komponentenname aus, und halten Sie dann die STRG-Taste gedrückt, während Sie Microsoft.Office.Interop.Word, version <version>.0.0.0 auswählen. Wenn die Assemblys nicht angezeigt werden, müssen Sie sie möglicherweise installieren (siehe Vorgehensweise: Installieren von primären Interopassemblys für Office).
3. Klicken Sie auf OK.

Hinzufügen erforderlicher Imports- oder using-Anweisungen

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Datei ThisAddIn.cs, und wählen Sie dann Code anzeigen aus. Fügen Sie die folgenden using-Anweisungen (C#) am Anfang der Codedatei ein, wenn sie noch nicht vorhanden sind.

using System.Collections.Generic;
using Excel = Microsoft.Office.Interop.Excel;
using Word = Microsoft.Office.Interop.Word;

Erstellen einer Liste mit Bankkonten

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektnamen, und wählen Sie Hinzufügen und anschließend Klasse aus. Nennen Sie die Klasse „Account.cs“. Wählen Sie Hinzufügen. Ersetzen Sie die Definition der Account-Klasse durch den folgenden Code. Die Klassendefinitionen verwenden automatisch implementierte Eigenschaften.

class Account
{
    public int ID { get; set; }
    public double Balance { get; set; }
}

Fügen Sie den folgenden Code in die ThisAddIn_Startup-Methode in ThisAddIn.cs ein, um eine bankAccounts-Liste mit zwei Konten zu erstellen. Die Listendeklarationen verwenden Auflistungsinitialisierer.

var bankAccounts = new List<Account>
{
    new Account
    {
        ID = 345,
        Balance = 541.27
    },
    new Account
    {
        ID = 123,
        Balance = -127.44
    }
};

Exportieren von Daten in Excel

Fügen Sie in der gleichen Datei die folgende Methode der ThisAddIn-Klasse hinzu. Die Methode richtet eine Excel-Arbeitsmappe ein, in die die Daten exportiert werden.

void DisplayInExcel(IEnumerable<Account> accounts,
           Action<Account, Excel.Range> DisplayFunc)
{
    var excelApp = this.Application;
    // Add a new Excel workbook.
    excelApp.Workbooks.Add();
    excelApp.Visible = true;
    excelApp.Range["A1"].Value = "ID";
    excelApp.Range["B1"].Value = "Balance";
    excelApp.Range["A2"].Select();

    foreach (var ac in accounts)
    {
        DisplayFunc(ac, excelApp.ActiveCell);
        excelApp.ActiveCell.Offset[1, 0].Select();
    }
    // Copy the results to the Clipboard.
    excelApp.Range["A1:B3"].Copy();
}

• Die Methode Add hat einen optionalen Parameter zum Angeben einer bestimmten Vorlage. Optionale Parameter ermöglichen es Ihnen, das Argument für diesen Parameter auszulassen, wenn Sie den Standardwert des Parameters verwenden möchten. Da im vorherigen Beispiel keine Argumente vorhanden sind, verwendet Add die Standardvorlage und erstellt eine neue Arbeitsmappe. Die entsprechende Anweisung in früheren Versionen von C# erfordert ein Platzhalterargument: excelApp.Workbooks.Add(Type.Missing). Weitere Informationen finden Sie unter Benannte und optionale Argumente.
• Die Eigenschaften Range und Offset des range-Objekts verwenden die Funktion Indizierte Eigenschaften. Diese Funktion ermöglicht es Ihnen, diese Eigenschaften von COM-Typen zu nutzen, indem Sie die folgende typische C#-Syntax verwenden. Indizierte Eigenschaften ermöglichen es Ihnen außerdem, die Value-Eigenschaft des Range-Objekts zu verwenden, sodass Sie die Value2-Eigenschaft nicht mehr verwenden müssen. Die Value-Eigenschaft ist indiziert, der Index ist jedoch optional. Optionale Argumente und indizierte Eigenschaften arbeiten im folgenden Beispiel zusammen.

// Visual C# 2010 provides indexed properties for COM programming.
excelApp.Range["A1"].Value = "ID";
excelApp.ActiveCell.Offset[1, 0].Select();

Sie können nicht Ihre eigenen indizierten Eigenschaften erstellen. Die Funktion unterstützt nur die Nutzung vorhandener indizierter Eigenschaften.

Fügen Sie den folgenden Code am Ende von DisplayInExcel hinzu, um die Spaltenbreite an den Inhalt anzupassen.

excelApp.Columns[1].AutoFit();
excelApp.Columns[2].AutoFit();

Diese Ergänzungen veranschaulichen eine weitere Funktion in C#: die Behandlung von Object-Werten, die von COM-Hosts wie z.B. Office zurückgegeben wurden, als wären sie vom Typ dynamic. COM-Objekte werden automatisch als dynamic behandelt, wenn Interoptypen einbetten den Standardwert, True, aufweist, oder entsprechend, wenn Sie auf die Assembly mit der EmbedInteropTypes-Compileroption verweisen. Weitere Informationen zum Einbetten von Interoptypen finden Sie in den Verfahren „So suchen Sie den PIA-Verweis“ und „So stellen Sie die PIA-Abhängigkeit wieder her“ weiter unten in diesem Artikel. Weitere Informationen zu dynamic finden Sie unter dynamic oder Verwenden von dynamischen Typen.

Aufrufen von DisplayInExcel

Fügen Sie den folgenden Code am Ende der ThisAddIn_StartUp-Methode hinzu. Der Aufruf von DisplayInExcel enthält zwei Argumente. Das erste Argument ist der Name der Liste mit den zu verarbeitenden Konten. Das zweite Argument ist ein mehrzeiliger Lambda-Ausdruck, der definiert, wie die Daten verarbeitet werden. Die ID- und balance-Werte für jedes Konto werden in angrenzenden Zellen angezeigt, und die Zeile wird rot dargestellt, wenn der Saldo kleiner als Null ist. Weitere Informationen finden Sie unter Lambdaausdrücke.

DisplayInExcel(bankAccounts, (account, cell) =>
// This multiline lambda expression sets custom processing rules
// for the bankAccounts.
{
    cell.Value = account.ID;
    cell.Offset[0, 1].Value = account.Balance;
    if (account.Balance < 0)
    {
        cell.Interior.Color = 255;
        cell.Offset[0, 1].Interior.Color = 255;
    }
});

Drücken Sie F5, um das Programm auszuführen. Ein Excel-Arbeitsblatt wird mit den Kontendaten angezeigt.

Hinzufügen eines Word-Dokuments

Fügen Sie den folgenden Code am Ende der ThisAddIn_StartUp-Methode hinzu, um ein Word-Dokument zu erstellen, das einen Link zur Excel-Arbeitsmappe enthält.

var wordApp = new Word.Application();
wordApp.Visible = true;
wordApp.Documents.Add();
wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);

Dieser Code veranschaulicht mehrere Features von C#: Die Möglichkeit, das Schlüsselwort ref in der COM-Programmierung wegzulassen, benannte Argumente und optionale Argumente. Die Methode PasteSpecial hat sieben Parameter, bei denen es sich um optionale Referenzparameter handelt. Benannte und optionale Argumente ermöglichen es Ihnen, die Parameter festzulegen, auf die Sie namentlich zugreifen möchten, und Argumente nur an diese Parameter zu senden. In diesem Beispiel geben die Argumente an, dass Sie eine Verknüpfung mit der Arbeitsmappe in der Zwischenablage erstellen (Parameter Link) und dass die Verknüpfung im Word-Dokument als Symbol angezeigt wird (Parameter DisplayAsIcon). C# ermöglicht auch das Weglassen des ref-Schlüsselworts für diese Argumente.

Ausführen der Anwendung

Drücken Sie F5, um die Anwendung auszuführen. Excel wird gestartet und zeigt eine Tabelle mit den Informationen der beiden Konten in bankAccounts an. Anschließend wird ein Word-Dokument angezeigt, das einen Link zur Excel-Tabelle enthält.

Bereinigen des abgeschlossenen Projekts

Wählen Sie in Visual Studio die Option Projektmappe bereinigen im Menü Erstellen aus. Andernfalls wird das Add-In jedes Mal ausgeführt, wenn Sie Excel auf Ihrem Computer öffnen.

Suchen des PIA-Verweises

1. Führen Sie die Anwendung erneut aus, aber wählen Sie nicht Projektmappe bereinigen aus.
2. Wählen Sie Start aus. Suchen Sie Microsoft Visual Studio <Version> und öffnen Sie eine Entwicklereingabeaufforderung.
3. Geben Sie in der Developer-Eingabeaufforderung für Visual Studio ildasm ein, und drücken Sie dann die EINGABETASTE. Das IL DASM-Fenster wird angezeigt.
4. Klicken Sie im IL DASM-Fenster im Menü Datei auf Datei>Öffnen. Doppelklicken Sie auf Visual Studio <Version> und dann noch einmal auf Projekte. Öffnen Sie den Ordner für das Projekt, und suchen Sie im Ordner „bin/Debug“ nach der Datei Projektname.dll. Doppelklicken Sie auf Projektname.dll. In einem neuen Fenster werden die Attribute Ihres Projekts sowie Verweise auf andere Module und Assemblys angezeigt. Die Assembly enthält die Namespaces Microsoft.Office.Interop.Excel und Microsoft.Office.Interop.Word. Standardmäßig importiert der Compiler in Visual Studio die benötigten Typen aus einer referenzierten PIA in Ihre Assembly. Weitere Informationen finden Sie unter Vorgehensweise: View Assembly Contents (Vorgehensweise: Anzeigen von Assemblyinhalt).
5. Doppelklicken Sie auf das Symbol MANIFEST. Es wird ein Fenster angezeigt, das eine Liste von Assemblys enthält, die vom Projekt referenzierte Elemente enthalten. Microsoft.Office.Interop.Excel und Microsoft.Office.Interop.Word sind nicht in der Liste enthalten. Da Sie die von Ihrem Projekt benötigten Typen in Ihre Assembly importiert haben, müssen Sie keine Verweise auf eine PIA installieren. Das Importieren der Typen in die Assembly erleichtert die Bereitstellung. Die PIAs müssen nicht auf dem Computer des Benutzers vorhanden sein. Eine Anwendung erfordert nicht die Bereitstellung einer bestimmten Version einer PIA. Anwendungen können mit mehreren Versionen von Office arbeiten, vorausgesetzt, die erforderlichen APIs sind in allen Versionen vorhanden. Da die Bereitstellung von primären Interop-Assemblys nicht mehr benötigt wird, können Sie eine Anwendung in erweiterten Szenarien erstellen, bei denen mehrere Versionen von Office, einschließlich früherer Versionen, verwendet werden. Ihr Code kann keine APIs verwenden, die in der Office-Version, mit der Sie arbeiten, nicht verfügbar sind. Es ist nicht immer eindeutig, ob eine bestimmte API in einer früheren Version verfügbar war. Das Arbeiten mit früheren Versionen von Office wird nicht empfohlen.
6. Schließen Sie das Manifest-Fenster und das Assembly-Fenster.

Wiederherstellen der PIA-Abhängigkeit

1. Wählen Sie im Projektmappen-Explorer die Schaltfläche Alle Dateien anzeigen aus. Erweitern Sie den Ordner Verweise, und wählen Sie Microsoft.Office.Interop.Excel aus. Drücken Sie F4, um das Fenster Eigenschaften anzuzeigen.
2. Ändern Sie im Fenster Eigenschaften die Eigenschaft Einbetten von Interop-Typen von True zu False.
3. Wiederholen Sie die Schritte 1 und 2 in dieser Prozedur für Microsoft.Office.Interop.Word.
4. Kommentieren Sie in C# die beiden Aufrufe von Autofit am Ende der DisplayInExcel-Methode aus.
5. Drücken Sie F5, um sicherzustellen, dass das Projekt immer noch ordnungsgemäß ausgeführt wird.
6. Wiederholen Sie die Schritte 1 bis 3 der vorherigen Prozedur, um das Assembly-Fenster zu öffnen. Beachten Sie, dass Microsoft.Office.Interop.Word und Microsoft.Office.Interop.Excel nicht mehr in der Liste der eingebetteten Assemblys sind.
7. Doppelklicken Sie auf das Symbol MANIFEST, und führen Sie einen Bildlauf durch die Liste der referenzierten Assemblys durch. Microsoft.Office.Interop.Word und Microsoft.Office.Interop.Excel befinden sich in der Liste. Da die Anwendung auf die Excel- und Word-PIAs verweist und die Eigenschaft Interoptypen einbetten auf False festgelegt ist, müssen beide Assemblys auf dem Computer des Endbenutzers vorhanden sein.
8. Wählen Sie in Visual Studio im Menü Erstellen die Option Projektmappe bereinigen aus, um das abgeschlossene Projekt zu bereinigen.

Weitere Informationen

• Automatisch implementierte Eigenschaften (C#)
• Objekt- und Auflistungsinitialisierer
• Visual Studio Tools für Office (VSTO)
• Benannte und optionale Argumente
• dynamic
• Verwenden von dynamischen Typen
• Lambdaausdrücke (C#)
• Exemplarische Vorgehensweise: Einbetten von Typinformationen aus Microsoft Office-Assemblys in Visual Studio
• Exemplarische Vorgehensweise: Einbetten von Typen aus verwalteten Assemblys in Visual Studio
• Exemplarische Vorgehensweise: Creating Your First VSTO Add-in for Excel (Exemplarische Vorgehensweise: Erstellen Ihres ersten VSTO-Add-Ins für Excel)