Office Development with Visual Studio : primary interop assemblies

Can I deploy my and all of its prerequisites in one file? (Mary Lee)

VSTO Team — Wed, 14 Oct 2009 22:16:01 GMT

One frequent customer question is about how to deploy an application and all of its prerequisites in a single .msi or .exe file. This question applies whether you are deploying any of the following:

Microsoft Office 2003 solutions with dependencies on .NET Framework 2.0, Visual Studio Tools for Office 2005 SE runtime, Microsoft Office 2007 primary interop assemblies.
Microsoft Office 2007 solutions with dependencies on .NET Framework 3.5 , Visual Studio Tools for Office runtime 3.0, Microsoft Office 2007 primary interop assemblies.
Microsoft Office 2007 solutions with dependencies on .NET Framework 3.5 SP1, Visual Studio Tools for Office runtime 3.0 SP1, Microsoft Office 2007 primary interop assemblies.
Microsoft Office 2007 solutions with dependencies on .NET Framework 3.5 SP1 Client Profile, Visual Studio Tools for Office runtime 3.0 SP1, Microsoft Office 2007 primary interop assemblies.
Really, any WinForms/WPF/console/whatever app with dependencies on .NET Framework, SQL Server Express, SQL Server compact, Visual C++ runtime, Windows Installer, or anything else.

There are three concepts in deployment related to prerequisites: nesting, merging, and chaining or bootstrapping.

Nesting is the process of embedding a Windows Installer file (.msi) within another .msi file. However, the How to create a nested .msi package article has an important disclaimer.

The drawbacks of creating a nested MSI installation are listed in the same article.

Nested Installations cannot share components.
An administrative installation cannot contain a nested installation.
Patching and upgrading will not work with nested installations.
The installer will not correctly cost a nested installation.
Integrated ProgressBars cannot be used with nested installations.
Resources that are to be advertised cannot be installed by the nested installation.
A package that performs a nested installation of an application should also uninstall the nested application when the parent product is uninstalled.

For these reasons, nesting is no longer supported.

Merging includes shared code, files, resources, registry entries, and setup logic to applications as a single compound file. Prerequisites available as a merge module (.msm) form can be added to a .msi file. For example, if a prerequisite is available as an .msm, you can add it to a Setup project in Visual Studio as shown in How to: Create or Add a Merge Module Project. However, merge modules cannot be serviced by the same owner as the .msi file, so it is difficult to fix issues in the merge module. Tao of the Windows Installer, Part 4 lists two cautionary notes:

Do not consume merge modules of vendors who do not promise to fix their merge modules promptly when bugs arrive
Be prepared to handle the heat when bugs are found in your merge module causing issues for others’ products that have consumed your merge module and you get to put out the flame

For these reasons, using merge modules is not recommended.

Nesting and merging create a single file to deploy an application and its prerequisites, but these methods are not supported and not recommended. Thus, the answer to the question in the title is no: you cannot or should not deploy an application and its prerequisites in one file.

Chaining or bootstrapping is the process of checking for and installing missing prerequisites, including installing the application that is going to be used to install the rest of the prerequisites and application. You can use Visual Studio to generate a chainer/bootstrapper that is called Setup.exe. This program checks for and installs missing prerequisites before installing the application or Office solution.

If you are deploying an Office 2007 solution in Visual Studio 2008 SP1, the .NET Framework 3.5 SP1, Visual Studio Tools for Office 3.0 SP1 runtime, and Microsoft Office 2007 primary interop assemblies are already selected in the Prerequisites Dialog Box.

To learn more about how to install prerequisites in Visual Studio, see the following topics.

How to: Install Prerequisites on End User Computers to Run Office Solutions

How to: Install Prerequisites in Windows Installer Deployment

How to: Install Prerequisites with a ClickOnce Application

If the prerequisite package does not appear in Visual Studio, you can create your own bootstrapper package. After you create a product.xml file that describes the prerequisite and a package.xml files that includes locale-specific error messages, you can copy the bootstrapper package to \Program Files\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages folder. For more information, see Creating Bootstrapper Packages.

Other tools besides Visual Studio: You can also use MSBuild and the GenerateBootstrapper Task to create a bootstrapper on a build computer. Alternatively, you can use the Windows Installer XML Toolset to generate .msi files and package prerequisites. For more information, see http://wix.sourceforge.net/.

