VC++ Directories

The goal of this post is to quickly explain what VC++ Directories are, what happened to them in VS 2010 and why the change was made.

Life in VS 2008

To start with, let’s take a look at the VS 2008 feature of VC++ Directories. If you were to go to the Tools->Options menu, you would see the following under the Project and Solutions settings

These are the IDE equivalents to the command line environment variables of PATH, INCLUDE, etc. However, these values only apply within the IDE or vcbuild.exe – they don’t apply when executing cl.exe, for example, directly from the command line. Additionally, as you can see from the Platform dropdown at the top of the dialog, you can customize these settings for each platform.

The implementation for these settings is to store the values in the VCComponents.dat file stored in %LOCALAPPDATA%\Microsoft\VisualStudio\9.0. Looking at the file, you’ll notice two things. First, it is in the LocalAppData directory, which means the settings are per-user, per-machine. The second thing you’ll notice is that the file is in an INI format, not the XML of a .vcproj file. This shows that the importing of the .dat file is some custom code of vcbuild.exe and the IDE.

Changes in VS 2010

The first thing you’ll notice in VS 2010 when working with VC++ Directories is that they appear to have disappeared. When you go to the Tools->Options window and look in Project and Solutions, you’ll see the window looks very similar to the screenshot above – only VC++ Directories is gone. However, if you bring up a VC++ project in the IDE and open the project properties window (right-click on the project node and select Properties), you will notice a Rule called VC++ Directories (Rules are the tree of selections on the left pane of the property page window) and that the values you see are the same defaults that you would get from VS 2008. Additionally, you can edit these properties in the same way as any other project property (including using the macro editor as shown – something not possible in VS 2008).

Of course, any edits you make right here are applied directly to the project you are working on – and directly to the project file itself. This means that the edits are NOT per-user, per-machine as they were in VS 2008. However, that option still exists in the form of a property sheet (If you don’t know about property sheets or how they work in VS 2010, I recommend reading my previous post about them here).

If you open up the Property Manager view to see the property sheets associated with your project, you’ll see that one of the property sheets is named Microsoft.Cpp.Win32.User. This property sheet is actually stored in LocalAppData, just as VCComponents.dat file was, in the directory %LocalAppData%\Microsoft\VisualStudio\10.0. Using the property editor on the property sheet (just right-click on this property sheet node and select Properties…), you can see that you are able to make edits directly to this file. Since all projects, by default, import this property sheet, you are effectively editing the VC++ directories in the same way you were able to do before.

Additionally, you can also delete the reference to this per-user, per-machine property sheet and create your own set of property sheets that set these values. Deleting the reference to this property sheet makes your project operate independently of any per-user, per-machine settings – and important step when trying to ensure correct behavior in a SCC (source code control) environment.

Why the Changes?

A reasonable question would be to ask why these changes were done. There are several reasons.

  1. VS 2008 VC++ Directories were applied to all projects loaded on that machine and could not be stopped.
    This is probably the biggest reason for the change. We’ve had many customers complain that they had different projects with very different setups. As you are probably well aware, the order that directories are listed for things like PATH and INCLUDE can have dramatic effects on the results of builds and being unable to customize these values easily on per-project (or groups of projects) basis required many unfortunate hacks by our customers.
  2. VS 2008 VC++ Directories were per-user, per-machine and made SCC enlistments fragile.
    Imagine that you want to be able to check in your entire project system – not just the source files and project files, but the entire build system as well. If you could do that, then you could go up to any machine with only the SCC system installed, check out the project system and build. However, if your build was dependent on settings that were per-machine, as in the case of VCComponents.dat, that was impossible. Instead, by deleting the reference to the per-user property sheet, a VS 2010-based build system can be made fully enlistment-based – a key feature we wanted to provide in VS 2010.
  3. VC 2008 VC++ Directories were inconsistent with the rest of the build technology.
    This is a minor, but satisfying, improvement. The VCComponents.dat was an INI based file that was hard-wired into the vcbuild engine, whereas the property sheet is a standard MSBuild file that uses the build-in rules of any MSBuild import – learning the one MSBuild language is all that is required. As a side benefit, the editing experience of the VC++ directories is also made consistent by moving the editor into the property editor.

A Note About Import/Export Settings

