Merge pull request #258 from heaths/extensibility

Add info about query API for extensibility

Author: Greg Van Liew

docs/extensibility/TOC.md

@@ -232,6 +232,7 @@
 #### [Specifying File Handlers for File Name Extensions](specifying-file-handlers-for-file-name-extensions.md)
 #### [Registering Verbs for File Name Extensions](registering-verbs-for-file-name-extensions.md)
 #### [Managing Side-by-Side File Associations](managing-side-by-side-file-associations.md)
+## [Locating Visual Studio](locating-visual-studio.md)
 # [Inside the Visual Studio SDK](internals/TOC.md)
 # [Support for the Visual Studio SDK](support-for-the-visual-studio-sdk.md)
 # [Visual Studio SDK Reference](visual-studio-sdk-reference.md)

docs/extensibility/breaking-changes-2017.md

@@ -59,14 +59,16 @@ Designer tooling for authoring of the new VSIX v3 manifest format is now availab
 
 Previously, only one installation of each major release of Visual Studio could exist on each machine. To support side-by-side installations of Visual Studio 2017, multiple user data paths for Visual Studio may exist on the user's machine.
 
-Code running inside the Visual Studio process should be updated to use the Visual Studio Settings Manager. Code running outside of the Visual Studio process can find the user path of a specific Visual Studio installation [by following the guidance here](https://blogs.msdn.microsoft.com/heaths/2016/09/15/changes-to-visual-studio-15-setup).
+Code running inside the Visual Studio process should be updated to use the Visual Studio Settings Manager. Code running outside of the Visual Studio process can find the user path of a specific Visual Studio installation [by following the guidance here](locating-visual-studio.md).
 
 ## Change: Global Assembly Cache (GAC)
 
 Most Visual Studio core assemblies are no longer installed into the GAC. The following changes were made so that code running in Visual Studio process can still find required assemblies at runtime.
 
+> [!NOTE] [INSTALLDIR] below refers to the installation root directory of Visual Studio. VSIXInstaller.exe will automatically populate this, but to write custom deployment code please read [locating Visual Studio](locating-visual-studio.md).
+
 * Assemblies that were only installed into the GAC:
-  * These assemblies are now installed under %VsFolder%\Common7\IDE\, %VsFolder%\Common7\IDE\PublicAssemblies or %VsFolder%\Common7\IDE\PrivateAssemblies. These folders are part of the Visual Studio process's probing paths.
+  * These assemblies are now installed under [INSTALLDIR]\Common7\IDE\, [INSTALLDIR]\Common7\IDE\PublicAssemblies or [INSTALLDIR]\Common7\IDE\PrivateAssemblies. These folders are part of the Visual Studio process's probing paths.
 * Assemblies that were installed into a non-probing path and into the GAC:
   * The copy in the GAC was removed from setup.
   * A .pkgdef file was added to specify a code base entry for the assembly.
@@ -80,22 +82,22 @@ Most Visual Studio core assemblies are no longer installed into the GAC. The fol
     "culture"="neutral"
     "version"=15.0.0.0
     ```
-    At runtime, the Visual Studio pkgdef subsystem will merge these entries into the Visual Studio process's runtime configuration file (under %VsAppDataFolder%\devenv.exe.config) as [`<codeBase>`](https://msdn.microsoft.com/en-us/library/efs781xb(v=vs.110).aspx) elements. This is the recommended way to let the Visual Studio process find your assembly, because it avoids searching through probing paths.
+    At runtime, the Visual Studio pkgdef subsystem will merge these entries into the Visual Studio process's runtime configuration file (under [VSAPPDATA]\devenv.exe.config) as [`<codeBase>`](https://msdn.microsoft.com/en-us/library/efs781xb(v=vs.110).aspx) elements. This is the recommended way to let the Visual Studio process find your assembly, because it avoids searching through probing paths.
 
 ### Reacting to this breaking change
 
 * If your extension is running within the Visual Studio process:
   * Your code will be able to find Visual Studio core assemblies.
   * Consider using a .pkgdef file to specify a path to your assemblies if necessary.
 * If your extension is running outside the Visual Studio process:
-  * Consider looking for Visual Studio core assemblies under %VsFolder%\Common7\IDE\, %VsFolder%\Common7\IDE\PublicAssemblies or %VsFolder%\Common7\IDE\PrivateAssemblies using configuration file or assembly resolver.
+  * Consider looking for Visual Studio core assemblies under [INSTALLDIR]\Common7\IDE\, [INSTALLDIR]\Common7\IDE\PublicAssemblies or [INSTALLDIR]\Common7\IDE\PrivateAssemblies using configuration file or assembly resolver.
 
 ## Change: Reduce registry impact
 
 ### Global COM registration
 
 * Previously, Visual Studio installed many registry keys into the HKEY_CLASSES_ROOT and HKEY_LOCAL_MACHINE hives to support native COM registration. To eliminate this impact, Visual Studio now uses [Registration-Free Activation for COM components](https://msdn.microsoft.com/en-us/library/ms973913.aspx).
-* As a result, most TLB / OLB / DLL files under %ProgramFiles(x86)%\Common Files\Microsoft Shared\MSEnv are no longer installed by default by Visual Studio. These files are now installed under %VsFolder% with corresponding Registration-Free COM manifests used by the Visual Studio host process.
+* As a result, most TLB / OLB / DLL files under %ProgramFiles(x86)%\Common Files\Microsoft Shared\MSEnv are no longer installed by default by Visual Studio. These files are now installed under [INSTALLDIR] with corresponding Registration-Free COM manifests used by the Visual Studio host process.
 * As a result, external code that relies on global COM registration for Visual Studio COM interfaces will no longer find these registrations. Code running inside Visual Studio process will not see a difference.
 
 ### Visual Studio registry
@@ -104,7 +106,7 @@ Most Visual Studio core assemblies are no longer installed into the GAC. The fol
   * HKLM\Software\Microsoft\VisualStudio\\**Version**: Registry keys created by MSI installers and per-machine extensions.
   * HKCU\Software\Microsoft\VisualStudio\\**Version**: Registry keys created by Visual Studio to store user-specific settings.
   * HKCU\Software\Microsoft\VisualStudio\\**Version**_Config: A copy of Visual Studio HKLM key above, plus the registry keys merged from .pkgdef files by extensions.
-* To reduce the impact on the registry, Visual Studio now uses the [RegLoadAppKey](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724886(v=vs.85).aspx) function to store registry keys in a private binary file under %VsAppDataFolder%\privateregistry.bin. Only a very small number of Visual Studio-specific keys remain in the system registry.
+* To reduce the impact on the registry, Visual Studio now uses the [RegLoadAppKey](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724886(v=vs.85).aspx) function to store registry keys in a private binary file under [VSAPPDATA]\privateregistry.bin. Only a very small number of Visual Studio-specific keys remain in the system registry.
 * Existing code running inside the Visual Studio process is not impacted. Visual Studio will redirect all registry operations under the HKCU Visual Studio-specific key to the private registry. Reading and writing to other registry locations will continue to use the system registry.
 * External code will need to load and read from this file for Visual Studio registry entries.
 

docs/extensibility/locating-visual-studio.md

@@ -0,0 +1,56 @@
+---
+title: "Locating Visual Studio | Microsoft Docs"
+ms.custom: ""
+ms.date: "08/21/2017"
+ms.reviewer: ""
+ms.suite: ""
+ms.technology: 
+  - "vs-ide-sdk"
+ms.tgt_pltfrm: ""
+ms.topic: "article"
+helpviewer_keywords: 
+  - "deployment, VSIX"
+ms.assetid: 680c3b25-7901-4768-8363-6d1fcd1ea636
+ms.author: "heaths"
+manager: "ghogen"
+translation.priority.mt: 
+  - "cs-cz"
+  - "de-de"
+  - "es-es"
+  - "fr-fr"
+  - "it-it"
+  - "ja-jp"
+  - "ko-kr"
+  - "pl-pl"
+  - "pt-br"
+  - "ru-ru"
+  - "tr-tr"
+  - "zh-cn"
+  - "zh-tw"
+---
+# Locating Visual Studio
+
+Starting with Visual Studio 2017, you can install multiple instances of the same version or even edition. This is helpful when you want to preview new functionality on your primary development machine while retaining your previous installation. Because of these changes, there is no single environment variable or registry value you can use to locate an instance. Instead, you can use a [COM query API](https://msdn.microsoft.com/library/microsoft.visualstudio.setup.configuration.aspx) to find instances based on criteria relevant to your extension.
+
+This is a fast, read-only API with NuGet packages available for native and managed code.
+
+| Code | Package |
+| ---- | --- |
+| Native | https://nuget.org/packages/Microsoft.VisualStudio.Setup.Configuration.Native |
+| Managed | https://nuget.org/packages/Microsoft.VisualStudio.Setup.Configuration.Interop |
+
+You can locate a single instance given a path or the current process, or enumerate all instances. See [our samples](https://github.com/Microsoft/vs-setup-samples) for complete examples of how to locate Visual Studio.
+
+## Tools
+
+To find Visual Studio and other tools in build environments, PowerShell scripts, installers, and more scenarios, we have a number of open source tools you can use directly or redistribute along with your own scripts.
+
+| Project | Description |
+| ------- | ----------- |
+| [vswhere](https://github.com/Microsoft/vswhere) | Single-file native executable to locate instances meeting criteria such as release or pre-release, what product is installed, and which workloads are installed. Also supports finding Visual Studio 2010 and newer, though less information is returned that for Visual Studio 2017 and newer. See the [wiki](https://github.com/Microsoft/vswhere/wiki) for examples. |
+| [VSSetup cmdlets](https://github.com/Microsoft/vssetup.powershell) | PowerShell cmdlets supported 2.0 and newer that return rich information as objects you can use to find instances based on the same criteria as _vswhere_ and to discover even more properties about instances. See the [wiki](https://github.com/Microsoft/vssetup.powershell/wiki) for examples. |
+| [VSIXBootstrapper](https://github.com/Microsoft/vsixbootstrapper) | Automatically locates _VSIXInstaller_ and passes the command line through to install a _*.vsix_ file. This can be useful in installers that do not have direct support for the query APIs. See the [wiki](https://github.com/Microsoft/vsixbootstrapper/wiki) for examples. |
+
+## See Also
+
+* [Changes to Visual Studio 2017 Setup](https://blogs.msdn.microsoft.com/heaths/2016/09/15/changes-to-visual-studio-15-setup)

docs/extensibility/set-install-root.md

@@ -31,15 +31,15 @@ translation.priority.mt:
 ---
 # Installing outside the extensions folder
 
-Starting with Visual Studio 2017 and VSIX v3 (version 3), there is now support for installing extension assets outside of the extensions folder. Currently, the following locations are enabled as valid installation locations (where [installdir] is mapped to the Visual Studio instance's installation directory):
+Starting with Visual Studio 2017 and VSIX v3 (version 3), there is now support for installing extension assets outside of the extensions folder. Currently, the following locations are enabled as valid installation locations (where [INSTALLDIR] is mapped to the Visual Studio instance's installation directory):
 
-* [installdir]\Common7\IDE\PublicAssemblies
-* [installdir]\Common7\IDE\ReferenceAssemblies
-* [installdir]\MSBuild
-* [installdir]\Schemas
-* [installdir]\Licenses
-* [installdir]\RemoteDebugger
-* [installdir]\VSTargets
+* [INSTALLDIR]\Common7\IDE\PublicAssemblies
+* [INSTALLDIR]\Common7\IDE\ReferenceAssemblies
+* [INSTALLDIR]\MSBuild
+* [INSTALLDIR]\Schemas
+* [INSTALLDIR]\Licenses
+* [INSTALLDIR]\RemoteDebugger
+* [INSTALLDIR]\VSTargets
 
 >**Note:** The VSIX format does not allow you to install outside the VS install folder structure.
 
@@ -67,7 +67,7 @@ This will add some metadata to the corresponding `ProjectReference` property ins
 
 ## How to set a subpath under the InstallRoot
 
-If you'd like to install to a subpath underneath the `InstallRoot`, you can do so by setting the `VsixSubPath` property just like the `InstallRoot` property. For instance, say we want our project reference's output to install to '[installdir]\MSBuild\MyCompany\MySDK\1.0'. We can do this easily with the property designer:
+If you'd like to install to a subpath underneath the `InstallRoot`, you can do so by setting the `VsixSubPath` property just like the `InstallRoot` property. For instance, say we want our project reference's output to install to '[INSTALLDIR]\MSBuild\MyCompany\MySDK\1.0'. We can do this easily with the property designer:
 
 ![set subpath](media/set-subpath.png)
 

docs/extensibility/shipping-visual-studio-extensions.md

@@ -70,4 +70,5 @@ After you've finished developing your extension, you can install it on other mac
 |[Preparing Extensions for Windows Installer Deployment](../extensibility/preparing-extensions-for-windows-installer-deployment.md)|Explains how to deploy your extension with Windows Installer.|  
 |[Signing VSIX Packages](../extensibility/signing-vsix-packages.md)|Explains how to sign VSIX packages.|  
 |[Private Galleries](../extensibility/private-galleries.md)|Explains how to create private galleries for extensions.|  
-|[Supporting Multiple Versions of Visual Studio](../extensibility/supporting-multiple-versions-of-visual-studio.md)|Shows how to have your extension support multiple versions of Visual Studio.|
+|[Supporting Multiple Versions of Visual Studio](../extensibility/supporting-multiple-versions-of-visual-studio.md)|Shows how to have your extension support multiple versions of Visual Studio.|
+|[Locating Visual Studio](locating-visual-studio.md)|Describes how to locate Visual Studio instances for custom extension deployment.|