For questions about bootstrapping, search for answers or post new questions in the ClickOnce and Setup & Deployment forum.

Happy deployment!

Mary Lee, Programming Writer.

Will your VSTO addin run on Office 2010 64-bit? Yes, probably. (Christin Boyd)

VSTO Team — Thu, 06 Aug 2009 01:05:00 GMT

The Visual Studio team is designing the runtime components for Office 2010 so that your Visual Studio Tools for Office 2005 and Visual Studio 2008 .NET addins, document solutions and spreadsheet solutions will run on 64-bit Office 2010. These runtime components will ship with Office 2010, so your end-users won’t even have to download a new runtime! How easy is that? There are a few rare exceptions that I’ll discuss in this blog entry.

The miracle of managed code allows you to write C# or Visual Basic .NET code that compiles to “Any CPU” using the Compile setting in your Visual Studio project. Your code compiles to MSIL with Visual Studio, and then at runtime it gets JIT compiled to the correct chip set, either AMD, Intel, 32-bit or 64-bit. The first exception to this wondrous technology is the oldest versions of .NET Framework 1.0 and 1.1 will not enable this 64-bit transformation.

The other thing to lookout for is calls to process invoke (p/invoke) in your code. If you try to call native API methods using p/invoke you could have issues with your VSTO solution running properly on 64-bit Office 2010.

You will have problems if your code makes deliberate calls to p/invoke a Win32 API that does not have exactly the same signature (method name, parameter list, and DLL name) of an equivalent Win64 API. This is true for any solution you write regardless of targeting Office as the platform. You can find a ton of information in MSDN and blogs by such luminaries as Scott Hanselman about writing Windows API calls so that they will run on either 32-bit or 64-bit Windows. Here is a generalized code snippet for handling cases where the method name or the DLL name is different:

//YourFunction has the same name, parameters, and DLL name in 32bit and 64bit
YourFunction();

Import("LIBRARY", EntryPoint = "YOURFUNCTION", CharSet = CharSet.Unicode)]
private static extern bool YouFunction();



//In some cases, the method name is different in Win32 API and Win64 API, 
//so use the following code block in stead of the above 3 lines of code.
if (Marshal.SizeOf(typeof(IntPtr)) == 4)
{
    YourFunction32();
}
else if (Marshal.SizeOf(typeof(IntPtr)) == 8)
{
    YourFunction64();
}



Import("LIBRARY32", EntryPoint = "YOURFUNCTION32", CharSet = CharSet.Unicode)]
private static extern bool YourFunction32();

Import("LIBRARY64", EntryPoint = " YOURFUNCTION64", CharSet = CharSet.Unicode)]
private static extern bool YourFunction64();

Resources:

Here are more resources to help you author your solutions today so that they will run without needing a recompile when your users install 64-bit Office 2010.

MSDN Library Visual Studio 2005 article on developing 64-bit Applications

MSDN Library Visual Studio 2008 article on developing 64-bit Applications

How to access the “real” x64 registry from a Win32 .NET Application – Part I

The Myth of .NET Purity, Reloaded

For migrating your really old apps with lots of native calls to .NET, try checking if your native calls have an equivalent .NET call:

Microsoft Win32 to Microsoft .NET Framework API Map

Interoperating with Unmanaged Code

Finally I should mention that this is my last post (for a while at least) on this blog because I am leaving Microsoft. I’m going to work on a charity project teaching robotics programming to high school kids in my “inner city” neighborhood for at least the next 6 months. The project is called Team Xbot! Keep an eye on these kids as they go on to good colleges and great jobs in the next few years!

Sincerely, Christin Boyd, Program Manager

BUG: “Old format or invalid type library” error when automating Excel (Christin Boyd)

VSTO Team — Tue, 07 Jul 2009 01:54:33 GMT

A customer recently reported this bug when running their Shared Addin for Excel on French Windows.

Error: 0x80028018 (-2147647512)
Description: Old Format or Invalid Type Library

His solution worked great on English Windows, but gave errors in any other language. This is a known problem in Excel and there are a few workarounds that work depending on the way you’re writing your Excel Addin. Let me take you through the problem, variations on the problem, and different solutions depending on which Visual Studio project template you choose to start your Addin.

