Project Class

Reference

Definition

Namespace:: Microsoft.Build.BuildEngine

Assembly:: Microsoft.Build.Engine.dll

Package:: Microsoft.Build.Engine v17.11.4

Source:: Project.cs

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Caution

This class has been deprecated. Please use Microsoft.Build.Evaluation.Project from the Microsoft.Build assembly instead.

This class represents an MSBuild project. It is a container for items, properties, and targets. It can load in project content from in-memory XML or from an XML file, and it can save to an XML file, preserving most whitespace and all XML comments.

All Project objects must be associated with an Engine object, in order to get at the loggers and other shared information. Also, when doing a "build", the Engine needs to keep track of which projects are currently building.

public ref class Project

[System.Obsolete("This class has been deprecated. Please use Microsoft.Build.Evaluation.Project from the Microsoft.Build assembly instead.")]
public class Project

public class Project

[<System.Obsolete("This class has been deprecated. Please use Microsoft.Build.Evaluation.Project from the Microsoft.Build assembly instead.")>]
type Project = class

type Project = class

Public Class Project

Inheritance: Object
Project

Attributes: ObsoleteAttribute

Remarks

A Project represents an MSBuild project. It is a container for items, properties and targets. It can load project content from in-memory XML or from an XML file, and can save to an XML file, preserving most white space and all XML comments.

Every Project must be associated with an Engine to access shared information. During a build, the Engine object keeps track of which projects are currently building.

Constructors

Project()	This default constructor creates a new Project object associated with the global Engine object.
Project(Engine, String)	Creates an instance of this class for the given engine, specifying a tools version to use during builds of this project.
Project(Engine)	Creates an instance of this class for the given engine.

Properties

BuildEnabled	This controls whether or not the building of targets/tasks is enabled for this project. This is for security purposes in case a host wants to closely control which projects it allows to run targets/tasks. By default, for a newly created project, we will use whatever setting is in the parent engine.
DefaultTargets	Read-write accessor for the "DefaultTargets" attribute of the <Project> element. This is passed in and out as a semicolon-separated list of target names.
DefaultToolsVersion	Public read-write accessor for the ToolsVersion xml attribute found on the <Project /> element. If this attribute is not present on the <Project/> element, getting the value will return the default tools version of the parent Engine. NOTE: This value is distinct from the effective tools version used during a build, as that value may be overridden during construction of the Project instance or by setting the Project.ToolsVersion property. Setting this attribute value will not change the effective tools version if it has been overridden. To change the effective tools version, set the Project.ToolsVersion property.
Encoding	Internal method for getting the project file encoding. When we have the managed vsproject assembly, this should be made public.
EvaluatedItems	Read-only accessor for the final collection of evaluated items, taking into account all conditions and property expansions. Through this collection, the caller can modify any of the items present, and it will be reflected in the project file the next time it is saved. However, adding or deleting items from this collection will not impact the project.
EvaluatedItemsIgnoringCondition	Read-only accessor for the collection of evaluated items, taking into account property expansions and wildcards, but ignoring "Condition"s. This way, an IDE can display all items regardless of whether they're relevant for a particular build flavor or not. Through this collection, the caller can modify any of the items present, and it will be reflected in the project file the next time it is saved. However, adding or deleting items from this collection will not impact the project. See the comments for the "evaluatedItemsIgnoringCondition" member variable up above.
EvaluatedProperties	Read-only accessor for the final set of evaluated properties for this project. This takes into account all conditions and property expansions, and gives back a single linear collection of project-level properties, which includes global properties, environment variable properties, reserved properties, and normal/imported properties. Through this collection, the caller can modify any normal properties, and the changes will be reflected in the project file when it is saved again. However, adding or deleting properties from this collection will not impact the project. PERF WARNING: cloning a BuildPropertyGroup can be very expensive -- use only when a copy of the entire property bag is strictly necessary
FullFileName	Gets or sets the fully qualified path + filename of the project file. This could be empty-string if the project doesn't have a file associated with it -- for example, if we were given the XML in memory.
GlobalProperties	Read-write accessor for the project's global properties collection. To set or modify global properties, a caller can hand us an entire new BuildPropertyGroup here, or can simply modify the properties in the BuildPropertyGroup that is already here. Global properties are those defined via the "/p:" switch on the MSBuild.exe command-line, or properties like "Configuration" set by the IDE prior to invoking MSBuild.
HasToolsVersionAttribute	Public read accessor to determine if the Project file has the ToolsVersion xml attribute e.g. <Project ToolsVersion="3.5"/> . This is different to knowing the inherited value and allows us to spot Whidbey (VS 8.0) projects.
Imports	Read-only accessor for the imported projects of this project
InitialTargets	Read-write accessor for the "InitialTargets" attribute of the <Project> element. This is passed in and out as a semicolon-separated list of target names. The "get" returns all of the initial targets in both the main project and all imported projects (after property expansion). The "set" only sets the initial targets for the main project.
IsDirty	Tells you whether this project file is dirty such that it would need to get saved to disk.
IsValidated	Indicates if the project (file) is to be validated against a schema.
ItemGroups	Read-only accessor for the raw item groups of this project. This is essentially a reflection of the data in the XML for this project's items as well as any <Import>'d projects.
ParentEngine	Gets the parent engine object.
PropertyGroups	Read-only accessor for the raw property groups of this project. This is essentially a reflection of the data in the XML for this project's properties as well as any <Import>'d projects.
SchemaFile	The schema against which the project (file) and all its imported files are validated.
Targets	Read-only accessor for the target groups of this project.
TimeOfLastDirty	Returns the timestamp of when the project was last touched in a way that would require it to need to be saved.
ToolsVersion	When gotten, returns the effective tools version being used by this project. If the tools version is being overridden, the overriding value will be the effective tools version. Otherwise, if there is a ToolsVersion attribute on the Project element, that is the effective tools version. Otherwise, the default tools version of the parent engine is the effective tools version. When set, overrides the current tools version of this project with the provided value. NOTE: This is distinct to the ToolsVersion attribute, if any, on the Project element. To get and set the ToolsVersion attribute on the Project element use the Project.DefaultToolsVersion property.
UsingTasks	Read-only accessor for the UsingTask elements of this project.
Xml	Read-only accessor for the string of Xml representing this project. Used for verification in unit testing.

