ProjectInstance Class

Definition

Namespace:

Microsoft.Build.Execution

Assembly:

Microsoft.Build.dll

Package:

Microsoft.Build v17.9.5

What the user gets when they clone off a ProjectInstance. They can hold onto this, change/query items and properties, and call it several times to build it.

public ref class ProjectInstance

public class ProjectInstance

type ProjectInstance = class

Public Class ProjectInstance

Inheritance

Object

ProjectInstance

Remarks

Instances of this class result when a project is cloned. Constructors are internal in order to require users to create project instances from existing projects.

New project instances are immutable, except that instance items can be added to them and instance properties set on them. Project instances are useful because they can be modified and built several times without disturbing the original project.

Neither this class nor any of its constituents is allowed to have references to Microsoft.Build.Construction or Microsoft.Build.Evaluation objects.

Project instance targets, host services, and the task registry are not exposed.

Constructors

ProjectInstance(Project, ProjectInstanceSettings)	Creates a ProjectInstance from an external created Project. Properties and items are cloned immediately and only the instance data is stored.
ProjectInstance(ProjectRootElement)	Creates a ProjectInstance directly. No intermediate Project object is created. This is ideal if the project is simply going to be built, and not displayed or edited. Uses the default project collection.
ProjectInstance(ProjectRootElement, IDictionary<String,String>, String, ProjectCollection)	Creates a ProjectInstance directly. No intermediate Project object is created. This is ideal if the project is simply going to be built, and not displayed or edited. Global properties may be null. Tools version may be null.
ProjectInstance(ProjectRootElement, IDictionary<String,String>, String, String, ProjectCollection)	Creates a ProjectInstance directly. No intermediate Project object is created. This is ideal if the project is simply going to be built, and not displayed or edited. Global properties may be null. Tools version may be null. Sub-toolset version may be null, but if specified will override all other methods of determining the sub-toolset.
ProjectInstance(String)	Creates a ProjectInstance directly. No intermediate Project object is created. This is ideal if the project is simply going to be built, and not displayed or edited. Uses the default project collection.
ProjectInstance(String, IDictionary<String,String>, String)	Creates a ProjectInstance directly. No intermediate Project object is created. This is ideal if the project is simply going to be built, and not displayed or edited. Uses the default project collection.
ProjectInstance(String, IDictionary<String,String>, String, ProjectCollection)	Creates a ProjectInstance directly. No intermediate Project object is created. This is ideal if the project is simply going to be built, and not displayed or edited. Global properties may be null. Tools version may be null.
ProjectInstance(String, IDictionary<String,String>, String, String, ProjectCollection)	Creates a ProjectInstance directly. No intermediate Project object is created. This is ideal if the project is simply going to be built, and not displayed or edited. Global properties may be null. Tools version may be null.

Properties

DefaultTargets	DefaultTargets specified in the project, or the logically first target if no DefaultTargets is specified in the project. The build builds these if no targets are explicitly specified to build.
Directory	The project's root directory, for evaluation of relative paths and setting the current directory during build. Is never null: projects not loaded from disk use the current directory from the time the build started.
EvaluatedItemElements	Gets a List<T> object containing evaluated items.
EvaluationId	The ID of the evaluation that produced this ProjectInstance. See LastEvaluationId.
FullPath	The full path to the project, for logging. If the project was never given a path, returns empty string.
GlobalProperties	Global properties this project was evaluated with, if any. Read only collection. Traverses project references.
ImportPaths	The full file paths of all the files that during evaluation contributed to this project instance. 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 instance itself is not included.
ImportPathsIncludingDuplicates	This list will contain duplicate imports if an import is imported multiple times. However, only the first import was used in evaluation.
InitialTargets	InitialTargets specified in the project, plus those in all imports, gathered depth-first. The build runs these before anything else.
IsImmutable	Whether the instance is immutable. This is set permanently when the instance is created.
ItemDefinitions	Read-only dictionary of item definitions in this project. Keyed by item type
Items	Enumerator over items in this project.
ItemTypes	Enumerator over item types of the items in this project
ProjectFileLocation	Location of the originating file itself, not any specific content within it. Never returns null, even if the file has not got a path yet.
Properties	Enumerator over properties in this project
Targets	Targets in the project. The build process can find one by looking for its name in the dictionary. This collection is read-only.
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.
TranslateEntireState	Serialize the entire project instance state. When false, only a part of the project instance state is serialized (properties and items). In this case out of proc nodes re-evaluate the project instance from disk to obtain the un-serialized state. This partial state recombination may lead to build issues when the project instance state differs from what is on disk.