The bug was originally documented in a KB 320369 article, which gives detailed repro steps, explanation, and two workarounds with sample code. So why am I writing a blog post if the KB article covers everything? Three reasons.

Because we’re fixing the problem in CLR 4 and I want to encourage you to use one of the recommended workarounds in your current solutions so that you’re ready when your users upgrade to .NET Framework 4.
Also, there are parts of the KB article that are a bit confusing, so I’ll try to add some color commentary to help explain what’s causing the problem.
And third, these problems do not occur if you use VSTO 2005 SE, VSTO 3.0 (which ships with Visual Studio 2008), or Visual Studio 2010. I’ll explain why and how later.

The KB article describes the problem:

Error: 0x80028018 (-2147647512)
Description: Old Format or Invalid Type Library

You receive this error calling an Excel method when the following conditions are true:

The method requires an LCID (locale identifier).

You run an English version of Excel. However, the regional settings for the computer are configured for a non-English language.

If the client computer runs the English version of Excel and the locale for the current user is configured for a language other than English, Excel will try to locate the language pack for the configured language. If the language pack is not found, the error is reported.

The quote from the KB article is accurate, but can be confusing. It is very difficult to determine if the Excel method you want to call requires LCID or not. The Primary Interop Assembly (PIA) does not indicate whether or not the LCID is needed, however VBA does not hide the need for LCID. Part of the reason why Excel hasn’t changed its methods is to maintain back compatibility with all the VBA code in the universe.

Fixed in VSTO

VSTO implemented a fix in VSTO 2005 Second Edition (SE). You can read more about this fix in Eric Carter’s blog post. The fix is also in all subsequent versions of Visual Studio 2008 and will be in Visual Studio 2010. You know you are using “VSTO” when you create a new Project in Visual Studio and select an Excel <version number> Workbook, Excel <version number> Template or Excel <version number> Addin. The fix was not implemented in the Shared Addin template in any version of Visual Studio. If you create a WinForms, WPF, Web or console application that calls Excel, then you will see this bug on non-English Windows.

Workarounds

If you are using the Shared Addin template, a WinForm, WPF, Web or Console application with any version of Visual Studio, then you should use the KB 320369 article to solve the problem.

The workaround is to write explicit calls to set the thread’s culture before calling into Excel. You can then reset the culture back to what it was before after you are finished calling Excel.

Install the Multilingual User Interface Pack for your version of Office.

Execute the Excel method or property by using InvokeMember so that you can specify the CultureInfo for the call. For example, the following code illustrates how you can invoke the Workbooks object Add method with "en-US" as the CultureInfo:

Dim oApp As New Excel.Application()
oApp.Visible = True
oApp.UserControl = True
Dim oBooks As Object = oApp.Workbooks
Dim ci As System.Globalization.CultureInfo = New System.Globalization.CultureInfo("en-US")
oBooks.GetType().InvokeMember("Add", Reflection.BindingFlags.InvokeMethod, Nothing, oBooks, Nothing, ci)

Or, instead of the above bullet and code sample, set the CultureInfo prior to calling the Excel method, and then you can reset it after your Excel call:

Dim oApp As New Excel.Application()
oApp.Visible = True
oApp.UserControl = True
Dim oldCI As System.Globalization.CultureInfo = _
    System.Threading.Thread.CurrentThread.CurrentCulture
System.Threading.Thread.CurrentThread.CurrentCulture = _
    New System.Globalization.CultureInfo("en-US")
oApp.Workbooks.Add()
System.Threading.Thread.CurrentThread.CurrentCulture = oldCI

The .NET Framework 4 will solve this whole culture problem. Excel is not going to change its culture sensitivity because of the need to support backwards compatibility. Starting with CLR 4.0, when managed code calls into a COM component and an LCID is required, then the CLR will pass LCID = 1033. Note that this is how VBA passes LCIDs. This means that Visual Studio 2010 project templates for Excel Addins can stop wrapping all Excel projects with LCID proxy. In the future, when you use VS 2010 and .NET 4 to write your Excel automation programs from a Shared Addin, console, Winforms, WPF, or Web application, you won’t need to wrap your calls either.

-Christin Boyd, Program Manager & Misha Shneerson, Senior Developer

