ProjectItem Class

Definition

Namespace:

Microsoft.Build.Evaluation

Assembly:

Microsoft.Build.dll

Package:

Microsoft.Build v17.9.5

An evaluated design-time item

public ref class ProjectItem

public class ProjectItem

type ProjectItem = class

Public Class ProjectItem

Inheritance

Object

ProjectItem

Remarks

Edits to this object will indirectly dirty the containing project because they will modify the backing XML.

Properties

DirectMetadata	Metadata directly on the item, if any. Does not include metadata from item definitions. Does not include built-in metadata. Never returns null.
DirectMetadataCount	Count of direct metadata on this item, if any. Does NOT count any metadata inherited from item definitions. Does not count built-in metadata, such as "FullPath".
EvaluatedInclude	Gets the evaluated value of the include, unescaped.
IsImported	If the item originated in an imported file, returns true. Otherwise returns false.
ItemType	Gets or sets the type of this item.
Metadata	Metadata on the item, if any. Includes metadata specified by the definition, if any. If there is no metadata, returns an empty collection. Does not include built-in metadata, such as "FullPath". Get the values of built-in metadata using GetMetadataValue(String). This is a read-only collection. To modify the metadata, use SetMetadataValue(String, String).
MetadataCount	Count of metadata on this item, if any. Includes any metadata inherited from item definitions. Includes both custom and built-in metadata.
Project	Project that this item lives in. ProjectItems always live in a project.
UnevaluatedInclude	Gets or sets the unevaluated value of the Include.
Xml	Backing XML item. Can never be null.

Methods

GetMetadata(String)	Gets an evaluated metadata on this item. Potentially includes a metadata from an item definition. Does not return built-in metadata, such as "FullPath". Returns null if not found.
GetMetadataValue(String)	Get the evaluated value of a metadata on this item, possibly from an item definition. Returns empty string if it does not exist. To determine whether a piece of metadata does not exist vs. simply has no value, use HasMetadata. May be used to access the value of built-in metadata, such as "FullPath". Attempting to get built-in metadata on a value that is not a valid path throws InvalidOperationException.
HasMetadata(String)	Returns true if a particular piece of metadata is defined on this item, otherwise false. Includes built-in metadata and metadata inherited from item definitions.
RemoveMetadata(String)	Removes any metadata with the specified name. Returns true if the evaluated metadata existed, otherwise false. If the metadata name is one of the built-in metadata, like "FullPath", throws InvalidArgumentException. If the metadata originates in an item definition, and was not overridden, throws InvalidOperationException.
Rename(String)	Renames the item. Equivalent to setting the UnevaluatedInclude value. Generally, no expansion occurs. This is because it would potentially result in several items, which is not meaningful semantics when renaming a single item. However if the item does not need to be split (which would invalidate its ProjectItemElement), and the new value expands to exactly one item, then its evaluated include is updated with the expanded value, rather than the unexpanded value.
SetMetadataValue(String, String)	Adds metadata with the specified name and value to the item. Updates an existing metadata if one already exists with the same name on the item directly, as opposed to inherited from an item definition. Updates the evaluated project, but does not affect anything else in the project until reevaluation. For example, if a piece of metadata named "m" is added on item of type "i", it does not affect "j" which is evaluated from "@(j->'%(m)')" until reevaluation. Also if the unevaluated value of "m" is set to something that is modified by evaluation, such as "$(p)", the evaluated value will be set to literally "$(p)" until reevaluation. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state without a reevaluation. Returns the new or existing metadatum.
SetMetadataValue(String, String, Boolean)	Overload of SetMetadataValue(String, String). Adds the option of not splitting the item element and thus affecting all sibling items. Sibling items are defined as all ProjectItem instances that were created from the same item element. This is a convenience that it is understood does not necessarily leave the project in a perfectly self consistent state without a reevaluation