Creating a Bootstrapper package for an Office 2013 VSTO Add-in with Visual Studio 2012

Rate This
  • Comments 15

UPDATE FROM APRIL 10, 2014:

Updating the “product.xml” code chunk below, to use the VSTO Runtime version that was updated on April 10, 2014.

To ensure that a particular version of a VSTO Runtime is prereq-ed by your add-in, developers using the in-the-box Bootstrapper package can manually tweak the Bootstrapper file to reflect the latest VSTO Runtime version.  As of April 10, 2014, this version number is 10.0.50325 – but you can always check the latest version by downloading the runtime from http://go.microsoft.com/fwlink/?LinkId=140384, and checking the version number in the file properties.

To tweak the Bootstrapper package, open the “product.xml” file under

C:\Program Files (x86)\Microsoft SDKs\Windows\v8.1A\Bootstrapper\Packages\VSTOR40

(substituting “Program Files” for a 32-bit operating system, and substituting a different version like “v8.0A” depending on your system configuration).

Once you have found the file, substitute the desired version into the following properties:

<BypassIf Property="VSTORuntimeVersionInstalled" Compare="VersionGreaterThanOrEqualTo" Value="10.0.50325"/>

<BypassIf Property="VSTORuntimeVersionOfficeInstalled" Compare="VersionGreaterThanOrEqualTo" Value="10.0.50325"/>

UPDATE FROM MARCH 06, 2013:

We heard your feedback! With the latest release of the Office Developer Tools for Visual Studio 2012, you no longer need to manually create a bootstrapper package.

Just make sure to enable the bootstrapper under the "Publish" dialog's "Prerequisites" settings:

VSTOR Bootstrapper

        

============ Original Post from December 2012 ============

At the SharePoint Conference last month, Preview 2 of the Office Developer Tools for Visual Studio 2012 was announced. The release offers a number of enhancements for VSTO developers: in particular, design-time support for Office 2013, and the ability to develop Add-Ins that target the .NET 4.5 Framework. Preview 2 also includes tooling for the new Apps for Office and Apps for SharePoint projects, Workflow enhancements, VSTA improvements, and much more. See the official announcement to share in the exciting news, or skip straight to downloading the tools.

Here is just a snippet of the VSTO portion of the announcement:

New in this release, Visual Studio Tools for Office (a.k.a. VSTO add-ins) now have design time and runtime support that target Office 2013 and .NET Framework 4.5. This has been a much-requested feature. We also fixed the top customer reported issues in the VSTO runtime for Office 2013. We’re looking forward to hearing your feedback!

Out of the box, Office 2010 SP1 and Office 2013 include a VSTO Runtime version that’s sufficient to run .NET 4.0 add-ins. Thus, if you’re targeting .NET 4.0 – whether or not you install Preview 2 on top of Visual Studio 2012 – customers with Office 2010 SP1 and higher will be able to run your add-ins without any additional installation. If you want to leverage the new .NET 4.5 support and/or ensure that your customers have the latest runtime (which includes some cumulative bug fixes), you will need to follow the steps below to create a Bootstrapper package.

First, create a folder in a convenient location, and name it “VSTOR40”. Eventually, you’ll move this folder to a particular location under “Program Files”, but you may want to place it on your Desktop or “My Documents” for now. That way, you won’t be required to run everything as administrator in order to create or edit files.

As you step through this process, it may help to keep a high-level overview of the end-result in mind. As shown in the image below, you’ll end up with a “VSTOR40” folder that contains “product.xml” and an “en” sub-folder, which in turn contains “eula.1033.txt” and “package.xml”.

image

Let’s start with product.xml. Create a new file, and copy-paste the following contents into it:

<?xml version="1.0" encoding="utf-8" ?>

 

