Publish ETW events for package restore nominations

In automated performance regression tests, it's helpful to validate that package restore nominations are not happening more often than required. However there are no telemetry events for this operation, so we do not have a direct way to measure this.

This change adds a new `TraceSource` to the .NET Project System, that ETW clients can opt into. When enabled, any package restore nominations are logged, including information about the reason for the nomination.

For example, if a package version is changed:

```
TargetFrameworks
    .NETCoreApp,Version=v8.0
        PackageReferences
            MetadataExtractor
                Version
                    Before: 2.8.1
                    After: 2.9.0
```

These ETW events are off by default. We'll enable them in the lab for performance regressions, and they will allow catching regressions in the number of nominations, as well as helping to quickly identify what changes led to that nomination. There's no impact in regular use.

Author: drewnoakes

src/Microsoft.VisualStudio.ProjectSystem.Managed/ProjectSystem/PackageRestore/PackageRestoreDataSource.cs

@@ -3,6 +3,7 @@
 using System.Threading.Tasks.Dataflow;
 using Microsoft.VisualStudio.Composition;
 using Microsoft.VisualStudio.IO;
+using Microsoft.VisualStudio.ProjectSystem.Telemetry;
 using Microsoft.VisualStudio.Text;
 using Microsoft.VisualStudio.Threading;
 
@@ -58,6 +59,7 @@ internal partial class PackageRestoreDataSource : ChainedProjectValueDataSourceB
     private readonly IManagedProjectDiagnosticOutputService _logger;
     private readonly INuGetRestoreService _nuGetRestoreService;
     private Hash? _lastHash;
+    private ProjectRestoreInfo? _lastRestoreInfo;
     private bool _enabled;
     private bool _wasSourceBlockContinuationSet;
 
@@ -109,10 +111,7 @@ internal async Task<IEnumerable<IProjectVersionedValue<RestoreData>>> RestoreAsy
 
         RestoreData restoreData = CreateRestoreData(e.Value.RestoreInfo, succeeded);
 
-        return new[]
-        {
-            new ProjectVersionedValue<RestoreData>(restoreData, e.DataSourceVersions)
-        };
+        return [new ProjectVersionedValue<RestoreData>(restoreData, e.DataSourceVersions)];
     }
 
     private async Task<bool> RestoreCoreAsync(PackageRestoreUnconfiguredInput value)
@@ -125,22 +124,43 @@ private async Task<bool> RestoreCoreAsync(PackageRestoreUnconfiguredInput value)
 
         // Restore service always does work regardless of whether the value we pass 
         // them to actually contains changes, only nominate if there are any.
-        Hash hash = RestoreHasher.CalculateHash(restoreInfo);
+        Hash hash = CalculateHash();
 
         if (await _cycleDetector.IsCycleDetectedAsync(hash, value.ActiveConfiguration, token))
         {
             _lastHash = hash;
+            _lastRestoreInfo = restoreInfo;
             return false;
         }
 
         if (_lastHash?.Equals(hash) == true)
         {
             await _nuGetRestoreService.UpdateWithoutNominationAsync(value.ConfiguredInputs);
+            _lastRestoreInfo = restoreInfo;
             return true;
         }
 
         _lastHash = hash;
 
+        if (DotNetProjectSystemEventSource.Instance.IsEnabled())
+        {
+            string changes;
+            if (_lastRestoreInfo is null)
+            {
+                changes = "Initial restore.";
+            }
+            else
+            {
+                RestoreStateComparisonBuilder builder = new();
+                _lastRestoreInfo.DescribeChanges(builder, restoreInfo);
+                changes = builder.ToString();
+            }
+
+            DotNetProjectSystemEventSource.Instance.NominateForRestore(projectFilePath: _project.FullPath, changes: changes);
+        }
+
+        _lastRestoreInfo = restoreInfo;
+
         JoinableTask<bool> joinableTask = JoinableFactory.RunAsync(() =>
         {
             return NominateForRestoreAsync(restoreInfo, value.ConfiguredInputs, token);
@@ -152,6 +172,13 @@ private async Task<bool> RestoreCoreAsync(PackageRestoreUnconfiguredInput value)
             registerFaultHandler: true);
 
         return await joinableTask;
+
+        Hash CalculateHash()
+        {
+            using var hasher = new IncrementalHasher();
+            restoreInfo.AddToHash(hasher);
+            return hasher.GetHashAndReset();
+        }
     }
 
     private async Task<bool> NominateForRestoreAsync(ProjectRestoreInfo restoreInfo, IReadOnlyCollection<PackageRestoreConfiguredInput> versions, CancellationToken cancellationToken)

