Add support for different build flavors using IsExperimental and IsProductComponent properties

[jcansdale]

Fixes #883

This PR makes it easy to install developer VSIX builds over the top of the release version (installed for all users).

The Publish configuration extension.vsixmanifest will include:

  <Installation AllUsers="true">

I wonder if we also should be using InstalledByMSI (see jaredpar/VsixUtil#1 (comment))?

The Debug and Release configurations will include:

  <Installation AllUsers="false" Experimental="true">

[jcansdale]

@tannergooding, I was wondering how the Roslyn team handles using slightly different source.extension.vsixmanifest files? You mentioned having, "an internal tool which fixes things up". Does this tweak the XML and add/remove the Experimental="true" attribute? How do you hook it into your .csproj?

The least-worst solution I've come up with so far is as follows. Unfortunately it involves duplicating the source.extension.vsixmanifest files in different folders, which isn't so elegant!

<None Condition="'$(Configuration)' == 'Debug'"
    Include="Configuration\Debug\source.extension.vsixmanifest" />
<None Condition="'$(Configuration)' == 'Release'"
    Include="Configuration\Release\source.extension.vsixmanifest" />
<None Condition="'$(Configuration)' == 'Publish'"
    Include="Configuration\Publish\source.extension.vsixmanifest" />

Thanks!

[jcansdale]

My second attempt uses the following:

  <!--
  Update 'Debug' and 'Release' configurations to have AllUsers="false" and Experimental="true"
  The Publish configuration will keep AllUsers="true" and Experimental="false".
  -->
  <Target Name="MakeVsixManifestExperimental" AfterTargets="DetokenizeVsixManifestFile"
          Condition=" '$(Configuration)' == 'Debug' Or '$(Configuration)' == 'Release' ">
    <Warning Text="NOTE: Tweaking '$(IntermediateVsixManifest)' to be 'Experimental'" />
    <XmlPoke XmlInputPath="$(IntermediateVsixManifest)" Query="/x:PackageManifest/x:Installation/@AllUsers" Value="false"
             Namespaces="&lt;Namespace Prefix='x' Uri='http://schemas.microsoft.com/developer/vsx-schema/2011' /&gt;" />
    <XmlPoke XmlInputPath="$(IntermediateVsixManifest)" Query="/x:PackageManifest/x:Installation/@Experimental" Value="true"
             Namespaces="&lt;Namespace Prefix='x' Uri='http://schemas.microsoft.com/developer/vsx-schema/2011' /&gt;" />
  </Target>

I think this is more maintainable because there's only a single source.extension.vsixmanifest file.

[jcansdale]

Once this PR goes though, you should be able to install the locally built VSIX over the top of the deployed version. The deployed version will use the Publish configuration and install with AllUsers=true and Experimental=false).

Also, you can associate VSIX files with the EXE found here: tools/VsixUtil/VsixUtil.exe
This will uninstall any previous Experimental version, before installing the target VSIX.

I'm adding a bunch of reviewers, so you all know this is possible. 😄

[tannergooding]

@jcansdale, the tool source is here: https://github.com/dotnet/roslyn-tools/tree/master/src/ModifyVsixManifest/ModifyVsixManifest.

Basically our default VSIX manifest has Experimental=true and does not specify AllUsers or InstalledByMSI. We then (post build, but pre-signing) copy the VSIX to a separate location and run the below command. The original output retains the Experimental flag and the copied output will lose the Experimental flag and gain the AllUsers and InstalledByMSI flags. We then use the copied output as the VSIX we insert into VS and you should be able to give the original to people who need to dogfood the latest bits.

& $modifyVsixManifestTool --vsix=$insertionVsix --remove=//x:PackageManifest/x:Installation/@Experimental --add-attribute=//x:PackageManifest/x:Installation`;AllUsers`;true --add-attribute=//x:PackageManifest/x:Installation`;InstalledByMSI`;true

[jcansdale]

@tannergooding Thanks for the link! You have a bunch if interesting tools in there. 😄

