Walkthrough: Office Programming (C# and Visual Basic)

Article
09/10/2012

Visual Studio 2010 introduces new features in C# and Visual Basic that improve Microsoft Office programming. Each language has added features that already exist in the other language.

The new features in C# include named and optional arguments, return values that have type dynamic, and, in COM programming, the ability to omit the ref keyword and to access indexed properties. The new features in Visual Basic include auto-implemented properties, statements in lambda expressions, and collection initializers.

Both languages enable embedding of type information, which allows deployment of assemblies that interact with COM components without deploying primary interop assemblies (PIAs) to the user's computer. For more information, see Walkthrough: Embedding Types from Managed Assemblies (C# and Visual Basic).

This walkthrough demonstrates the new features in the context of Office programming, but many of them are also useful in general programming. In the walkthrough, you will first use an Excel Add-in application to create an Excel workbook. You will then create a Word document that contains a link to the workbook. Finally, you will see how the PIA dependency can be turned on and off.

Prerequisites

You must have Microsoft Office Excel 2010 or 2007 and Microsoft Office Word 2010 or 2007 installed on your computer to complete this walkthrough.

If you are using an operating system that is older than Windows Vista, make sure that .NET Framework 2.0 is installed.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

To set up an Excel Add-in application

Start Visual Studio.
On the File menu, point to New, and then click Project.
In the Installed Templates pane, expand Visual Basic or Visual C#, expand Office, and then click 2010 (or 2007 if you are using Office 2007).
In the Templates pane, click Excel 2010 Add-in (or Excel 2007 Add-in).
Look at the top of the Templates pane to make sure that .NET Framework 4 appears in the Target Framework box.
Type a name for your project in the Name box, if you want to.
Click OK.
The new project appears in Solution Explorer.

To add references

In Solution Explorer, right-click your project's name and then click Add Reference. The Add Reference dialog box appears.
On the .NET tab, select Microsoft.Office.Interop.Excel, version 14.0.0.0 (or version 12.0.0.0 for Excel 2007), in the Component Name list, and then hold down the CTRL key and select Microsoft.Office.Interop.Word, version 14.0.0.0 (or version 12.0.0.0 for Word 2007).
Click OK.

To add necessary Imports statements or using directives

In Solution Explorer, right-click the ThisAddIn.vb or ThisAddIn.cs file and then click View Code.

Add the following Imports statements (Visual Basic) or using directives (C#) to the top of the code file if they are not already present.

Imports Microsoft.Office.Interop

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

To create a list of bank accounts

In Solution Explorer, right-click your project's name, click Add, and then click Class. Name the class Account.vb if you are using Visual Basic or Account.cs if you are using C#. Click Add.
Replace the definition of the Account class with the following code. The class definitions use auto-implemented properties, new to Visual Basic in Visual Studio 2010. For more information, see Auto-Implemented Properties (Visual Basic).
```
Public Class Account
    Property ID As Integer = -1
    Property Balance As Double 
End Class
```
```
class Account
{
    public int ID { get; set; }
    public double Balance { get; set; }
}
```

To create a bankAccounts list that contains two accounts, add the following code to the ThisAddIn_Startup method in ThisAddIn.vb or ThisAddIn.cs. The list declarations use collection initializers, new to Visual Basic in Visual Studio 2010. For more information, see Collection Initializers (Visual Basic).

Dim bankAccounts As New List(Of Account) From {
    New Account With {
                          .ID = 345,
                          .Balance = 541.27
                     },
    New Account With {
                          .ID = 123,
                          .Balance = -127.44
                     }
    }

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

To export data to Excel

In the same file, add the following method to the ThisAddIn class. The method sets up an Excel workbook and exports data to it.
```
Sub DisplayInExcel(ByVal accounts As IEnumerable(Of Account),
               ByVal DisplayAction As Action(Of Account, Excel.Range))

    With Me.Application
        ' Add a new Excel workbook.
        .Workbooks.Add()
        .Visible = True
        .Range("A1").Value = "ID"
        .Range("B1").Value = "Balance"
        .Range("A2").Select()

        For Each ac In accounts
            DisplayAction(ac, .ActiveCell)
            .ActiveCell.Offset(1, 0).Select()
        Next 

        ' Copy the results to the Clipboard.
        .Range("A1:B3").Copy()
    End With 
End Sub
```
```
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();
}
```
Two new C# features are used in this method. Both of these features already exist in Visual Basic.
- Method Add has an optional parameter for specifying a particular template. Optional parameters, new in Visual C# 2010, enable you to omit the argument for that parameter if you want to use the parameter's default value. Because no argument is sent in the previous example, Add uses the default template and creates a new workbook. The equivalent statement in earlier versions of C# requires a placeholder argument: excelApp.Workbooks.Add(Type.Missing).
  
  For more information, see Named and Optional Arguments (C# Programming Guide).
- The Range and Offset properties of the Range object use the indexed properties feature. This feature enables you to consume these properties from COM types by using the following typical C# syntax. Indexed properties also enable you to use the Value property of the Range object, eliminating the need to use the Value2 property. The Value property is indexed, but the index is optional. Optional arguments and indexed properties work together in the following example.
```
// Visual C# 2010 provides indexed properties for COM programming.
excelApp.Range["A1"].Value = "ID";
excelApp.ActiveCell.Offset[1, 0].Select();
```
  In earlier versions of the language, the following special syntax is required.
```
// In Visual C# 2008, you cannot access the Range, Offset, and Value 
// properties directly.
excelApp.get_Range("A1").Value2 = "ID";
excelApp.ActiveCell.get_Offset(1, 0).Select();
```
  You cannot create indexed properties of your own. The feature only supports consumption of existing indexed properties.
  
  For more information, see How to: Use Indexed Properties in COM Interop Programming (C# Programming Guide).
Add the following code at the end of DisplayInExcel to adjust the column widths to fit the content.
```
' Add the following two lines at the end of the With statement.
.Columns(1).AutoFit()
.Columns(2).AutoFit()
```
```
excelApp.Columns[1].AutoFit();
excelApp.Columns[2].AutoFit();
```
These additions demonstrate another new feature in C# 2010: treating Object values returned from COM hosts such as Office as if they have type dynamic. This happens automatically when Embed Interop Types is set to its default value, True, or, equivalently, when the assembly is referenced by the /link compiler option. Type dynamic allows late binding, already available in Visual Basic, and avoids the explicit casting required in Visual C# 2008 and earlier versions of the language.

For example, excelApp.Columns[1] returns an Object, and AutoFit is an Excel Range method. Without dynamic, you must cast the object returned by excelApp.Columns[1] as an instance of Range before calling method AutoFit.
```
// Casting is required in Visual C# 2008.
((Excel.Range)excelApp.Columns[1]).AutoFit();

// Casting is not required in Visual C# 2010.
excelApp.Columns[1].AutoFit();
```
For more information about embedding interop types, see procedures "To find the PIA reference" and "To restore the PIA dependency" later in this topic. For more information about dynamic, see dynamic (C# Reference) or Using Type dynamic (C# Programming Guide).

To invoke DisplayInExcel

Add the following code at the end of the ThisAddIn_StartUp method. The call to DisplayInExcel contains two arguments. The first argument is the name of the list of accounts to be processed. The second argument is a multiline lambda expression that defines how the data is to be processed. The ID and balance values for each account are displayed in adjacent cells, and the row is displayed in red if the balance is less than zero. Multiline lambda expressions are a new feature in Visual Basic 2010. For more information, see Lambda Expressions (Visual Basic).

DisplayInExcel(bankAccounts,
       Sub(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 Then
               cell.Interior.Color = RGB(255, 0, 0)
               cell.Offset(0, 1).Interior.Color = RGB(255, 0, 0)
           End If 
       End Sub)

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

To run the program, press F5. An Excel worksheet appears that contains the data from the accounts.

To add a Word document

Add the following code at the end of the ThisAddIn_StartUp method to create a Word document that contains a link to the Excel workbook.
```
Dim wordApp As New Word.Application
wordApp.Visible = True
wordApp.Documents.Add()
wordApp.Selection.PasteSpecial(Link:=True, DisplayAsIcon:=True)
```
```
var wordApp = new Word.Application();
wordApp.Visible = true;
wordApp.Documents.Add();
wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);
```
This code demonstrates several of the new features in C#: the ability to omit the ref keyword in COM programming, named arguments, and optional arguments. These features already exist in Visual Basic. The PasteSpecial method has seven parameters, all of which are defined as optional reference parameters. Prior to Visual C# 2010, you had to define object variables to use as arguments for the seven parameters, even when you had no meaningful values to send in. Named and optional arguments enable you to designate the parameters you want to access by name, and to send arguments to only those parameters. In this example, arguments are sent to indicate that a link to the workbook on the Clipboard should be created (parameter Link), and that the link is to be displayed in the Word document as an icon (parameter DisplayAsIcon). Visual C# 2010 also enables you to omit the ref keyword for these arguments. Compare the following code segment from Visual C# 2008 with the single line required in Visual C# 2010:
```
// Call to PasteSpecial in Visual C# 2008. 
object iconIndex = Type.Missing;
object link = true;
object placement = Type.Missing;
object displayAsIcon = true;
object dataType = Type.Missing;
object iconFileName = Type.Missing;
object iconLabel = Type.Missing;
wordApp.Selection.PasteSpecial(ref iconIndex,
                               ref link,
                               ref placement,
                               ref displayAsIcon,
                               ref dataType,
                               ref iconFileName,
                               ref iconLabel);

// Call to PasteSpecial in Visual C# 2010.
wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);
```

To run the application

Press F5 to run the application. Excel starts and displays a table that contains the information from the two accounts in bankAccounts. Then a Word document appears that contains a link to the Excel table.

To clean up the completed project

In Visual Studio, click Clean Solution on the Build menu. Otherwise, the add-in will run every time that you open Excel on your computer.

To find the PIA reference

Run the application again, but do not click Clean Solution.
On the Start menu, click All Programs. Next click Microsoft Visual Studio 2010, then Visual Studio Tools, then Visual Studio Command Prompt (2010).
Type ildasm in the Visual Studio Command Prompt (2010) window, and then press ENTER. The IL DASM window appears.
On the File menu in the IL DASM window, click Open. Double-click Visual Studio 2010, and then double-click Projects. Open the folder for your project, and look in the bin/Debug folder for your project name.dll. Double-click your project name.dll. A new window displays your project's attributes, in addition to references to other modules and assemblies. Note that namespaces Microsoft.Office.Interop.Excel and Microsoft.Office.Interop.Word are included in the assembly. By default in Visual Studio 2010, the compiler imports the types you need from a referenced PIA into your assembly.

For more information, see How to: View Assembly Contents.
Double-click the MANIFEST icon. A window appears that contains a list of assemblies that contain items referenced by the project. Microsoft.Office.Interop.Excel and Microsoft.Office.Interop.Word are not included in the list. Because the types your project needs have been imported into your assembly, references to a PIA are not required. This makes deployment easier. The PIAs do not have to be present on the user's computer, and because an application does not require deployment of a specific version of a PIA, applications can be designed to work with multiple versions of Office, provided that the necessary APIs exist in all versions.

Because deployment of PIAs is no longer necessary, you can create an application in advanced scenarios that works with multiple versions of Office, including earlier versions. However, this works only if your code does not use any APIs that are not available in the version of Office you are working with. It is not always clear whether a particular API was available in an earlier version, and for that reason working with earlier versions of Office is not recommended.

Note

Office did not publish PIAs before Office 2003. Therefore, the only way to generate an interop assembly for Office 2002 or earlier versions is by importing the COM reference.
Close the manifest window and the assembly window.

To restore the PIA dependency

In Solution Explorer, click the Show All Files button. Expand the References folder and select Microsoft.Office.Interop.Excel. Press F4 to display the Properties window.
In the Properties window, change the Embed Interop Types property from True to False.
Repeat steps 1 and 2 in this procedure for Microsoft.Office.Interop.Word.
In C#, comment out the two calls to Autofit at the end of the DisplayInExcel method.
Press F5 to verify that the project still runs correctly.
Repeat steps 1-3 from the previous procedure to open the assembly window. Notice that Microsoft.Office.Interop.Word and Microsoft.Office.Interop.Excel are no longer in the list of embedded assemblies.
Double-click the MANIFEST icon and scroll through the list of referenced assemblies. Both Microsoft.Office.Interop.Word and Microsoft.Office.Interop.Excel are in the list. Because the application references the Excel and Word PIAs, and the Embed Interop Types property is set to False, both assemblies must exist on the end user's computer.
In Visual Studio, click Clean Solution on the Build menu to clean up the completed project.

Walkthrough: Office Programming (C# and Visual Basic)

Prerequisites

To set up an Excel Add-in application

To add references

To add necessary Imports statements or using directives

To create a list of bank accounts

To export data to Excel

To invoke DisplayInExcel

To add a Word document

To run the application

To clean up the completed project

To find the PIA reference

To restore the PIA dependency

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources