Table of Contents
Shell (Isolated or Integrated)
Visual Studio Isolated Shell
Walkthrough: Creating a Basic Isolated Shell Application
Customizing the Isolated Shell
Extending the Isolated Shell
Elements of the Isolated Shell
Visual Studio Shell (Integrated)
Distributing Isolated Shell Applications
Installing an Isolated Shell Application
Servicing Guidelines for Isolated Shell Applications
Shell (Isolated or Integrated)
10/20/2017 • 2 min to read • Edit Online
You can create your own Visual Studio-based application in either integrated or isolated mode. In integrated mode,
many Visual Studio features are available in addition to your application. In the isolated mode, you choose a subset
of Visual Studio features that you wish to distribute along with your own extension.
Integrated Mode
Integrated mode enables your users to use standard Visual Studio features along with your custom tools. The
integrated shell is intended primarily for hosting programming languages and software development tools.
Custom tools that are built on the integrated shell automatically merge with any other edition of Visual Studio that
is installed on the same computer. You can provide a redistributable version of the Visual Studio integrated shell if
Visual Studio is not already installed.
The redistributable version of the Visual Studio integrated shell does not include programming languages and the
features that support their respective project systems.
NOTE
The Visual Studio shell integrated mode can be installed together with all editions of Visual Studio except the Express editions.
For more information, see Visual Studio Shell (Integrated).
Isolated Mode
Isolated mode allows you to create custom tools that run side-by-side with other versions of Visual Studio. It is
intended primarily for tools that can access Visual Studio services without depending on all the standard Visual
Studio features. You can customize the appearance of applications built on the Visual Studio isolated shell. You can
easily turn off the features and menu command groups that you do not wish to appear together with your
application.
For more information, see Visual Studio Isolated Shell.
Distributing your Integrated or Isolated Shell Application
In order to distribute your integrated or isolated shell application, you need to include your application, a special
integrated or isolated shell redistributable, and an installation program. For more information about distribution
and installation, see Distributing Isolated Shell Applications.
IMPORTANT
The End User License Agreement (EULA) for the Visual Studio integrated and isolated shells includes a section on data
collection (Section 3. Data). It describes the customer usage data that may be collected by Microsoft from users of either the
integrated or isolated shell software that you build into your application. For more information, see Microsoft Visual Studio
Product Family Privacy Statement.
If you collect separate usage data from your customers through your application, you must provide appropriate notice to
users of your application of what you collect. When you distribute either the isolated or integrated shell software as part of
your application, according to the Visual Studio Software Development Kit license, you must include one of the following:
the End User License Agreement as part of your application license
your own EULA that requires your customers to agree to terms that protect the Visual Studio integrated or
isolated shell at least as much as the Microsoft End User License Terms for the shell software
Additional Resources
For more information about redistributable packages, see the Visual Studio Extensibility Downloads Web site.
See Also
Shipping Visual Studio Extensions
Visual Studio Isolated Shell
10/20/2017 • 3 min to read • Edit Online
The Visual Studio isolated shell allows you to create stand-alone applications that can run side-by-side with other
versions of Visual Studio. It is used primarily to host specialized tools that can use Visual Studio services but also
have a customized appearance and branding. Visual Studio features and menu command groups can be easily
turned on and off. Application titles, application icons, and splash screens are fully customizable. For a list of
customizable features, see Customizing the Isolated Shell.
To work with an isolated shell project, you must install the Visual Studio SDK. Starting in Visual Studio 2015, you
do not install the Visual Studio SDK from the download center. It is included as an optional feature in Visual Studio
setup. You can also install the VS SDK later on. For more information, see Installing the Visual Studio SDK.
To create an isolated shell application, start with a Visual Studio Shell Isolated project. This project contains
everything that you need to develop and test your own isolated shell application. When you are ready to write the
setup program that deploys your application, you must get the isolated shell redistributable package from
Microsoft Visual Studio Shell (Isolated) Redistributable Package.
NOTE
Before you can access the isolated shell redistributable package, you will be asked to fill out a brief customer survey. After
filling out the survey, you'll be directed to a Visual Studio Connect page with redistributable package download links. You can
find the download links on subsequent visits to the Visual Studio Connect site under the PROGRAMS | VISUAL STUDIO
2015 INTEGRATED AND ISOLATED SHELL tab.
NOTE
For more information about how to deploy an isolated shell-based application, see Walkthrough: Creating a Basic Isolated
Shell Application.
Working with the isolated shell
A Visual Studio isolated shell application has full access to Visual Studio services and supports special
customization and branding. There are several ways you can customize an isolated shell application:
You can use VSPackages and Managed Extensibility Framework (MEF) component parts to extend an
isolated shell application just as you would use them in any other Visual Studio extension. For more
information, see Extending the Isolated Shell.
To make Visual Studio features and menu command groups available or unavailable, update the .vsct file in
the user interface (UI) project of the application.
To remove Options pages or other Visual Studio shell components from the application, update the
.pkgundef file of the application.
To modify other aspects of the appearance or behavior of the shell, update the .pkgdef file of the application.
Some aspects of the shell can also be specified when the application is started. To do this, update the
parameters in the call to the Start entry point of the appenvstub.dll.
For more information about the different elements that you can customize, see Elements of the Isolated
Shell.
Standard Features of the Isolated Shell
The following features are standard to all editions of Visual Studio.
FEATURE CATEGORY
FEATURE
IDE Features
Import/Export Settings
Toolbox Control Installer
Task List & Error List
Output Window
Start Page
Properties Window
Toolbox
Solution Explorer
Bookmark Window
Class View
Object Browser
Command Window
Document Outline
Resource View
External Tool
Windows Communication Foundation (WCF) Add Service
Reference
Language Integrated Query (LINQ) Support
FEATURE CATEGORY
FEATURE
Editor/Designer
Code browsing tools (unified find, source definition,
inheritance)
IntelliSense
SmartTags
Code Snippets Manager
Code Snippets
Refactoring
Pretty listing
IntelliSense Filtering
Code Definition Window
Application Designer
Windows Forms Designer
Windows Presentation Foundation (WPF) Designer
Debugging
C# Expression Evaluator
Local debugging
Managed debugging
Edit and Continue
Cross-thread debugging
Visualizations
DataTips
Native debugging
Script debugging
Interop debugging
Just-in-time (JIT) debugging
Multi-process debugging
XSLT debugging
Attach to local process
Trace Points
Breakpoint Constraints
FEATURE CATEGORY
FEATURE
Data
Server Explorer (Simplified - Data Only)
Data bind to local data (.MDF or .MDB)
Data bind to object
Data bind to Web service
Full set of data controls
XML editor
Data bind to local database server
Data Sources window
Web
HTML Editor
Web Browser
Web Forms Designer
Web Site Project
Web Application Project
Extensibility
See Also
Shell (Isolated or Integrated)
Consumes VSPackages and MEF components
Walkthrough: Creating a Basic Isolated Shell
Application
10/20/2017 • 8 min to read • Edit Online
This walkthrough shows how to create an isolated shell solution, customize the Help About tool window, and
create a setup program that installs the isolated shell.
Prerequisites
To follow this walkthrough, you must install the Visual Studio SDK. For more information, see Visual Studio SDK.
To deploy the isolated shell, you must also use the Visual Studio Shell (Isolated) Redistributable Package.
Creating an Isolated Shell Solution
This section shows how to use the Visual Studio Shell Isolated project template to create an isolated shell
solution. The solution contains the following projects:
The SolutionName.AboutBoxPackage project, which allows you to customize the appearance of the
Help/About box.
The ShellExtensionsVSIX project, which contains the source.extension.vsixmanifest file that defines the
different components of the isolated shell application.
The SolutionName project, which produces the executable file that invokes the isolated shell application.
This project contains the Shell Customization folder, which allows you to customiz the appearance and
behavior of the isolated shell application.
The SolutionName UI project, which produces a satellite assembly that defines active menu commands
and localizable strings.
To create a basic isolated shell solution
1. Open Visual Studio and create a new project.
2. In the New Project window, expand Other Project Types and then Extensibility. Select the Visual
Studio Shell Isolated project template.
3. Name the project MyVSShellStub and specify a location. Make sure that Create directory for solution is
checked, and then click OK.
The new solution appears in Solution Explorer.
4. Build the solution and start debugging the isolated shell application.
The Visual Studio isolated shell appears. The title bar reads MyVSShellStub. The title bar icon is generated
from \MyVSShellStub\Resource Files\ApplicationIcon.ico.
Customizing the Application Name and Icon
You may want to brand your application by using the name of your company and its logo in the title bar. The
following steps show how to change the name and icon that are displayed in the custom application title bar by
changing the package definition file, MyVSShellStub.Application.pkgdef.
To customize the application name and icon
1. In the MyVSShellStub project, open \Shell Customization\MyVSShellStub.Application.pkgdef.
2. Change the
AppName
element value to "AppName"="Fabrikam Music Editor"
3. To change the application icon, copy a different icon to the
\MyVSShellStub\MyVSShellStub\MyVSShellStub\ directory. Rename the existing ApplicationIcon.ico file to
ApplicationIcon1.ico. Rename the new file to ApplicationIcon.ico.
4. Build the solution and start debugging. The isolated shell IDE appears. The title bar has your new icon next
to the words Fabrikam Music Editor.
Customizing the Default Web Browser Home Page
This section shows how to change the default home page of the Web Browser window by changing the package
definition file.
To customize the default Web Browser home page
1. In the MyVSShellStub.Application.pkgdef file, change the
"http://www.microsoft.com".
DefaultHomePage
element value to
2. Rebuild the MyVSShellStub project.
3. Build the solution and start debugging.
4. In View / Other Windows, click Web Browser. The Web Browser window displays the Microsoft
Corporation home page.
Removing the Print Command
The .vsct file in an isolated shell UI project consists of a set of declarations of the form
> , where Element is one of the standard Visual Studio menus and commands.
<Define name=No_
Element
If a declaration is uncommented, that menu or command is excluded from the isolated shell. Conversely, if a
declaration is commented, the menu or command is included in the isolated shell.
In the following steps, you uncomment print command in your .vsct file.
To remove the print command
1. Verify that the Print command appears on the File menu in the isolated shell application.
2. In the MyVSShellStubUI project, open \Resource Files\MyVSShellStubUI.vsct for editing.
3. Uncomment this line:
<!-- <Define name="No_PrintChildrenCommand"/> -->
4. This removes the print command.
5. Start debugging the isolated shell application. Verify that the File / Print command is gone.
Removing Features from the Isolated Shell
You can remove some of the packages that are loaded with Visual Studio by editing the .pkgundef file if you do
not want those features in your custom isolated shell application. You specify the package in one of the subkeys
of the $RootKey$\Packages registry key.
NOTE
To find the GUIDs of Visual Studio features, see Package GUIDs of Visual Studio Features.
The following procedure shows how to remove the XML editor from the isolated shell.
To remove the XML editor
1. Open the MyVSShellStub.pkgundef file in the Shell Customization folder of the MyVSShellStub project.
2. Uncomment the following line:
[$RootKey$\Packages\{87569308-4813-40a0-9cd0-d7a30838ca3f}]
3. Rebuild the solution and start debugging the isolated shell. Open an XML file,for example,
\MyVSShellStub\MyVSShellStub\MyVSShellStubUI\MyVSShellStubUI.vsct. Verify that the XML keywords
in the file are not colorized and that typing "<" on a line does not bring up XML tooltips.
Customizing the Help/About box
You can customize the Help/About box, which is created as part of the isolated shell project template.
To customize the company name
1. The company name, copyright information, product version, and product description are found in the
MyVSShellStub.AboutBoxPackage project, in the \Properties\AssemblyInfo.cs file. Open this file.
2. Change the AssemblyCompany value to Fabrikam, the AssemblyProduct and AssemblyTitle values to
Fabrikam Music Editor, and the AssemblyCopyright value to Copyright © Fabrikam 2015:
[assembly:
[assembly:
[assembly:
[assembly:
[assembly:
[assembly:
[assembly:
[assembly:
AssemblyTitle("Fabrikam Music Editor")]
AssemblyDescription("")]
AssemblyConfiguration("")]
AssemblyCompany("Fabrikam")]
AssemblyProduct("Fabrikam Music Editor")]
AssemblyCopyright("Copyright © Fabrikam 2015")] [assembly: AssemblyCompany("Fabrikam")]
AssemblyProduct("Fabrikam Music Editor ")]
AssemblyCopyright("Copyright © Fabrikam 2015")]
3. To add a description of the product, change the
Fabrikam Music editor.:
AssemblyDescription
value to The description of
[assembly: AssemblyDescription("The description of Fabrikam Music editor.")]
4. Start debugging and in the isolated shell application, open the Help / About box. You should see the
changed strings. The title of the Help/About box is the same as the AssemblyTitle value in
AssemblyInfo.cs.
5. The properties of the Help/About box itself are found in the
MyVSShellStub.AboutBoxPackage\AboutBox.xaml file. To change the width of the Help/About box, go to
the AboutDialogStyle block and set the Width property to 200:
<Style x:Key="AboutDialogStyle" TargetType="Window">
<Setter Property="Height" Value="Auto" />
<Setter Property="Width" Value="200" />
<Setter Property="ShowInTaskbar" Value="False" />
<Setter Property="ResizeMode" Value="NoResize" />
<Setter Property="WindowStyle" Value="SingleBorderWindow" />
<Setter Property="SizeToContent" Value="Height" />
</Style>
6. Rebuild the solution and start debugging the isolated shell. The Help/About box should be approximately
square.
Before You Deploy the Isolated Shell Application
Your isolated shell application can be installed on any computer that has the Visual Studio Shell (Isolated)
Redistributable Package. For more information about the redistributable package, see the Visual Studio
Extensibility Downloads website.
Deploying the Isolated Shell Application
You deploy your isolated shell application to a target computer by creating a setup project. You must specify
these things:
The layout of the folders and files on the target computer.
The launch conditions that guarantee that the .NET Framework and the Visual Studio shell runtime are
installed on the target computer.
In the following procedure you will need to install InstallShield Limited Edition on your computer.
To create the setup project
1. In Solution Explorer, right-click the solution node and then click Add New Project.
2. In the New Project dialog box, expand Other Project Types and then select Setup and Deployment.
Select the InstallShield template. Name the new project MySetup and then click OK.
3. If InstallShield Limited Edition is already installed, continue to the next step.
If InstallShield Limited Edition is not already installed, the InstallShield download page appears. Follow the
instructions to download and install the product, choosing the version of InstallShield that is compatible
with your version of Visual Studio. You must decide whether to register your installation of InstallShield or
use it as an evaluation. You must restart Visual Studio after you complete the installation.
IMPORTANT
You must start Visual Studio as an administrator before you create an InstallShield project. If you do not do so, you
will get an error when you build the project.
The next steps show how to configure the setup project.
IMPORTANT
Make sure that you have built the release configuration of your isolated shell project at least once before you configure the
setup project.
To configure the setup project
1. In the Solution Explorer, under the MySetup project, choose Project Assistant. On the bottom row of
the Project Assistant window, choose Application Information. Enter Fabrikam as your company
name and Fabrikam Music Editor as your application name. Choose the forward arrow at the bottom
right of the Project Assistant.
2. Select Yes under Does your application require any software to be installed on the machine? and
then select Microsoft .NET Framework 4.5 Full Package.
3. Choose the Application Files button at the bottom of the window, and make sure that the Fabrikam
Music Editor folder is selected.
4. Choose the Add Files button. In the Add Files dialog box, add the following files from the
MyVSShellStub\Release folder:
a. MyVSShellStub.exe.config
b. DebuggerProxy.dll
c. DebuggerProxy.dll.manifest
d. MyVSShellStub.pkgdef
e. MyVSShellStub.pkgundef
f. MyVSShellStub.winprf
g. Splash.bmp
5. Click the Add Project Outputs button and add MyVSShellStub/Primary Output. Click OK.
6. In the left pane, under Destination Computer, right-click the Fabrikam Music Editor [INSTALLDIR]
node and add a New Folder named Extensions.
7. Right-click the Extensions node in the left pane and add a new folder named Application.
8. Select the Application folder and click the Add Project Outputs button, then select the primary output
from the MyVSShellStub.AboutBoxPackage project.
9. Click the Add Files button and from the \MyVSShellStub\Release\Extensions\Application\ folder add the
following files:
MyVSShellStub.AboutBoxPackage.pkgdef
MyVSShellStub.Application.pkgdef
10. Right-click the Fabrikam Music Editor [INSTALLDIR] node in the left pane and add a new folder named
1033.
11. Select the 1033 folder and then click the Add Project Outputs button, and select the primary output from
the MyVSShellStubUI project.
12. Move to the Application Shortcuts window.
13. Click New to create a shortcut and select [ProgramFilesFolder]\Fabrikam\Fabrikam Music
Editor\MyVSShellStub.Primary Output.
14. Move to the Installation Interview pane.
15. Set all items to No.
16. In Solution Explorer, in the MySetup project, open Define Setup Requirements and Actions \
Requirements. The Requirements window opens.
17. Right click System Software Requirements and select Create New Launch Condition. The System
Search Wizard appears.
18. In the What do you want to find? pane, choose Registry Entry in the drop-down list and click Next.
19. In the How do you want to look for it? pane, select HKEY_LOCAL_MACHINE as the registry root. Enter
SOFTWARE\Wow6432Node\Microsoft\DevDiv\vs\Servicing\14.0\isoshell for 64-bit systems or
SOFTWARE\Microsoft\DevDiv\vs\Servicing\14.0\isoshell for 32-bit systems, and enter Install as the
registry value. Click Next.
20. In the What do you want to do with the value? pane, enter This product requires the Visual Studio
2015 Isolated Shell Redistributable to be installed. as the display text and click Finish.
21. Rebuild the isolated shell solution to create the setup project.
You can find the setup.exe file in the following folder:
\MyVSShellStub\MySetup\MySetup\Express\SingleImage\DiskImages\DISK1
Testing the Installation Program
To test the setup, copy the setup.exe file to a different computer and run the Setup executable. You should be able
to run the isolated shell application.
Customizing the Isolated Shell
10/20/2017 • 6 min to read • Edit Online
You can customize your Visual Studio isolated shell application by changing different aspects of the Visual Studio
user interface and by restricting the commands and features included in your specialized application.
Using the Application.pkgdef file
The isolated shell template solution includes a SolutionName.Application.pkgdef file that allows you to modify the
following features:
T h e applic at ion t it le
You can customize the application title, which is the name that is displayed in the title bar of the application, by
changing the value of the "AppName" row in the SolutionName.Application.pkgdef file. For more details, see
Walkthrough: Creating a Basic Isolated Shell Application.
If you do not want the application title to display the project that is currently loaded, change the value of the
"ShowHierarchyRootInTitle" row in the SolutionName.Application.pkgdef file from dword:00000001 to
dword:00000000.
T h e applic at ion ic on
You can customize the application icon, which is the icon that is displayed by the application name in the
application title bar. Copy a different icon to the icon directory. In Solution Explorer, add the icon to the Resource
Files folder. Then open the VSShellStub.rc file and replace the value of IDI_STUBPROGRAM with the name of the
new icon. For more details, see Walkthrough: Creating a Basic Isolated Shell Application.
T h e c om m an d-lin e logo
You can customize the command-line logo, which is the text that appears when the application is started from the
command line, by changing the value of the "CommandLineLogo" row in the SolutionName.Application.pkgdef
file. For more details, see Walkthrough: Creating a Basic Isolated Shell Application
T h e n a m e o f t h e u se r fi l e s su b fo l d e r
You can change the name of the folder your application maintains for user files by changing the value of the
"UserFilesSubFolderName" row in SolutionName.Application.pkgdef file.
T h e t i t l e o f t h e so l u t i o n t r e e n o d e i n t h e N e w P r o j e c t d i a l o g
You can customize the title of the solution node in the New Project dialog by changing the value of the
"NewProjDlgSlnTreeNodeTitle" row in the SolutionName.Application.pkgdef file.
T h e i n st a l l e d t e m p l a t e s h e a d e r i n t h e N e w P r o j e c t d i a l o g
You can change the installed templates header in the New Project dialog by changing the value of the
"NewProjDlgInstalledTemplatesHdr" row in the SolutionName.Application.pkgdef file.
W h e t h e r o r n o t t o h i d e M i sc e l l a n e o u s fi l e s b y d e fa u l t
You can specify whether or not to hide Miscellaneous files by default by changing the value of the
"HideMiscellaneousFilesByDefault" row in the SolutionName.Application.pkgdef file. To hide Miscellaneous files,
set the value dword:00000001 , and to show the files, set the value dword:00000000 .
W h e t h e r o r n o t t o d i sa b l e t h e o u t p u t w i n d o w
You can specify whether or not to disable the output window in your application by changing the value of the
"DisableOutputWindow" row in the SolutionName.Application.pkgdef file. To disable the output window, set the
value dword:00000001 , and to show the output window, set the value dword:00000000 .
W h e t h e r o r n o t t o a l l o w d r o p p e d fi l e s o n t h e m a i n w i n d o w
You can specify whether or not to allow dropped files on the main window in your application by changing the
value of the "AllowsDroppedFilesOnMainWindow" row in the SolutionName.Application.pkgdef file. To allow
dropped files, set the value
dword:00000001
, and to disallow dropped files, set the value
dword:00000000
.
T h e d e fa u l t se a r c h p a g e
You can customize the web browser page, which is page that is displayed when the web browser window is
opened, by changing the value of the "DefaultSearchPage" row in the SolutionName.Application.pkgdef file.
T h e d e fa u l t h o m e p a g e
You can customize the home page by changing the value of the "DefaultHomePage" row in the
SolutionName.Application.pkgdef file. For more details, see Walkthrough: Creating a Basic Isolated Shell
Application
W h e t h e r o r n o t t o h i d e t h e so l u t i o n c o n c e p t
You can specify whether or not to hide the solution in your application by changing the value of the
"HideSolutionConcept" row in the SolutionName.Application.pkgdef file. To hide the solution, set the value
dword:00000001 , and to show the solution, set the value dword:00000000 .
T h e d e fa u l t d e b u g e n g i n e
You can change the debug engine your application uses by changing the value of the "DefaultDebugEngine" row in
the SolutionName.Application.pkgdef file to the GUID of your debug engine.
T h e fi l e e x t e n si o n o f t h e u se r o p t i o n s fi l e
You can change the name of the folder your application maintains for user files by changing the value of the
"UserOptsFileExt" row in SolutionName.Application.pkgdef file.
T h e so l u t i o n fi l e e x t e n si o n
You can change the extension used for your solution files by changing the value of the "SolutionFileExt" row in the
SolutionName.Application.pkgdef file.
T h e d e fa u l t u se r fi l e s fo l d e r r o o t
You can change the name of the root folder of the user files for your application by changing the value of the
"UserFilesSubFolderName" row in the SolutionName.Application.pkgdef file.
T h e so l u t i o n fi l e c r e a t o r i d e n t i fi e r
You can change the identifier used for your solution files by changing the value of the
"SolutionFileCreatorIdentifier" row in the SolutionName.Application.pkgdef file.
T h e d e fa u l t p r o j e c t s l o c a t i o n
You can change the name of the default projects location by changing the value of the "DefaultProjectsLocation"
row in the SolutionName.Application.pkgdef file.
T h e applic at ion loc aliz at ion pac kage
You can change the localization package used for your application by changing the value of the
"AppLocalizationPackage" row in the SolutionName.Application.pkgdef file.
W h e t h e r o r n o t t o sh o w t h e h i e r a r c h y r o o t i n t h e t i t l e
You can specify whether or not to show the hierarchy root in the title bar in your application by changing the value
of the "ShowHierarchyRootInTitle" row in the SolutionName.Application.pkgdef file. To show the hierarchy root, set
the value dword:00000001 , and to hide the hierarchy root, set the value dword:00000000 .
Sp e c i fy i n g a st a r t p a g e
To specify a start page for your custom application, in the SolutionName.Application.pkgdef file, set the
"DisableStartPage" value to dword:00000000 , and under [$RootKey$\StartPage\Default] set the URI to the location
of the .xaml file:
DisableStartPage=dword:00000000
[$RootKey$\StartPage\Default]
"Uri"="$RootFolder$\<name of XAML file>"
In the Applicationcommands.vsct file in the SolutionNameUI project, comment out the
"No_ShellPkg_startPageCommand" entry:
<!--<Define name="No_ShellPkg_StartPageCommand"/>-->
You must add the .xaml file, and any graphics files you need, to the SolutionName project. These files must actually
be copied to the SolutionName project directory, not added from some other directory.
On all the files, set the Item Type property to Isolated Shell File in order for the files to be copied to the
$RootFolder$ directory. (To set the Item Type property, right-click the file and select Properties. This property is
found under Configuration Properties, General.)
For more information on customizing start pages, see Customizing the Start Page.
Using other elements of the isolated shell
You can use other files and projects that are included in the isolated shell solution template to further customize
your application.
En a b l e / d i sa b l e Vi su a l St u d i o p a c k a g e s
The SolutionName.pkgundef file allows you to disable certain kinds of Visual Studio functionality by excluding
certain packages. For example, the following line:
[$RootKey$\Projects\{A2FE74E1-B743-11d0-AE1A-00A0C90FFFC3}\AddItemTemplates\TemplateDirs\{39c9c826-8ef8-40798c95-428f5b1c323f}]
removes the Miscellaneous Files project from the set of project templates displayed in the New Project dialog. For
more details, see Walkthrough: Creating a Basic Isolated Shell Application.
En a b l e / d i sa b l e m e n u c o m m a n d s
The SolutionNameUI.vsct file includes a commented-out list of all the menu commands available to the isolated
shell. To disable a given command, uncomment the corresponding row. For example, to disable the Window/Split
comment, uncomment the <Define name="No_SplitCommand"/> row. For more details, see Walkthrough: Creating a
Basic Isolated Shell Application.
T h e b i t m a p u se d o n t h e sp l a sh sc r e e n
You can customize the bitmap used on the splash screen, which is the window that is displayed when the
application is started, by changing the value of the "SplashScreenBitmap" row in the
SolutionName.Application.pkgdef file. For more details, see Walkthrough: Creating a Basic Isolated Shell
Application.
T h e Hel p/A bo u t w i n do w
In the isolated shell template there is a separate project you can use to customize the Help/About box for your
application. For more details, see Walkthrough: Creating a Basic Isolated Shell Application.
Extending the Isolated Shell
10/20/2017 • 3 min to read • Edit Online
You can extend the Visual Studio isolated shell by adding a VSPackage, a Managed Extensibility Framework (MEF)
component part, or a generic VSIX project to your isolated shell application.
NOTE
The following steps presuppose that you have created a basic isolated shell application by using the Visual Studio Shell
Isolated project template. For more information about this project template, see Walkthrough: Creating a Basic Isolated Shell
Application.
Locations for the Visual Studio Package Project Template
The Visual Studio Package project template can be found in three different locations in the New Project dialog:
1. Under Visual Basic, Extensibility. The default language of the project is Visual Basic.
2. Under Visual C#, Extensibility. The default language of the project is C#.
3. Under Other Project Types, Extensibility. The default language of the project is C++.
Adding a VSPackage
You can add a VSPackage to your isolated shell application. The following steps show how to create one that adds
menu commands.
To add a new VSPackage
1. Add a Visual Studio Package project named
MenuCommandsPackage
.
2. On the Basic VSPackage Information page of the wizard, set Company name to
VSPackage name to FabrikamMenuCommands . Choose the Next button.
Fabrikam
and
3. On the next page, select Menu Command and then choose Next.
4. On the next page, set Command name to
and then choose Next.
Fabrikam Command
and Command ID to
cmdidFabrikamCommand
5. On the Select Test Project Options page, clear the test options, and then choose the Finish button.
6. In the ShellExtensionsVSIX project, open the source.extension.vsixmanifest file.
The Assets section should contain an entry for the VSShellStub.AboutBoxPackage project.
7. Choose the New button.
8. In the Add New Asset window, in the Type list, select Microsoft.VisualStudio.VsPackage.
9. In the Source list, make sure that A project in the current solution is selected. In the Project list box,
select MenuCommandsPackage.
10. Save and close the file.
11. Rebuild the solution and start debugging the isolated shell.
,
12. On the menu bar, choose Tools menu, then Fabrikam Command.
A message box should appear.
13. Stop debugging the application.
Adding a MEF Component Part
The following steps show how to add a MEF component part to your isolated shell application.
To add a MEF component
1. In the Add New Project dialog box, under Visual C#, Extensibility, use the Editor Margin template to
add a project. Name it ShellEditorMargin .
2. In the ShellExtensionsVSIX project, open the Source.extension.vsixmanifest file in the Design view, not the
Code view.
3. In the
Asset
section, choose Add Content.
4. In the Add New Asset window, in the Type list, select Microsoft.VisualStudio.MefComponent.
5. In the Source list, make sure that A project in the current solution is selected. In the Project list box,
select ShellEditorMargin.
6. Save and close the file.
7. Rebuild the solution and start debugging the isolated shell.
8. Open a text file.
A green margin that contains the words "Hello world!" should be displayed at the bottom of the text file
window.
9. Stop debugging the application.
Adding a Generic VSIX Project
To add a generic VSIX project
1. In the Add New Project dialog box, under Visual C#, Extensibility, use the VSIXProject template to add a
project. Name it EmptyVSIX .
2. In the ShellExtensionsVSIX project, open the Source.extensions.vsixmanifest file in the Design view, not the
Code view.
3. In the
Assets
section, choose New.
4. In the Add New Asset window, in the Type list, select the kind of content you want to add.
5. In Source, make sure that the A project in current solution option is selected. In the list box, select the
name of your VSIX project.
6. Save and close the file.
7. If this project includes compiled code, you must edit the project so that the assembly is included in the
output.
a. Unload the VSIX project and open the project file.
b. In the first
<PropertyGroup>
c. Save and reload the project.
block, change the value of
<CopyBuildOutputToOutputDirectory>
to
true
.
8. Build and run the solution.
See Also
Walkthrough: Creating a Basic Isolated Shell Application
Elements of the Isolated Shell
10/20/2017 • 3 min to read • Edit Online
You can modify the registry settings, run-time settings, and application entry point of your isolated shell
application, and its .vsct, .pkgdef, and.pkgundef files.
Registry Settings
Both the .pkgdef and the .pkgundef files modify the registry settings for the isolated shell application. When the
application is run, the registry settings are defined in the following sequence:
When the application is run, the registry settings are defined in the following sequence:
1. The registry key for the application is created.
2. The registry is updated from the .pkgdef file of the application by defining specified keys and entries.
3. For every package that is part of your application, the registry is updated from the .pkgdef file of that
package. Each package is defined in the .pkgdef file of the application by the $RootKey$\Packages\
{vsPackageGuid} key for the package.
4. The registry is updated from the AppEnvConfig.pkgdef and BaseConfig.pkgdef in the Visual Studio SDK
installation path\Common7\IDE\ShellExtensions\Platform directory. These files are part of Visual Studio and
also part of the Visual Studio Shell (isolated mode) redistributable package.
5. The registry is updated from the .pkgundef file of the application by removing specified keys and entries.
Run-Time Settings
When a user starts the isolated shell application, it calls the Start entry point of the Visual Studio shell. Application
settings are defined when your application starts, as follows:
1. The Visual Studio shell checks the application registry for specific keys. If the setting for a key is specified in
the call to the Start entry point, then that value overrides the value in the registry.
2. If neither the registry nor the entry point parameter specifies the value of a setting, then the default value for
the setting is used.
When a user starts your application from the command line, all command-line switches are passed to the
Visual Studio shell, which treats them in the same way that Devenv does. For more information about
Devenv switches, see Devenv Command Line Switches and Devenv Command-Line Switches for VSPackage
Development. For more information about how a package registers for command line switches, see Adding
Command-Line Switches.
The Start Entry Point
The Appenvstub.dll file contains entry points for accessing the isolated shell. When the application starts, it calls the
Start entry point of Appenvstub.dll.
You can change the behavior of the application by changing the value of the last parameter that is passed to the
Start entry point. For more information, see Isolated Shell Entry Point Parameters (C++).
The .Vsct File
The .vsct file lets you specify which standard Visual Studio UI elements are available in the application. For more
information, see .Vsct Files.
The .Pkgundef File
When the application is installed on a computer on which Visual Studio is already installed, a copy of the Visual
Studio registry entries is made for the application. By default, the application uses VSPackages that are already
installed on the computer. The .pkgundef file lets you exclude registry entries in order to remove specific elements
of the Visual Studio shell or extensions from the application. For more information, see .Pkgundef Files.
The .pkgundef file lets you exclude registry entries in order to remove specific elements of the Visual Studio shell or
extensions from the application. For more information, see .Pkgundef Files.
The set of package GUIDs that you can exclude are listed in Package GUIDs of Visual Studio Features.
The .Pkgdef File
The .pkgdef file lets you define registry entries for the application that are set when the application is installed. For
a description of the .pkgdef file and a list of registry entries that the Visual Studio shell uses, see .Pkgdef Files.
Substitution Strings
The substitution strings used in the .pkgdef and .pkgundef files are listed in Substitution Strings Used in .Pkgdef
and .Pkgundef Files.
Other Settings
If your isolated shell application depends on Microsoft.VisualStudio.GraphModel.dll, you need to add the following
binding redirect to your Isolated Shell application's .config file:
<dependentAssembly>
<assemblyIdentity name="Microsoft.VisualStudio.GraphModel" publicKeyToken="b03f5f7f11d50a3a"
culture="neutral" />
<bindingRedirect oldVersion="11.0.0.0" newVersion="12.0.0.0"/>
</dependentAssembly>
Modifying the Isolated Shell By Using the .Vsct File
10/20/2017 • 1 min to read • Edit Online
The UI project for a Visual Studio isolated shell project contains a .vsct file that lets you specify which application
groups and individual commands are available in the application. The following is an excerpt from an unmodified
.vsct file.
<!-<!-<!-<!--
<Define
<Define
<Define
<Define
name="No_WindowListCommand"/> -->
name="No_MoreWindowsCommand"/> -->
name="No_PaneNextPaneCommand"/> -->
name="No_PanePrevPaneCommand"/> -->
By default, most commands and command groups are included. To exclude a command or command group, simply
uncomment that command or group.
For example, to remove the next pane and previous pane commands, uncomment the
No_PanePrevPaneCommand entries:
No_PaneNextPaneCommand
and
<Define name="No_PaneNextPaneCommand"/> <Define name="No_PanePrevPaneCommand"/>
For a more detailed example these customizations, see Walkthrough: Creating a Basic Isolated Shell Application.
Referenced Files
The default .vsct file for an application references the following files. These files are located in the
\VisualStudioIntegration\Common\Inc\ subdirectory of the Visual Studio SDK installation directory.
FILE
DESCRIPTION
wbids.h
UI identities for the Web Browse package.
AppIDCmdUsed.vsct
Command table for primary Visual Studio UI elements.
EmulatorCmdUsed.vsct
Command table for Emacs and Brief editor emulation UI
elements.
Vsdebugguids.h
Defines the GUIDs of the commands, options page, and other
features of the Visual Studio debugger.
VsDbgCmdUsed.vsct
Command table for the debugger.
The AppIDCmdUsed.vsct file includes Visual Studio UI elements based on the symbols defined in the application
.vsct file.
For more information, see Designing XML Command Table (.Vsct) Files and the VSCT XML Schema Reference.
See Also
Visual Studio Isolated Shell
Modifying the Isolated Shell By Using the .Pkgundef
File
10/20/2017 • 1 min to read • Edit Online
You can modify the .pkgundef file to exclude specified registry entries from an isolated shell application. Typically,
the first time an application is started on a computer, the Visual Studio shell copies the existing Visual Studio
registry entries to the root registry key for the application. This includes any references to currently installed
VSPackages.
To exclude a specific registry entry from an isolated shell application, add to the application .pkgundef file the
package key followed by the entry. Keys and entries are represented just as in the .pkgdef file; that is, as
[$RootKey$] or [$RootKey$\subkey] and "entry"=value, where subkey is the subkey to affect, entry is the entry to
remove, and value is either "" or dword:00000000 .
To exclude multiple entries from a registry key, just list the key one time, followed by a line for each entry to
exclude.
To exclude a whole registry key from an isolated shell application, add the key to the application .pkgundef file but
do not specify any registry entries for that key.
You can add comments to the .pkgundef file. A single-line comment must have two slashes as the first two
characters.
For example, to remove the Connect to Database and Connect to Serve r commands on the Tools menu, you
can uncomment the line:
[$RootKey$\Packages\{8D8529D3-625D-4496-8354-3DAD630ECC1B}]
and add the line:
[$RootKey$\Packages\{198E76C1-34C0-424D-9957-B3EBD80265FB}]
to the application's .pkgundef file.
See Also
Package GUIDs of Visual Studio Features
Customizing the Isolated Shell
Modifying the Isolated Shell By Using the .Pkgdef File
10/20/2017 • 10 min to read • Edit Online
The .pkgdef file supports settings that you can use to customize an isolated shell application. It specifies values that are created when an
application is installed on a computer and that are referenced by the Visual Studio shell when it starts the application. The settings are
organized in the file based on the applicable registry keys.
WARNING
Note that .pkgdef files that are not declared in the .vsixmanifest file of the VSPackage are not scanned when Visual Studio starts.
The .pkgdef file contains sections that are each identified by a key, either
root key for the application.
Each section contains name/value pairs that have the following format:
[$RootKey$]
"
ValueName
or
"=
[$RootKey$\
subkey ] , where $RootKey$ is the
Value.
Values are either a string that is enclosed in quotes, or a 32-bit integer that is represented as a dword. Values have the following
constraints:
All dword values are in hexadecimal format, for example
dword:00000001
.
For boolean values, 1 represents true, and 0 represents false.
All GUID strings are in registry format, for example,
"{00000000-0000-0000-0000-000000000000}"
.
All localizable resource identifiers have the form "@resourceID" or "#resourceID", where resourceID is the resource identifier in the
application UI package, for example, "@102" . The application UI package is the package that is referenced in the
AppLocalizationPackage setting.
For example,
"HideSolutionConcept"=dword:00000001
"DefaultDebugEngine"="{00000000-0000-0000-0000-000000000000}"
You can add comments to the .pkgdef file. A single-line comment has two slashes as the first two characters.
For a list of the substitution strings, see Substitution Strings Used in .Pkgdef and .Pkgundef Files.
The following sections describe specific registry values that affect the behavior of the Visual Studio shell in isolated mode. You can also
define additional registry values for the application in this file.
NOTE
If a setting is not provided in the .pkgdef file, then no corresponding entry is made in the registry.
Settings
The following table describes the values defined under [$RootKey$].
NAME
TYPE
VALUE
AddinsAllowed
dword
True if add-ins can be loaded; otherwise, false.
The default value is true.
NAME
TYPE
VALUE
AllowsDroppedFilesOnMainWindow
dword
True if the main window can accept dropped
files; otherwise, false. Files dropped on the main
window are opened by using the
OpenDocumentViaProject method. This is
equivalent to opening a document by using the
Open command on the File menu in the
application.
The default value is true.
AppIcon
string
The full path of the program icon. This icon
appears in the title bar to the left of the
application name.
The default value is
"$RootFolder$\solutionName.ico", where
solutionName is the name of the application
solution file.
AppLocalizationPackage
string
The GUID of the VSPackage that contains the UI
satellite assembly for the application. This
VSPackage includes a compiled version of the
.vsct file and can include other localized strings.
Feature sets and menu command groups can be
enabled or disabled by changing the settings in
the UI project .vsct file.
The default value is "{vsUiPackageGuid}", where
vsUiPackageGuid is the GUID assigned to the
application UI package.
AppName
string
The name of the application. The name appears
in the title bar of the application window.
The default value is the name of the application
solution file.
CommandLineLogo
string
The banner text when the application is run in a
console window. This setting affects only
applications that support command-line build
operations.
The default value is
"companyNamesolutionName Version 1.0.",
where companyName is the name of the
company provided when Windows was installed,
and solutionName is the name of the
application solution file.
DefaultDebugEngine
string
The GUID of the default debug engine to use
for the application.
Note: An empty GUID (all zeros) indicates that
the application does not specify a default debug
engine. This enables the debugger to select the
debug engine to use.
The default value is "{00000000-0000-00000000-000000000000}".
NAME
TYPE
VALUE
DefaultHomePage
string
The default home page URL for the internal
Web browser window.
If the Home page option is available in the
application, then this setting also affects the
default state of the option. For more
information, see Web Browser, Environment,
Options Dialog Box.
The default value is the URL of the company
provided when Windows was installed.
DefaultProjectsLocation
string
The full path of the default projects folder. For
example,
"DefaultProjectsLocation"="$MyDocuments$\MyVSShellStub\Pro
If the Visual Studio projects location option is
available in the application, then this setting also
affects the default state of the option. For more
information, see NIB: General, Projects and
Solutions, Options Dialog Box.
The default value is
"$MyDocuments$\solutionName", where
solutionName is the name of the application
solution file.
DefaultSearchPage
string
The default search page URL for the internal
Web browser window.
If the Search page option is available in the
application, then this setting also affects the
default state of the option. For more
information, see Web Browser, Environment,
Options Dialog Box.
The default value is "http://search.live.com".
DefaultUserFilesFolderRoot
string
The name of the user folder, relative to the
current user's My Documents folder.
The default value is the name of the application
solution file.
DisableOutputWindow
dword
Indicates whether the isolated shell should treat
the output window as disabled.
If this value is set to true, Visual Studio does not
display the solution build manager output in the
Output window and hides the Show Output
window when build starts check box in the
Projects and Solutions category in the
Options dialog box.
The default value is false.
HideMiscellaneousFilesByDefault
dword
True to hide the Miscellaneous Files folder by
default in Solution Explorer; otherwise, false.
If the Show Miscellaneous files in Solution
Explorer option is available in the application,
then this setting also affects the default state of
the option. For more information, see
Documents, Environment, Options Dialog Box.
The default value is false.
NAME
TYPE
VALUE
HideSolutionConcept
dword
True to create all projects as stand-alone
projects and hide the solution and solutionrelated commands for stand-alone projects by
default; otherwise, false.
If the Always show solution option is available
in the application, then this setting also affects
the default state of the option. For more
information, see NIB: General, Projects and
Solutions, Options Dialog Box.
The default value is false.
NewProjDlgInstalledTemplatesHdr
string
The name for the Visual Studio nstalled
templates header in the Templates list in the
New Project dialog box. This is either a string
or a localizable resource identifier that is loaded
from the application UI package.
The default value is "solutionName installed
templates", where solutionName is the name of
the application solution file.
NewProjDlgSlnTreeNodeTitle
string
The name for the Visual Studio Solutions node
in the Project types tree in the New Project
dialog box. This is either a string or a localizable
resource identifier that is loaded from the
application UI package.
The default value is "solutionName installed
templates", where solutionName is the name of
the application solution file.
SolutionFileCreatorIdentifier
string
The application identifier, which appears as the
second line in the solution files that are
generated by the application. This line indicates
the application that created the file. By
convention, this value includes both the name
of the application and the application version
number. For example,
"SolutionFileCreatorIdentifier"="MyVSShellStub
Solution File, Format Version 10.00"
The VSLauncher.exe program, which is the
default program for opening a Visual Studio
solution file, uses this second line to determine
the version of Visual Studio in which to open
the solution file. The application would require
its own launcher to handle its associated
solution files. The launcher could also use this
second line in the solution file to determine in
which version of the application to open the
solution.
Note: The Visual Studio VSLauncher.exe
program does not handle .sln files that were
created by an isolated shell application.
The default value is "solutionName Solution File,
Format Version 10.00", where solutionName is
the name of the application solution file.
SolutionFileExt
string
The solution filename extension for the
application. We recommend that you choose a
unique filename extension (not.sln).
The default value is "solutionName_sln", where
solutionName is the name of the application
solution file.
NAME
TYPE
VALUE
SplashScreenBitmap
string
The full path of the bitmap file for the splash
screen for the application.
The default value is "$RootFolder$\Splash.bmp".
ThisVersionDTECLSID
string
The class identifier (CLSID) of the automation
object for the application.
The application automation object is the toplevel object for the application in the Visual
Studio shell automation model and implements
the EnvDTE._DTE interface.
If the application automation object is correctly
registered under the
HKEY_CLASSES_ROOT\CLSID registry key, then
you can use the
CComPtrBase::CoCreateInstance function to
directly create an instance of the application.
The Visual Studio shell uses this CLSID to
register the application automation object in the
Running Object Table (ROT) by using the
ACTIVEOBJECT_WEAK flag. This lets you use the
GetActiveObjectfunction to retrieve a pointer to
a running instance of the application. In
addition, if you define a ProgID for the
application automation object, then the Visual
Studio shell also registers each instance of the
application in the ROT by using an item moniker
of the form progID:processID, where progID is
the ProgID of the application automation object,
and processID is the process identifier for that
instance of the application. For example, if you
create a moniker as follows:
CreateItemMoniker(L"!",
instanceString
, &instanceMoniker)
where instanceString is the
progID:processID string. then you could use
instanceMoniker with the ROT GetObject
function to get the instance.
If the ThisVersionDTECLSID setting is omitted,
then the application is not exposed through the
Component Object Model (COM). In this case,
an instance of the application cannot be created
by calling the CComPtrBase::CoCreateInstance
function and cannot be registered in the ROT.
Each version of a VSPackage must have a
different CLSID.
The default value is the GUID that Visual Studio
generated for the automation object of the
application.
NAME
TYPE
VALUE
ThisVersionSolutionCLSID
string
The CLSID of the solution object for the
application.
The solution automation object contains
information about the current open solution in
an instance of the application and implements
the EnvDTE._Solution interface.
If the solution automation object is correctly
registered under the
HKEY_CLASSES_ROOT\CLSID registry key, then
you can use the
CComPtrBase::CoCreateInstance function to
directly create a solution object for the
application.
The Visual Studio shell uses this CLSID to
register the solution automation object in the
ROT by using the ACTIVEOBJECT_WEAK flag.
If this setting is omitted, then the solution class
is not registered with the Component Object
Model (COM), and a solution object cannot be
created by calling the
CComPtrBase::CoCreateInstance function and
cannot be registered in the ROT.
The default value is a GUID that Visual Studio
generated for the solution object of the
application.
UserFilesSubFolderName
string
The name of the subfolder under the user's My
Documents folder in which the application
creates user files and subfolders.
The default value is the name of the application
solution file.
UserOptsFileExt
string
The extension for solution user options files for
the application.
The default value is the name of the application
solution file.
Binding Path Settings
The [$RootKey$\BindingPaths\{00000000-0000-0000-0000-000000000000}] key contains the list of directories that the shell checks for
assemblies. These directories are added to the list of directories that the shell probes for private assemblies for the application.
By default, no binding-path entries are added to the .pkgdef file. However, the following subdirectories of the Visual Studio installation
directory are automatically added to the application binding-path list in the registry.
Common7\IDE\
Common7\IDE\\PrivateAssemblies
Common7\IDE\\PublicAssemblies
To add a directory to the binding path, add an entry of the form "directoryName"="", where directoryName is an absolute path.
For example,
[$RootKey$\BindingPaths\{00000000-0000-0000-0000-000000000000}]
"$RootFolder$\directory1"=""
"%CommonProgramFiles%\directory2"=""
Profile Settings
The following table describes the values that are defined for each associated package under [$RootKey$\Profile].
NAME
TYPE
VALUE
AutoSaveFile
string
The directory in which the application stores
auto-save files.
The default value is
"$RootFolder$\Profiles\CurrentSettings.vssetting
s".
Package Satellite DLL Settings
The following table describes the values that are defined under [$RootKey$\Packages\{vsPackageGuid}\SatelliteDll] for the satellite DLL
of each associated package, where vsPackageGuid is the GUID of the associated package.
NAME
TYPE
VALUE
DllName
string
The file name of the DLL.
The default value is "solutionNameui.dll", where
solutionName is the name of the application
solution file.
Path
string
The directory that contains the satellite DLL.
The default value is "$PackageFolder$".
Package Menu Item Settings
The [$RootKey$\Menus] registry key defines UI resource files for the application.
Menu item values have the form "{vsUiPackageGuid}"=", resourceId, versionNumber", where vsUiPackageGuid is the GUID of the
application UI package, resourceId is the resource identifier of the CTMENU resource that contains the UI elements, and versionNumber
is a virtual version number for the CTMENU resource. For more information, see Registering Interop Assembly Command Handlers.
By default, a menu item entry is created in the .pkgdef file for the application UI package.
For each package that provides menu items and that is distributed as a part of the application, add a menu item entry for the package.
See Also
Customizing the Isolated Shell
.Pkgundef Files
Substitution Strings Used in .Pkgdef and .Pkgundef
Files
10/20/2017 • 1 min to read • Edit Online
You can use the substitution strings listed below in the .pkgdef and .pkgundef files you define for your Visual
Studio isolated shell application.
Substitution strings
STRING
DESCRIPTION
$=RegistryEntry$
The value of the RegistryEntry entry. If the registry entry
string ends in a backslash (\), then the default value of the
registry subkey is used. For example, the substitution string
$=HKEY_CURRENT_USER\Environment\TEMP$ is expanded to
the temporary folder of the current user.
$AppName$
The qualified name of the application that is passed to the
AppEnv.dll entry points. The qualified name consists of the
application name, an underscore, and the class identifier
(CLSID) of the application automation object, which is also
recorded as the value of the ThisVersionDTECLSID setting in
the project .pkgdef file.
$AppDataLocalFolder
The subfolder under %LOCALAPPDATA% for this application.
$BaseInstallDir$
The full path of the location where Visual Studio was installed.
$CommonFiles$
The value of the %CommonProgramFiles% environment
variable.
$MyDocuments$
The full path of the My Documents folder of the current user.
$PackageFolder$
The full path of the directory that contains the package
assembly files for the application.
$ProgramFiles$
The value of the %ProgramFiles% environment variable.
$RootFolder$
The full path of the root directory of the application.
STRING
DESCRIPTION
$RootKey$
The root registry key for the application. By default the root is
in
HKEY_CURRENT_USER\Software\CompanyName\ProjectName
\VersionNumber (when the application is running, _Config is
appended to this key). It is set by the RegistryRoot value in
the SolutionName.pkgdef file.
The $RootKey$ string can be used to retrieve a registry value
under the application subkey. For example, the string
"$=$RootKey$\AppIcon$" will return the value of the AppIcon
entry under the application root subkey.
The parser processes the .pkgdef file sequentially, and can
access a registry entry under the application subkey only if the
entry has been previously defined
$ShellFolder$
The full path of the location where Visual Studio was installed.
$System$
The Windows\system32 folder.
$WINDIR$
The Windows folder.
If the parser does not recognize the substitution string or it cannot determine the value of a registry entry or an
environment variable, then it does not perform substitution on that part of the string.
Isolated Shell Entry Point Parameters (C++)
10/20/2017 • 1 min to read • Edit Online
When a Visual Studio shell-based application starts, it calls the Start entry point of the Visual Studio shell. The
following settings can be overridden in the call to the Start entry point of the shell. For a description of each setting,
see .Pkgdef Files.
AddinsAllowed
AllowsDroppedFilesOnMainWindow
AppName
CommandLineLogo
DefaultHomePage
DefaultProjectsLocation
DefaultSearchPage
DefaultUserFilesFolderRoot
DisableOutputWindow
HideMiscellaneousFilesByDefault
HideSolutionConcept
NewProjDlgInstalledTemplatesHdr
NewProjDlgSlnTreeNodeTitle
SolutionFileCreatorIdentifier
SolutionFileExt
UserFilesSubFolderName
UserOptsFileExt
The Visual Studio Shell Isolated template creates a source file, solutionName.cpp, where solutionName is the
solution name for the application. This file defines the main entry point for the application, the _tWinMain
function. This function invokes the Start entry point of the shell.
You can change the behavior of the application by changing these settings when the application starts.
Parameters
The Start entry point of the Visual Studio shell defines five parameters. Do not change the first four parameters. The
fifth parameter takes a settings override list. The Start entry point of the shell is called from the main entry point of
an application.
The Start entry point of the shell has the following signature.
typedef int (__cdecl *STARTFCN)(LPSTR, LPWSTR, int, GUID *, WCHAR *pszSettings);
If you do not want to override any application settings, leave the value of the settings override parameter as a null
pointer.
To override one or more settings, pass a Unicode string that contains the settings to be overridden. The string is a
semicolon-separated list of name-value pairs. Each pair contains the name of the setting to override, followed by an
equal sign (=), followed by the value to apply to the setting.
NOTE
Do not include whitespace in the Unicode strings.
For boolean settings, the following strings represent the value true; all other strings represent the value false. These
strings are case-insensitive.
+
1
-1
on
true
yes
Example
To disable add-ins and change the default projects location for your application, you can set the last parameter to
"AddinsAllowed=false;DefaultProjectsLocation=%USERPROFILE%\temp".
See Also
Customizing the Isolated Shell
.Pkgdef Files
Package GUIDs of Visual Studio Features
10/20/2017 • 2 min to read • Edit Online
You can use the following GUIDs in the .pkgundef file of your isolated shell application to exclude specific packages
from the application.
Package GUIDs
FEATURE AREA
RAW PACKAGE NAME
PACKAGE GUID
Core IDE
Undo Package
{1D76B2E0-F11B-11D2-AFC300105A9991EF}
Visual Studio Environment Package
{DA9FB551-C724-11d0-AE1F00A0C90FFFC3}
Visual Studio Commands Definition
Package
{44E07B02-29A5-11D3-B88200C04F79F802}
Visual Studio Directory Listing Package
{5010C52F-44AB-4051-8CE1D36C20D989B4}
Visual Studio Common IDE Package
{6E87CFAD-6C05-4ADF-9CD73B7943875B7C}
Visual Studio Environment Menu
Package
{715F10EB-9E99-11D2-BFC200C04F990235}
Visual Studio COM+ Library Manager
Package
{ED8979BC-B02F-4dA9-A667D3256C36220A}
Visual Studio Source Control
Integration Package
{53544C4D-E3F8-4AA0-81958A8D16019423}
Visual Studio Solution Build Package
{282BD676-8B5B-11D0-8A3400A0C91E2ACD}
Text Management Package
{F5E7E720-1401-11d1-883B0000F87579D2}
Visual Studio VsSettings Package
{F74C5077-D848-4630-80C9B00E68A1CA0C}
Help
Visual Studio Help Package
{4A791146-19E4-11D3-B86B00C04F79F802}
Task List, Error List
ErrorListPackage
{4A9B7E50-AA16-11D0-A8C500A0C921A4D2}
Class Outline
Class Outline Package
{21AF45B0-FFA5-11D0-G63F00A0C922E851}
FEATURE AREA
RAW PACKAGE NAME
PACKAGE GUID
Toolbox Controls Installer
Toolbox Controls Installer Package
{2C298B35-07DA-45F1-96A3BE55D91C8d7A}
Web Projects
Microsoft.VisualStudio.Web
{349C5850-65DF-11DA-938400065B846F21}
Visual Web Developer Project System
Package
{39C9C826-8EF8-4079-8C95428F5B1C323F}
Visual Web Developer Project
Persistence Package
{8FF02D1A-C177-4AC8-A62F88FC6EA65F57}
Visual Web Developer Web Migration
Package
{C1DAB116-2D63-493A-B97010D7DD0B476E}
Visual Web Developer Web Package
{E7f851C8-6267-4794-B0FE7BCAB6DACBB4}
Visual Web Developer Web
{DC7F691A-91FC-4F7B-923EFE829C3A18DC}
Visual Studio HTM Editor Package
{1B437D20-F8FE-11D2-A6AE00104BCC7269}
Visual Web Developer HTML Source
Editor Package
{BFCC0C3C-6F87-4285-A6C8BB616061800D}
CSS Editor
Visual Studio CSS Editing Package
{A764E895-518D-11d2-9A8900C04F79EFC3}
XML Editor
Visual Studio XML Editor Package
{87569308-4813-40A0-9CD0D7A30838CA3F}
Web Browser
Visual Studio Web Browser Package
{E8B06F41-6D01-11D2-AA7D00C04F990343}
Web Application Project Factory, for
View in Browser functionality
{349C5851-65DF-11DA-938400065B846F21}
Binary Editor
Visual Studio Binary Editor Package
{5B98C2C0-CD7B-11D0-92DF00A0C9138C45}
Windows Forms Designer
Windows Forms Designer Hosting
Package
{68939055-38E0-4D17-92CB8909710D8178}
Windows Forms Designer Package
{7494682B-37A0-11D2-A27300C04F8EF4FF}
Windows Forms Designer Resources
Package
{7B5D447B-0B12-41EA-A84EC822034422D4}
Windows Forms Application
Configuration Package
{80C7728B-70A6-4528-866973E02D1B9C41}
HTML Editor
FEATURE AREA
RAW PACKAGE NAME
PACKAGE GUID
ElementHost Designer Package
{7EAB3C71-59FF-4571-A5F3643F255FC2E6}
Debugger UI
Visual Studio Debugger
{C9DD4A57-47FB-11D2-83E700C04F9902C1}
Database Tools
Visual Database Tools Package
{220A4C17-7E7C-4663-BBCC5E607C6543CD}
Visual Studio Database Tools Designers
{EF828E39-70F5-4b8e-A3A04C0ECD28A69A}
Visual Studio Data Designers
{D6C919AA-1217-41E2-a13B9B92E1866305}
Visual Studio Data Package
{E1AA7737-69BE-43d0-A425E3097651E192}
Visual Studio Data Designer Extensibility
Package
{A8F602E2-40CE-4dAF-AE82A457A91728B9}
Visual Studio Explorers and Designers
Package
{8D8529D3-625D-4496-83543DAD630ECC1B}
Microsoft Report Designer
{F3A96850-E2AE-4E00-92788FE23F225A0D}
CommonModelingPackage
{D1091694-EA72-4BDD-891878324CC25448}
Microsoft.VisualStudio.TextTemplating
{A9696DE6-E209-414D-BBECA0506fb0E924}
Visual SourceSafe Provider Package
{AA8EB8CD-7A51-11D0-92C300A0C9138C45}
Visual SourceSafe Provider Stub
Package
{53544C4D-B03D-4209-A7D0D9DD13A4019B}
WPFFlavor.WPFPackage
{B3BAE735-386C-4030-8329EF48EEDA4036}
XamlDesignerPackage
{512be089-83ec-4cc6-8483cf16565ae209}
XamlLanguagePackage
{2ef1ec52-c8bf-4fe0-8eceba9c0d5d1603}
XamlDiagnosticsPackage
{8291c340-36b8-4c91-8c40cce75398ff75}
Visual Studio Code Snippets Package
{0B680757-2C29-4531-80FA535A5178AA98}
DSL Runtime
SourceSafe Support
WPF Designer
Code Snippets
FEATURE AREA
RAW PACKAGE NAME
PACKAGE GUID
Managed Language Project Support
Visual Studio Component Enumerator
{588205E0-66e0-11D3-860000C04F6123B3}
Visual Studio Settings and Project
Designers Package
{67909B06-91E9-4F3E-AB50495046BE9A9A}
Export Template Package
{F1E4CFCA-4573-4345-87187BDE2b1F0BE8}
Export Template...
Some packages should never be removed because many other features take dependencies on them. For example,
the ones listed under "Core IDE" should never be removed.
Some features cannot be completely removed. For example, there is no package that can be unregistered to
remove Class View and its associated menus, options, and services. The Class View window is provided by the
Visual Studio Environment Package, which also provides other key IDE features. If you wanted to remove Class
View, you'd also have to remove Find and Replace, the environment Options pages, the Command Window,
and the Output window.
Visual Studio Shell (Integrated)
10/20/2017 • 4 min to read • Edit Online
The Visual Studio integrated shell includes the integrated development environment (IDE), debugger, and source
control integration. No programming language is included. However, the integrated shell does provide a
framework that allows you to add programming languages.
The Visual Studio integrated shell is actually a combination of the Visual Studio isolated shell plus an additional
install which include integrated shell specific components. Your integrated shell application should include both the
isolated shell redistributable package from Microsoft Visual Studio Shell (Isolated) Redistributable Package as well
as the integrated shell redistributable package from Microsoft Visual Studio Shell (Integrated) Redistributable
Package.
NOTE
Before you can access the isolated and integrated shell redistributable packages, you will be asked to fill out a brief customer
survey. After filling out the survey, you'll be directed to a Visual Studio Connect page with redistributable package download
links. You can find the download links on subsequent visits to the Visual Studio Connect site under the PROGRAMS |
VISUAL STUDIO 2015 INTEGRATED AND ISOLATED SHELL tab.
If you install your integrated shell application on the same computer as a full version of Visual Studio, your
application's components will be integrated directly into Visual Studio.
Features in the Integrated Shell
Feature Area
Feature
Language Support
- None
IDE
Settings
Create settings
Import and export settings
Reset settings
Toolbox integration
Task List integration
Help integration
Options dialog box
Fonts and colors management
Output window
Command window
Window management
Commands, menus, and key bindings
Domain-specific language (DSL) runtime
Project System and Project Types
- Solutions and solution folders
- Solution configuration manager
- Item management
- Single-project and multi-project solutions
- Application Designer (simplified project properties)
- Add Web Reference
- Add Service Reference
- Single-project
- Web site project types
- Web application projects
Build
- Custom build steps in IDE
- Pre-compilation for intellectual property (IP) protection
- Code signing
MSBuild
Editor
- Code browsing tools (unified find, source definition,
inheritance)
- Code navigation
- IntelliSense
- SmartTags
- Refactoring
- Pretty listing
- IntelliSense filtering
- Code Definition window
Designer
- Windows Presentation Foundation Designer
- Windows Forms Designer
- Web Designer and HTML Editor
Data
- Server Explorer (Simplified: data only). See Note 1.
- Data Sources window
- Full set of data controls
- XML Editor
- Data bind to local data source (.MDF or .MDB)
- Data bind to object
- Data bind to Web service
- Data bind to local database server
- Data bind to remote database server
- DDL tools for remote data
- Server Explorer extensibility (Visual Studio SDK samples)
Debugger
- Local debugging. See Note 2.
- Managed debugging
- Local debugging
- Attach to local process
- Attach to remote process
- Anonymous delegate
- Application domains
- ASPX Debugging
- Attributes
- Break during Func-eval
- Breakpoints
- Breakpoint constraints
- Callstack
- Command window
- Cross-thread debugging
- Data Tips
- Data visualizer
- Debugger support for managed debugging assistants
(MDAs)
- Debugger support for type forwarder
- DTEEvents support for OTB
- JMC Stepper
- Debugger AppID test (DBGCLR)
- Debugger profile
- Debugger tools and options
- Debugging iterator
- Design-time expression evaluation
- C# Expression Evaluator
- Disassembly
- Edit and Continue
- Expression evaluator windows (Watch, Locals, Autos)
- Exception Helper
- Exceptions
- Execution
- Generics
- Getting right source
- HPC/Cluster debugging
- Integrated multi-language debugging
- InterOp debugging
- Just-in-time debugging
- Local debugging
- Managed debugging
- Manual control (Processes window)
- Memory
- MiniDump support
- Modules
- Multi-process debugging
- Native debugging
- New debug engine support
- Optimized code debugging
- Output windows filtering
- Process hosting for managed debugging
- Processes
- Quickwatch
- Registers
- Registers in stack
- Remote debugging
- Return values
- Script debugging
- Source service support
- Security
- Side-by-side
- SQL
- Symbol server
- Trace points
- Thread
- Visualizations
- Extensible Stylesheet Language Transformations (XSLT)
debugger
64-bit Support
- 64-bit debugging for both managed and native code, all
languages
- x64 native support
Source Code Control (SCC)
- Basic SCC integration. See Note 3.
- Tools and options verification
Extensibility
- Consume VSPackages and MEF components
Notes
1. Data Tools
The integrated shell includes database development tools such as data extensibility support and the simplified
Solution Explorer. However, SQL Server Express, SQL Reporting, and Crystal Reports are not included in the
integrated shell.
2. Debugging Support
The integrated shell includes the same debugging engine that is included in the Community version of Visual
Studio. The debugging engine includes the common debugger for managed code, and also related features, such
as Run, Attach, Set Breakpoint, Edit and Continue, and others. However, the debugging engine does not support
SQL Server database debugging.
Although support for native debugging is included in the basic debugger package, you cannot extend it to support
additional languages.
3. Source Code Control Integration
The integrated shell provides APIs for implementing source-code control (SCC) and for providing the MSSCCIbased common source control integration components.
Although SCC integration is not a regular feature of the Pro edition of Visual Studio, SCC integration is provided in
the integrated shell.
4. Build Support
The integrated shell provides build support. You can find information about builds in the MSBuild Reference.
Features Not Included in the Integrated Shell
The following is a list of features that are not included in the integrated shell:
Class Designer
PreEmptive Protection - Dotfuscator
Language features
VSHost
No Visual Studio languages or their associated project templates or project item templates, are included in
the integrated shell. No language-specific implementations of other features are included, for example
Visual Basic code snippets.
See Also
Visual Studio SDK
Distributing Isolated Shell Applications
10/20/2017 • 1 min to read • Edit Online
You must install Visual Studio and the Visual Studio SDK in order to create an isolated shell application. To
distribute the application to the machines of other users or customers, you must include a special redistributable
package for the isolated shell.
Prerequisites for Distributing Isolated Shell Applications
NAME
DESCRIPTION
Visual Studio SDK
The SDK you must have to develop and test extensions of
Visual Studio. You can also use the SDK to create your own
instance of the Visual Studio isolated shell.
Visual Studio is a prerequisite for the SDK.
Microsoft Visual Studio Isolated Shell Redistributable
The redistributable that you include in your Setup program
when you build a tools environment on the Visual Studio
isolated shell. The isolated Shell redistributable package
includes the .NET Framework 4.5.
Creating an Installation Program for the Application
You must create a special installation program for your integrated or isolated shell application. For more
information, see Installing an Isolated Shell Application.
Allowing for Updates to your Application
Your installation program must allow for the possibility that your application will be updated, either by Microsoft
updates or by your company's updates. For more information about updates, see Servicing Guidelines for Isolated
Shell Applications.
Installing an Isolated Shell Application
10/20/2017 • 10 min to read • Edit Online
To install a Shell app you must perform the following steps.
Prepare your solution.
Create a Windows Installer (MSI) package for your application.
Create a Setup bootstrapper.
All of the example code in this document comes from the Shell Deployment Sample, which you can
download from the Code Gallery on the MSDN website. The sample shows the results of performing each of
these steps.
Prerequisites
To perform the procedures that this topic describes, the following tools must be installed on your computer.
The Visual Studio SDK
The Windows Installer XML Toolset version 3.6
The sample also requires the Microsoft Visualization and Modeling SDK, which not all shells require.
Preparing Your Solution
By default, Shell templates build to VSIX packages, but this behavior is intended primarily for debugging purposes.
When you deploy a Shell application, you must use MSI packages to allow for registry access and for restarts
during installation. To prepare your application for MSI deployment, perform the following steps.
To prepare a Shell application for MSI deployment
1. Edit each .vsixmanifest file in your solution.
In the Identifier element, add an
their values to true .
InstalledByMSI
element and a
SystemComponent
element, and then set
These elements prevent the VSIX installer from trying to install your components and the user from
uninstalling them by using the Extensions and Updates dialog box.
2. For each project that contains a VSIX manifest, edit the build tasks to output the content to the location from
which your MSI will install. Include the VSIX manifest in the build output, but don't build a .vsix file.
Creating an MSI for Your Shell
To build your MSI package, we recommend that you use the Windows Installer XML Toolset because it gives
greater flexibility than a standard Setup project.
In your Product.wxs file, set detection blocks and the layout of Shell components.
Then create Registry entries, both in the .reg file for your solution and in ApplicationRegistry.wxs.
Detection Blocks
A detection block consists of a Property element that specifies a prerequisite to detect and a Condition element
that specifies a message to return if the prerequisite isn't present on the computer. For example, your Shell
application will require the Microsoft Visual Studio Shell redistributable, and the detection block will resemble the
following markup.
<Property Id="ISOSHELLSFX">
<RegistrySearch Id="IsoShellSfx" Root="HKLM"
Key="Software\Microsoft\DevDiv\vs\Servicing\\$(var.ShellVersion)\IsoShell\$(var.ProductLanguage)"
Name="Install" Type="raw" />
</Property>
<Property Id="INTSHELLSFX">
<RegistrySearch Id="IntShellSfx" Root="HKLM"
Key="SOFTWARE\Microsoft\DevDiv\vs\Servicing\$(var.ShellVersion)\devenv\$(var.ProductLanguage)" Name="Install"
Type="raw" />
</Property>
<Condition Message="This application requires $(var.IsoShellName). Please install $(var.IsoShellName) then
run this installer again.">
<![CDATA[Installed OR ISOSHELLSFX]]>
</Condition>
<Condition Message="This application requires $(var.IntShellName). Please install $(var.IntShellName) then
run this installer again.">
<![CDATA[Installed OR INTSHELLSFX]]>
</Condition>
Layout of Shell Components
You must add elements to identify the target directory structure and the components to install.
To se t t h e l a y o u t o f Sh e l l c o m p o n e n t s
1. Create a hierarchy of Directory elements to represent all of the directories to create on the file system on
the target computer, as the following example shows.
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="CompanyDirectory" Name="$(var.CompanyName)">
<Directory Id="INSTALLDIR" Name="$(var.FullProductName)">
<Directory Id="ExtensionsFolder" Name="Extensions" />
<Directory Id="Folder1033" Name="1033" />
</Directory>
</Directory>
</Directory>
<Directory Id="ProgramMenuFolder">
<Directory Id="ApplicationProgramsFolder" Name="$(var.FullProductName)"/>
</Directory>
</Directory>
These directories are referred to by
Id
when files that must be installed are specified.
2. Identify the components that the Shell and your Shell application require, as the following example shows.
NOTE
Some elements may refer to definitions in other .wxs files.
<Feature Id="ProductFeature" Title="$(var.ShortProductName)Shell" Level="1">
<ComponentGroupRef Id="ApplicationGroup" />
<ComponentGroupRef Id="HelpAboutPackage" />
<ComponentRef Id="GeneralProfile" />
<ComponentGroupRef Id="EditorAdornment"/>
<ComponentGroupRef Id="SlideShowDesignerGroup"/>
<!-- Note: The following ComponentGroupRef is required to pull in generated authoring from project
references. -->
<ComponentGroupRef Id="Product.Generated" />
</Feature>
a. The ComponentRef element refers to another .wxs file that identifies files that the current component
requires. For example, GeneralProfile has the following definition in HelpAbout.wxs.
<Fragment Id="FragmentProfiles">
<DirectoryRef Id="INSTALLDIR">
<Directory Id="ProfilesFolder" Name="Profiles">
<Component Id='GeneralProfile' Guid='*'>
<File Id='GeneralProfile' Name='General.vssettings' DiskId='1'
Source='$(var.BuildOutputDir)Profiles\General.vssettings' KeyPath='yes' />
</Component>
</Directory>
</DirectoryRef>
</Fragment>
The DirectoryRef element specifies where these files go on the user's computer. The Directory
element specifies that it will be installed into a sub-directory, and each File element represents a file
that's built or that exists as part of the solution and identifies where that file can be found when the
MSI file is created.
b. The ComponentGroupRef element refers to a group of other components (or components and
component groups). For instance, ComponentGroupRef under ApplicationGroup is defined as follows in
Application.wxs.
<ComponentGroup Id="ApplicationGroup">
<ComponentGroupRef Id="DebuggerProxy" />
<ComponentRef Id="MasterPkgDef" />
<ComponentRef Id="SplashResource" />
<ComponentRef Id="IconResource" />
<ComponentRef Id="WinPrfResource" />
<ComponentRef Id="AppExe" />
<ComponentRef Id="AppConfig" />
<ComponentRef Id="AppPkgDef" />
<ComponentRef Id="AppPkgDefUndef" />
<ComponentRef Id="$(var.ShortProductName)UI1033" />
<ComponentRef Id="ApplicationShortcut"/>
<ComponentRef Id="ApplicationRegistry"/>
</ComponentGroup>
NOTE
Required dependencies for Shell (Isolated) applications are: DebuggerProxy, MasterPkgDef, Resources (especially the
.winprf file), Application, and PkgDefs.
Registry Entries
The Shell (Isolated) project template includes a ProjectName.reg file for registry keys to merge on installation.
These registry entries must be part of the MSI for both installation and cleanup purposes. You must also create
matching registry blocks in ApplicationRegistry.wxs.
To i n t e g r a t e r e g i st r y e n t r i e s i n t o t h e M SI
1. In the Shell Customization folder, open ProjectName.reg.
2. Replace all instances of the $RootFolder$ token with the path of the target installation directory.
3. Add any other registry entries that your application requires.
4. Open ApplicationRegistry.wxs.
5. For each registry entry in ProjectName.reg, add a corresponding registry block, as the following examples
show.
PROJECTNAME.REG
APPLICATIONREGISTY.WXS
[HKEY_CLASSES_ROOT\CLSID\{bb431796-a179-4df7b65d-c0df6bda7cc6}]
<RegistryKey Id='DteClsidRegKey' Root='HKCR'
Key='$(var.DteClsidRegKey)'
Action='createAndRemoveOnUninstall'>
@="PhotoStudio DTE Object"
<RegistryValue Type='string' Name='@'
Value='$(var.ShortProductName) DTE Object' />
</RegistryKey>
[HKEY_CLASSES_ROOT\CLSID\{bb431796-a179-4df7b65d-c0df6bda7cc6}\LocalServer32]
<RegistryKey Id='DteLocSrv32RegKey' Root='HKCR'
Key='$(var.DteClsidRegKey)\LocalServer32'
Action='createAndRemoveOnUninstall'>
@="$RootFolder$\PhotoStudio.exe"
<RegistryValue Type='string' Name='@'
Value='[INSTALLDIR]$(var.ShortProductName).exe' />
</RegistryKey>
In this example, Var.DteClsidRegKey resolves to the registry key in the top row. Var.ShortProductName
resolves to PhotoStudio .
Creating a Setup Bootstrapper
Your completed MSI will install only if all the prerequisites are installed first. To ease the end user experience,
create a Setup program that gathers and installs all prerequisites before it installs your application. To ensure a
successful installation, perform these actions:
Enforce installation by Administrator.
Detect whether the Visual Studio Shell (Isolated) is installed.
Run one or both Shell installers in order.
Handle restart requests.
Run your MSI.
Enforcing Installation by Administrator
This procedure is required to enable the Setup program to access required directories such as \Program Files\.
To e n fo r c e i n st a l l a t i o n b y A d m i n i st r a t o r
1. Open the shortcut menu for the Setup project, and then choose Properties.
2. Under Configuration Properties/Linker/Manifest File, set UAC Execution Level to
requireAdministrator.
This property puts the attribute that requires the program to be run as Administrator into the embedded
manifest file.
Detecting Shell Installations
To determine whether the Visual Studio Shell (Isolated) must be installed, first determine whether it's already
installed by checking the registry value of
HKLM\Software\Microsoft\DevDiv\vs\Servicing\ShellVersion\isoshell\LCID\Install.
NOTE
These values are also read by the Shell detection block in Product.wxs.
HKLM\Software\Microsoft\AppEnv\14.0\ShellFolder specifies the location where the Visual Studio Shell was
installed, and you can check for files there.
For an example of how to detect a Shell installation, see the
Shell Deployment Sample.
GetProductDirFromReg
function of Utilities.cpp in the
If one or both of the Visual Studio Shells that your package requires isn't installed on the computer, you must add
them to your list of components to install. For an example, see the ComponentsPage::OnInitDialog function of
ComponentsPage.cpp in the Shell Deployment Sample.
Running the Shell Installers
To run the Shell installers, call the Visual Studio Shell redistributables by using the correct command-line
arguments. At a minimum, you must use the command-line arguments /norestart /q and watch for the return
code to determine what should be done next. The following example runs the Shell (Isolated) redistributable.
dwResult = ExecCmd("Vs_IsoShell.exe /norestart /q", TRUE);
Running the Shell Language Pack Installers
If you instead find that the shell or shells have been installed and just need a language pack, you can install the
language packs as the following example shows.
dwResult = ExecCmd("Vs_IsoShellLP.exe /norestart /q", TRUE);
Deciphering Return Values
On some operating systems, the Visual Studio Shell (Isolated) installation will require a restart. This condition can
be determined by the return code of the call to ExecCmd .
RETURN VALUE
DESCRIPTION
ERROR_SUCCESS
Installation completed. You can now install your application.
ERROR_SUCCESS_REBOOT_REQUIRED
Installation completed. You can install your application after
the computer has been restarted.
3015
Installation is in progress. A computer restart is required to
continue the installation.
Handling Restarts
When you ran the Shell installer by using the /norestart argument, you specified that it wouldn't restart the
computer or ask for the computer to be restarted. However, a restart might be required, and you must ensure that
your installer continues after the computer is restarted.
To handle restarts correctly, make sure that only one Setup program is set to resume and that the resume process
will be handled correctly.
If either ERROR_SUCCESS_REBOOT_REQUIRED or 3015 is returned, your code should restart the computer before
the installation continues.
To handle restarts, perform these actions:
Set the registry to resume installation when Windows starts.
Perform a double restart of the bootstrapper.
Delete the Shell installer ResumeData key.
Restart Windows.
Reset the start path of the MSI.
Setting the Registry to Resume Setup When Windows Starts
The HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunOnce\ registry key executes at
system startup with administrative permissions and then is erased. HKEY_CURRENT_USER contains a similar key,
but it runs as a normal user and isn't appropriate for installations. You can resume installation by putting a string
value in the RunOnce key that calls your installer. However, we recommend that you call the installer by using a
/restart or similar parameter to notify the application that it's resuming instead of starting. You can also include
parameters to indicate where you are in the installation process, which is especially useful in installations that may
require multiple restarts.
The following example shows a RunOnce registry key value for resuming an installation.
"c:\MyAppInstaller.exe /restart /SomeOtherDataFlag"
Installing Double Restart of Bootstrapper
If Setup is used directly from RunOnce, the desktop won't be able to load completely. To make the full user
interface available, you must create another execution of Setup and end the RunOnce instance.
You must re-execute the Setup program so that it obtains the correct permissions, and you must give it enough
information to know where you stopped before the restart, as the following example shows.
if (_cmdLineInfo.IsRestart())
{
TCHAR path[MAX_PATH]={0};
GetModuleFileName(NULL, path, MAX_PATH * sizeof(TCHAR));
ShellExecute( NULL, _T( "open" ), path, _T("/install"), 0, SW_SHOWNORMAL );
}
Deleting the Shell Installer ResumeData Key
The Shell installer sets the HKLM\Software\Microsoft\VisualStudio\14.0\Setup\ResumeData registry key with data
to resume Setup after restart. Because your application, not the Shell installer, is resuming, delete that registry key,
as the following example shows.
CString resumeSetupPath(MAKEINTRESOURCE("SOFTWARE\\Microsoft\\VisualStudio\\14.0\\Setup\\ResumeData"));
RegDeleteKey(HKEY_LOCAL_MACHINE, resumeSetupPath);
Restarting Windows
After you set the required registry keys, you can restart Windows. The following example invokes the restart
commands for different Windows operating systems.
OSVERSIONINFO ov;
HANDLE htoken ;
//Ask for the SE_SHUTDOWN_NAME token as this is needed by the thread calling for a system shutdown.
if (OpenProcessToken(GetCurrentProcess(), TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &htoken))
{
LUID luid ;
LookupPrivilegeValue(NULL, SE_SHUTDOWN_NAME, &luid) ;
TOKEN_PRIVILEGES
privs ;
privs.Privileges[0].Luid = luid ;
privs.PrivilegeCount = 1 ;
privs.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED ;
AdjustTokenPrivileges(htoken, FALSE, &privs, 0, (PTOKEN_PRIVILEGES) NULL, 0) ;
}
//Use InitiateSystemShutdownEx to avoid unexpected restart message box
try
{
if ( (ov.dwMajorVersion > 5) || ( (ov.dwMajorVersion == 5) && (ov.dwMinorVersion > 0) ))
{
bExitWindows = InitiateSystemShutdownEx(0, _T(""), 0, TRUE, TRUE, REASON_PLANNED_FLAG);
}
else
{
#pragma prefast(suppress:380,"ignore warning about legacy api")
bExitWindows = InitiateSystemShutdown(0, _T(""), 0, TRUE, TRUE);
}
}
catch(...)
{
//advapi32.dll call not available! Will not restart!
}
Resetting the Start Path of MSI
Before restart, the current directory is the location of your Setup program but, after restart, the location becomes
the system32 directory. Your Setup program should reset the current directory before each MSI call, as the
following example shows.
CString GetSetupPath()
{
TCHAR file[MAX_PATH];
GetModuleFileName(NULL, file, MAX_PATH * sizeof(TCHAR));
CString path(file);
int fpos = path.ReverseFind('\\');
if (fpos != -1)
{
path = path.Left(fpos + 1);
}
return path;
}
Running the Application MSI
After the Visual Studio Shell installer returns ERROR_SUCCESS, you can run the MSI for your application. Because
your Setup program is providing the user interface, start your MSI in quiet mode (/q) and with logging (/L), as the
following example shows.
TCHAR temp[MAX_PATH];
GetTempPath(MAX_PATH, temp);
CString boutiqueInstallCmd, msi, log;
CString cmdLine(MAKEINTRESOURCE("msiexec /q /I %s /L*vx %s REBOOT=ReallySuppress"));
CString name(MAKEINTRESOURCE("PhotoStudioIntShell.msi"));
log.Format(_T("\"%s%s.log\""), temp, name);
msi.Format(_T("\"%s%s\""), GetSetupPath(), name);
boutiqueInstallCmd.Format(cmdLine, msi, log);
//TODO: You can use MSI API to gather and present install progress feedback from your MSI.
dwResult = ExecCmd(boutiqueInstallCmd, FALSE);
See Also
Walkthrough: Creating a Basic Isolated Shell Application
Servicing Guidelines for Isolated Shell Applications
10/20/2017 • 2 min to read • Edit Online
When you distribute a Visual Studio isolated shell application, you must be able to provide software updates for
your application after it is installed. To do this, you must install your application by using a Microsoft Installer (MSI)
file. This kind of installation allows software updates provided by Microsoft to be redistributed by Web download
and consumed by your customers without custom intervention.
Servicing Requirements
You can ensure that your isolated shell installation can allow updates by making sure your installation program
meets the following three criteria.
Redistribute by Using an MSI
You must use an MSI to redistribute your application, because an MSI preserves product identity and makes sure
that the application has a physical location on the client computer. Merge modules (.msm files) do not provide such
assurances and should not be used.
Accounting for Custom Actions
Custom actions are nonstandard installation directives in an installer program. Custom actions change parameters
such as file locations, registry settings, user settings, or other installation items. Custom actions might manipulate
data at installation time.
When you use custom actions in an installation program, you must ensure that every install-time custom action
must have a corresponding custom action to undo the action when the user uninstalls the application. If your
installation program fails to provide corresponding uninstall custom action, removing your application will leave it
partially installed.
A custom action that relies on a specific version of a file or hash values will fail when software updates change
these versions or hash values. In this case your custom action must manually update these values. An additional
problem occurs if versions of a file or hash values are shared between product versions. Avoid this dependency
whenever possible.
Accounting for Shared Files
Shared files have the same names and are installed to the same location by multiple products. These products may
differ in version, Stock Keeping Unit (SKU), or both, and the products can co-exist on a given computer. However,
shared files create servicing problems for several reasons:
Updating shared files can cause application compatibility issues because an update to one application may
change the version of a file used by a second application that has not been updated. Installers for products
that share files count references to the shared files. Therefore, uninstalling a product does not affect shared
files beyond decrementing the count of installed instances.
The Quick Fix Engineering (QFE) installer reverts versions of files to the versions of the products that the QFE
installer serviced. This process potentially breaks an application that had delivered an updated shared file.