|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System;
using System.Collections;
using System.Runtime.InteropServices;
#nullable disable
namespace Microsoft.Build.Framework
{
/// <summary>
/// This interface defines a project item that can be consumed and emitted by tasks.
/// </summary>
[ComVisible(true)]
[Guid("8661674F-2148-4F71-A92A-49875511C528")]
public interface ITaskItem
{
/// <summary>
/// Gets or sets the item "specification" e.g. for disk-based items this would be the file path.
/// </summary>
/// <remarks>
/// This should be named "EvaluatedInclude" but that would be a breaking change to this interface.
/// </remarks>
/// <value>The item-spec string.</value>
string ItemSpec
{
get;
set;
}
/// <summary>
/// Gets the names of all the metadata on the item.
/// Includes the built-in metadata like "FullPath".
/// </summary>
/// <value>The list of metadata names.</value>
ICollection MetadataNames
{
get;
}
/// <summary>
/// Gets the number of pieces of metadata on the item. Includes
/// both custom and built-in metadata.
/// </summary>
/// <value>Count of pieces of metadata.</value>
int MetadataCount
{
get;
}
/// <summary>
/// Allows the values of metadata on the item to be queried.
/// </summary>
/// <param name="metadataName">The name of the metadata to retrieve.</param>
/// <returns>The value of the specified metadata.</returns>
string GetMetadata(string metadataName);
/// <summary>
/// Allows a piece of custom metadata to be set on the item.
/// </summary>
/// <param name="metadataName">The name of the metadata to set.</param>
/// <param name="metadataValue">The metadata value.</param>
void SetMetadata(string metadataName, string metadataValue);
/// <summary>
/// Allows the removal of custom metadata set on the item.
/// </summary>
/// <param name="metadataName">The name of the metadata to remove.</param>
void RemoveMetadata(string metadataName);
/// <summary>
/// Allows custom metadata on the item to be copied to another item.
/// </summary>
/// <remarks>
/// RECOMMENDED GUIDELINES FOR METHOD IMPLEMENTATIONS:
/// 1) this method should NOT copy over the item-spec
/// 2) if a particular piece of metadata already exists on the destination item, it should NOT be overwritten
/// 3) if there are pieces of metadata on the item that make no semantic sense on the destination item, they should NOT be copied
/// </remarks>
/// <param name="destinationItem">The item to copy metadata to.</param>
void CopyMetadataTo(ITaskItem destinationItem);
/// <summary>
/// Get the collection of custom metadata. This does not include built-in metadata.
/// </summary>
/// <remarks>
/// RECOMMENDED GUIDELINES FOR METHOD IMPLEMENTATIONS:
/// 1) this method should return a clone of the metadata
/// 2) writing to this dictionary should not be reflected in the underlying item.
/// </remarks>
/// <returns>Dictionary of cloned metadata</returns>
IDictionary CloneCustomMetadata();
}
}
|