<Product

  xmlns="http://schemas.microsoft.com/developer/2004/01/bootstrapper"

  ProductCode="Microsoft.VSTORuntime.4.0">

  <RelatedProducts>

    <EitherProducts>

      <DependsOnProduct Code="Microsoft.Net.Client.3.5" />

      <DependsOnProduct Code=".NETFramework,Version=v4.0,Profile=Client" />

      <DependsOnProduct Code=".NETFramework,Version=v4.5,Profile=Client" />

    </EitherProducts>

  </RelatedProducts>

  <!-- Defines the list of files to be copied on build. -->

  <PackageFiles CopyAllPackageFiles="false">

    <PackageFile Name="vstor_redist.exe" HomeSite="VSTORRedist" PublicKey="3082010a0282010100baa4496c10fb229c65a216983bcb6162fa7429ad8d0619d27158198a5e570d69626e36a04efd2279e01dc71a618efafca3112516c8c0582c318a88ae321e88db7f3e7457f785a43653ca41ef69b8699e6d56eb6ee4b2264d73d16471b41fd66184880021ef6858835b498fb4dfd335d6cbd9309f53fc7a6b9a842bb7216774d4f678b6618798947c2acf67e919bed9ba63ed3c4e3e7d02ebf37fafcf0fb7817ef4fbe8f79148bb8f3d8cc807931cf3bd75e4fc6320299f39f34154381e546440b484aa37aef3008ce20dfaa1b20f22b5a7a9aed617b930f002232010fa6b590fe0ad9f9e608193034c0d9b6219b3bb96bc915aa67886769b6ccd4cec12b538470203010001"/>

  </PackageFiles>

 

  <InstallChecks>

    <RegistryCheck Property="VSTORuntimeVersionOfficeInstalled" Key="HKLM\SOFTWARE\Microsoft\VSTO Runtime Setup\v4" Value="Version"/>

    <RegistryCheck Property="VSTORuntimeVersionInstalled" Key="HKLM\SOFTWARE\Microsoft\VSTO Runtime Setup\v4R" Value="Version"/>

  </InstallChecks>

 

  <!-- Defines how to run the Setup package. -->

  <Commands Reboot="Defer">

    <Command

      PackageFile="vstor_redist.exe"

      Arguments=" /q /norestart"

      EstimatedInstalledBytes="2600000"

      EstimatedTempBytes="4500000"

      EstimatedInstallSeconds="60">

      <InstallConditions>

        <BypassIf Property="VSTORuntimeVersionInstalled" Compare="VersionGreaterThanOrEqualTo" Value="10.0.50325"/>

        <BypassIf Property="VSTORuntimeVersionOfficeInstalled" Compare="VersionGreaterThanOrEqualTo" Value="10.0.50325"/>

 

        <!-- Requires the user to be an admin user when installing the prerequisite -->

        <FailIf Property="AdminUser" Compare="ValueEqualTo" Value="false" String="AdminRequired"/>

      </InstallConditions>

      <ExitCodes>

        <ExitCode Value="0" Result="Success"/>

        <ExitCode Value="1641" Result="SuccessReboot"/>

        <ExitCode Value="3010" Result="SuccessReboot"/>

        <DefaultExitCode Result="Fail" FormatMessageFromSystem="true" String="GeneralFailure" />

      </ExitCodes>

    </Command>

  </Commands>

</Product>

 

Now create an “en” folder, and a file named “package.xml” within it. Into that file, copy-paste the following text:

<?xml version="1.0" encoding="utf-8" ?>

<Package

  xmlns="http://schemas.microsoft.com/developer/2004/01/bootstrapper"

  Name="DisplayName"

  Culture="Culture"

  LicenseAgreement="eula.1033.txt">

  <PackageFiles>

    <PackageFile Name="eula.1033.txt"/>

  </PackageFiles>

 

  <!-- Defines a localizable string table for error messages. -->

  <Strings>

    <String Name="DisplayName">Microsoft Visual Studio 2010 Tools for Office Runtime (x86 and x64)</String>

    <String Name="Culture">en</String>

    <String Name="AdminRequired">Administrator permissions are required to install the Microsoft Visual Studio 2010 Tools for Office Runtime (x86 and x64). Contact your administrator.</String>

    <String Name="GeneralFailure">A failure occurred attempting to install the Microsoft Visual Studio 2010 Tools for Office Runtime (x86 and x64).</String>

    <String Name="VSTORRedist">http://go.microsoft.com/fwlink/?LinkId=158918</String>

  </Strings>

</Package>

 

 

Finally, for “eula.1033.txt” (the end-user license agreement for the VSTO Runtime), you can simply re-use the same Eula that shipped with the VSTO Runtime (and which you got on your machine when you installed “Preview 2” of the office tools).

To find that file, simply navigate to one of the following locations:

x64 versions of Windows:

  • C:\Program Files\Common Files\microsoft shared\VSTO\10.0\Microsoft Visual Studio 2010 Tools for Office Runtime (x64)

