Project Class

Definition

Namespace:

Microsoft.Build.Evaluation

Assembly:

Microsoft.Build.dll

Package:

Microsoft.Build v17.11.4

Source:

Project.cs

Represents an evaluated project with design time semantics. Always backed by XML; can be built directly, or an instance can be cloned off to add virtual items/properties and build. Edits to this project always update the backing XML.

public ref class Project

public class Project

type Project = class

Public Class Project

Inheritance

Object

Project

Remarks

UNDONE: (Multiple configurations.) Protect against problems when attempting to edit, after edits were made to the same ProjectRootElement either directly or through other projects evaluated from that ProjectRootElement.

Constructors

Project()	Construct an empty project, evaluating with the global project collection's global properties and default tools version. Project will be added to the global project collection when it is named.
Project(IDictionary<String,String>, String, ProjectCollection, NewProjectFileOptions)	Construct an empty project, evaluating with the specified project collection and the specified global properties and default tools version, either of which may be null. Project will be added to the specified project collection when it is named.
Project(IDictionary<String,String>, String, ProjectCollection)	Construct an empty project, evaluating with the specified project collection and the specified global properties and default tools version, either of which may be null. Project will be added to the specified project collection when it is named.
Project(NewProjectFileOptions)	Construct an empty project, evaluating with the global project collection's global properties and default tools version. Project will be added to the global project collection when it is named.
Project(ProjectCollection, NewProjectFileOptions)	Construct an empty project, evaluating with the specified project collection's global properties and default tools version. Project will be added to the specified project collection when it is named.
Project(ProjectCollection)	Construct an empty project, evaluating with the specified project collection's global properties and default tools version. Project will be added to the specified project collection when it is named.
Project(ProjectRootElement, IDictionary<String,String>, String, ProjectCollection, ProjectLoadSettings)	Construct over a ProjectRootElement object, evaluating with specified global properties and toolset, either or both of which may be null. Project is added to the global project collection if it has a name, or else when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(ProjectRootElement, IDictionary<String,String>, String, ProjectCollection)	Construct over a ProjectRootElement object, evaluating with specified global properties and toolset, either or both of which may be null. Project is added to the global project collection if it has a name, or else when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(ProjectRootElement, IDictionary<String,String>, String, String, ProjectCollection, ProjectLoadSettings)	Construct over a ProjectRootElement object, evaluating with specified global properties and toolset, either or both of which may be null. Project is added to the global project collection if it has a name, or else when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(ProjectRootElement, IDictionary<String,String>, String)	Construct over a ProjectRootElement object, evaluating with specified global properties and toolset, either or both of which may be null. Project is added to the global project collection if it has a name, or else when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(ProjectRootElement)	Construct over a ProjectRootElement object, evaluating with the global project collection's global properties and default tools version. Project is added to the global project collection if it has a name, or else when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(String, IDictionary<String,String>, String, ProjectCollection, ProjectLoadSettings)	Construct over an existing project file, evaluating with the specified global properties and using the tools version provided, either or both of which may be null. Project is added to the global project collection. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection. May throw IO-related exceptions.
Project(String, IDictionary<String,String>, String, ProjectCollection)	Construct over an existing project file, evaluating with the specified global properties and using the tools version provided, either or both of which may be null. Project is added to the global project collection. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection. May throw IO-related exceptions.
Project(String, IDictionary<String,String>, String, String, ProjectCollection, ProjectLoadSettings)	Construct over an existing project file, evaluating with the specified global properties and using the tools version provided, either or both of which may be null. Project is added to the global project collection. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection. May throw IO-related exceptions.
Project(String, IDictionary<String,String>, String)	Construct over an existing project file, evaluating with specified global properties and toolset, either or both of which may be null. Project is added to the global project collection. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection. May throw IO-related exceptions.
Project(String)	Construct over an existing project file, evaluating with the global project collection's global properties and default tools version. Project is added to the global project collection. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection. May throw IO-related exceptions.
Project(XmlReader, IDictionary<String,String>, String, ProjectCollection, ProjectLoadSettings)	Construct over a text reader over project xml, evaluating with specified global properties and toolset, either or both of which may be null. Project will be added to the specified project collection when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(XmlReader, IDictionary<String,String>, String, ProjectCollection)	Construct over a text reader over project xml, evaluating with specified global properties and toolset, either or both of which may be null. Project will be added to the specified project collection when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(XmlReader, IDictionary<String,String>, String, String, ProjectCollection, ProjectLoadSettings)	Construct over a text reader over project xml, evaluating with specified global properties and toolset, either or both of which may be null. Project will be added to the specified project collection when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(XmlReader, IDictionary<String,String>, String)	Construct over a text reader over project xml, evaluating with specified global properties and toolset, either or both of which may be null. Project will be added to the global project collection when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.
Project(XmlReader)	Construct over a text reader over project xml, evaluating with the global project collection's global properties and default tools version. Project will be added to the global project collection when it is named. Throws InvalidProjectFileException if the evaluation fails. Throws InvalidOperationException if there is already an equivalent project loaded in the project collection.

