{"id":2283,"date":"2010-03-22T06:35:00","date_gmt":"2010-03-22T06:35:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/visualstudio\/2010\/03\/22\/troubleshooting-pkgdef-files\/"},"modified":"2022-10-14T15:14:32","modified_gmt":"2022-10-14T22:14:32","slug":"troubleshooting-pkgdef-files","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-pkgdef-files\/","title":{"rendered":"Troubleshooting pkgdef Files"},"content":{"rendered":"<h2><\/h2>\n<p>For those using the Visual Studio 2010 SDK to create extensions for Visual Studio, you should find the creation and use of <strong>.pkgdef<\/strong> files to be mostly automatic (see <a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/whats-a-pkgdef-and-why\/\">What&#8217;s a PkgDef and Why?<\/a>). However, like anything involving computers and software, there are occasions that require manual intervention because they aren\u2019t covered by the automatic settings or things can go wrong. This article illustrates some possible issues with .pkgdef files and provides techniques for discovering what\u2019s wrong and correcting them.<\/p>\n<p>Please note that these techniques apply not only to the Visual Studio 2010 IDE, but also to applications built using the Visual Studio 2010 Shell (Isolated) (or Integrated). All of the examples assume the case of VS 2010 running on 32-bit Windows 7. For other cases, substitute the appropriate file locations and names and registry root key.<\/p>\n<h3>What Could Go Wrong?<\/h3>\n<p>First of all, how do you know if something goes wrong? A problem with a .pkgdef file usually manifests itself in one of two ways:<\/p>\n<ol>\n<li>All or part of a Visual Studio extension, such as a VS Package, simply fails to load or an error message is displayed about needing to reinstall Visual Studio.<\/li>\n<li>Your Visual Studio extension tries to retrieve a registry value it expected to be included in the install and does not find it. The result can be anything from using an appropriate default to displaying a message about an exception.<\/li>\n<\/ol>\n<p>Either of these symptoms can be caused by one or more of the issues listed below. The list is by no means intended to be exhaustive.<\/p>\n<ul>\n<li><a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-pkgdef-files\/#issue-per-user-extension-is-not-enabled\">Per-user Extension Is Not Enabled<\/a><\/li>\n<li><a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-pkgdef-files\/#issue-pkgdef-file-is-not-found\">pkgdef File Is Not Found<\/a><\/li>\n<li><a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-pkgdef-files\/#issue-invalid-syntax\">Invalid Syntax<\/a><\/li>\n<li><a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-pkgdef-files\/#issue-unrecognized-substitution-string\">Unrecognized Substitution String<\/a><\/li>\n<li><a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-pkgdef-files\/#issue-invalid-registry-key\">Invalid Registry Key<\/a><\/li>\n<li><a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-pkgdef-files\/#issue-registry-value-collisions\">Registry Value Collisions<\/a><\/li>\n<\/ul>\n<h3>Issue: <a title=\"peruserextension\" name=\"peruserextension\"><\/a>Per-user Extension Is Not Enabled<\/h3>\n<p>Pkgdef files that are installed as part of a user extension deployed using the new VSIX format are copied to a sub-folder of %LocalAppData%MicrosoftVisualStudio10.0Extensions. The pkgdef loader does not automatically search for pkgdef files here. Rather, it loads pkgdef files for <a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/how-vsix-extensions-are-discovered-and-loaded-in-vs-2010\/\">user extensions that have been enabled<\/a>, which the Extension Manager and the stand-alone VSIX installer both do automatically. If you choose to unpack a VSIX file yourself, or otherwise do a manual xcopy-style deployment, it\u2019s easy to forget the step that enables the extension. This is easily fixed.<\/p>\n<h3>Remedy: Use the Extension Manager to enable per-user extensions<\/h3>\n<p>It\u2019s entirely possible that if you manually deployed the contents of a VSIX file, you simply need to enable it in the Extension Manager dialog and restart Visual Studio before the pkgdef loader will pick it up.<\/p>\n<h3>Remedy: Enable per-user extensions when running as administrator<\/h3>\n<p>On a related note, there is an option to disable loading of all per-user extensions when running \u2018as administrator\u2019 (elevated), regardless of being enabled or not. This is controlled under <strong>Tools-Options-Extension Manager<\/strong> as <strong>Load per user extensions when running as administrator<\/strong>. Make sure this checkbox is checked (when appropriate).<\/p>\n<h3>Issue: <a title=\"filenotfound\" name=\"filenotfound\"><\/a>pkgdef File Is Not Found<\/h3>\n<p>For all other extensions (those that are not per user), the pkgdef loader searches the locations listed in the PkgDefSearchPath of the master pkgdef file. The value of PkgDefSearchPath has three elements:<\/p>\n<ol>\n<li>$RootFolder$Common7IDEExtensions<\/li>\n<li>$RootFolder$Common7IDECommonExtensions<\/li>\n<li>$RootFolder$Common7IDEdevenv.admin.pkgdef<\/li>\n<\/ol>\n<p>$RootFolder$ is the location where Visual Studio is installed (C:Program FilesMicrosoft Visual Studio 10.0). The first two search elements are folders, which are recursively scanned looking for pkgdef files. The third element is a specific pkgdef file (which does not typically exist, but is kept in the list as a placeholder for system administrators).<\/p>\n<p>An easy mistake to make is to drop a pkgdef file into either $RootFolder$ or $RootFolder$Common7IDE or some other sub-folder and expect the pkgdef loader to just find it. However, these locations are not in the search path.<\/p>\n<h3>Remedy: Use \/log to discover which pkgdef files are loaded<\/h3>\n<p>You can find out exactly which pkgdef files the loader is finding, using the <a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-extensions-with-the-activity-log\/\">\/log command line option for Visual Studio<\/a>. Among the items the pkgdef loader logs are the full expanded value for the PkgDefSearchPath, a list of all of the pkgdef files found on the search path, and a list of the pkgdef files found for enabled extensions.<\/p>\n<table border=\"1\" cellspacing=\"0\" cellpadding=\"3\">\n<tbody>\n<tr>\n<td valign=\"top\"><span style=\"font-size: xx-small;\"><strong>Trick<\/strong><\/span>\nSince the pkgdef loader will not rebuild the cache if it does not think it is out of date, there is a bit of a trick to using \/log to debug pkgdef load issues when you are not sure which files it is finding (and thus which ones to touch). Use Notepad to create a file called \u201clog.pkgdef\u201d that contains a single comment line (\u201c\/\/ comment\u201d) and copy it to C:Program FilesMicrosoft Visual Studio 10.0Common7IDEExtensions. This ensures that the pkgdef loader has a new file to process. If you need to run \/log more than once with this file in place, be sure that it gets saved with a new timestamp before each run.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Run: <strong>devenv.exe \/log<\/strong><\/p>\n<p>When Visual Studio is finished loading (status bar reads \u201cReady\u201d), File &#8211; Exit, start Windows Explorer, browse to <strong>C:UsersUserAppDataRoamingMicrosoftVisualStudio10.0<\/strong>, and open the file <strong>ActivityLog.xml.<\/strong> It should open in Internet Explorer using the associated XSL to format it in an table.<\/p>\n<p>Near the top of the file, Visual Studio will list the PkgDefSearchPath:<\/p>\n<p><img decoding=\"async\" title=\"LogPkgDefSearchPath\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/LogPkgDefSearchPath_thumb_2.png\" alt=\"LogPkgDefSearchPath\" width=\"743\" height=\"45\" border=\"0\" \/><\/p>\n<p>This is followed by the number of files found and then the list of those files, for example:<\/p>\n<p><img decoding=\"async\" title=\"LogFileScanLoad\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/LogFileScanLoad_thumb.png\" alt=\"LogFileScanLoad\" width=\"609\" height=\"60\" border=\"0\" \/><\/p>\n<p>Armed with the knowledge of which folders are being scanned and which pkgdef files were discovered, you should now be able to make sure your pkgdef file is deployed to an appropriate location.<\/p>\n<h3>Remedy: Install System-wide extensions under the PkgDefSearchPath<\/h3>\n<p>Any extension that is not installed per-user should be installed in a sub-folder of $RootFolder$Common7IDEExtensions or $RootFolder$Common7IDECommonExtensions.<\/p>\n<h3>Issue: <a title=\"invalidsyntax\" name=\"invalidsyntax\"><\/a>Invalid Syntax<\/h3>\n<p>This issue is most likely to crop up if you run into a situation where you must create or edit a pkgdef file manually. Like any language, it\u2019s easy to forget a closing quote or insert an extra one.<\/p>\n<p>The <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/cc138553(VS.100).aspx\">syntax of a pkgdef file<\/a> is actually quite simple. Each line can be one of:<\/p>\n<ul>\n<li>comment \u2013 starts with a semi-colon (\u2018;\u2019&#8217;) or double-slash (\u2018\/\/\u2019)<\/li>\n<li>registry key \u2013 starts with a square bracket (\u2018[\u2018) and ends with a square bracket (\u2018]\u2019) that defines a section of values<\/li>\n<li>registry value \u2013 starts with a name in double quotes or the at sign (\u2018@\u2019 not in quotes) for a \u2018default\u2019 value of a key, followed by an equals sign, and then a string or numeric value<\/li>\n<\/ul>\n<p>Common syntax mistakes include:<\/p>\n<ul>\n<li>Not enclosing a registry value name in double quotes:\nincorrect: name=\u201dvalue\u201d\ncorrect: \u201cname\u201d=\u201dvalue\u201d<\/li>\n<li>Enclosing the symbol for the default value of a registry key in double quotes:\nincorrect: \u201c@\u201d=\u201dvalue\u201d\ncorrect: @=\u201dvalue\u201d<\/li>\n<li>Omitting an opening or closing double quote for a name or string value<\/li>\n<li>Adding comments at the end of a line defining a key or value. Comments must be on their own line.<\/li>\n<\/ul>\n<p>The pkgdef loader is not very tolerant of syntax errors and will simply refuse to load a pkgdef file that contains even a single error, rather than risk corruption of the pkgdef cache. When it does reject a pkgdef, this information is written to the activity log.<\/p>\n<h3>Remedy: Use \/log to discover pkgdef file syntax errors<\/h3>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/visualstudio\/troubleshooting-extensions-with-the-activity-log\/\">Use \/log to generate ActivityLog.xml<\/a>. Any syntax errors will be highlighted in red, along with a warning showing the name of the offending file (which is not loaded).<\/p>\n<p><img decoding=\"async\" title=\"LogSyntaxErr\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/LogSyntaxErr_thumb_2.png\" alt=\"LogSyntaxErr\" width=\"590\" height=\"125\" border=\"0\" \/><\/p>\n<p>In this example, the value of \u201cfoo\u201d is missing the closing quote expected for strings and the value of bar is given as <em>word<\/em>, rather than <em>dword <\/em>or <em>qword<\/em>. The name for \u201cbax\u201d is not put in quotes. Once you edit the file to make these corrections (and save it and deploy it to the correct location), the pkgdef loader will see that the file has been updated and rebuild the cache automatically (you do not have to force this rebuild by deleting the registry value from the cache again).<\/p>\n<h3>Remedy: Use the <strong>PkgDef Editor extension for <\/strong>Visual Studio<\/h3>\n<p>Another way to find and fix syntax errors is to download and install the new editor extension we\u2019ve created to give syntax coloring and error output for pkgdef files. It can be found in the Visual Studio gallery, either through the Extension Manager or <a href=\"http:\/\/visualstudiogallery.msdn.microsoft.com\/en-us\/bc9bbceb-a17e-4919-9c24-e803e48aa051\">directly in the gallery<\/a>. Just search for \u201cpkgdef\u201d under the <strong>Tools<\/strong> category and download the <strong>PkgDef Editor<\/strong> extension.<\/p>\n<p><img decoding=\"async\" title=\"EditSyntaxErr\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/EditSyntaxErr_thumb.png\" alt=\"EditSyntaxErr\" width=\"263\" height=\"119\" border=\"0\" \/><\/p>\n<p>In this example, the same errors as above are flagged, along with the pop-up message describing the problem with the value of \u201cfoo\u201d.<\/p>\n<h3>Issue: <a title=\"substitutionstring\" name=\"substitutionstring\"><\/a>Unrecognized Substitution String<\/h3>\n<p>pkgdef files are made portable by tokenizing system-specific and user-specific information. These are known as <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/ee390882(VS.100).aspx\">substitution strings<\/a>. Examples are <strong>$RootKey$<\/strong>, which defines the root of the Visual Studio configuration registry, the starting point for all key values, and <strong>$PackageFolder$<\/strong>, which is the full path in the file system to the location from where the current pkgdef file is being loaded.<\/p>\n<p>Substitution strings are case-sensitive and must be enclosed between two dollar-signs (\u2018$\u2019). Common mistakes related to tokens are:<\/p>\n<ul>\n<li>Omitting the closing dollar-sign&#8221; on a substitution string name:\nincorrect: [$RootKeysubkey]\ncorrect: [$RootKey$subkey]<\/li>\n<li>Using incorrect case or spelling:\nincorrect: \u201cpathtomyfile\u201d=\u201d$packagefolder$myfile.dll\u201d or \u201c$pkgfolder$myfile.dll\u201d\ncorrect: \u201cpathtomyfile\u201d=\u201d$PackageFolder$myfile.dll\u201d<\/li>\n<\/ul>\n<p>When the pkgdef loader cannot recognize a substitution string, it simply does nothing and uses it \u2018as is\u2019. When this happens in a registry key or value name, it means the key or value will not be put in the correct location or get the correct name.<\/p>\n<h3>Remedy: Search the registry<\/h3>\n<p>This can be very difficult to debug, except by knowing what to look for. When this happens for a string value, it is a little easier to detect, simply by looking in the registry using regedit.exe:<\/p>\n<p><img decoding=\"async\" title=\"RegToken\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/RegToken_thumb.png\" alt=\"RegToken\" width=\"453\" height=\"92\" border=\"0\" \/><\/p>\n<p>In this example, the value for \u201cbax\u201d was specified with \u201c$PkgFolder$\u201d, rather than \u201c$PackageFolder$\u201d.<\/p>\n<h3>Remedy: Use <strong>PkgDef Language Integration for <\/strong>Visual Studio<\/h3>\n<p>As seen above, the <strong>PkgDef Editor <\/strong>extension can make it much easier to see problems with pkgdef files. In particular, it knows the valid tokens for string substitution and can flag the ones it does not recognized:<\/p>\n<p><img decoding=\"async\" title=\"EditTokenErr\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/EditTokenErr_thumb_1.png\" alt=\"EditTokenErr\" width=\"316\" height=\"167\" border=\"0\" \/><\/p>\n<p>In this example, all of the string substitution tokens (anything starting and ending with the dollar-sign) are highlighted (in blue) and the unrecognized tokens are flagged as errors. One string contains a value that was intended to be a string substitution, but is missing the closing dollar-sign, so it is not highlighted. Also in this example, it is easy to see that $RegRoot$ is not a recognized string substitution, but using regedit it was simply missing-in-action.<\/p>\n<h3>Issue: <a title=\"invalidkey\" name=\"invalidkey\"><\/a>Invalid Registry Key<\/h3>\n<p>The pkgdef loader will not write to arbitrary registry locations. It only writes registry entries within the configuration hive of Visual Studio (or an Visual Studio Shell (Isolated) application). This rule is easily followed by starting all key\/section names with $RootKey$.<\/p>\n<h3>Remedy: Use \/log to discover invalid registry keys<\/h3>\n<p>The pkgdef loader will log attempts to write to locations outside of the application\u2019s configuration hive:<\/p>\n<p><img decoding=\"async\" title=\"LogSection\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/LogSection_thumb.png\" alt=\"LogSection\" width=\"590\" height=\"65\" border=\"0\" \/><\/p>\n<p>In this example, using the file from the previous example, $RegRoot$ was not recognized as a substitution string, so it did not get replaced with the appropriate root key for the application. And the result is not a valid location for a registry key for the application.<\/p>\n<h3>Issue: <a title=\"registrycollision\" name=\"registrycollision\"><\/a>Registry Value Collisions<\/h3>\n<p>Sometimes the same registry value is being set by more than one pkgdef file. In other cases, a registry value is being set, but it\u2019s not clear which pkgdef file is doing it. You can either scan all of the pkgdef files and discover where the value is being set. Or use \/log again.<\/p>\n<h3>Remedy: Use \/log to discover which pkgdef(s) set a value<\/h3>\n<p>To discover <em>all<\/em> pkgdef files that are setting a value, use a simple trick: explicitly set that same value by temporarily changing the master pkgdef (C:Program FilesMicrosoft Visual Studio 10.0Common7IDEdevenv.pkgdef) to explicitly set the value before all of the other pkgdef files are processed. This will require Administrator rights to edit the file, but is otherwise straightforward. Make a backup copy of devenv.pkgdef, then bring it up in an editor. Below the [$Initialization$] section, add a new section for the parent key of the value. Then add the key value below it, save it, and run devenv.exe with \/log. The pkgdef loader will log all of the additional writes to that value, along with the path to the offending pkgdef.<\/p>\n<p><img decoding=\"async\" title=\"LogCollision\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/LogCollision_thumb_2.png\" alt=\"LogCollision\" width=\"644\" height=\"50\" border=\"0\" \/><\/p>\n<p>In this example, we caught the blog.pkgdef file writing to the value \u201cfoo\u201d under \u201c$RootKey$MyExtension\u201d. The next step is to determine why and whether this needs to change (be sure to put devenv.pkgdef back the way you found when you\u2019re done).<\/p>\n<h3>Summary<\/h3>\n<p>This post has described several tactics for troubleshooting pkgdef issues. The most basic of these is to use \/log, along with a trick for forcing PkgDef Management to rebuild the pkgdef cache. You may also find that the <strong>PkgDef Editor <\/strong>extension is helpful when editing pkgdef files.<\/p>\n<table>\n<tbody>\n<tr>\n<td><strong><img decoding=\"async\" title=\"BillWeinberger\" src=\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/03\/BillWeinberger_3.jpg\" alt=\"BillWeinberger\" width=\"108\" height=\"108\" align=\"left\" border=\"0\" \/> Bill Weinberger<\/strong>: Developer, Visual Studio Platform<\/p>\n<p>Bill has been with the VS Platform team for about two years, and has more than a few previous years of software industry experience working on IDEs and vertical applications. For Visual Studio 2010, he was a key contributor to PkgDef Management.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n","protected":false},"excerpt":{"rendered":"<p>For those using the Visual Studio 2010 SDK to create extensions for Visual Studio, you should find the creation and use of .pkgdef files to be mostly automatic (see What&#8217;s a PkgDef and Why?). However, like anything involving computers and software, there are occasions that require manual intervention because they aren\u2019t covered by the automatic [&hellip;]<\/p>\n","protected":false},"author":13,"featured_media":255385,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[155],"tags":[287],"class_list":["post-2283","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-visual-studio","tag-tips-and-tricks"],"acf":[],"blog_post_summary":"<p>For those using the Visual Studio 2010 SDK to create extensions for Visual Studio, you should find the creation and use of .pkgdef files to be mostly automatic (see What&#8217;s a PkgDef and Why?). However, like anything involving computers and software, there are occasions that require manual intervention because they aren\u2019t covered by the automatic [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/posts\/2283","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/users\/13"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/comments?post=2283"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/posts\/2283\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/media\/255385"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/media?parent=2283"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/categories?post=2283"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/tags?post=2283"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}