Project.GetItemProvenance Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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:
|
| GetItemProvenance(ProjectItem, EvaluationContext) | |
| GetItemProvenance(String, EvaluationContext) | |
| GetItemProvenance(String, String) |
Overload of GetItemProvenance(String). |
| GetItemProvenance(String, String, EvaluationContext) |
GetItemProvenance(ProjectItem)
Overload of GetItemProvenance(String).
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
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
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
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
Applies to
GetItemProvenance(String, String)
Overload of GetItemProvenance(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
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.