I can see how it makes sense to tweak this pre-signing. Since we have a separate configuration for Publish, using the XmlPoke seems to work well. I'll chat to the team about this.

[jcansdale]

Oh, it seems we don't actually use the Publish configuration. 😕

I've changed it so that it defaults to AllUsers=false and Experimental=true. For the Release configuration, this will be tweaked to be AllUsers=true and Experimental=false.

[paladique]

Looks great, works great! Not sure if there's been a discussion about this already, but should we have a name other than "Experimental" for a local install? I could see confusion about what experimental actually means to someone building locally. It's just two definitions now, but a VS experimental instance is also local.

[paladique]

Also, what happens if I keep automatic updates checked and an update happens? Does it overwrite my experimental install?

[jcansdale]

@paladique,

Not sure if there's been a discussion about this already, but should we have a name other than "Experimental" for a local install?

Good question! At the moment when you build a Debug configuration of the VSIX, its extension.vsixmanifest will be have Experimental=true and AllUsers=false. This is the only configuration that can feasibly be installed locally.

If you build a Release configuration of the VSIX, it will have the Experimental=false and AllUsers=true. You would struggle to install this version and if you managed, it would silently revert to the last version installed via Extensions and Updates. You'll get the kind of thing @grokys had when trying to uninstall the AllUsers=true version:

28/02/2017 17:32:17 - Uninstalling 'GitHub Extension for Visual Studio', version 2.2.0.8.
28/02/2017 17:32:21 - System.InvalidOperationException: The VSIX's catalog does not include a 'Component' which is required for install/uninstall.

Good point about the potential for confusion with the "Experimental" instance of Visual Studio! Let me know if you can think of a way to clarify the wording.

[jcansdale]

@paladique,

Also, what happens if I keep automatic updates checked and an update happens? Does it overwrite my experimental install?

It looks like experimental installs are sticky and don't automatically update. I did some experiments with a feed containing experimental installs and it looks like you have to explicitly trigger the update.

[jcansdale]

From README.md:

Build Flavors

By default, building will create a VSIX with Experimental="true" and AllUsers="false" in its extension.vsixmanifest. These settings are necessary in order to easily install a standalone VSIX file. There is no need to uninstall the version previously installed via Visual Studio setup / Extensions and Updates.

To build and install a Debug configuration VSIX:

build.cmd
install.cmd

To build and install a Release configuration VSIX:

set Configuration=Release
build.cmd
install.cmd

To build a VSIX that could be deployed via the gallery / Extensions and Updates:

set Configuration=Release
set IsExperimental=false
build.cmd
install.cmd

To build a VSIX that could be deployed via Visual Studio setup:

set Configuration=Release
set IsExperimental=false
set IsProductComponent=false
build.cmd
install.cmd

[grokys]

This should be IsProductComponent=true however I'm not sure we should even put this section in the publicly readable readme as it's for internal use only.

[jcansdale]

I wanted to keep everything together as much as possible. The Roslyn build uses similar stuff, so it isn't secret knowledge or anything. Since the .csproj files are public, I thought this documentation for them should be as well.

[jcansdale]

Opps. Good catch on IsProductComponent=true. Updated.

[grokys]

Might be worth making clear these instructions are for cmd.exe - when running them in powershell the set commands have no effect.

[jcansdale]

@tannergooding do you know if Experimental has broken in recent version of the tooling? We're suddenly getting our Experimental version loaded at the same time as the AllUsers version. Very frustrating! 😭

[tannergooding]

I'm not aware of anything that changed here.

[jcansdale]

I've worked out what the problem is. I assumed the Experimental flag would make the extension load instead of the AllUsers extension. Apparently the extension is actually overlaid on top of the AllUsers extension. This seems to work fine as long as none of your package GUIDs have changed!

The issue we were seeing was triggered when one of our package GUIDs did change. This caused both versions of our extension to load and all kinds of problems!

This is definitely something to watch out for if you ever remove a package! I struggle to believe this is how it's supposed to work. Maybe @tinaschrepfer could confirm?