<\/p>\n
What is the purpose of this ordered layout? Why are there multiple property groups (import groups, etc.) instead of only one? Well, read on.<\/span><\/span><\/p>\n \u00a0<\/span><\/p>\n The concept of an ordered layout is a natural outcome of MSBuild\u2019s sequential evaluation model. \u00a0If your project file consists of two definitions of a property, such as below, the last definition overrides the preceding ones. So, the value \u201cxyz\u201d will be used during build time. <\/span><\/span><\/p>\n \n <MyProperty>abc<\/MyProperty><\/p>\n <MyProperty>xyz<\/MyProperty><\/p>\n \n The first property definition need not necessarily be in the project file itself. You could have included it via some import that is imported before the second definition of the property. What I say about properties here is also true about item definition metadata (in general, this holds true for the entire article).<\/span><\/span><\/p>\n <\/p>\n Having said that, let me now show you the layout. The following skeletal (but legal) MSBuild file captures the layout succinctly. Any .vcxproj file generated by VS will contain these top-level MSBuild elements and in this particular order (although they may contain multiple copies of each such top-level element). Note that Labels are arbitrary tags only read and written by Visual Studio and used as signposts for editing; they have no other function.<\/span><\/span><\/p>\n <Project DefaultTargets=”Build” ToolsVersion=”4.0″ xmlns=’http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003′ ><\/p>\n \u00a0 <ItemGroup Label=”ProjectConfigurations” \/><\/p>\n \u00a0 <PropertyGroup Label=”Globals” \/><\/p>\n \u00a0 <Import Project=”$(VCTargetsPath)Microsoft.Cpp.default.props” \/><\/p>\n \u00a0 <PropertyGroup Label=”Configuration” \/><\/p>\n \u00a0 <Import Project=”$(VCTargetsPath)Microsoft.Cpp.props” \/><\/p>\n \u00a0 <ImportGroup Label=”ExtensionSettings” \/><\/p>\n \u00a0 <ImportGroup Label=”PropertySheets” \/><\/p>\n \u00a0 <PropertyGroup Label=”UserMacros” \/><\/p>\n \u00a0 <PropertyGroup \/><\/p>\n \u00a0 <ItemDefinitionGroup \/><\/p>\n \u00a0 <ItemGroup \/><\/p>\n \u00a0 <Import Project=”$(VCTargetsPath)Microsoft.Cpp.targets” \/><\/p>\n \u00a0 <ImportGroup Label=”ExtensionTargets” \/><\/p>\n <\/Project><\/p>\n <\/p>\n Let me explain what each of these elements are and why they are ordered this way.<\/p>\n <\/p>\n <!– This is the root node. It specifies the MSBuild version to use<\/p>\n and also the default target to be executed when this file is passed<\/p>\n to MSBuild.exe –><\/p>\n <Project DefaultTargets=”Build” ToolsVersion=”4.0″ xmlns=’http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003′ ><\/p>\n \u00a0 <!– This contains the project configurations known to the project<\/p>\n \u00a0 (such as Debug|Win32 and Release|Win32). –><\/p>\n \u00a0 <ItemGroup Label=”ProjectConfigurations” \/><\/p>\n \u00a0 <!– This contains project level settings such as ProjectGuid,<\/p>\n \u00a0 RootNamespace, etc. These properties are not normally overridden<\/p>\n \u00a0\u00a0elsewhere in the project file. This group is not configuration<\/p>\n \u00a0 dependent and so only one Globals group generally exists in the<\/p>\n \u00a0\u00a0project file. –><\/p>\n \u00a0 <PropertyGroup Label=”Globals” \/><\/p>\n \u00a0 <!– This property sheet contains the default settings for a VC++<\/p>\n \u00a0\u00a0project. It contains\u00a0definitions of all the project settings such<\/p>\n \u00a0\u00a0as Platform, PlatformToolset, OutputPath, TargetName, UseOfAtl,<\/p>\n \u00a0 etc. and also all the item definition group defaults for each known<\/p>\n \u00a0 item group. In general, properties in this file are not tool-specific. –><\/p>\n \u00a0 <Import Project=”$(VCTargetsPath)Microsoft.Cpp.default.props” \/><\/p>\n \u00a0 <!– This property group has an attached configuration condition<\/p>\n \u00a0 (such as Condition=”‘$(Configuration)|$(Platform)’==’Debug|Win32′”)<\/p>\n \u00a0\u00a0and comes in multiple\u00a0copies, one per configuration. This property<\/p>\n \u00a0\u00a0group hosts configuration-wide properties.\u00a0These properties control<\/p>\n \u00a0\u00a0the inclusion of system property sheets in Microsoft.Cpp.props.<\/p>\n \u00a0 E.g. if we define the property <CharacterSet>Unicode<\/CharacterSet>,<\/p>\n \u00a0\u00a0then the system\u00a0property sheet microsoft.Cpp.unicodesupport.props<\/p>\n \u00a0 will be included (as can be seen in the Property Manager). Indeed,<\/p>\n \u00a0\u00a0in one of the imports of Microsoft.Cpp.props, we can see the line:<\/p>\n \u00a0 <Import Condition=”‘$(CharacterSet)’ == ‘Unicode'”\u00a0\u00a0 Project=”$(VCTargetsPath)microsoft.Cpp.unicodesupport.props”\/> –><\/p>\n \u00a0 <PropertyGroup Label=”Configuration” \/><\/p>\n \u00a0 <!– This property sheet (directly or via imports) defines the<\/p>\n \u00a0 default values for many tool-specific properties such as the<\/p>\n \u00a0 compiler\u2019s Optimization, WarningLevel properties, Midl tool\u2019s<\/p>\n \u00a0\u00a0TypeLibraryName property, etc. In addition, it imports various<\/p>\n \u00a0\u00a0system property\u00a0sheets based on configuration properties defined<\/p>\n \u00a0\u00a0in the property group immediately above. –><\/p>\n \u00a0 <Import Project=”$(VCTargetsPath)Microsoft.Cpp.props” \/><\/p>\n \u00a0 <!– This group contains imports for the property sheets that<\/p>\n \u00a0\u00a0are part of Build Customizations (or Custom Build Rules as this<\/p>\n \u00a0\u00a0feature was called in earlier editions). A Build Customization<\/p>\n \u00a0 is defined by up to three files \u2013 a .targets file, a .props file<\/p>\n \u00a0\u00a0and .xml file. This import\u00a0group contains the imports for the<\/p>\n \u00a0.props file. –><\/p>\n \u00a0 <ImportGroup Label=”ExtensionSettings” \/><\/p>\n \u00a0 <!– This group contains the imports for user property sheets.<\/p>\n \u00a0\u00a0These are the property sheets you add through the Property<\/p>\n \u00a0 Manager view in VS. The order in which these imports are listed<\/p>\n \u00a0 is relevant and is reflected in the Property Manager. The project<\/p>\n \u00a0\u00a0file normally contains multiple instances of this kind of import<\/p>\n \u00a0\u00a0group, one for each project configuration.\u00a0 –><\/p>\n \u00a0 <ImportGroup Label=”PropertySheets” \/><\/p>\n \u00a0 <!– UserMacros are as variables used to customize your build<\/p>\n \u00a0 process. E.g. you can define\u00a0a user macro to define your custom<\/p>\n \u00a0\u00a0output path as $(CustomOutpuPath) and use it to define other<\/p>\n \u00a0 variables. This property group houses such properties. Note that<\/p>\n \u00a0\u00a0in VS2010, this group is not populated by the IDE since we do not<\/p>\n \u00a0\u00a0support user macros for configurations (we do for property sheets<\/p>\n \u00a0\u00a0though). –><\/p>\n \u00a0 <PropertyGroup Label=”UserMacros” \/><\/p>\n \u00a0 <!– This property group normally comes with a configuration<\/p>\n \u00a0 condition attached. You will also\u00a0see multiple instances of the<\/p>\n \u00a0 property group, one per configuration. It differs in its identity<\/p>\n \u00a0 from the other property groups above by the fact that it does<\/p>\n \u00a0 not have a label (to look at it in another way, it has a label<\/p>\n \u00a0 that is equal to the empty string). This group contains project<\/p>\n \u00a0 configuration level settings. These settings apply to all files<\/p>\n \u00a0\u00a0that are part of the specified item group. Build Customization<\/p>\n \u00a0\u00a0item definition metadata also gets initialized here. –><\/p>\n \u00a0 <PropertyGroup \/><\/p>\n \u00a0 <!– Similar to the property group immediately above, but it<\/p>\n \u00a0 contains item definitions and item\u00a0definition metadata instead<\/p>\n \u00a0\u00a0of properties. –><\/p>\n \u00a0 <ItemDefinitionGroup \/><\/p>\n \u00a0 <!– Contains the items (source files, etc.) in the project.<\/p>\n \u00a0 You will generally have multiple item groups \u2013 one per item<\/p>\n \u00a0\u00a0type. –><\/p>\n \u00a0 <ItemGroup \/><\/p>\n \u00a0 <!– Defines (directly or via imports) VC++ targets such as<\/p>\n \u00a0\u00a0build, clean, etc. –><\/p>\n \u00a0 <Import Project=”$(VCTargetsPath)Microsoft.Cpp.targets” \/><\/p>\n \u00a0 <!– This group contains imports for the Build Customization<\/p>\n \u00a0\u00a0target files. –><\/p>\n \u00a0 <ImportGroup Label=”ExtensionTargets” \/><\/p>\n <\/Project><\/p>\n \n The above ordering ensures that editing the project file via that IDE gives expected results. E.g. when you define a property value in the property pages, the IDE will generally place the property definition in the property group with the empty label. This ensures that default values brought in the system property sheets are overridden by user defined values. Similarly, the target files are imported at the end since they consume the properties defined above and since they generally do not define properties themselves. Likewise, user property sheets are imported after the system property sheets (included via <\/span>Microsoft.Cpp.props). This ensures that the user can override any defaults brought in by the system property sheets.<\/span><\/span><\/p>\n \u00a0<\/span><\/p>\n If a .vcxproj file does not follow this layout, the build results may not be like you expected. E.g. properties defined by the user using property pages may not be used during the build since they could have been overridden by the system property sheets in this different layout.<\/span><\/span><\/p>\n \u00a0<\/span><\/p>\n Even the IDE design time experience may suffer, although VS does its best to work with any .vcxproj file. If your .vcxproj file does not have, say, the <\/span>PropertySheets import group, then you will not see any user property sheets in the Property Manager view (you might still see the system property sheets though). However, when you add a property sheet from the Property Manager view, then VS will create one such labeled import group for you at the right place in the .vcxproj file and add the import for the new property sheet. If however, your .vcxproj has a layout very different from the one described above, VS may not know what the right place is so it may end up creating it at an arbitrary location. In general, the heuristic used by VS IDE should work well for minor to moderate inconsistencies in the .vcxproj file layout.<\/span><\/span><\/p>\n \u00a0<\/span><\/p>\n You may want to know how VS magically knows where to write a particular property. E.g. when you set <\/span>UseOfAtl property in the general property page, it gets written to <\/span>Configuration property group whereas the <\/span>TargetName property in the same general property page gets written to the label-less property group.\u00a0 That is told to VS by the property itself. Well actually by the property schema in the <\/span>property page xml<\/span><\/a> file. Recall that property page xml defines the static information about a Rule and all its properties. One such piece of information is the preferred position of a Rule property in the destination file (the file where its value will be written). The preferred position is defined by taking advantage of the existence of Labels. Labels are used to distinguish the various top-level elements of the same type (such as two property groups).\u00a0\u00a0 Thus, a property can declare in the property page xml file, which of the property groups it would like to be housed in when the time comes for it to be defined in the project file. <\/span><\/span><\/p>\n \u00a0<\/span><\/p>\n Finally, here is the skeletal MSBuild file that will illustrate the file layout of a property sheet (.props) file in VS2010. The functionality of the layout elements can be inferred based on the discussion above.<\/span><\/span><\/p>\n \u00a0<\/span><\/p>\n <Project ToolsVersion=”4.0″ xmlns=”http:\/\/schemas.microsoft.com\/developer\/msbuild\/2003″><\/p>\n \u00a0 <ImportGroup Label=”PropertySheets” \/><\/p>\n \u00a0 <PropertyGroup Label=”UserMacros” \/><\/p>\n \u00a0 <PropertyGroup \/><\/p>\n \u00a0 <ItemDefinitionGroup \/><\/p>\n \u00a0 <ItemGroup \/><\/p>\n <\/Project><\/p>\n \u00a0<\/span><\/p>\n To summarize, the ordered layout of .vcxproj and .props files comports with MSBuild sequential evaluation model. The use of Labels helps the IDE in reading element definitions from and writing them to the right location in the file.<\/span><\/span><\/p>\n
![\"Pavan](\"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-content\/uploads\/sites\/4\/2010\/05\/Pavan202_thumb_1-1.png\" "\\"Pavan")
<\/a>Short Bio:<\/strong> Pavan Adharapurapu is a developer on the Visual Studio Project and Build team. As part of VS 2010, he has worked on numerous features of the VC++ project system such as property sheets, filters, property pages, platform and tool extensibility, etc. His long term focus is on developing a “common project system” infrastructure which could be used to quickly build richly featured project systems. Prior to joining the Visual Studio team in 2008, he was working on Workflow technologies in Microsoft Dynamics Axapta. Pavan holds a Masters degree in Computer Science (CS) from the University of California, Los Angeles (UCLA) and a Bachelors degree in CS from the Indian Institute of Technology (IIT), Madras. He lives in Redmond, WA with his wife and loves to play soccer and watch movies in his spare time.<\/p>\n