Methods

AddNewImport(String, String)	Adds a new <Import> element to the end of the project.
AddNewItem(String, String, Boolean)	Adds a new item to the project, and optionally escapes the Include value so it's treated as a literal value.
AddNewItem(String, String)	Called from the IDE to add a new item of a particular type to the project file. This method tries to add the new item near the other items of the same type.
AddNewItemGroup()	Adds a new <ItemGroup> element to the project, and returns the corresponding BuildItemGroup object which can then be populated with items or anything else that might belong inside an <ItemGroup>.
AddNewPropertyGroup(Boolean)	Adds a new <PropertyGroup> element to the project, and returns the corresponding BuildPropertyGroup object which can then be populated with properties.
AddNewUsingTaskFromAssemblyFile(String, String)	Adds a new <UsingTask> element to the end of the project
AddNewUsingTaskFromAssemblyName(String, String)	Adds a new <UsingTask> element to the end of the project
Build()	Builds the default targets in this project.
Build(String)	Builds the specified target in this project.
Build(String[], IDictionary, BuildSettings)	Builds the specified list of targets in this project using the specified flags, and returns the target outputs.
Build(String[], IDictionary)	Builds the specified list of targets in this project, and returns the target outputs.
Build(String[])	Builds the specified list of targets in this project.
GetConditionedPropertyValues(String)	This returns a list of possible values for a particular property. It gathers this list by looking at all of the "Condition" attributes in the project file.
GetEvaluatedItemsByName(String)	Retrieves a group of evaluated items of a particular item type.
GetEvaluatedItemsByNameIgnoringCondition(String)	Retrieves a group of evaluated items of a particular item type. This is really just about the items that are persisted in the project file, ignoring all "Condition"s, so that an IDE can display all items regardless of whether they're relevant for a particular build flavor or not.
GetEvaluatedProperty(String)	Returns a single evaluated property value. Call this to retrieve a few properties. If you need to retrieve many properties use EvaluatedProperty accessor.
GetProjectExtensions(String)	Returns the project extensions string for the given ID.
Load(String, ProjectLoadSettings)	Reads in the contents of this project from a project XML file on disk.
Load(String)	Reads in the contents of this project from a project XML file on disk.
Load(TextReader, ProjectLoadSettings)	Reads in the contents of this project from a string containing the Xml contents.
Load(TextReader)	Reads in the contents of this project from a string containing the Xml contents.
LoadXml(String, ProjectLoadSettings)	Reads in the contents of this project from a string containing the Xml contents.
LoadXml(String)	Reads in the contents of this project from a string containing the Xml contents.
MarkProjectAsDirty()	This forces a re-evaluation of the project the next time somebody calls EvaluatedProperties or EvaluatedItems. It is also a signal that the project file is dirty and needs to be saved to disk.
RemoveAllItemGroups()	Removes all <ItemGroup>'s from the main project file, but doesn't touch anything in any of the imported project files.
RemoveAllPropertyGroups()	Removes all <PropertyGroup>'s from the main project file, but doesn't touch anything in any of the imported project files.
RemoveImportedPropertyGroup(BuildPropertyGroup)	Removes a <PropertyGroup> from the main project file.
RemoveItem(BuildItem)	Removes an item from the main project file.
RemoveItemGroup(BuildItemGroup)	Removes a <ItemGroup> from the main project file.
RemoveItemGroupsWithMatchingCondition(String)	Removes all <ItemGroup>'s from the main project file that have a specific "Condition". This will not remove any item groups from imported project files.
RemoveItemsByName(String)	Removes all items of a particular type from the main project file.
RemovePropertyGroup(BuildPropertyGroup)	Removes a <PropertyGroup> from the main project file.
RemovePropertyGroupsWithMatchingCondition(String, Boolean)	Removes all <PropertyGroup>'s from the main project file that have a specific "Condition". This will not remove any property groups from imported project files.
RemovePropertyGroupsWithMatchingCondition(String)	Removes all <PropertyGroup>'s from the main project file that have a specific "Condition". This will not remove any property groups from imported project files.
ResetBuildStatus()	Resets the state of each target in this project back to "NotStarted", so that a subsequent build will actually build those targets again.
Save(String, Encoding)	Saves the current contents of the project to an XML project file on disk using the supplied encoding.
Save(String)	Saves the current contents of the project to an XML project file on disk. This method will NOT add the ?xml node if it's not already present
Save(TextWriter)	Saves the current contents of the project to a TextWriter object.
SetImportedProperty(String, String, String, Project, PropertyPosition, Boolean)	Set a property at a particular position inside an imported project file. The property will be in a group that has the specified condition. If necessary, a new property or property group will be created.
SetImportedProperty(String, String, String, Project, PropertyPosition)	Set a property at a particular position inside an imported project file. The property will be in a group that has the specified condition. If necessary, a new property or property group will be created.
SetImportedProperty(String, String, String, Project)	Sets the value of a property that comes from an imported project. Updates the current project (the one this method is called on) with a property that has no Xml behind it, and updates the imported project with a real backed property.
SetProjectExtensions(String, String)	Sets the project extensions string.
SetProperty(String, String, String, PropertyPosition, Boolean)	Sets a property, and optionally escapes it so that it will be treated as a literal value despite any special characters that may be in it.
SetProperty(String, String, String, PropertyPosition)	Set a property at a particular position inside the project file. The property will be in a group that has the specified condition. If necessary, a new property or property group will be created.
SetProperty(String, String, String)	This method is called from the IDE to set a particular property at the project level. The IDE doesn't care which property group it's in, as long as it gets set. This method will search the existing property groups for a property with this name. If found, it will change the value in place. Otherwise, it will either add a new property to that property group, or possibly even add a new property group to the project. This method also takes the "Condition" string for the property group that the IDE wants this property placed under.
SetProperty(String, String)	Sets (or adds) a property to the project at a sensible location.

Applies to

Share via