X86 versions of Windows:

  • C:\Program Files\Common Files\microsoft shared\VSTO\10.0\Microsoft Visual Studio 2010 Tools for Office Runtime (x86)

And copy the “eula.1033.txt” file from there into your “VSTOR40\en” folder.

Almost there! Now all that remains is to copy the folder into the appropriate location on your machine (the same machine you’ll be using to publish the project). To do this:

1) Locate the Bootstrapper packages folder. On a machine where you’ve installed Visual Studio 2012, the default installation locations should be:

x64 version of Windows:

  • C:\Program Files (x86)\Microsoft SDKs\Windows\v8.0A\Bootstrapper\Packages

x86 version of Windows:

  • C:\Program Files\Microsoft SDKs\Windows\v8.0A\Bootstrapper\Packages

If the folder is not there, you can determine the location by looking it up in the registry ��� see http://msdn.microsoft.com/en-us/library/ms165429.aspx for more information.

2) Move your VSTOR40 folder into the Bootstrapper packages folder that you’ve identified above. In the end, your path and folder structure should look like this:

VSTOR40

You’re done! After you close and re-open Visual Studio, you should be able to activate the VSTO Runtime Bootstrapper prerequisite. To do this, open your project, go to the project’s properties, and then navigate to the “Publish” tab. Under the “Install Settings” group, click on the “Prerequisites…” button. In the window that opens, set the checkmark next to

“Microsoft Visual Studio 2010 Tools for Office Runtime (x86 and x64)”.

Publish

That’s it! After you publish your solution, end-users who don’t have the VSTO Runtime will automatically get the latest version of the runtime from the web.

Questions? Comments? Don’t hesitate to ask.

~ Michael Zlatkovsky | Program Manager, Visual Studio Tools for Office & Apps for Office

