Visual Studio Project Templates #2: Uploading to Visual Studio Gallery

In the previous blog post I explained how to create project templates and import them into Visual Studio. This manual import might be sufficient for internal use, but if you plan to distribute your project templates an automatic installer would be much more professional. Fortunately, Visual Studio allows the creation of installer packages and even provides us with a simple possibility of hosting those packages and making it publicly available.

In practive this is done by packing one or multiple project templates into an installer (a *.vsix file) and publish this package on Visual Studio Gallery. This mechanism allows you (or your colleagues, customers, etc.) to access your templates directly from the Extensions and Updates modules within Visual Studio, without even opening a web browser – just download and run the installer, and all the template projects will appear in the New Project window from then on!

Sounds like a cool feature, right? Well, it surely is as soon as the templates are online – but actually deploying and publishing such an installer takes quite some time if you don’t know all the (undocumented) hints and shortcuts! Here are the necessary steps (please notice that these require at least one fully functional project template – if you’re not at this point yet, read Visual Studio Project Templates #1 first):

  1. To create an installer package, first you need to make sure that Visual Studio SDK is installed on your machine. When this is finished, choose File -> New -> Project… and create a new “VSIX Project”. This project type can be found in the Templates -> Visual C# -> Extensibility category.
  2. The source.extension.vsixmanifest File will be opened in the visual designer. On the “Metadata” page, fill in project name, author, version and all the other (partially optional) meta data. Most of these values will be presented to potential users either before downloading or while running the installer package. If you’re ready, make sure you write down the Project ID (or, even better and simpler, copy it to an empty notepad document) – we will need it in one of the next steps.
  3. You should also check the “Install Targets” page and add all the Visual Studio version you want your installer package to be available for. If you want your installer to be compatible also with future versions of Visual Studio, it’s important to provide a value like [11.0,] (e.g., using Visual Studio 2012 = Version 11.0 as minimum version) as the Version Range!
  4. This step applies only if one of the project templates that shall be part of the installer references third party libraries that can be obtained via Nuget.
    In this case, create a folder named “packages” as part of the VSIX project and import all those referenced library packages to this folder. Then select these packages in the Solution Explorer, open the Properties pane and make sure that Build Action is set to “Content” and Include in VSIX is “True” for all of these packages.
    Now we will need the Project ID assigned in step 2! For all project templates that depend on one of the packages you’ve just imported, do the following: Extract the ZIP file’s contents, open the MyTemplate.vstemplate file in notepad or any text editor, and add the following lines as child of the <VSTemplate> node (directly after the closing </TemplateContent> tag):

    <WizardExtension>
    	<Assembly>NuGet.VisualStudio.Interop, Version=1.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a</Assembly>
    	<FullClassName>NuGet.VisualStudio.TemplateWizard</FullClassName>
    </WizardExtension>
    <WizardData>
    	<packages repository="extension" repositoryId="YOUR_PROJECT_ID">
    		<package id="THIRD_PARTY_PACKAGE_ID_1" version="THIRD_PARTY_PACKAGE_VERSION_1" />
    		<package id="THIRD_PARTY_PACKAGE_ID_2" version="THIRD_PARTY_PACKAGE_VERSION_2" />
    		... other third party packages ...
    	</packages>
    </WizardData>
    

    Be sure to replace YOUR_PROJECT_ID with the Project ID assigned in step 2, and adapt the lines starting with <package...> or add additional lines if you reference more than two packages. Finally, create a ZIP file again containing all the project template files.

  5. On the “Assets” page, add all the project templates you want as content of this installer package (all that shall be imported into Visual Studio when running the installer) by clicking the New button and selecting the options according to the following screen shot within the Add New Asset windows:
    Add New Asset windowFinally, click the Browse button to search for the ZIP file that contains the project template to import. As mentioned already, an installer package may contain multiple project templates all of which will be imported into Visual Studio when running the installer.
  6. Build the VSIX project! It will produce a *.vsix file which you can distribute. Double-clicking this file will install all your project templates to Visual Studio. (To be able to adapt the installer, rebuild it and test it again, you can uninstall it from Visual Studio in the Extensions and Updates window that can be accessed from the Tools menu.)
  7. If you’d like your project templates to appear in (different) categories in the New Project window instead of directly under the Visual C# category, rename the *.vsix file to *.zip, and extract its contents to some empty folder. Open the ProjectTemplates folder, it will contain all the ZIP files representing your project templates. Here you can create a new folder called “CSharp” and in there several subfolders with names according to the desired sub-categories (you can both use existing categories and establish new ones). Move each ZIP file from the root folder to the respective subfolder that represents the category the project template shall appear in. Finally, navigate back to the root folder, create a ZIP file and rename it to *.vsix – done!
  8. As an alternative to distribute the installer manually, Microsoft allows you to host installers on Visual Studio Gallery. Doing so will enable other users to download your installer and install your project templates directly within Visual Studio, from the Extensions and Updates window that can be accessed from the Tools menu.To upload the newly created installer package to Visual Studio Gallery, go to http://visualstudiogallery.msdn.microsoft.com/, log in with your Microsoft Account and click “Upload”. In step 1, choose the “Project or item template” option. You’ll then be asked to select your installer (*.vsix) file and upload it. Finally, step 3 will ask you for additional information that can be matched with users’ search criteria to offer your installer for download.
  9. If your installer contains multiple project templates, chances are high that you are presented the error message “Invalid Multiple ZIP Files in in VSIX” in the second part of the Visual Studio Gallery upload process. The Visual Studio Gallery uploader seems to be quite buggy, i was struggling with this exact error forever… Here is a workaround that worked at least for me:
    Rename the *.vsix file to *.zip, extract its contents to some empty folder, and open the ProjectTemplates folder. It seems that for Visual Studio Gallery to accept your installer, each category-folder (see step 7) may only contain one single ZIP file. This means that you could either ensure that each category contains only one of your project templates, but this might be too limiting in most cases. The alternative is to rename to ProjectTemplates folder, for example to ProjectTemplates1, and duplicate it to additional folders ProjectTemplates2, ProjectTemplates3, an so on. Now you can remove all the ZIP files except for one from each of the folders.
    Moreover, it seems that the uploader doesn’t like similar folder names – e.g., if you have one folder called ProjectTemplates1 you should not create another one called ProjectTemplates10, since this contains the name of an existing folder. If 9 different project template folders are not enough, consider naming the folders ProjectTemplatesA, ProjectTemplatesB, and so on!
    For this to work you’ll also need to adapt the extension.vsixmanifest file: Inside the <Assets> node, create one
    <Asset Type="Microsoft.VisualStudio.ProjectTemplate" Path="ProjectTemplatesX"/>
    line for each project template folder you have created.
    Finally, create a ZIP file again, rename it to *.vsix and try to upload it again!