Visual Studio Integration (MSBuild)
Visual Studio 2005 hosts MSBuild to load and build managed projects. Because MSBuild is responsible for the project, almost any project in the MSBuild format can be successfully used in Visual Studio, even if the project was authored by a different tool and has a customized build process.
This topic describes specific aspects of Visual Studio's MSBuild hosting that should be considered when customizing projects and .targets files that you wish to load and build in Visual Studio. These will help you make sure Visual Studio features like IntelliSense and debugging work for your custom project.
Project File Name Extensions
MSBuild.exe recognizes any project file name extension matching the pattern .*proj. However, Visual Studio only recognizes a subset of these project file name extensions, which determine the language-specific project system that will load the project. Visual Studio does not have a language-neutral MSBuild based project system.
For example, the Visual C# project system loads .csproj files, but Visual Studio is not able to load a .xxproj file. A project file for source files in an arbitrary language must use the same extension as Visual Basic, Visual C#, or Visual J# project files to be loaded in Visual Studio.
Well-Known Target Names
Clicking the Build command in Visual Studio will execute the default target in the project. Often, this target is also named Build. Choosing the Rebuild or Clean command will attempt to execute a target of the same name in the project. Clicking Publish will execute a target named PublishOnly in the project.
Configurations and Platforms
Configurations are represented in MSBuild projects by properties grouped in a PropertyGroup element that contains a Condition attribute. Visual Studio looks at these conditions in order to create a list of project configurations and platforms to display. To successfully extract this list, the conditions must have a format similar to the following:
Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' "
Condition=" '$(Configuration)' == 'Release' "
Condition=" '$(Something)|$(Configuration)|$(SomethingElse)' == 'xxx|Debug|yyy' "
Visual Studio looks at the conditions on PropertyGroup, ItemGroup, Import, property, and item elements for this purpose.
Additional Build Actions
Visual Studio allows you to change the item collection name of a file in a project with the Build Action property of the File Properties window. Compile, EmbeddedResource, Content, and None item collection names are always listed in this menu, along with any other item collection names already in your project. To ensure any custom item collection names are always available in this menu, you can add the names to an item collection named AvailableItemName. For example, adding the following to your project file will add the custom type JScript to this menu for all projects that import it:
<ItemGroup>
<AvailableItemName Include="JScript"/>
</ItemGroup>
Note
Some item collection names are special to Visual Studio but not listed in this dropdown.
In-Process Compilers
When possible, Visual Studio will attempt to use the in-process versions of the Visual Basic or Visual C# compilers for increased performance. For this to work correctly, the following conditions must be met:
In a target of the project, there must be a task named Csc (for Visual C# projects) or Vbc (for Visual Basic projects)
The UseHostCompilerIfAvailable parameter of the task must be set to true.
Only supported parameter values must be specified. All parameters specified on the task are supported by the in-process compiler, but some parameter values are unsupported. The following Csc task parameter values are not supported by the Visual C# in-process compiler:
NoConfig: false and empty values are unsupported.
ResponseFiles: non-empty values are unsupported.
AdditionalLibPaths: non-empty values are unsupported.
AddModules: non-empty values are unsupported.
CodePage: non-zero values are unsupported.
GenerateFullPaths: true is unsupported.
LinkResources: non-empty values are unsupported.
If these conditions are not met, the project will compile using the command line compiler instead of the in-process compiler.
Design-Time IntelliSense
To get IntelliSense support in Visual Studio before a build has generated an output assembly, the following conditions must be met:
There must be a target named Compile.
Either the Compile target or one of its dependencies must call the compiler task for the project, such as Csc or Vbc.
Either the Compile target or one of its dependencies must cause the compiler to receive all the necessary parameters for IntelliSense, particularly all references.
The conditions listed in the "In-Process Compilers" section must be met.
Building Solutions
Within Visual Studio, the solution file and project build ordering are controlled by Visual Studio itself. When building a solution with msbuild.exe on the command line, MSBuild parses the solution file and orders the project builds. In both cases the projects are built individually in dependency order, and project to project references are not traversed. In contrast, when individual projects are built with msbuild.exe, project to project references are traversed.
When building inside Visual Studio, the property $(BuildingInsideVisualStudio) is set to true. This can be used in your project or .targets files to cause the build to behave differently.
Displaying Properties and Items
Visual Studio recognizes certain property names and values. For example, the following property in a project will cause Windows Application to appear in the Application Type box in the Project Designer.
<OutputType>WinExe</OutputType>
The property value can be edited in the Project Designer and saved in the project file. If such a property is given an invalid value by hand-editing, Visual Studio will show a warning when the project is loaded and replace the invalid value with a default value.
Visual Studio understands defaults for some properties. These properties will not be persisted into the project file unless they have non-default values.
Properties with arbitrary names are not displayed in Visual Studio. To modify arbitrary properties in Visual Studio, you must open the project file in the XML editor and edit them by hand. For more information, see How to: Edit Project Files.
Items defined in the project with arbitrary item collection names are by default displayed in the Solution Explorer under their project node. To hide an item from display, set the Visible metadata to false. For example, the following item will participate in the build process but not be displayed in Solution Explorer.
<ItemGroup>
<IntermediateFile Include="cache.temp">
<Visible>false</Visible>
</IntermediateFile>
</ItemGroup>
Items declared in files imported into the project are not displayed by default. Items created during the build process are never displayed in Solution Explorer.
Conditions on Items and Properties
During a build, all conditions are fully respected.
When determining property values to display, properties that Visual Studio considers configuration dependent are evaluated differently than properties it considers configuration independent. For properties it considers configuration dependent, Visual Studio sets the Configuration and Platform properties appropriately and instructs MSBuild to re-evaluate the project. For properties it considers configuration independent, it is indeterminate how conditions will be evaluated.
Conditional expressions on items are always ignored for the purposes of deciding whether the item should be displayed in Solution Explorer.
Debugging
In order to find and launch the output assembly and attach the debugger, Visual Studio needs the properties OutputPath, AssemblyName, and OutputType correctly defined. The debugger will fail to attach if the build process did not cause the compiler to generate a .pdb file.
Design-Time Target Execution
Visual Studio attempts to execute targets with certain names when it loads a project. These targets include Compile, ResolveAssemblyReferences, ResolveCOMReferences, GetFrameworkPaths, and CopyRunEnvironmentFiles. Visual Studio runs these targets so that the compiler can be initialized to provide IntelliSense, the debugger can be initialized, and references displayed in Solution Explorer can be resolved. If these targets are not present, the project will load and build correctly but the design-time experience in Visual Studio will not be fully functional.
Editing Project Files in Visual Studio
When it is necessary to edit an MSBuild project directly, you can open the project file in the Visual Studio XML editor. For more information, see How to: Edit Project Files.
IntelliSense and Validation
When using the XML editor to edit project files, IntelliSense and validation is driven by the MSBuild schema files. These are installed by Visual Studio in the schema cache, which can be found in the [Visual Studio installation location]\Xml\Schemas folder.
The core MSBuild types are defined in Microsoft.Build.Core.xsd and common types used by Visual Studio are defined in Microsoft.Build.CommonTypes.xsd. To customize the schemas so that you have IntelliSense and validation for custom item collection names, properties, and tasks, you can either edit Microsoft.Build.xsd, or create your own schema that includes the CommonTypes or Core schemas. If you create your own schema you will have to direct the XML editor to find it using the Properties window.
Editing Loaded Project Files
Visual Studio caches the content of project files and files imported by project files. If you edit a loaded project file, Visual Studio will automatically prompt you to reload the project so that the changes take effect. However if you edit a file imported by a loaded project, there will be no reload prompt and you must unload and reload the project manually to make the changes take effect.
Output Groups
Several targets defined in Microsoft.Common.targets have names ending in OutputGroups or OutputGroupDependencies. Visual Studio calls these targets to get specific lists of project outputs. For example, the SatelliteDllsProjectOutputGroup target creates a list of all the satellite assemblies a build will create. These output groups are used by features like publishing, deployment, and project to project references. Projects that do not define them will load and build in Visual Studio, but some features may not work correctly.
Reference Resolution
Reference resolution is the process of using the reference items stored in a project file to locate actual assemblies. Visual Studio must trigger reference resolution in order to show detailed properties for each reference in the Properties window. The following list describes the three types of references and how they are resolved.
Assembly references:
The project system calls a target with the well-known name ResolveAssemblyReferences. This target should produce items with the item collection name ReferencePath. Each of these items should have an item specification (the value of the Include attribute of an item) containing the full path to the reference. The items should have all the metadata from the input items passed through in addition to the following new metadata:
CopyLocal, indicating whether the assembly should be copied into the output folder, set to true or false.
OriginalItemSpec, containing the original item specification of the reference.
ResolvedFrom, set to "{TargetFrameworkDirectory}" if it was resolved from the .NET Framework directory.
COM references:
The project system calls a target with the well-known name ResolveCOMReferences. This target should produce items with the item collection name ComReferenceWrappers. Each of these items should have an item specification containing the full path to the interop assembly for the COM reference. The items should have all the metadata from the input items passed through, in addition to new metadata with the name CopyLocal, indicating whether the assembly should be copied into the output folder, set to true or false
Native references
The project system calls a target with the well-known name ResolveNativeReferences. This target should produce items with the item collection name NativeReferenceFile. The items should have all the metadata from the input items passed through, in addition to a new piece of metadata named OriginalItemSpec, containing the original item specification of the reference.