Methods

AddItem(String, String)	Adds an item with no metadata to the project
AddItem(String, String, IEnumerable<KeyValuePair<String,String>>)	Adds an item with metadata to the project. Metadata may be null.
Build()	Build default target/s with loggers of the project collection. Returns true on success, false on failure. Only valid if mutable.
Build(IEnumerable<ILogger>)	Build default target/s with specified loggers. Returns true on success, false on failure. Loggers may be null. Only valid if mutable.
Build(IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>)	Build default target/s with specified loggers. Returns true on success, false on failure. Loggers may be null. Only valid if mutable.
Build(String, IEnumerable<ILogger>)	Build a target with specified loggers. Returns true on success, false on failure. Target may be null. Loggers may be null. Only valid if mutable.
Build(String, IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>)	Build a target with specified loggers. Returns true on success, false on failure. Target may be null. Loggers may be null. Remote loggers may be null. Only valid if mutable.
Build(String[], IEnumerable<ILogger>)	Build a list of targets with specified loggers. Returns true on success, false on failure. Targets may be null. Loggers may be null. Only valid if mutable.
Build(String[], IEnumerable<ILogger>, IDictionary<String,TargetResult>)	Build a list of targets with specified loggers. Returns true on success, false on failure. Targets may be null. Loggers may be null. Only valid if mutable.
Build(String[], IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>)	Build a list of targets with specified loggers. Returns true on success, false on failure. Targets may be null. Loggers may be null. Remote loggers may be null. Only valid if mutable.
Build(String[], IEnumerable<ILogger>, IEnumerable<ForwardingLoggerRecord>, IDictionary<String,TargetResult>)	Build a list of targets with specified loggers. Returns true on success, false on failure. Targets may be null. Loggers may be null. Remote loggers may be null. Only valid if mutable.
DeepCopy()	Create an independent, deep clone of this object and everything in it. Useful for compiling a single file; or for keeping build results between builds. Clone has the same mutability as the original.
DeepCopy(Boolean)	Create an independent, deep clone of this object and everything in it, with specified mutability. Useful for compiling a single file; or for keeping build results between builds.
EvaluateCondition(String)	Evaluates the provided string as a condition by expanding items and properties, using the current items and properties available, then doing a logical evaluation. This is useful for the immediate window. Does not expand bare metadata expressions.
ExpandString(String)	Evaluates the provided string by expanding items and properties, using the current items and properties available. This is useful for some hosts, or for the debugger immediate window. Does not expand bare metadata expressions.
FilteredCopy(RequestedProjectState)	Create an independent clone of this object, keeping ONLY the explicitly requested project state.
FromFile(String, ProjectOptions)	Create a file based ProjectInstance.
FromProjectRootElement(ProjectRootElement, ProjectOptions)	Create a ProjectRootElement based ProjectInstance.
GetEvaluatedItemIncludeEscaped(ProjectItemDefinitionInstance)	Returns the evaluated, escaped value of the provided item definition's include.
GetEvaluatedItemIncludeEscaped(ProjectItemInstance)	Returns the evaluated, escaped value of the provided item's include.
GetItems(String)	Get a list of all the items in the project of the specified type, or an empty list if there are none. This is a read-only list.
GetItemsByItemTypeAndEvaluatedInclude(String, String)	get items by item type and evaluated include value
GetMetadataValueEscaped(ProjectItemDefinitionInstance, String)	Gets the escaped value of the metadatum with the provided name on the provided item definition.
GetMetadataValueEscaped(ProjectItemInstance, String)	Gets the escaped value of the metadatum with the provided name on the provided item.
GetMetadataValueEscaped(ProjectMetadataInstance)	Gets the escaped value of the provided metadatum.
GetProperty(String)	Get any property in the item that has the specified name, otherwise returns null
GetPropertyValue(String)	Get the value of a property in this project, or an empty string if it does not exist.
GetPropertyValueEscaped(ProjectPropertyInstance)	Get the escaped value of the provided property
RemoveItem(ProjectItemInstance)	Removes an item from the project, if present. Returns true if it was present, false otherwise.
RemoveProperty(String)	Removes any property with the specified name. Returns true if the property had a value (possibly empty string), otherwise false.
SetProperty(String, String)	Add a property with the specified name and value. Overwrites any property with the same name already in the collection.
ToProjectRootElement()	Creates a ProjectRootElement from the contents of this ProjectInstance.
UpdateStateFrom(ProjectInstance)	Replaces the project state (GlobalProperties, Properties and Items) with that from the ProjectInstance provided.