.NET4Office : Office Programming Model

Setting a Range of Cells in One Call

Eric Carter — Wed, 16 Mar 2005 17:35:00 GMT

A reader writes:

I've enjoyed reading your online blog about Excel/Dotnet integration. I have a question, that if anyone would know the answer to, hopefully you do.

Is there any trick that can be used to speed up insertion of large blocks of data into a worksheet from dotnet? For example, I may have a large rectangular array I retrieved as the result of a database query that I set into the Value of a range.

Here’s how you do this. You need to create an object array dimensioned to the size of the block you want to set. Populate the object array. You also need to get a Range object that spans the size of block. Then you use the Value2 property and set it to your object array.

Here’s an example that does this:

private void Sheet1_Startup(object sender, System.EventArgs e)

{

int numberOfRows = 10;

int numberOfColumns = 10;

object[,] theValues = new object[numberOfRows, numberOfColumns];

for (int i = 0; i < numberOfRows; i++)

{

for (int j = 0; j < numberOfColumns; j++)

{

theValues[i, j] = i * j;

}

Excel.Range theRange = this.Range["A1", "J10"];

theRange.Value2 = theValues;

}

VSTO Security Model Principles

Eric Carter — Tue, 01 Mar 2005 21:44:00 GMT

VSTO takes a very strong stance on security to prevent the spread of macro viruses or worms. VSTO's security model involves the trust of two things: 1) the assembly associated with the document must be trusted and 2) the location the document is coming from must be trusted. VSTO's default security model for assemblies is that no assembly is trusted by default. VSTO's default security model for documents is that only documents on the local machine are trusted by default. When a VSTO customized document is loaded both assembly trust and document location trust are checked to determine whether to load. No matter where the assembly is, you must have .NET policy in place to trust the assembly. If the customized document resides locally on your computer this is sufficient.

But if the customized document is being opened from the intranet or internet zone (such as from http://myserver/myvstodoc.xls) then you must add additional .NET policy to trust the location the document is coming from. This is to prevent a repurposing attack where a document from an untrusted intranet or more likely internet zone tries to repurpose a VSTO document customization that the attacker knows is trusted within an organization. It is also to protect from an attack where a repurposed document comes in through e-mail--any document opened directly from e-mail is in the internet zone and won't be trusted until you "save it to disk" e.g. copy it to your local computer.

One solution is to the document location trust problem is to copy the document to your local machine which puts it in the "Local Machine" zone and VSTO will then trust the document location (since the document is now copied to Local Machine) and will load the customization if there is .NET policy to trust the associated assembly. The other option is to add .NET security policy to trust customized documents coming http://myserver.

I will provide more detail in a future post on how to configure .NET security policy to trust assemblies and how to configure .NET security policy to trust documents.

Want to work on VSTO technologies?

Eric Carter — Mon, 21 Feb 2005 23:29:00 GMT

Visual Studio Tools for Office is really taking off and the team that creates VSTO is growing fast.

If you are interested in working at Microsoft and helping us build tools to help developers build customizations for Office, please check out this list of openings on the VSTO team: http://ericca.members.winisp.net/VSTOJobs.html. There are test, developer, and program management positions that are open.

You can use the "Contact" link at the left to submit resume and contact information directly to me and I'll work to hook you up with the right people providing your background and experience look like they hit the mark.

Awesome Videos Illustrating VSTO's Data Binding Features

Eric Carter — Wed, 19 Jan 2005 19:38:00 GMT

Kathleen has just posted two new videos showing how VSTO's Data Binding Features work. I guarantee you'll be wowed by these videos. The first shows the creation of a databound list and controls in Excel created by simply dragging and dropping. The second shows how to create databound bookmarks in a Word document. They are each only about 5 minutes long. Check 'em out.

Demo 9 -- How to Bind Data to Controls
Demo 10 -- How to Bind Data to Controls on a Word Document.

Some new VSTO resources

Eric Carter — Sat, 08 Jan 2005 18:48:00 GMT

If you haven't checked it out yet, Chris Kunicki has created a VSTO Zone at his site that has a bunch of useful information about VSTO:

http://www.officezealot.com/vsto/

Also, Kathleen has posted some more VSTO video tutorials:

Demo 5--How to Resize Excel Controls
D emo 6 - How to Add Controls to the Actions Pane
Demo 7 – How to Set the Stack Order of Controls on the Actions Pane
Demo 8 - How to Change Controls on the Actions Pane

Working with Word Collections and using get_Item

Eric Carter — Wed, 29 Dec 2004 22:47:00 GMT

Items in a Word collection are accessed in two different ways depending on whether the index into the collection is strongly typed or weakly typed. In the case of the KeyBindings collection for example, the index is strongly typed as an integer. As such, you can use the index operation ([]) to get to an item in a collection. The code looks like this:

Word.KeyBinding k = Application.KeyBindings[1];

For a collection for which the index into the collection is weakly typed as an object passed by reference, you must use the get_Item method of the collection. The Templates collection is an example of this. It has a weakly typed index of type object passed by reference. This is because you can either pass a string if you know the name of the template in the collection or you can pass an integer for the index of the template in the collection. To get a Template from the Templates collection by integer index you can write this code:

object index = 1;

Word.Template t = Application.Templates.get_Item(ref index);

To get a Template from the Templates collection by string name you can write this code:

object index = "Normal.dot";

Word.Template t = Application.Templates.get_Item(ref index);

Note that in both cases, you must declare an object first and then pass a reference to the object. When passing parameters by reference, you must always declare a variable first and then pass that declared variable by reference.

Visual Studio isn’t much help when trying to figure this out. It will encourage you to use the index operator even on a collection like templates through Intellisense prompts as shown below. But if you try to use the index operator when the index is passed by reference, you will get a compile error.

Visual Studio Intellisense leads you down the wrong path of using the index operator with an object parameter passed by reference.

Furthermore, Visual Studio Intellisense doesn’t display get_Item as a method you can call on the collection in the popup Intellisense as shown below. Nonetheless, get_Item is an available method on Word collections.

Visual Studio Intellisense Doesn't Show the get_Item method.

Writing user defined functions for Excel in .NET

Eric Carter — Wed, 01 Dec 2004 20:53:00 GMT

I've updated this article with some new guidance--for the details, see this post.

Excel enables the creation of user defined functions that can be used in Excel formulas. A developer must create a special kind of DLL called an XLL. Excel also allows you to write custom functions in VBA that can be used in Excel formulas. Unfortunately, Excel does not support or recommend writing an XLL that uses managed code. If you are willing to take your chances that your XLL might not run in current or future versions of Excel, there are solutions available that enable this scenario—search the web for “managed XLL”.

Fortunately, there is an easier way to create a user defined function that doesn’t require you to create an XLL dll. Excel XP, Excel 2003, and Excel 2007 support something called an Automation Add-in. An Automation Add-in can be created quite simply in C# or VB.NET. I'm going to show you an example in C#.

First, launch Visual Studio 2005 or Visual Studio 2008 and create a new C# class library project called AutomationAddin for this example. Screenshots here will show Visual Studio 2005 and Excel 2003, but the steps are pretty much the same for Visual Studio 2008 and Excel 2007. I'll note inline where they are different.

Then, in your Class1.cs file, enter the code shown below. Replace the GUID with your own GUID that you create by using Generate GUID in the Tools menu of Visual Studio.

using System;
using System.Runtime.InteropServices;
using Microsoft.Win32;

namespace AutomationAddin
{

// Replace the Guid below with your own guid that

// you generate using Create GUID from the Tools menu

[Guid("5268ABE2-9B09-439d-BE97-2EA60E103EF6")]
[ClassInterface(ClassInterfaceType.AutoDual)]
[ComVisible(true)]
public class MyFunctions
{
public MyFunctions()
{

}

    public double MultiplyNTimes(double number1, double number2, double timesToMultiply)
    {
      double result = number1;
      for (double i = 0; i < timesToMultiply; i++)
      {
        result = result * number2;
      }

return result;
}

    [ComRegisterFunctionAttribute]
    public static void RegisterFunction(Type type)
    {

Registry.ClassesRoot.CreateSubKey(

GetSubKeyName(type, "Programmable"));

RegistryKey key = Registry.ClassesRoot.OpenSubKey(

GetSubKeyName(type, "InprocServer32"), true);

key.SetValue("",

System.Environment.SystemDirectory + @"\mscoree.dll",

RegistryValueKind.String);
}

    [ComUnregisterFunctionAttribute]
    public static void UnregisterFunction(Type type)
    {

Registry.ClassesRoot.DeleteSubKey(

GetSubKeyName(type, "Programmable"), false);
}

private static string GetSubKeyName(Type type,

string subKeyName)

{

System.Text.StringBuilder s =

new System.Text.StringBuilder();

s.Append(@"CLSID\{");

s.Append(type.GUID.ToString().ToUpper());

s.Append(@"}\");

s.Append(subKeyName);

return s.ToString();

}
}
}

With this code written, show the properties for the project by double clicking on the properties node under the project in Solution Explorer. Click on the Build tab and check the check box that says “Register for COM Interop”. At this point you have an extra step if you are running on Windows Vista or higher. Visual Studio has to be run with administrator privileges to register for COM interop. Save your project and exit Visual Studio. Then find Visual Studio in the Start menu and right click on it and choose "Run as Administrator". Reopen your project in Visual Studio. Then choose “Build” to build the add-in.

Now launch Excel and go to the Tools, Add-ins dialog in Excel 2003 and click on the Automation button. If you are running Excel 2007, you get to the Automation servers dialog by following these steps:

1. Launch Excel and click the Microsoft Office button in the top left corner of the window.

2. Choose Excel Options.

3. Click the Add-Ins tab in the Excel Options dialog.

4. Choose Excel Add-Ins from the combo box labeled Manage. Then click the Go button.

5. Click the Automation button in the Add-Ins dialog.

You can find the class you created by looking for AutomationAddin.MyFunctions in the list of Automation add-ins:

By clicking OK in this dialog, you add AutomationAddin.MyFunctions to the list of installed add-ins as shown here. In prior versions of these instructions, you would get a dialog at this point about not being able to find mscoree.dll. I've updated this article so this doesn't happen anymore--the magic is in the two final lines of RegisterFunction that register the full path to mscoree.dll which makes Excel happier.

Now, let’s try to use the function MultiplyNTimes inside Excel. First create a simple spreadsheet that has a number, a second number to multiple the first by, and a third number for how many times you want to multiply the first number by the second number. An example spreadsheet is shown here:

Click on an empty cell in the workbook below the numbers and then click on the Insert Function button in the formula bar. From the dialog of available formulas, drop down the “Or select a category” drop down box and choose “AutomationAddin.MyFunctions. Then click on the MultiplyNTimes function as shown here:

When you press the OK button, Excel pops up a dialog to help you grab function arguments from the spreadsheet as shown here:

Finally, click OK and see your final spreadsheet as shown here with your custom formula in cell C5.

You might experiment with other functions that return other types of values. For example, the code snippet below shows several other functions you could add to your MyFunctions class. To use this code you must add a reference to the Excel 11.0 Object Library for Excel 2003 or the Excel 12.0 Object model for Excel 2007 and also add the code “using Excel = Microsoft.Office.Interop.Excel” to the top of your class file. Note in particular that when you declare a parameter as an object, Excel passes you a Range object. Also note how optional parameters are supported by AddNumbers.

public string GetStars(double Number)
{
string s = "";
for (double i = 0; i < Number; i++)
{
s = s + "*";
}
return s;
}

public double AddNumbers(double Number1, [Optional] object Number2, [Optional] object Number3)
{
double result = 0;
result += Convert.ToDouble(Number1);

if (!(Number2 is System.Reflection.Missing))
{
    Excel.Range r2 = Number2 as Excel.Range;
    double d2 = Convert.ToDouble(r2.Value2);
    result += d2;
}

if (!(Number3 is System.Reflection.Missing))
{
    Excel.Range r3 = Number3 as Excel.Range;
    double d3 = Convert.ToDouble(r3.Value2);
    result += d3;
}

return result;
}

public double CalculateArea(object Range)
{
Excel.Range r = Range as Excel.Range;
return Convert.ToDouble(r.Width) * Convert.ToDouble(r.Height);
}

public double NumberOfCells(object Range)
{
Excel.Range r = Range as Excel.Range;
return r.Cells.Count;
}

public string ToUpperCase(string input)
{
return input.ToUpper();
}

When foreach in Excel goes wrong

Eric Carter — Thu, 18 Nov 2004 18:04:00 GMT

This seems like a reasonable piece of code:

For Each oCell As Excel.Range In Me.Range("a1:b5")
oCell.Value = "test"
Next

so does this:

foreach Excel.CustomProperty prop in worksheet.CustomProperties
{
Console.WriteLine(prop.Name);
}

Unfortunately, when you run this code you will get a "Missing member" exception. Some collections in Excel can't be "for-eached" over. To do "foreach" the CLR has to get an enumerator from the collection. The CLR and CLR interop expect to find a _NewEnum member method on the collection. Some Excel collections have a _NewEnum member that is implemented as a property and not a method.

There is a KB on this issue: http://support.microsoft.com/?kbid=328347

Clearly this is not happy, but there is a work around--use a for next loop and get members of the collection using Item with a 1-based index.

Hopefully, this is an issue we will get fixed in VS 2005 so that all Excel collections, even the ones that have a _NewEnum member that is a property, can be for-eached.

Office Watsoning and Exceptions in VSTO 2005 Beta 1

Eric Carter — Tue, 09 Nov 2004 02:32:00 GMT

[EDITOR'S NOTE] Blogging has been slow as we are spending almost all our time getting Beta 2 out the door.

You may have had the experience of Excel or Word causing an Office Watson error at debug time when you have an exception that occurs in your Windows Forms event handlers in VSTO 2005.

The problem is related to the way that Windows Forms is integrated into Excel and Word. A Windows Forms windows procedure integrates with the existing Excel and Word message loops. When the debugger is attached, Windows Forms uses a windows procedure that doesn't catch any exceptions that occur so that you can see those exceptions in the debugger. When an exception occurs and you let it continue, the exception goes to the windows procedure and then propagates out to the Excel and Word message loops that are written in native code. The Excel or Word message loop sees an exception that it doesn't know how to handle and invokes Office Watson and shuts down the process.

Theoretically, this should also repro in managed add-in development in other applications like Outlook--for example, if you create a modeless form and throw an exception from a handler within the modeless form. I haven't gone and tried this though.

This doesn't occur when you have an exception in a COM event handler like say the BeforeDoubleClick event for a NamedRange. This is because the interop layer catches these exceptions and converts them to HRESULTs that Office ignores when firing events.

This also doesn't occur for Windows Forms event handlers when the debugger is not attached because Windows Forms uses a different windows procedure that catches exceptions that occur and displays a dialog box.

For VSTO 2005 Beta 2, we are working to change this behavior so Office won't Watson in any of these cases.

Also in Beta 1, you really should run with "Break when thrown" checked for Common Language Runtime Exceptions in your Exceptions dialog (Debug->Exceptions->Break On Specific Exceptions". Otherwise, you will miss exceptions that are occurring in your code because they'll often get caught by the interop layer.

Another officewiki.org plug.

Eric Carter — Thu, 28 Oct 2004 03:23:00 GMT

I've been doing some C# development with the Excel object model and when you look at Excel objects in the object browser or in intellisense there are two major problems you run into:

1) Methods that would be hidden in VBA are shown in the object browser when using C#. You really probably shouldn't be calling these hidden methods.

2) It is hard to tell which parameters are required and which are optional. I mean, you can usually guess that if it the parameter is of type object, it is probably optional and you can pass a Type.Missing to it, but you can't know for sure.

Which is why I've been using officewiki.org as a tool to help me with these problems. Officewiki.org only shows you the methods and properties that are not hidden. It also tells you explicitly which parameters are optional.

It's really easy to type in a URL to get right to the object you want. Here are some examples:

Workbooks object: http://www.officewiki.org/default.aspx/Excel.Workbooks

Workbooks.Count property: http://www.officewiki.org/default.aspx/Excel.WorkbooksCountProperty

Workbooks.Add method: http://www.officewiki.org/default.aspx/Excel.WorkbooksAddMethod

Outlook Inspector object: http://www.officewiki.org/default.aspx/Outlook.Inspector

and so forth.

FAQ: Why do my forms in my managed add-in or VSTO 2003 look Windows 95-ish

Eric Carter — Sat, 23 Oct 2004 04:37:00 GMT

This is a frequent question that comes up. You develop a managed add-in or VSTO 2003 code behind. You show a windows form and yuck--it looks like Windows XP never happened. The buttons aren't pretty like the Windows XP buttons. Everything looks circa Windows 95.

The trick is you have to tell Windows Forms to use the Windows XP theming by writing this line of code somewhere in your application before you start creating and showing forms:

System.Windows.Forms.Application.EnableVisualStyles();

That's it! Prettiness restored.

VSTO 2005 Video Magic

Eric Carter — Fri, 22 Oct 2004 00:09:00 GMT

If you haven't had a chance yet to see these great videos that Kathleen has made of VSTO in action, check them out. They're each about 6 minutes long are are really nice glimpses into some of the cool features of VSTO 2005. Keep 'em coming Kathleen!

Demo 1 – Locate and Delete NamedRange Controls

Demo 2 - Resize Controls Within Worksheet Cells

Demo 3 - Add a Custom User Control to your Document

Demo 4 - How Column and Row Order is Persisted in a Data-bound List Object

More on getting Outlook to shut down

Eric Carter — Wed, 20 Oct 2004 22:48:00 GMT

I recently posted some code showing how to get Outlook to shut down.

I contended that you shouldn't have to call ReleaseCOMObject as is shown in some MSDN articles to get Outlook to shut down.

Indeed, David Mortenson who has worked on interop here at Microsoft warns further about ReleaseCOMObject.

One other point that David has made relating to the technique I showed for getting Outlook to shutdown (set variables containing Outlook OM objects to null and force a garbage collection and ) is that you actually sometimes have to write this code.

// Set objects using Outlook OM objects to null

GC.Collect();
GC.WaitForPendingFinalizers();
GC.Collect();
GC.WaitForPendingFinalizers();

For my simple example where the objects I was setting to null were just variables pointing to Outlook OM objects, you wouldn't have to do this, but if you are setting a class to null which has a finalizer and that class has a variable containing an Outlook OM object, you would have to do this to make sure that class releases all it's OM objects it is holding on to.

Building a Status Report Application With VSTO 2005 & Word

Eric Carter — Thu, 14 Oct 2004 19:39:00 GMT

Another new article on MSDN about VSTO 2005--this time by J. Jason De Lorme. Jason mentions that VSTO 2005 doesn't support complex databinding against XMLNodes. We did add an "UpdateXML" method (renamed to LoadXML in Beta 2) on an XMLNode that should make some of the tasks you do with XML in Word easier--I wonder if this would have helped Jason at all for his scenario.