src/Microsoft.VisualStudio.ProjectSystem.Managed/ProjectSystem/PackageRestore/Snapshots/IRestoreState.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE.md file in the project root for more information.
+
+using Microsoft.VisualStudio.Text;
+
+namespace Microsoft.VisualStudio.ProjectSystem.PackageRestore;
+
+/// <summary>
+/// A data object at some level within the restore state snapshot, <see cref="ProjectRestoreInfo"/>.
+/// </summary>
+/// <typeparam name="T"></typeparam>
+internal interface IRestoreState<T> where T : class
+{
+    /// <summary>
+    /// Adds state from this object to <paramref name="hasher"/>.
+    /// </summary>
+    /// <param name="hasher"></param>
+    void AddToHash(IncrementalHasher hasher);
+
+    /// <summary>
+    /// Compares all state between this instance and <paramref name="after"/>, and logs details of any changes.
+    /// </summary>
+    void DescribeChanges(RestoreStateComparisonBuilder builder, T after);
+}

src/Microsoft.VisualStudio.ProjectSystem.Managed/ProjectSystem/PackageRestore/Snapshots/IncrementalHasherExtensions.cs

@@ -0,0 +1,23 @@
+// Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE.md file in the project root for more information.
+
+using Microsoft.VisualStudio.Text;
+
+namespace Microsoft.VisualStudio.ProjectSystem.PackageRestore;
+
+internal static class IncrementalHasherExtensions
+{
+    public static void AppendProperty(this IncrementalHasher hasher, string name, string value)
+    {
+        hasher.Append(name);
+        hasher.Append("|");
+        hasher.Append(value);
+    }
+
+    public static void AppendArray<T>(this IncrementalHasher hasher, ImmutableArray<T> items) where T : class, IRestoreState<T>
+    {
+        foreach (T item in items)
+        {
+            item.AddToHash(hasher);
+        }
+    }
+}

src/Microsoft.VisualStudio.ProjectSystem.Managed/ProjectSystem/PackageRestore/Snapshots/ProjectRestoreInfo.cs

@@ -1,30 +1,49 @@
 // Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE.md file in the project root for more information.
 
+using Microsoft.VisualStudio.Text;
+
 namespace Microsoft.VisualStudio.ProjectSystem.PackageRestore;
 
 /// <summary>
-///     A complete set of restore data for a project.
+/// A complete set of restore data for a project.
 /// </summary>