As part of moving the VC++ Directories out of the Tools->Options and into property sheets, I should also note that this means they are no longer considered part of VC++ Settings in Visual Studio. The settings are meant for IDE specific configuration settings, and VC++ Directories are now built-in directly to the build process and are found via standard property sheet mechanisms. Therefore there is no longer any need to have these participate in import/export – they are put into a single property sheet file (by default) that can be shared between different versions of VS – and work the same both inside and outside of the IDE.

The one exception to this is migration – if you migrate your settings from VS2008, the VC++ directories from the earlier version will be migrated up and into the per-user property sheet file for you.

For SDK Authors

As a closing remark for those of you out there that would edit the VC++ Directories as part of your SDK installation. That scenario is still supported – either via the VCProjectEngine APIs or by directly editing the new property sheet (see the MSBuild APIs for simply editing access). However, I would also urge you to think anew about what it means to install your SDK.

The VC++ Directories approach does provide a way to install your SDK into the user’s build system, but it has a few major drawbacks.

  1. You can’t uninstall – at least not easily – given the other changes that the user may have done since the install.
  2. You are automatically applied to all projects, whether they want to use your SDK or not.
  3. In VS 2010, you are no longer necessarily applied to all projects because the per-user property sheet link may have been removed.

Instead, think about how you can provide the options for customers to enable you in their projects. For example, if you provide your own property sheets than can be added into the customers projects on demand, then the user has control over their environment – and you can also be checked into the SCC enlistment, enabling the enlistment scenario described earlier.

The downside of this approach, of course, is that the SDK isn’t immediately available after installation. This is an opt-in model. But using the tool extensibility, controlled by switches, you can also create a system that is an opt-out as well. Basically, the new directories design combined with the new extensibility model provides a lot of flexibility. We’d love to work with all the SDK providers to try to come up with some best practices and patterns – so drop us a line!

