Project.GetItemProvenance Method

Definition

Overloads

GetItemProvenance(ProjectItem)

Overload of GetItemProvenance(String).

GetItemProvenance(String)

Finds all the item elements in the logical project with itemspecs that match the given string:

  • elements that would include (or exclude) the string
  • elements that would update the string (not yet implemented)
  • elements that would remove the string (not yet implemented).
GetItemProvenance(ProjectItem, EvaluationContext)

See GetItemProvenance(ProjectItem).

GetItemProvenance(String, EvaluationContext)

See GetItemProvenance(String).

GetItemProvenance(String, String)

Overload of GetItemProvenance(String).

GetItemProvenance(String, String, EvaluationContext)

See GetItemProvenance(String, String).

GetItemProvenance(ProjectItem)

public:
 System::Collections::Generic::List<Microsoft::Build::Evaluation::ProvenanceResult ^> ^ GetItemProvenance(Microsoft::Build::Evaluation::ProjectItem ^ item);
public System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult> GetItemProvenance (Microsoft.Build.Evaluation.ProjectItem item);
member this.GetItemProvenance : Microsoft.Build.Evaluation.ProjectItem -> System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult>
Public Function GetItemProvenance (item As ProjectItem) As List(Of ProvenanceResult)

Parameters

item
ProjectItem

The ProjectItem object that indicates: the itemspec to match and the item type to constrain the search in. The search is also constrained on item elements appearing before the item element that produced this item. The element that produced this item is included in the results.

Returns

List<ProvenanceResult>

Applies to

GetItemProvenance(String)

Finds all the item elements in the logical project with itemspecs that match the given string:

  • elements that would include (or exclude) the string
  • elements that would update the string (not yet implemented)
  • elements that would remove the string (not yet implemented).
public:
 System::Collections::Generic::List<Microsoft::Build::Evaluation::ProvenanceResult ^> ^ GetItemProvenance(System::String ^ itemToMatch);
public System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult> GetItemProvenance (string itemToMatch);
member this.GetItemProvenance : string -> System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult>
Public Function GetItemProvenance (itemToMatch As String) As List(Of ProvenanceResult)

Parameters

itemToMatch
String

The string to perform matching against.

Returns

List<ProvenanceResult>

A list of ProvenanceResult, sorted in project evaluation order.

Examples

         The following snippet shows what <code data-dev-comment-type="c">GetItemProvenance("a.cs")</code> returns for various item elements.
<A Include="a.cs;*.cs"></A> // Occurrences:2; Operation: Include; Provenance: StringLiteral | Glob
             <B Include="*.cs" Exclude="a.cs"></B> // Occurrences: 1; Operation: Exclude; Provenance: StringLiteral
             <C Include="b.cs"></C> // NA
             <D Include="@(A)"></D> // Occurrences: 2; Operation: Include; Provenance: Inconclusive (it is an indirect occurrence from a referenced item)
             <E Include="$(P)"></E> // Occurrences: 4; Operation: Include; Provenance: FromLiteral (direct reference in $P) | Glob (direct reference in $P) | Inconclusive (it is an indirect occurrence from referenced properties and items)
             <PropertyGroup><P>a.cs;*.cs;@(A)</P></PropertyGroup>

Remarks

This method and its overloads are useful for clients that need to inspect all the item elements that might refer to a specific item instance. For example, Visual Studio uses it to inspect projects with globs. Upon a file system or IDE file artifact change, VS calls this method to find all the items that might refer to the detected file change (e.g. 'which item elements refer to "Program.cs"?'). It uses such information to know which elements it should edit to reflect the user or file system changes.

Literal string matching tries to first match the strings. If the check fails, it then tries to match the strings as if they represented files: it normalizes both strings as files relative to the current project directory

GetItemProvenance suffers from some sources of inaccuracy: - it is performed after evaluation, thus is insensitive to item data flow when item references are present (it sees items as they are at the end of evaluation)

This API and its return types are prone to change.

Applies to

