Document whether tasks can cache TaskItems

[rainersigwald]

A task can safely cache TaskItems as far as I can tell. We should document that.

I validated with code like this: task-with-cached-TaskItem.zip

A task that trivially caches a TaskItem object:

public class Class1 : Task
{
    private static TaskItem item = new("itemSpec", 
        new Dictionary<string, string>() { 
            ["MetaA"] = "valueA" 
        });

    [Output]
    public TaskItem OutParam { get; private set; }

    public override bool Execute()
    {
        OutParam = item;

        return true;
    }
}

A project that calls it twice and modifies the output of the first time:

<Project>
 <UsingTask TaskName="Class1" AssemblyFile="S:\play\task-transformation\bin\Debug\net5.0\task-transformation.dll" />

 <Target Name="TryModify">
  <Class1>
   <Output TaskParameter="OutParam" ItemName="O" />
  </Class1>

  <Message Importance="High" Text="First   O: @(O->'%(Identity), a: %(MetaA) b: %(MetaB)')" />

  <ItemGroup>
   <O MetaB="b" />
  </ItemGroup>

  <Message Importance="High" Text="Changed O: @(O->'%(Identity), a: %(MetaA) b: %(MetaB)')" />

  <Class1>
   <Output TaskParameter="OutParam" ItemName="O2" />
  </Class1>

  <Message Importance="High" Text="Last O: @(O->'%(Identity), a: %(MetaA) b: %(MetaB)')" />
  <Message Importance="High" Text="    O2: @(O2->'%(Identity), a: %(MetaA) b: %(MetaB)')" />
 </Target>
</Project>

This produces

❯ dotnet build .\XMLFile1.csproj
Microsoft (R) Build Engine version 17.0.0-preview-21409-06+682bfcaf3 for .NET
Copyright (C) Microsoft Corporation. All rights reserved.

  First   O: itemSpec, a: valueA b:
  Changed O: itemSpec, a: valueA b: b
  Last    O: itemSpec, a: valueA b: b
         O2: itemSpec, a: valueA b:

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:00.10

So the mutated object logged as "Changed O" must be a distinct object from the one in the static.