-internal class ProjectRestoreInfo
+internal sealed class ProjectRestoreInfo(
+    string msbuildProjectExtensionsPath,
+    string projectAssetsFilePath,
+    string originalTargetFrameworks,
+    ImmutableArray<TargetFrameworkInfo> targetFrameworks,
+    ImmutableArray<ReferenceItem> toolReferences)
+    : IRestoreState<ProjectRestoreInfo>
 {
-    // If additional fields/properties are added to this class, please update RestoreHasher
+    // IMPORTANT: If additional state is added, update AddToHash and DescribeChanges below.
 
-    public ProjectRestoreInfo(string msbuildProjectExtensionsPath, string projectAssetsFilePath, string originalTargetFrameworks, ImmutableArray<TargetFrameworkInfo> targetFrameworks, ImmutableArray<ReferenceItem> toolReferences)
-    {
-        MSBuildProjectExtensionsPath = msbuildProjectExtensionsPath;
-        ProjectAssetsFilePath = projectAssetsFilePath;
-        OriginalTargetFrameworks = originalTargetFrameworks;
-        TargetFrameworks = targetFrameworks;
-        ToolReferences = toolReferences;
-    }
+    public string MSBuildProjectExtensionsPath { get; } = msbuildProjectExtensionsPath;
+
+    public string ProjectAssetsFilePath { get; } = projectAssetsFilePath;
+
+    public string OriginalTargetFrameworks { get; } = originalTargetFrameworks;
 
-    public string MSBuildProjectExtensionsPath { get; }
+    public ImmutableArray<TargetFrameworkInfo> TargetFrameworks { get; } = targetFrameworks;
 
-    public string ProjectAssetsFilePath { get; }
+    public ImmutableArray<ReferenceItem> ToolReferences { get; } = toolReferences;
 
-    public string OriginalTargetFrameworks { get; }
+    public void AddToHash(IncrementalHasher hasher)
+    {
+        hasher.AppendProperty(nameof(ProjectAssetsFilePath),        ProjectAssetsFilePath);
+        hasher.AppendProperty(nameof(MSBuildProjectExtensionsPath), MSBuildProjectExtensionsPath);
+        hasher.AppendProperty(nameof(OriginalTargetFrameworks),     OriginalTargetFrameworks);
 
-    public ImmutableArray<TargetFrameworkInfo> TargetFrameworks { get; }
+        hasher.AppendArray(TargetFrameworks);
+        hasher.AppendArray(ToolReferences);
+    }
 
-    public ImmutableArray<ReferenceItem> ToolReferences { get; }
+    public void DescribeChanges(RestoreStateComparisonBuilder builder, ProjectRestoreInfo after)
+    {
+        builder.CompareString(MSBuildProjectExtensionsPath, after.MSBuildProjectExtensionsPath, nameof(MSBuildProjectExtensionsPath));
+        builder.CompareString(ProjectAssetsFilePath, after.ProjectAssetsFilePath, nameof(ProjectAssetsFilePath));
+        builder.CompareString(OriginalTargetFrameworks, after.OriginalTargetFrameworks, nameof(OriginalTargetFrameworks));
+
+        builder.CompareArray(TargetFrameworks, after.TargetFrameworks, nameof(TargetFrameworks));
+        builder.CompareArray(ToolReferences, after.ToolReferences, nameof(ToolReferences));
+    }
 }

src/Microsoft.VisualStudio.ProjectSystem.Managed/ProjectSystem/PackageRestore/Snapshots/ReferenceItem.cs

@@ -1,14 +1,15 @@
 // Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this file to you under the MIT license. See the LICENSE.md file in the project root for more information.
 
 using System.Diagnostics;
+using Microsoft.VisualStudio.Text;
 
 namespace Microsoft.VisualStudio.ProjectSystem.PackageRestore;
 
 /// <summary>
 /// Represents a reference item involved in package restore, with its associated metadata.
 /// </summary>
 [DebuggerDisplay("Name = {Name}")]
-internal sealed class ReferenceItem
+internal sealed class ReferenceItem : IRestoreState<ReferenceItem>
 {
     // If additional state is added to this class, please update RestoreHasher
 
@@ -29,4 +30,25 @@ public ReferenceItem(string name, IImmutableDictionary<string, string> metadata)
     /// Gets the name/value pair metadata associated with the reference.
     /// </summary>
     public IImmutableDictionary<string, string> Metadata { get; }
+
+    public void AddToHash(IncrementalHasher hasher)
+    {
+        hasher.AppendProperty(nameof(Name), Name);
+
+        foreach ((string key, string value) in Metadata)
+        {
+            hasher.AppendProperty(key, value);
+        }
+    }
+
+    public void DescribeChanges(RestoreStateComparisonBuilder builder, ReferenceItem after)
+    {
+        builder.PushScope(Name);
+
+        builder.CompareString(Name, after.Name, name: "%(Identity)");
+
+        builder.CompareDictionary(Metadata, after.Metadata);
+
+        builder.PopScope();
+    }
 }