Properties

AllEvaluatedItemDefinitionMetadata	Item definition metadata encountered during evaluation. These are read during the second evaluation pass. Unlike those returned by the ItemDefinitions property, these are ordered, and include any metadata that were subsequently overridden by others with the same name and item type. It does not include any elements whose conditions did not evaluate to true. It does not include any item definition metadata added since the last evaluation.
AllEvaluatedItems	Items encountered during evaluation. These are read during the third evaluation pass. Unlike those returned by the Items property, these are ordered with respect to all other items encountered during evaluation, not just ordered with respect to items of the same item type. In some applications, like the F# language, this complete mutual ordering is significant, and such hosts can use this property. It does not include any elements whose conditions did not evaluate to true. It does not include any items added since the last evaluation.
AllEvaluatedProperties	Properties encountered during evaluation. These are read during the first evaluation pass. Unlike those returned by the Properties property, these are ordered, and includes any properties that were subsequently overridden by others with the same name. It does not include any properties whose conditions did not evaluate to true. It does not include any properties added since the last evaluation.
ConditionedProperties	Collection of possible values implied for properties contained in the conditions found on properties, property groups, imports, and whens. For example, if the following conditions existed on properties in a project: Condition="'$(Configuration)|$(Platform)' == 'Debug|x86'" Condition="'$(Configuration)' == 'Release'" the table would be populated with { "Configuration", { "Debug", "Release" }} { "Platform", { "x86" }} This is used by Visual Studio to determine the configurations defined in the project.
DirectoryPath	The root directory for this project. Is never null: in-memory projects use the current directory from the time of load.
DisableMarkDirty	Whether MarkDirty() is temporarily disabled. This allows, for example, a global property to be set without the project getting marked dirty for reevaluation as a consequence.
EvaluationCounter	Obsolete. Use LastEvaluationId instead.
FullPath	The full path to this project's file. May be null, if the project was not loaded from disk. Setter renames the project, if it already had a name.
GlobalProperties	Read only dictionary of the global properties used in the evaluation of this project.
Imports	All the files that during evaluation contributed to this project, as ProjectRootElements, with the ProjectImportElement that caused them to be imported. This does not include projects that were never imported because a condition on an Import element was false. The outer ProjectRootElement that maps to this project itself is not included.
ImportsIncludingDuplicates	This list will contain duplicate imports if an import is imported multiple times. However, only the first import was used in evaluation.
IsBuildEnabled	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 project collection. When build is disabled, the Build method on this class will fail. However if the host has already created a ProjectInstance, it can still build it. (It is free to put a similar check around where it does this.)
IsDirty	Whether this project is dirty such that it needs reevaluation. This may be because its underlying XML has changed (either through this project or another) either the XML of the main project or an imported file; or because its toolset may have changed.
ItemDefinitions	Read-only dictionary of item definitions in this project. Keyed by item type.
Items	Items in this project, ordered within groups of item types.
ItemsIgnoringCondition	Items in this project, ordered within groups of item types, including items whose conditions evaluated to false, or that were contained within item groups who themselves had conditioned evaluated to false. This is useful for hosts that wish to display all items, even if they might not be part of the build in the current configuration.
ItemTypes	Item types in this project. This is an ordered collection.
LastEvaluationId	The ID of the last evaluation for this Project. A project is always evaluated upon construction and can subsequently get evaluated multiple times via ReevaluateIfNecessary() It is an arbitrary number that changes when this project reevaluates. Hosts don't know whether an evaluation actually happened in an interval, but they can compare this number to their previously stored value to find out, and if so perhaps decide to update their own state. Note that the number may not increase monotonically. This number corresponds to the and can be used to connect evaluation logging events back to the Project instance.
ProjectCollection	Gets or sets the project collection which contains this project. Can never be null. Cannot be modified.
ProjectFileLocation	Location of the originating file itself, not any specific content within it. If the file has not been given a name, returns an empty location.
Properties	Properties in this project. Since evaluation has occurred, this is an unordered collection.
SkipEvaluation	Whether ReevaluateIfNecessary is temporarily disabled. This is useful when the host expects to make a number of reads and writes to the project, and wants to temporarily sacrifice correctness for performance.
SubToolsetVersion	The sub-toolset version that, combined with the ToolsVersion, was used to determine the toolset properties for this project.
Targets	Targets in the project. The key to the dictionary is the target's name. Overridden targets are not included in this collection. This collection is read-only.
ThrowInsteadOfSplittingItemElement	Certain item operations split the item element in multiple elements if the include contains globs, references to items or properties, or multiple item values. The items operations that may expand item elements are: RemoveItem(ProjectItem) RemoveItems(IEnumerable<ProjectItem>) AddItem(String, String, IEnumerable<KeyValuePair<String,String>>) AddItemFast(String, String, IEnumerable<KeyValuePair<String,String>>) Microsoft.Build.Evaluation.ProjectItem.ChangeItemType(System.String) Rename(String) RemoveMetadata(String) SetMetadataValue(String, String) SetMetadataValue(String, String, Boolean) When this property is set to true, the previous item operations throw an InvalidOperationException instead of expanding the item element.
ToolsVersion	The tools version this project was evaluated with, if any. Not necessarily the same as the tools version on the Project tag, if any; it may have been externally specified, for example with a /tv switch. The actual tools version on the Project tag, can be gotten from Xml.ToolsVersion. Cannot be changed once the project has been created.
Xml	The backing Xml project. Can never be null.