Best Practices for Deployment with Visual Studio 2008 SP1 (Mary Lee, Rachel Schaw)

VSTO Team — Tue, 03 Feb 2009 02:01:00 GMT

After you develop Office solutions with Visual Studio Tools for Office, you can use Visual Studio 2008 SP1 to simplify your deployment experience. First, you can take advantage of the smaller .NET Framework Client Profile to decrease download time. Next, the Office 2007 primary interop assemblies (PIAs) are included in-the-box with VS2008 SP1 to avoid having to generate bootstrapper manifests. Finally, you can also troubleshoot any installation problems with the event viewer.

Develop your Office 2007 solutions against the .NET Framework Client Profile. The large size of the .NET Framework 3.5 SP1 can lead to long download times. The .NET Framework Client Profile is only 25MB in size, so download times are reduced when installing from the component vendor's web site. For more information about how to configure your solution to use the .NET Framework Client Profile, see How to: Target a Specific .NET Framework.

Deploying the Office 2007 primary interop assemblies is now (mostly) hassle-free. Visual Studio 2008 SP1 includes the Office 2007 PIAs as part of the update. This relieves you from having to download the PIA installer, download a code sample that contains the bootstrapper manifests, move the manifests to a certain directory, compile the ComponentCheck.cpp file to verify that the correct version of Microsoft Office is installed, and dance the hula. Instead, developing with one of the Visual Studio Tools for Office project templates already marks the Microsoft Office 2007 primary interop assemblies as a prerequisites. All you have to do is right-click on the project in Solution Explorer and click Publish.

Troubleshooting the installation and deployment process is more transparent. Any errors that occur are now logged in the event viewer. For example, I deliberately installed the same Office solution twice to generate the following error in the event viewer. Developers commonly see this error when they build and debug an Office solution on their development computer, and then try to install the Office solution on the same development computer. To avoid this problem, use a different account to test the installer on the development computer, or use a different test computer. For more information about the event viewer, see Event Logging (2007 System).

Visual Studio 2008 SP1 also introduced ClickOnce manifests that do not need to be signed. However, Visual Studio Tools for Office relies on signed manifests to identify the publisher and determine if the Office solution is trusted. Optional signing is a feature in VS2008 SP1 that does not apply to Office developers. For more information about trusting Office solutions, see Granting Trust to Office Solutions (2007 System).

Mary Lee, Programming Writer.

Rachel Shaw, Program Manager.

Office Programmability in Visual Basic and C# in VS 2010 (Beth Massi)

VSTO Team — Tue, 16 Dec 2008 00:39:43 GMT

The Visual Basic team posted a walkthrough today on some of the new language features in Visual Basic and C# to help with Office programmability in Visual Studio 2010. Specific features include adding optional parameters to C# 4.0 (VB already has this) and removing the dependency on the Primary Interop Assemblies (PIAs).

You can download the CTP and see it in action for yourself and give feedback here.

Enjoy,
-Beth Massi, Visual Studio Community

Common Pitfalls during PIA Deployment and Installation (Mary Lee)

VSTO Team — Tue, 20 May 2008 22:05:00 GMT

Deploying or installing the Office primary interop assemblies (PIAs) can sometimes be problematic. There are several common errors that occur when you try to deploy or install the PIAs.

Deployment pitfalls

A. Can I deploy the PIA DLL with my setup project? Yes, you can include the PIA DLL in your setup project, but we recommend that you use the Primary Interop Assemblies for the 2007 Microsoft Office system redistributable file from the Microsoft Download Center. this way, the installer copies the PIAs into the GAC, and also installs binding redirects. The binding redirects ensure that the latest version of the PIAs on the computer are always loaded. This is how a solution developed for Microsoft Office 2003 still works on the 2007 Microsoft Office system.

Installation pitfalls

A. Do you have administrator privileges? The account used to install the PIAs must have administrator privileges.

B. Is the .NET Framework already installed? The computer must have a version of the .NET Framework installed (version 1.1, 2.0, 3.0, or 3.5) before the PIA installer is run. Windows XP does not include any version of the .NET Framework unless .NET 1.1 was downloaded from Windows Update. Windows Vista does include a version of the .NET Framework. When Microsoft Office is first installed, the .NET Framework installation is detected and the PIAs are automatically installed.