Comments (31)

  1. pisiiki says:

    I have been trying this in vs2010 beta 1 and I see some differences, the icons of the property sheets doesn’t look the same and I was unable to add "child sheets". Is there a newer version than beta1 right now?

  2. Aleria says:


    This is just a step back!

    The property sheets are just plainly unfriendly to use and there’s no easy way to add global paths now, either!

    Why, Microsoft, why????? So many rely on this feature, me included. We need a global path options that’s accessible and per-project settings!

  3. korendir says:

    This is both a step back and a step forward.

    I really like the idea of being able to manage this on a project by project basis, but I also need an easy way to add global paths.  The old way worked well and I don’t see the need to remove it in favor of property sheets.

    Having both the new and old methods would allow for complete customization of paths and be the most flexable for indivudual developer needs.

  4. Brian Tyler says:

    pisiiki – No, I’m afraid that Beta 1 is the only publically available version out at the moment – and yes – there are several bugs in the property manager that is causing problems there.

    Aleria/Korendir – Wow, that is some feedback. THANK YOU! I love to see people open and honest.

    I have a question for you, however. I’m trying to understand whether we have a situation where (a) I didn’t explain something well or (b) there is a strong issue with the usability.

    To be clear – everything that you could do with VC Directories VS2008 can be done in VS2010. Not counting the new abilities in 2010, the big change is that rather than going to Tools->Options, you go to the property manager and bring up the property editor for the User property sheet. This continues to give you global path options that are applied to all projects that are (a) upgraded or (b) created in VS 2010. Only if you break the link to the user property sheet does a project stop getting those directories (which is the feature that has been asked for by others).

    So, please!, let me know whether

    a. We had a misunderstanding.

    b. There is a scenario I am not seeing that won’t work in 2010.

    c. The property manager UI is an unacceptable replacement for the Tools->Options UI.

  5. tactoth says:

    I’m just wondering if it’s possible to configue global VC directories when there’s no active project.

  6. Phaeron says:

    The new UI path is confusing, because you have to go through a project-local path in order to reach a property sheet that is actually a per-user setting. I think it would be a lot less confusing if you could open the property sheet editor for the per-user sheet from the old VC++ Directories location. Many programmers I know have no idea that property sheets and the Property Manager exist, but they do know about Tools > Options > VC++ Directories.

    As for the property sheet based SDK opt-in, that’s a good idea, but I’m not sure how it would work here. The bane of project deployment is absolute filesystem paths, which means you don’t want to reference the SDK directory from the project. On the other hand, you can’t have SDKs installing into the Visual Studio directory either, since they would have to do so for every new version of Visual Studio. So where would the property sheets go?

  7. tom says:

    you missed the info that "Microsoft.Cpp.Win32.User" is NOT loaded automatically for XP users.

    This is really a blocking factor for us to try VC10, and together with other bugs in this very property manager, the user experience is very much worsened, if not possible(I wasn’t able to try VC10 IDE util now actually), though the solution is just one line of info.

    I was lost at following your blogs until I read this:

  8. Neil says:

    Slightly off topic but I have a gripe with the "Include Directories" dialog in your second screenshot.  Why does it have to default to being so small?  It only displays 3-4 lines and on virtually all of my projects I have to resize the window to see all the lines and their full paths each time I restart VS.  (Not specific to VS 2010, this is the same behaviour in 2008 and previously.)

  9. Alex says:

    I agree that the change is for all good. This really helps to solve all the problems mentioned in the article and maybe even more. SCC integration is now really much easier.

    The only thing need to be done, I think (and hope a lot of people agree), is to return the settings in the Tools -> Options -> VC++ Directories.

    Let those settings modify the Microsoft.Cpp.*.User property files. Provide the users who are satisfied with old behavior with a method they used to, and provide the advanced users with all power of inherited property sheets.

  10. Gabest says:

    It happened to me once with an imported project that in the property manager there was no inherited Microsoft.Cpp.Win32.User, couldn’t find out what triggers its inclusion.

    There are also a few bugs in the new system, like it auto-surrounds the path with "…" but it just does not work unless I manually remove it, and the changes aren’t seen until the project is reloaded (or vs itself, cannot remember exactly).

  11. Adam says:

    This is a great feature.  I can understand why some people might have a problem w/ this when they are doing their home development where they just want things to work, but if you are doing professional development global includes are just bad practice.  Using property sheets and setting up your paths on a per-project basis is definitely a best practice because it allows all developers to benefit from a consistent environment w/o having to alter their global configurations whenever someone adds a new library (instead they just pull the new property sheet from source control)

  12. pisiiki says:

    I have spent a full evening configuring a big solution with the new features and I found that this is in fact an improvement. The problem here is probably that for the average programmer this is worse and they will need a lot of time to adapt to the sheets and this advanced config system. I know a lot of people for example that just ask for the redistribuitables because they don’t know that they can static link the libs. I mean, a lot of peole there prefer to stay FAR away from the properties of their projects. I would suggest here that a good solution would be to keep both things and to "point" the user to the sheets. You said that a global config is still supported via an external file, but these programmers won’t never know about this and some of this guys are probably the pros of the following five years so better to keep then within vs.

  13. tom,

    The fact that the user-machine property sheet is not imported by XP in beta 1 is a bug that should be fixed by beta 2.  Thanks for reporting it though.

  14. Axel says:

    I always wondered why "VC++ directories" is under "Projects and Solutions".

    This is not a project setting. It’s a setting that affects the whole IDE.

    Now at least that makes some sense. But it would be really nice to have some additional menu entry under "Environment" that manages global paths.

  15. Aleria says:

    I agree with Alex above.

    The global settings needs to be moved back so it can be accessed easily. I do understand the problem and the solution with both global and per is a good one, but the global paths are too difficult to access!

    Plus the property sheets that we would find under the project settings are just plain unfriendly for paths.


    This is fine, but when they are longs paths, it just gets difficult to see and manage. The old VC++ Directories was good and easy to use. So why not use it and adapt it to the new system?

    I am mostly just using VS for private programming, so this would indeed benefit me more than the current system.

  16. Richard says:

    Actually, from a builder’s standpoint this has one large advantage.  I can publish my build properties sheet so that when the developer checks in a change that breaks the build, but it builds just dandy on his machine, she/he can easily substitute in the build environment to determine the problem.

  17. Joe says:

    Moving this from Tools->Options makes absolutely no sense. Why would you do that? Is there some binary imperative that requires you to be inconsistent? Global settings are global settings. What harm would it do to maintain them in both places? Moreover, how do you edit the global settings without opening a solution?

    (Having said that, one little feature that would be nice is if you navigate to a directory in this dialog or in a solution, to have the IDE check whether a macro could be used on the path OR whether the path could be relative and ask!)

  18. ScottL says:

    Great! This change sounds excellent, I wish you’d done it years ago, I’ve spent way too long trying to solve problems caused by the "Options->VC++ Directories".

    It’d be even better if by default the per user properties were not included in a project.

    Good work.

  19. Aleria says:

    ScottL, I think that should be an option.

    Not having those directories by default would certainly be a step backwards for me, and many other hobbyists.

  20. Jalf says:

    As already mentioned, it seems odd that the "official" way to edit *global* paths is to open a project, and access the property sheets associated with it. And the UI for editing paths in property sheets is just horrible. Semicolon-separated strings? What is this, the 80’s? The old VC++ Directories UI formatted the paths clearly. Why can’t the .props UI do the same?

    To be honest, I don’t like the format in the underlying .props file either. It’s supposed to be XML, isn’t it? So why not structure this data as XML too? Get rid of the semicolons, and add a <path> tag or something instead.

    But I love the underlying change. The more configuration properties can be migrated to property sheets, the better. 😉

  21. Brian Tyler says:

    Well, I have to say this topic has obviously touched a nerve among many of you. I’ve been holding off responding because this thread has restarted the conversation internally and we are still looking to see what we might have time to do in order to address some of the concerns.

    The thrust of the discussion is around the discoverability and usability for the "global settings" folks. The design of having VC Directories as fundamental parts of the build engine and to make them property-sheet based isn’t changing – it’s a requirement for those that can’t have global settings. However, we are going to see if there is anything we can do to make the experience for others less painful.

    No promises – we have very little time to work with here as we are focused on improving the performance and stability of the product. I just want to be open and honest with where we are.

    I’ll keep you apprised :)

  22. Aleria says:

    That sounds better than nothing, but perhaps you should have written about this earlier or blog about more information while the IDE is still in WIP state so you have time to make changes?

  23. While I have no problem with this change in principle, I simply haven’t managed to get the beta implementation to work.

    For example, I frequently reference the DirectX SDK so I thought it would be a good idea to add these to the default property sheets. However, adding these properties via the VS UI surrounds the new property in double quotes causing it not to work. The only way to get it to work is then to remove the quotes by editing the file manually.

  24. Anna says:

    BAD Feature.

    Recently installed the DXSDK, and now I have to add the directories to each and every project.

    I cannot cope with this, please re-add the default directories as an optional alternative that all projects inherit from.

  25. Brian Tyler says:

    Anna, I don’t believe we had a communication over the blog post :) As I said above "Since all projects, by default, import this property sheet, you are effectively editing the VC++ directories in the same way you were able to do before"

    Therefore you don’t have to edit every project – only the .user property sheet which all projects inherit by default. I think you have what you are looking for.

  26. Dusty says:

    I think the solution is to provide an optional way to edit the global includes that is more user friendly.

    The current method is anything but that.

  27. Joe says:

    I’ve now spent the day using the abomination known as Visual Studio 2010. It was horrid and quite disappointing (in general, it created slightly smaller exe’s than 2005, but they ran slower.) That said, the directories feature as described here is designed very badly. Placing them in the solution clearly implies that these are overrides, not the base settings in any way shape or form.

    You guys have forgotten the golden rule: just because you can do something doesn’t mean you should.

    (On the other hand, I’d gladly accept the idiocy of this design if Visual Studio 2010 Beta 1 was such a horrid pile of junk.)

  28. Rosália says:


    I just started testing VStudio 2010 and the disappearance of VC++ Directories got me a little surprised/annoyed.

    I think the making-it-more-customizable is a noble cause, but putting global stuff inside project settings.. isn’t this too much of a hack? If the project settings included the per-project directories and an option to use or not the global option additionally, would this go too far from the current design?

    I also agree with what was said, the older menu was aesthetically more pleasant.

    It is really great that we have the opportunity to discuss this here, anyway.

  29. Simon Buchan says:

    Damn, looks like half the people here are missing the boat: the reason you edit these paths under a project is because they are local to the project now! Which makes more sense, really.

    But I do agree with the other half that not having to dig up a buried .xml file to edit global paths would be more optimal :).

    I would like an easier way to edit shared configs in general, though. I’ve always thought the default config structure should be a shared config with TargetName, imports, defines, etc…, and Debug and Release configs which extend the shared config, adding _DEBUG, /o2, etc…. Now the vcxproj format lets us do that, but we need to edit xml like it’s 1999 – unless I’m missing something?

  30. Aleria says:

    It makes little sense that GLOBAL paths are project specific. There are project-only paths, as well and it does make sense to be able to edit those in the project options.

  31. Olaf van der Spek says:

    Previous VC versions allowed per-project include and lib paths already, right?

    The main improvement appears to be clean up of where those settings get stored.

    However, the feature (global paths) is unfindable right now.

    I agree with the presentation and storage as well, this needs to be improved.