Implement package pinning

[florelis]

This PR builds on top of #2769. I can close that PR in favor of this one, or we can merge that one first to make the changes smaller and easier to review :)

Changes in this PR (not in #2769):

• Modified the CompositePackage to be able to hold more than one available package, each from a different source. The GetAvailableVersionKeys() function now can return versions from multiple sources, so the source field of PackageVersionKey is more relevant now. If the same version is available from multiple sources, they are returned in the order the available packages were added, which matches the previous behavior of just adding the first available package found.
• Added a PinBehavior enum which is passed as an argument to an IPackage's functions for getting available versions. Only the CompositePackage uses it (as it needs both an installed and an available package) and it is used to determine whether we ignore pinned versions when listing the available versions or not. For example, for list we don't care about pins, for upgrade we do consider them, and for upgrade --include-pinned we care about them unless they have Pinning type.
  • Added this new argument all through the codebase. I'm open to making it have a default value, but I wanted to highlight all the places it is used to be sure I made the appropriate choice on each place.
• Updated existing tests to new behaviors. For example, CompositeSource tests now need to ensure that the test packages have a reference to their source as it is used to determine if they are pinned.
• There was already some work for pinning done for the RequiresExplicitUpgrade manifest field. This change is mostly independent of that one, as in my mind the pinning from RequiresExplicitUpgrade is a property of the installed package, whereas user-defined pins are properties of the available packages from each source, so they are handled at different places.

Closes #476
Related to #2611

Microsoft Reviewers: Open in CodeFlow

[florelis]

Here's a little screenshot of this thing in action:

[florelis]

I moved the logic to filter out pinned versions out of CompositePackage's GetAvailableVersionKeys() and GetAvailableVersion(). Instead, now the version keys returned from GetAvailableVersionKeys() include the pinned state for that version. Versions from different sources may have different pin types, and versions that match a gating pin are not marked as pinned. Callers can the use that info to decide what to do.

I added another function like GetAvailableVersion() that also returns the pinned state.

I kept the PinBehavior argument for GetLatestAvailableVersion() because the logic there is more complicated and so it is harder to have each caller do it.

I'm still missing using the --force argument, and the messages that I'm exposing could probably be more specific.

[florelis]

/azp run

[azure-pipelines]

Pull request contains merge conflicts.

[yao-msft]

[felipecrs]

That's great news! I can't wait to test it :)

[denelon]

We're checking to see if any other PRs are super close to done, and we'll get a preview build out quickly™️.