GetItemProvenance(ProjectItem, EvaluationContext)

public:
 System::Collections::Generic::List<Microsoft::Build::Evaluation::ProvenanceResult ^> ^ GetItemProvenance(Microsoft::Build::Evaluation::ProjectItem ^ item, Microsoft::Build::Evaluation::Context::EvaluationContext ^ evaluationContext);
public System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult> GetItemProvenance (Microsoft.Build.Evaluation.ProjectItem item, Microsoft.Build.Evaluation.Context.EvaluationContext evaluationContext);
member this.GetItemProvenance : Microsoft.Build.Evaluation.ProjectItem * Microsoft.Build.Evaluation.Context.EvaluationContext -> System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult>
Public Function GetItemProvenance (item As ProjectItem, evaluationContext As EvaluationContext) As List(Of ProvenanceResult)

Parameters

item
ProjectItem

The ProjectItem object that indicates: the itemspec to match and the item type to constrain the search in. The search is also constrained on item elements appearing before the item element that produced this item. The element that produced this item is included in the results.

evaluationContext
EvaluationContext

The evaluation context to use in case reevaluation is required. To avoid reevaluation use RecordEvaluatedItemElements.

Returns

List<ProvenanceResult>

Applies to

GetItemProvenance(String, EvaluationContext)

public:
 System::Collections::Generic::List<Microsoft::Build::Evaluation::ProvenanceResult ^> ^ GetItemProvenance(System::String ^ itemToMatch, Microsoft::Build::Evaluation::Context::EvaluationContext ^ evaluationContext);
public System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult> GetItemProvenance (string itemToMatch, Microsoft.Build.Evaluation.Context.EvaluationContext evaluationContext);
member this.GetItemProvenance : string * Microsoft.Build.Evaluation.Context.EvaluationContext -> System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult>
Public Function GetItemProvenance (itemToMatch As String, evaluationContext As EvaluationContext) As List(Of ProvenanceResult)

Parameters

itemToMatch
String

The string to perform matching against.

evaluationContext
EvaluationContext

The evaluation context to use in case reevaluation is required. To avoid reevaluation use RecordEvaluatedItemElements.

Returns

List<ProvenanceResult>

Applies to

GetItemProvenance(String, String)

public:
 System::Collections::Generic::List<Microsoft::Build::Evaluation::ProvenanceResult ^> ^ GetItemProvenance(System::String ^ itemToMatch, System::String ^ itemType);
public System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult> GetItemProvenance (string itemToMatch, string itemType);
member this.GetItemProvenance : string * string -> System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult>
Public Function GetItemProvenance (itemToMatch As String, itemType As String) As List(Of ProvenanceResult)

Parameters

itemToMatch
String

The string to perform matching against.

itemType
String

The item type to constrain the search in.

Returns

List<ProvenanceResult>

Applies to

GetItemProvenance(String, String, EvaluationContext)

public:
 System::Collections::Generic::List<Microsoft::Build::Evaluation::ProvenanceResult ^> ^ GetItemProvenance(System::String ^ itemToMatch, System::String ^ itemType, Microsoft::Build::Evaluation::Context::EvaluationContext ^ evaluationContext);
public System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult> GetItemProvenance (string itemToMatch, string itemType, Microsoft.Build.Evaluation.Context.EvaluationContext evaluationContext);
member this.GetItemProvenance : string * string * Microsoft.Build.Evaluation.Context.EvaluationContext -> System.Collections.Generic.List<Microsoft.Build.Evaluation.ProvenanceResult>
Public Function GetItemProvenance (itemToMatch As String, itemType As String, evaluationContext As EvaluationContext) As List(Of ProvenanceResult)

Parameters

itemToMatch
String

The string to perform matching against.

itemType
String

The type of the item to perform matching against.

evaluationContext
EvaluationContext

The evaluation context to use in case reevaluation is required. To avoid reevaluation use RecordEvaluatedItemElements.

Returns

List<ProvenanceResult>

Applies to