Leave a Comment
  • Please add 7 and 2 and type the answer here:
  • Post
  • Hi Michael, thanks for this, it meets a lot of needs. I do have a question though about shared addins for Office 2013, using Framework 4.5 and shimming though. Will there be any updating for the COM shim wizard that Misha Shneerson and Andrew Whitechapel had worked on previously? There still are cases where shared addins are useful, and having the project templates and shimming available in VS 2013 for Framework 4.5 use would be great.

    Thanks again.

    Ken Slovak

    Outlook MVP

  • Ken,

    The question about the drop of the shared add-in has been raised directly to Microsoft without any response. I also last month published a blog article about it.

    xldennis.wordpress.com/.../com-add-ins-excel-2013-important-news

    I hope it will be re-included in a future Service Pack to VS 2012 but to be honest I believe it's gone forever.

    Kind regards,

    Dennis

    Excel MVP

  • For the past several weeks using VS 2012 I have been trying to get .NET 4 Client Profile (or just the full version for that matter) and VSTOR40 to install if they are missing on the machine where my Excel 2010 macro-enabled Workbook fires up.  I am doing what you have described above (and have done the other 2 radio button options) without any luck.

    If the workbook does not find  .NET 4 Client Profile, for example, it only puts up this error message

    Title: Microsoft Office Document Customization

    Message: The following Microsoft Office solutioin cannot be loaded because a compatible version of the .NET Framework is not installed: ABCRSPL1_PL2ImportTemplate.xlsx.

    For more information, see go.microsoft.com/fwlink.

    and allows me to click on two buttons, one is Details which provides nothing in the screen below this message and the other is OK. I click OK and nothing happens.  Arrg!!!

    I suspect it may be something in the Product.xml that needs to be changed but I am not sure what.

    BTW: I have a WiX 3.6 bootstrapped project that will install .NET 4 Client Profile via an .msi but still have yet to get VSTOR40 to work with it.  

    If you could shed any light on this it would be greatly appreciated.  Thanks.

  • Actually I did get this to work. I was hoping opening the workbook would invoke the setup program (hmm...I wonder) versus having to specifically run it to set up .NET 4 Client Profile and VSTOR4, but the setup.exe does work.  

    Good post though this helped BIGTIME!!!

  • Awesome work. This really screwed me when I first deployed one of my new apps and got a really generic error, pretty much saying the wrong version of .NET was installed, on one of my client's PCs.

    Turns out it was missing VSTO runtime, and of course it wasn't available as a pre-req so I missed it. Fixed now! Thanks!

  • There seems to be a bug in the German version of the Office Developer Tools for Visual Studio 2012:

    The C:\Program Files (x86)\Microsoft SDKs\Windows\v8.0A\Bootstrapper\Packages\VSTOR40 folder contains the German Language Pack ("Microsoft Visual Studio 2010 Tools für Office Laufzeit (x86 und x64) Language Pack - DEU") but not the runtime package itself. In VS "Publish->Prerequisites" there is no item for the runtime but only an item for the language pack. I wasn't aware that runtime and language pack are two things so I selected just the available language pack. On some Windows 7 machines I got setup failures because of the missing runtime.

    Using your instructions I managed to fix the packages manually - would be nice to see it fixed in some future update.

  • @Guido,

    Thanks for reporting the issue, and glad you were able to find a workaround in the meantime.  I will file a bug on my team to investigate.

    Best,

    - Michael

  • I have a solution in VS 2012 targeting 4.5 framework. I added new vsto project targeting 2010 excel. I came across the same issue with 4.0 Framework. After going through a bunch of searches I landed here. After installing the latest office toolkit, all my 2010 templates are replaced with 2013. How can I get back my 2010 templates? Is it possible to use 2010 excel and target 4.5 framework? because earlier to installing the latest toolkit I have already added a 2010 excel addin project, after installing the new updates I am getting the same Upgrade error which I used to get while changing the target framework from 4.0 to 4.5. Any help is highly appreciated.

    Thanks,

    Maanu.

  • @Maanu,

    As noted in the Office Developer Tools for VS 2012 announcement (blogs.msdn.com/.../office-developer-tools-for-visual-studio-2012-now-available.aspx):

    "Now that's we've added .NET 4.5 support to 2013, we've properly re-categorized the templates in the "New Project" dialog according to the .NET framework version that they support. So, if you're looking for the Office 2010 templates after installing the latest tools, be sure to adjust the ".NET Framework" dropdown to ".NET Framework 4.0". Again, to recap, both the 2010 and 2013 templates support .NET Framework 4.0, but only the 2013 templates support .NET Framework 4.5 -- and the "New Project" dialog respects that categorization."

    Hope this helps.  Let me know if you have any more questions,

    ~ Michael Zlatkovsky | Program Manager, Visual Studio Tools for Office & Apps for Office

  • @Guido (and anyone using a localized version of Visual Studio),

    I am happy to say we resolved the issue.  There were some forward-links we adjusted on the back-end, but the experience should now work right out of the box, without the need to re-download the Office Developer Tools for Visual Studio 2012.

    Note that the title of the bootstrapper package in the Prerequisites list will still say it's a Language Pack, but it's actually the VSTO Runtime PLUS the Language Pack.

  • Hi Michael,

    I have a Class Library targeting .NET 4.0 being referenced by VSTO word 2010 add-in targeting .NET 4.0.

    I upgraded the Class Library to .NET 4.5 only to find out that I could not

    1)  compile VSTO word 2010 add-in due to .NET framework mismatch

    2) change the Target Framework on the add-in to .NET 4.5 due to the message "Attempted re-targeting of the project has been cancelled. The .NET

    Framework version you selected is not supported by this project type."

    Please advise,

    -Sashi.

  • @Sashi:  .NET 4.5 is only available for Office 2013.  So I think your two options are either to target Office 2013 (by migrating the project to VS 2012 + Office Developer Tools for VS 2012 from aka.ms/OfficeDevToolsForVS2012), or to change the class library back to use .NET 4.0.

    Hope this helps,

    ~ Michael

  • Can it be used in VS2010?

    How about the german package language?

  • @Selo:

    VS 2010 already includes the boostrapper.  When you select (on a German VS 2010 installation) the VSTO Runtime German Language Pack, this will install both the runtime and the language pack.

    Note that starting with the bootstrapper described above, and now in VS 2013 (and in the Office Developer Tools for VS 2012), the Runtime prerequisite will be displayed as just the runtime, without language packs, even on non-English machines.  This is because the newer runtime package automatically installs the language packs for the target operating system when it's installed, so there is no longer the need to pre-req the language pack.

    Hope this helps,

    - Michael

  • nice, it's very fine, thank you very much!

Page 1 of 1 (15 items)

Creating a Bootstrapper package for an Office 2013 VSTO Add-in with Visual Studio 2012