C. Is Business Contact Manager installed? If Outlook 2007 with Business Contact Manager is already installed on the computer, you may see the following error message when you install the Primary Interop Assemblies for the 2007 Microsoft Office system from the Microsoft Download Center:

Error 1316: Setup cannot read from file {PATH}\PIARedist.MSI. Check your connection to the network, or CD-ROM drive. For other potential solutions, see SETUP.CHM.

Business Contact Manager for Outlook 2007 installs the PIAs by default, and the file name is PIARedist.MSI. However, the file from the Microsoft Download Center is called o2007pia.msi. When you install the PIAs from the Microsoft Download Center, this name conflict causes the 1316 error.

The easiest thing to do here is to just ignore the error, because this message means that the PIAs are already installed. If you want to correct the error, uninstall the PIAs through the list of installed programs for the specific computer. Then you can reinstall the PIAs with the Primary Interop Assemblies for the 2007 Microsoft Office system from the Microsoft Download Center.

I don't recommend that you follow the workaround posted at Error 1316 when installing Office 2007 PIA’s, which changes the name of the o2007pia.msi file to piaredist.msi and updates the product.xml to point to piaredist.msi. If you change the name of the o2007pia.msi, anyone that installs the PIAs after you will experience the 1316 error.

If you discover other PIA pitfalls, please feel free to leave a comment or question so I can update this entry. Thanks for reading!

Mary Lee, programming writer.

Adding the Office Primary Interop Assemblies as a Prerequisite in your ClickOnce installer (Mary Lee)

VSTO Team — Fri, 09 May 2008 00:21:00 GMT

When you use ClickOnce in Visual Studio 2008 to deploy your Office solution, you can include prerequisites such as the .NET Framework 3.5, the Visual Studio Tools for Office system 3.0 Runtime, and Windows Installer 3.1. However, the primary interop assemblies (PIAs) for the 2007 Microsoft Office system are not automatically listed in the Prerequisites dialog box.

Fortunately, you can add the PIAs to the Prerequisites dialog box. The following procedure adds the 2007 Microsoft Office Primary Interop Assemblies to the Prerequisites Dialog Box. This procedure may look lengthy, but you only have to do it once.

1. Download the OfficeVSTO2005SEWindowsInstallerV3.msi sample, which is part of the deployment whitepaper at Deploying Visual Studio 2005 Tools for Office Second Edition Solutions Using Windows Installer (Part 1 of 2).

2. Install OfficeVSTO2005SEWindowsInstallerV3.msi.

3. Copy the contents of %ProgramFiles%\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample Version 3\packages to %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages

4. Compile the component checker. This step checks if the computer has the correct version of Office installed to match the PIAs that are being installed.

a) Open a Visual Studio command prompt

b) Change directories to %ProgramFiles%\Microsoft Visual Studio 2005 Tools for Office SE Resources\VSTO2005SE Windows Installer Sample Version 3\projects\Checks

c) Type the following command: cl.exe /Oxs /MT /GS ComponentCheck.cpp advapi32.lib

d) Copy ComponentCheck.exe to the %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\Office2007PIA folder and the %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\Office2003PIA folder.

5. Download and extract the Office 2007 PIAs from 2007 Microsoft Office System Update: Redistributable Primary Interop Assemblies.

6. Copy the o2007pia.msi file to the %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\Office2007PIA folder.

7. In VS2008, on the Project menu, click ProjectName Properties.

8. Click the Publish tab.

9. Click the Prerequisites button to open the Prerequisites dialog box.

You should see the PIAs listed in the Prerequisites dialog box like the following image. Because the package.xml file does not define a HomeSite (a location to download the file), you will see a build warning. Even if you have selected Download prerequisites from the component vendor's web site, the PIAs will go into a directory alongside your solution installer.

If you want to learn more about adding your own entries to the Prerequisites dialog box, see Adding Custom Prerequisites.

For more information about common problems when deploying the Office primary interop assemblies, see http://blogs.msdn.com/vsto/archive/2008/05/20/common-pitfalls-during-pia-deployment-and-installation.aspx.

For troubleshooting assistance, try the VSTO Power Tools, a suite of tools to help you develop and deploy Office solutions. For example, you can use the VSTO Troubleshooter to examine end user computers for missing prerequisites.

Mary Lee, programming writer.