Add support for Linked files as PackageFile

In the IDE it's trivial to add linked files so they end up in specified locations.

This makes it easy to add linked files by automatically using the %(Link) metadata if present
on items that don't already have a %(TargetPath) assigned.

With the addition of PackageFile as an available item name/build action, supporting
linked package files makes this very easy to use.

Fixes NuGet/Home#5327

Author: kzu

src/Build/NuGet.Build.Packaging.Tasks/AssignPackagePath.cs

@@ -147,6 +147,10 @@ ITaskItem EnsurePackagePath(ITaskItem file, IDictionary<string, ITaskItem> kindM
 			}
 
 			var targetPath = file.GetMetadata("TargetPath");
+			// Linked files already have the desired target path specified by the user
+			if (string.IsNullOrEmpty(targetPath))
+				targetPath = file.GetMetadata("Link");
+
 			// NOTE: TargetPath allows a framework-specific file to still specify its relative 
 			// location without hardcoding the target framework (useful for multi-targetting and 
 			// P2P references).
@@ -166,6 +170,9 @@ ITaskItem EnsurePackagePath(ITaskItem file, IDictionary<string, ITaskItem> kindM
 				targetPath = targetPath.Substring(packageFolder.Length + 1);
 			}
 
+			// At this point we have the correct calculated target path, so persist it for inspection if necessary.
+			output.SetMetadata("TargetPath", targetPath);
+
 			// If we have no known package folder, files go to their RelativeDir location.
 			// This allows custom packaging paths such as "workbooks", "docs" or whatever, which aren't prohibited by 
 			// the format.

src/Build/NuGet.Build.Packaging.Tests/AssignPackagePathTests.cs

@@ -279,6 +279,63 @@ public void when_file_has_target_framework_and_tfm_then_existing_value_is_preser
 			}));
 		}
 
+		[Fact]
+		public void when_content_file_has_link_then_package_path_is_relative_to_link()
+		{
+			var task = new AssignPackagePath
+			{
+				BuildEngine = engine,
+				Kinds = kinds,
+				Files = new ITaskItem[]
+				{
+					new TaskItem(@"..\..\readme.txt", new Metadata
+					{
+						{ "Link", @"docs\readme.txt" },
+						{ "PackageId", "A" },
+						{ "Kind", "Content" },
+						{ "TargetFramework", "any" },
+					})
+				}
+			};
+
+			Assert.True(task.Execute());
+
+			Assert.Contains(task.AssignedFiles, item => item.Matches(new
+			{
+				TargetPath = @"docs\readme.txt",
+				PackagePath = @"contentFiles\any\any\docs\readme.txt",
+			}));
+		}
+
+		[Fact]
+		public void when_none_file_has_link_then_package_path_is_relative_to_link()
+		{
+			var task = new AssignPackagePath
+			{
+				BuildEngine = engine,
+				Kinds = kinds,
+				Files = new ITaskItem[]
+				{
+					new TaskItem(@"..\..\readme.txt", new Metadata
+					{
+						{ "Link", @"docs\readme.txt" },
+						{ "PackageId", "A" },
+						{ "Kind", "None" },
+						{ "TargetFramework", "any" },
+					})
+				}
+			};
+
+			Assert.True(task.Execute());
+
+			Assert.Contains(task.AssignedFiles, item => item.Matches(new
+			{
+				TargetPath = @"docs\readme.txt",
+				PackagePath = @"docs\readme.txt",
+			}));
+		}
+
+
 		[Fact]
 		public void when_content_is_not_framework_specific_then_has_any_lang_and_tfm()
 		{

src/Build/NuGet.Build.Packaging.Tests/Scenarios/given_a_library_with_content/library_with_content.csproj

@@ -6,6 +6,9 @@
 		<TargetFrameworkMoniker>MonoAndroid,Version=v5.1</TargetFrameworkMoniker>
   </PropertyGroup>
 	<ItemGroup>
+    <PackageFile Include="..\given_a_custom_build_project\Readme.txt">
+      <Link>docs\Readme.txt</Link>
+    </PackageFile>
     <Content Include="quickstart\cs-any.txt">
       <CodeLanguage>cs</CodeLanguage>
       <TargetFramework>any</TargetFramework>

src/Build/NuGet.Build.Packaging.Tests/given_a_library_with_content.cs

@@ -74,6 +74,22 @@ public void when_removing_inferred_package_file_from_content_then_content_is_not
 			Assert.DoesNotContain(result.Items, item => item.GetMetadata("PackagePath").StartsWith("contentFiles"));
 		}
 
+		[Fact]
+		public void linked_package_file_has_relative_package_path()
+		{
+			var result = Builder.BuildScenario(nameof(given_a_library_with_content), new
+			{
+				PackageId = "ContentPackage"
+			});
+
+			result.AssertSuccess(output);
+
+			Assert.Contains(result.Items, item => item.Matches(new
+			{
+				PackagePath = @"docs\Readme.txt",
+			}));
+		}
+
 		#region Content scenarios
 
 		[Fact]