ProjectRootElement Class

Definition

Namespace:

Microsoft.Build.Construction

Assembly:

Microsoft.Build.dll

Package:

Microsoft.Build v17.9.5

ProjectRootElement class represents an MSBuild project, an MSBuild targets file or any other file that conforms to MSBuild project file schema. This class and its related classes allow a complete MSBuild project or targets file to be read and written. Comments and whitespace cannot be edited through this model at present.

Each project root element is associated with exactly one ProjectCollection. This allows the owner of that project collection to control its lifetime and not be surprised by edits via another project collection.

public ref class ProjectRootElement : Microsoft::Build::Construction::ProjectElementContainer

public class ProjectRootElement : Microsoft.Build.Construction.ProjectElementContainer

type ProjectRootElement = class
    inherit ProjectElementContainer

Public Class ProjectRootElement
Inherits ProjectElementContainer

Inheritance

Object

ProjectElement

ProjectElementContainer

ProjectRootElement

Remarks

Comments and white space cannot be edited through this model at present. Each project root element is associated with exactly one project collection. This allows the owner of that project collection to control its lifetime and not be surprised by edits that come from another project collection.

Properties

AllChildren	Get an enumerator over all descendants in a depth-first manner. (Inherited from ProjectElementContainer)
AllParents	All parent elements of this element, going up to the ProjectRootElement. None if this itself is a ProjectRootElement. None if this itself has not been attached to a parent yet. (Inherited from ProjectElement)
Children	Get enumerable over all the children (Inherited from ProjectElementContainer)
ChildrenReversed	Get enumerable over all the children, starting from the last (Inherited from ProjectElementContainer)
ChooseElements	Get a read-only collection of the child chooses, if any
Condition	Condition should never be set, but the getter returns null instead of throwing because a nonexistent condition is implicitly true
ConditionLocation	This does not allow conditions, so it should not be called.
ContainingProject	ProjectRootElement (possibly imported) that contains this Xml. Cannot be null. (Inherited from ProjectElement)
Count	Number of children of any kind (Inherited from ProjectElementContainer)
DefaultTargets	Gets or sets the value of DefaultTargets. If there is no DefaultTargets, returns empty string. If the value is null or empty, removes the attribute.
DefaultTargetsLocation	Location of the defaulttargets attribute, if any
DirectoryPath	The directory that the project is in. Essential for evaluating relative paths. Is never null, even if the FullPath does not contain directory information. If the project has not been loaded from disk and has not been given a path, returns the current-directory from the time the project was loaded - this is the same behavior as Whidbey/Orcas. If the project has not been loaded from disk but has been given a path, this path may not exist.
ElementName	Gets the name of the associated element. Useful for display in some circumstances. (Inherited from ProjectElement)
Encoding	Encoding that the project file is saved in, or will be saved in, unless otherwise specified.
EscapedFullPath
FirstChild	First child, if any, otherwise null. Cannot be set directly; use PrependChild(). (Inherited from ProjectElementContainer)
FullPath	Full path to the project file. If the project has not been loaded from disk and has not been given a path, returns null. If the project has not been loaded from disk but has been given a path, this path may not exist. Setter renames the project, if it already had a name.
HasUnsavedChanges	Whether the XML has been modified since it was last loaded or saved.
ImportGroups	Get a read-only collection of the child import groups, if any.
ImportGroupsReversed	Get a read-only collection of the child import groups, if any, in reverse order
Imports	Get a read-only collection of the child imports
InitialTargets	Gets or sets the value of InitialTargets. If there is no InitialTargets, returns empty string. If the value is null or empty, removes the attribute.
InitialTargetsLocation	Location of the initialtargets attribute, if any
ItemDefinitionGroups	Get a read-only collection of the child item definition groups, if any
ItemDefinitionGroupsReversed	Get a read-only collection of the child item definition groups, if any, in reverse order
ItemDefinitions	Get a read-only collection of the child item definitions, if any, in all item definition groups anywhere in the project file.
ItemGroups	Get a read-only collection over the child item groups, if any. Does not include any that may not be at the root, i.e. inside Choose elements.
ItemGroupsReversed	Get a read-only collection of the child item groups, if any, in reverse order
Items	Get a read-only collection of the child items, if any, in all item groups anywhere in the project file. Not restricted to root item groups: traverses through Choose elements.
Label	Gets or sets the Label value. Returns empty string if it is not present. Removes the attribute if the value to set is empty. (Inherited from ProjectElement)
LabelLocation	Location of the "Label" attribute on this element, if any. If there is no such attribute, returns null; (Inherited from ProjectElement)
LastChild	Last child, if any, otherwise null. Cannot be set directly; use AppendChild(). (Inherited from ProjectElementContainer)
LastWriteTimeWhenRead	The last-write-time of the file that was read, when it was read. This can be used to see whether the file has been changed on disk by an external means.
Location	Location of the corresponding Xml element. May not be correct if file is not saved, or file has been edited since it was last saved. In the case of an unsaved edit, the location only contains the path to the file that the element originates from. (Inherited from ProjectElement)
NextSibling	Next sibling element. May be null. (Inherited from ProjectElement)
OuterElement	The outer markup associated with this project element. (Inherited from ProjectElement)
Parent	Null if this is a ProjectRootElement. Null if this has not been attached to a parent yet. (Inherited from ProjectElement)
PreserveFormatting	Whether the XML is preserving formatting or not.
PreviousSibling	Previous sibling element. May be null. (Inherited from ProjectElement)
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. This is a case where it is legitimate to "not have a location".
Properties	Geta read-only collection of the child properties, if any, in all property groups anywhere in the project file. Not restricted to root property groups: traverses through Choose elements.
PropertyGroups	Get a read-only collection of the child property groups, if any. Does not include any that may not be at the root, i.e. inside Choose elements.
PropertyGroupsReversed	Get a read-only collection of the child property groups, if any, in reverse order
RawXml	Gets the XML representing this project as a string. Does not remove any dirty flag.
Sdk	Gets or sets a semicolon delimited list of software development kits (SDK) that the project uses. If a value is specified, an Sdk.props is simplicity imported at the top of the project and an Sdk.targets is simplicity imported at the bottom from the specified SDK. If the value is null or empty, removes the attribute.
SdkLocation	Location of the Sdk attribute, if any
Targets	Get a read-only collection of the child targets
TimeLastChanged	The time that this object was last changed. If it hasn't been changed since being loaded or created, its value is MinValue.
ToolsVersion	Gets or sets the value of ToolsVersion. If there is no ToolsVersion, returns empty string. If the value is null or empty, removes the attribute.
ToolsVersionLocation	Location of the toolsversion attribute, if any
TreatAsLocalProperty	Gets or sets the value of TreatAsLocalProperty. If there is no tag, returns empty string. If the value being set is null or empty, removes the attribute.
TreatAsLocalPropertyLocation	Location of the TreatAsLocalProperty attribute, if any
UsingTasks	Get a read-only collection of the child usingtasks, if any
Version	Version number of this object. A host can compare this to a stored version number to determine whether a project's XML has changed, even if it has also been saved since. The actual value is meaningless: an edit may increment it more than once, so it should only be compared to a stored value.

