ProjectItem Class


An evaluated design-time item

public ref class ProjectItem
public class ProjectItem
type ProjectItem = class
Public Class ProjectItem


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



Metadata directly on the item, if any. Does not include metadata from item definitions. Does not include built-in metadata. Never returns null.


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".


Gets the evaluated value of the include, unescaped.


If the item originated in an imported file, returns true. Otherwise returns false.


Gets or sets the type of this item.


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).


Count of metadata on this item, if any. Includes any metadata inherited from item definitions. Includes both custom and built-in metadata.


Project that this item lives in. ProjectItems always live in a project.


Gets or sets the unevaluated value of the Include.


Backing XML item. Can never be null.



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.


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.


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.


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.


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

Applies to