Methods

AddItem(String, String, IEnumerable<KeyValuePair<String,String>>)	Adds an item with metadata to the project. Metadata may be null, indicating no metadata. Does not modify the XML if a wildcard expression would already include the new item. Evaluates on a best-effort basis: -expands with all items. Items that are defined in the XML below the new item may be used, even though in a real evaluation they would not be. -only this item is evaluated. Other items that might depend on it is not affected. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state until reevaluation.
AddItem(String, String)	Adds an item with no metadata to the project. Any metadata can be added subsequently. Does not modify the XML if a wildcard expression would already include the new item. Evaluates on a best-effort basis: -expands with all items. Items that are defined in the XML below the new item may be used, even though in a real evaluation they would not be. -only this item is evaluated. Other items that might depend on it is not affected. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state until reevaluation.
AddItemFast(String, String, IEnumerable<KeyValuePair<String,String>>)	Adds an item with metadata to the project. Metadata may be null, indicating no metadata. Makes no effort to see if an existing wildcard would already match the new item, unless it is the first item in an item group. Makes no effort to locate the new item near similar items. Appends the item to the first item group that does not have a condition and has either no children or whose first child is an item of the same type. Evaluates on a best-effort basis: -expands with all items. Items that are defined in the XML below the new item may be used, even though in a real evaluation they would not be. -only this item is evaluated. Other items that might depend on it is not affected. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state until reevaluation.
AddItemFast(String, String)	Adds an item with no metadata to the project. Makes no effort to see if an existing wildcard would already match the new item, unless it is the first item in an item group. Makes no effort to locate the new item near similar items. Appends the item to the first item group that does not have a condition and has either no children or whose first child is an item of the same type. Evaluates on a best-effort basis: -expands with all items. Items that are defined in the XML below the new item may be used, even though in a real evaluation they would not be. -only this item is evaluated. Other items that might depend on it is not affected. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state until reevaluation.
Build()	Starts a build using this project, building the default targets. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>)	Starts a build using this project, building the default targets and the specified loggers. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(IEnumerable<ILogger>)	Starts a build using this project, building the default targets and the specified loggers. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(ILogger)	Starts a build using this project, building the default targets and the specified logger. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(String, IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>)	Starts a build using this project, building the specified target with the specified loggers. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(String, IEnumerable<ILogger>)	Starts a build using this project, building the specified target with the specified loggers. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(String)	Starts a build using this project, building the specified target. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(String[], IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>, EvaluationContext)	See Build(String[], IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>).
Build(String[], IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>)	Starts a build using this project, building the specified targets with the specified loggers. Returns true on success, false on failure. If build is disabled on this project, does not build, and returns false. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(String[], IEnumerable<ILogger>)	Starts a build using this project, building the specified targets with the specified loggers. Returns true on success, false on failure. If build is disabled on this project, does not build, and returns false. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
Build(String[])	Starts a build using this project, building the specified targets. Returns true on success, false on failure. Works on a privately cloned instance. To set or get virtual items for build purposes, clone an instance explicitly and build that. Does not modify the Project object.
CreateProjectInstance()	Returns an instance based on this project, but completely disconnected. This instance can be used to build independently. Before creating the instance, this will reevaluate the project if necessary, so it will not be dirty.
CreateProjectInstance(ProjectInstanceSettings, EvaluationContext)	See CreateProjectInstance(ProjectInstanceSettings).
CreateProjectInstance(ProjectInstanceSettings)	Returns an instance based on this project, but completely disconnected. This instance can be used to build independently. Before creating the instance, this will reevaluate the project if necessary, so it will not be dirty. The instance is immutable; none of the objects that form it can be modified. This makes it safe to access concurrently from multiple threads.
ExpandString(String)	Evaluates the provided string by expanding items and properties, as if it was found at the very end of the project file. This is useful for some hosts for which this kind of best-effort evaluation is sufficient. Does not expand bare metadata expressions.
FromFile(String, ProjectOptions)	Create a file based project.
FromProjectRootElement(ProjectRootElement, ProjectOptions)	Create a ProjectRootElement based project.
FromXmlReader(XmlReader, ProjectOptions)	Create a XmlReader based project.
GetAllGlobs()	Finds all the globs specified in item includes.
GetAllGlobs(EvaluationContext)	See GetAllGlobs().
GetAllGlobs(String, EvaluationContext)	See GetAllGlobs(String).
GetAllGlobs(String)	Overload of GetAllGlobs().
GetEvaluatedItemIncludeEscaped(ProjectItem)	Returns the evaluated, escaped value of the provided item's include.
GetEvaluatedItemIncludeEscaped(ProjectItemDefinition)	Returns the evaluated, escaped value of the provided item definition's include.
GetItemProvenance(ProjectItem, EvaluationContext)	See GetItemProvenance(ProjectItem).
GetItemProvenance(ProjectItem)	Overload of GetItemProvenance(String).
GetItemProvenance(String, EvaluationContext)	See GetItemProvenance(String).
GetItemProvenance(String, String, EvaluationContext)	See GetItemProvenance(String, String).
GetItemProvenance(String, String)	Overload of GetItemProvenance(String).
GetItemProvenance(String)	Finds all the item elements in the logical project with itemspecs that match the given string: elements that would include (or exclude) the string elements that would update the string (not yet implemented) elements that would remove the string (not yet implemented).
GetItems(String)	All the items in the project of the specified type. If there are none, returns an empty list. Use AddItem or RemoveItem to modify items in this project.
GetItemsByEvaluatedInclude(String)	Returns all items that have the specified evaluated include. For example, all items that have the evaluated include "bar.cpp". Typically there will be zero or one, but sometimes there are two items with the same path and different item types, or even the same item types. This will return them all.
GetItemsIgnoringCondition(String)	All the items in the project of the specified type, irrespective of whether the conditions on them evaluated to true. This is a read-only list: use AddItem or RemoveItem to modify items in this project.
GetLogicalProject()	Returns an iterator over the "logical project". The logical project is defined as the unevaluated project obtained from the single MSBuild file that is the result of inlining the text of all imports of the original MSBuild project manifest file.
GetMetadataValueEscaped(ProjectItem, String)	Gets the escaped value of the metadatum with the provided name on the provided item.
GetMetadataValueEscaped(ProjectItemDefinition, String)	Gets the escaped value of the metadatum with the provided name on the provided item definition.
GetMetadataValueEscaped(ProjectMetadata)	Gets the escaped value of the provided metadatum.
GetProperty(String)	Get any property in the project that has the specified name, otherwise returns null.
GetPropertyValue(String)	Get the unescaped value of a property in this project, or an empty string if it does not exist.
GetPropertyValueEscaped(ProjectProperty)	Get the escaped value of the provided property.
MarkDirty()	Called to forcibly mark the project as dirty requiring reevaluation. Generally this is not necessary to set; all edits affecting this project will automatically make it dirty. However there are potential corner cases where it is necessary to mark the project dirty directly. For example, if the project has an import conditioned on a file existing on disk, and the file did not exist at evaluation time, then someone subsequently creates that file, the project cannot know that reevaluation would be productive. In such a case the host can help us by setting the dirty flag explicitly so that ReevaluateIfNecessary() will recognize an evaluation is indeed necessary. Does not mark the underlying project file as requiring saving.
ReevaluateIfNecessary()	Reevaluate the project to get it into a queryable state, if it's dirty. This incorporates all changes previously made to the backing XML by editing this project. Throws InvalidProjectFileException if the evaluation fails.
ReevaluateIfNecessary(EvaluationContext)	See ReevaluateIfNecessary().
RemoveGlobalProperty(String)	Removes a global property. If it was set, returns true, and marks the project as requiring reevaluation.
RemoveItem(ProjectItem)	Removes an item from the project. Item must be associated with this project. Item must not originate from an imported file. Returns true if the item was in this evaluated project, otherwise false. As a convenience, if the parent item group becomes empty, it is also removed. If the item originated from a wildcard or semicolon separated expression, expands that expression into multiple items first. Updates the evaluated project, but does not affect anything else in the project until reevaluation. For example, if an item of type "i" is removed, "j" which is evaluated from "@(i)" will not be modified until reevaluation. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state until reevaluation.
RemoveItems(IEnumerable<ProjectItem>)	Removes all the specified items from the project. Items that are not associated with this project are skipped.
RemoveProperty(ProjectProperty)	Removes the specified property. Property must be associated with this project. Property must not originate from an imported file. Returns true if the property was in this evaluated project, otherwise false. As a convenience, if the parent property group becomes empty, it is also removed. Updates the evaluated project, but does not affect anything else in the project until reevaluation. For example, if "p" is removed, it will be removed from the evaluated project, but "q" which is evaluated from "$(p)" will not be modified until reevaluation. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state.
Save()	Save the project to the file system, if dirty. Uses the default encoding.
Save(Encoding)	Save the project to the file system, if dirty.
Save(String, Encoding)	Save the project to the file system, if dirty or the path is different.
Save(String)	Save the project to the file system, if dirty or the path is different. Uses the default encoding.
Save(TextWriter)	Save the project to the provided TextWriter, whether or not it is dirty. Uses the encoding of the TextWriter. Clears the Dirty flag.
SaveLogicalProject(TextWriter)	Saves a "logical" or "preprocessed" project file, that includes all the imported files as if they formed a single file.
SetGlobalProperty(String, String)	Change a global property after the project has been evaluated. If the value changes, this makes the project require reevaluation. If the value changes, returns true, otherwise false.
SetProperty(String, String)	Set or add a property with the specified name and value. Overwrites the value of any property with the same name already in the collection if it did not originate in an imported file. If there is no such existing property, uses this heuristic: Updates the last existing property with the specified name that has no condition on itself or its property group, if any, and is in this project file rather than an imported file. Otherwise, adds a new property in the first property group without a condition, creating a property group if necessary after the last existing property group, else at the start of the project. Returns the property set. Evaluates on a best-effort basis: -expands with all properties. Properties that are defined in the XML below the new property may be used, even though in a real evaluation they would not be. -only this property is evaluated. Anything else that would depend on its value is not affected. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state until reevaluation.