Methods

AddImport(String)	Convenience method that picks a location based on a heuristic: If import groups exist, inserts into the last one without a condition on it. Otherwise, creates an import at the end of the project.
AddImportGroup()	Convenience method that picks a location based on a heuristic: Creates an import group at the end of the project.
AddItem(String, String)	Convenience method that picks a location based on a heuristic: Finds item group with no condition with at least one item of same type, or else adds a new item group; adds the item to that item group with items of the same type, ordered by include.
AddItem(String, String, IEnumerable<KeyValuePair<String,String>>)	Convenience method that picks a location based on a heuristic: Finds first item group with no condition with at least one item of same type, or else an empty item group; or else adds a new item group; adds the item to that item group with items of the same type, ordered by include. Does not attempt to check whether the item matches an existing wildcard expression; that is only possible in the evaluated world.
AddItemDefinition(String)	Convenience method that picks a location based on a heuristic: Finds first item definition group with no condition with at least one item definition of same item type, or else adds a new item definition group.
AddItemDefinitionGroup()	Convenience method that picks a location based on a heuristic: Adds an item definition group after the last existing item definition group, if any; otherwise adds an item definition group after the last existing property group, if any; otherwise adds a new item definition group at the end of the project.
AddItemGroup()	Convenience method that picks a location based on a heuristic: Adds an item group after the last existing item group, if any; otherwise adds an item group after the last existing property group, if any; otherwise adds a new item group at the end of the project.
AddProperty(String, String)	Convenience method that picks a location based on a heuristic. Updates the last existing property with the specified name that has no condition on itself or its property group, if any. 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.
AddPropertyGroup()	Convenience method that picks a location based on a heuristic: Adds a new property group after the last existing property group, if any; otherwise at the start of the project.
AddTarget(String)	Convenience method that picks a location based on a heuristic: Creates a target at the end of the project.
AddUsingTask(String, String, String)	Convenience method that picks a location based on a heuristic: Creates a usingtask at the end of the project. Exactly one of assemblyName or assemblyFile must be null.
AppendChild(ProjectElement)	Inserts the provided element as the last child. Throws if the parent is not itself parented. Throws if the node to add is already parented. Throws if the node to add was created from a different project than this node. (Inherited from ProjectElementContainer)
Clone()	Returns a shallow clone of this project element. (Inherited from ProjectElement)
Clone(ProjectRootElement)	Returns a shallow clone of this project element. (Inherited from ProjectElement)
CopyFrom(ProjectElement)	Applies properties from the specified type to this instance. (Inherited from ProjectElement)
Create()	Initialize an in-memory, empty ProjectRootElement instance that can be saved later. Uses the global project collection.
Create(NewProjectFileOptions)	Initialize an in-memory, empty ProjectRootElement instance that can be saved later using the specified NewProjectFileOptions. Uses the global project collection.
Create(ProjectCollection)	Initialize an in-memory, empty ProjectRootElement instance that can be saved later. Uses the specified project collection.
Create(ProjectCollection, NewProjectFileOptions)	Initialize an in-memory, empty ProjectRootElement instance that can be saved later using the specified ProjectCollection and NewProjectFileOptions.
Create(String)	Initialize an in-memory, empty ProjectRootElement instance that can be saved later. Uses the global project collection.
Create(String, NewProjectFileOptions)	Initialize an in-memory, empty ProjectRootElement instance that can be saved later using the specified path and NewProjectFileOptions. Uses the global project collection.
Create(String, ProjectCollection)	Initialize an in-memory, empty ProjectRootElement instance that can be saved later. Uses the specified project collection.
Create(String, ProjectCollection, NewProjectFileOptions)	Initialize an in-memory, empty ProjectRootElement instance that can be saved later. Uses the specified project collection.
Create(XmlReader)	Initialize a ProjectRootElement instance from an XmlReader. Uses the global project collection. May throw InvalidProjectFileException.
Create(XmlReader, ProjectCollection)	Initialize a ProjectRootElement instance from an XmlReader. Uses the specified project collection. May throw InvalidProjectFileException.
Create(XmlReader, ProjectCollection, Boolean)	Initialize a ProjectRootElement instance from an XmlReader. Uses the specified project collection. May throw InvalidProjectFileException.
CreateChooseElement()	Creates a choose. Caller must add it to the location of choice in the project.
CreateImportElement(String)	Creates an import. Caller must add it to the location of choice in the project.
CreateImportGroupElement()	Creates an import group. Caller must add it to the location of choice in the project.
CreateItemDefinitionElement(String)	Creates an item definition. Caller must add it to the location of choice in the project.
CreateItemDefinitionGroupElement()	Creates an item definition group. Caller must add it to the location of choice in the project.
CreateItemElement(String)	Creates an item node. Caller must add it to the location of choice in the project.
CreateItemElement(String, String)	Creates an item node with an include. Caller must add it to the location of choice in the project.
CreateItemGroupElement()	Creates an item group. Caller must add it to the location of choice in the project.
CreateMetadataElement(String)	Creates a metadata node. Caller must add it to the location of choice in the project.
CreateMetadataElement(String, String)	Creates a metadata node. Caller must add it to the location of choice in the project.
CreateMetadataElement(String, String, ElementLocation)	Creates a metadata node. Caller must add it to the location of choice in the project.
CreateNewInstance(ProjectRootElement)	Returns a new instance of ProjectRootElement that is affiliated with the same ProjectRootElementCache.
CreateOnErrorElement(String)	Creates an on error node. Caller must add it to the location of choice in the project.
CreateOtherwiseElement()	Creates an otherwise node. Caller must add it to the location of choice in the project.
CreateOutputElement(String, String, String)	Creates an output node. Exactly one of itemType and propertyName must be specified. Caller must add it to the location of choice in the project.
CreateProjectExtensionsElement()	Creates a project extensions node. Caller must add it to the location of choice in the project.
CreateProjectSdkElement(String, String)	Creates a project SDK element attached to this project.
CreatePropertyElement(String)	Creates a property. Caller must add it to the location of choice in the project.
CreatePropertyGroupElement()	Creates a property group. Caller must add it to the location of choice in the project.
CreateTargetElement(String)	Creates a target. Caller must add it to the location of choice in this project.
CreateTaskElement(String)	Creates a task. Caller must add it to the location of choice in this project.
CreateUsingTaskBodyElement(String, String)	Creates a Task element for use in a using task. Caller must add it to the location of choice in the project under a using task.
CreateUsingTaskElement(String, String, String)	Creates a using task. Caller must add it to the location of choice in the project. Exactly one of assembly file and assembly name must be provided.
CreateUsingTaskElement(String, String, String, String, String)	Creates a using task. Caller must add it to the location of choice in the project. Exactly one of assembly file and assembly name must be provided. Also allows providing optional runtime and architecture specifiers. Null is OK.
CreateUsingTaskParameterElement(String, String, String, String)	Creates a Parameter for use in a using ParameterGroup. Caller must add it to the location of choice in the project under a using task.
CreateUsingTaskParameterGroupElement()	Creates a ParameterGroup for use in a using task. Caller must add it to the location of choice in the project under a using task.
CreateWhenElement(String)	Creates a when. Caller must add it to the location of choice in this project.
DeepClone()	Returns a clone of this project.
DeepClone(ProjectRootElement, ProjectElementContainer)	Returns a clone of this project element and all its children. (Inherited from ProjectElementContainer)
DeepCopyFrom(ProjectElementContainer)	Applies properties from the specified type to this instance. (Inherited from ProjectElementContainer)
InsertAfterChild(ProjectElement, ProjectElement)	Insert the child after the reference child. Reference child if provided must be parented by this element. Reference child may be null, in which case this is equivalent to PrependChild(child). Throws if the parent is not itself parented. Throws if the reference node does not have this node as its parent. Throws if the node to add is already parented. Throws if the node to add was created from a different project than this node. (Inherited from ProjectElementContainer)
InsertBeforeChild(ProjectElement, ProjectElement)	Insert the child before the reference child. Reference child if provided must be parented by this element. Reference child may be null, in which case this is equivalent to AppendChild(child). Throws if the parent is not itself parented. Throws if the reference node does not have this node as its parent. Throws if the node to add is already parented. Throws if the node to add was created from a different project than this node. (Inherited from ProjectElementContainer)
Open(String)	Initialize a ProjectRootElement instance by loading from the specified file path. Uses the global project collection. May throw InvalidProjectFileException.
Open(String, ProjectCollection)	Initialize a ProjectRootElement instance by loading from the specified file path. Uses the specified project collection. May throw InvalidProjectFileException.
Open(String, ProjectCollection, Nullable<Boolean>)	Initialize a ProjectRootElement instance by loading from the specified file path. Uses the specified project collection and preserves the formatting of the document if specified.
PrependChild(ProjectElement)	Inserts the provided element as the first child. Throws if the parent is not itself parented. Throws if the node to add is already parented. Throws if the node to add was created from a different project than this node. (Inherited from ProjectElementContainer)
Reload(Boolean, Nullable<Boolean>)	Reload the existing project root element from its file. An InvalidOperationException is thrown if the project root element is not associated with any file on disk. See ReloadFrom(XmlReader, Boolean, Nullable<Boolean>)
ReloadFrom(String, Boolean, Nullable<Boolean>)	Reload the existing project root element from the given path An InvalidOperationException is thrown if the path does not exist. See ReloadFrom(XmlReader, Boolean, Nullable<Boolean>)
ReloadFrom(XmlReader, Boolean, Nullable<Boolean>)	Reload the existing project root element from the given reader A reload operation completely replaces the state of this ProjectRootElement object. This operation marks the object as dirty (see Microsoft.Build.Construction.ProjectRootElement.MarkDirty(System.String,System.String) for side effects). If the new state has invalid XML or MSBuild syntax, then this method throws an InvalidProjectFileException. When this happens, the state of this object does not change. Reloading from an XMLReader will retain the previous root element location (FullPath, DirectoryPath, ProjectFileLocation).
RemoveAllChildren()	Remove all the children, if any. (Inherited from ProjectElementContainer)
RemoveChild(ProjectElement)	Removes the specified child. Throws if the child is not currently parented by this object. This is O(1). May be safely called during enumeration of the children. (Inherited from ProjectElementContainer)
Save()	Save the project to the file system, if dirty. Uses the Encoding returned by the Encoding property. Creates any necessary directories. May throw IO-related exceptions. Clears the dirty flag.
Save(Encoding)	Save the project to the file system, if dirty. Creates any necessary directories. May throw IO-related exceptions. Clears the dirty flag.
Save(String)	Save the project to the file system, if dirty or the path is different. Creates any necessary directories. May throw IO related exceptions. Clears the Dirty flag.
Save(String, Encoding)	Save the project to the file system, if dirty or the path is different. Creates any necessary directories. May throw IO related exceptions. Clears the Dirty flag.
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.
ShouldCloneXmlAttribute(XmlAttribute)	Hook for subclasses to specify whether the given attribute should be cloned or not (Inherited from ProjectElement)
TryOpen(String)	Returns the ProjectRootElement for the given path if it has been loaded, or null if it is not currently in memory. Uses the global project collection.
TryOpen(String, ProjectCollection)	Returns the ProjectRootElement for the given path if it has been loaded, or null if it is not currently in memory. Uses the specified project collection.
TryOpen(String, ProjectCollection, Nullable<Boolean>)	Returns the ProjectRootElement for the given path if it has been loaded, or null if it is not currently in memory. Uses the specified project collection.