有关ResolvedFileToPublish XML元素的完整说明？

Question

默认情况下，ASP.NET Core SPA项目模板在其.csproj文件中有一个部分，如下所示：

<!-- Include the newly-built files in the publish output -->
<ItemGroup>
  <DistFiles Include="$(SpaRoot)dist\**; $(SpaRoot)dist-server\**" />
  <DistFiles Include="$(SpaRoot)node_modules\**" Condition="'$(BuildServerSideRenderer)' == 'true'" />
  <ResolvedFileToPublish Include="@(DistFiles->'%(FullPath)')" Exclude="@(ResolvedFileToPublish)">
    <RelativePath>%(DistFiles.Identity)</RelativePath>
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
  </ResolvedFileToPublish>
</ItemGroup>

我在Google上找不到任何好的文档，但是我认为本部分可能对我想做的事情有所帮助。我想出于自己的目的对其进行修改，但是首先我需要完全理解它，因此有人可以向我解释以下内容：

• 在哪里SpaRoot设置？
• 到底是ResolvedFileToPublish做什么的？
• 在哪里DistFiles设置？
• 在哪里FullPath设置？
• 什么是@(DistFiles->'%(FullPath)'“箭头符号”是什么意思？
• 怎么Exclude="@(ResolvedFileToPublish)"办？
• DistFiles.Identity指的是什么，在哪里设置？

更新：此页面提供有关此项目的一些文档，但内容不多：https :
//docs.microsoft.com/zh-cn/aspnet/core/host-and-deploy/visual-studio-publish-profiles?view=aspnetcore- 2.2＃selective-file-inclusion

Answer 1

在哪里SpaRoot设置？

SpaRoot由模板设置为项目中的属性。项目包含“静态”部分；这是根级别PropertyGroup和ItemGroup元素。

请注意，属性就像一个全局键值字典（并且只要a中的XML节点PropertyGroup定义了属性，它就会覆盖具有相同名称的现有属性）。但是项目类似于列表。您可以添加（<MyItem Include="..."/>），删除（... Remove="..."）甚至更新项目（... Update="..."仅在静态部分中，没有在目标内包含/删除目标意味着“全部更新”，您只能使用Condition属性进行过滤）。项目就像对象，它们具有一个称为“ Identity”的“ ID”，并且可以具有称为“元数据”的其他属性。“身份”是在中指定的部分Include，它可以是文件名，也可以不是。如果引用了文件，则会自动添加一些众所周知的元数据（例如文件修改日期和FullPath）。元数据也可以在项目XML元素上定义为属性（例如，如Version="1.2.3"PackageReference项目中所示）或作为项目元素的子元素（例如RelativePath，如上所示）。

ResolvedFileToPublish到底做什么？

通过运行包含逻辑的目标在构建引擎中执行构建。.NET项目运行的所有构建逻辑均由MSBuild代码控制，该代码使用与项目文件相同的语法。因此，通过使用导入或SDK，.csproj文件本身就是构建定义而不是配置文件。使用BeforeTargets/之类的机制AfterTargets，可以在特定点挂入构建过程以执行代码；在这种情况下，模板包含一个挂接到发布逻辑中的目标。

ResolvedFileToPublish本身并没有做任何特别的事情。XML元素告诉msbuild ResolvedFileToPublish根据文件规范将项目添加到列表，仅当项目配置有服务器端呈现时才是其中的一个（属性是AFAIK也存在于模板的项目的静态部分中） ）。

在构建的后期，来自.NET SDK的目标使用这些项目来计算文件以在发布操作，工具打包和/或单文件发布（3.0功能）期间进行复制，请参阅Microsoft.NET.Publish.targets用于@(Microsoft.NET.Publish.targets)访问项目列表的代码。

按照惯例，只要Microsoft / 3rd-party构建逻辑使用不以下划线（_）开头的属性或项目，都将允许/期望通过构建自定义项（例如SPA模板中提供的）对属性或项进行配置。因此，我们打算添加ResolvedFileToPublish被认为是“公共API”但不是的项目_ResolvedFileToPublishAlways。通过将构建的SPA文件添加为项目，我们可以告诉发布逻辑在发布过程中包括它们。

DistFiles在哪里设置？

DistFiles由此模板/逻辑组成。几乎没有关于可以使用哪些项目或属性名称的限制。这也可能已被命名SpaDistFiles或类似名称。该模板创建了一些中间项目，以后可用于创建ResolvedFileToPublish项目，并希望该名称与构建逻辑中使用的任何其他名称不冲突。

FullPath在哪里设置？

完整路径是msbuild会自动添加到引用磁盘上文件的项目的众所周知的自动属性。

虽然项目的标识可能是ClientApp\dist\myapp\index.html（或包含的相对路径..\），但其FullPath元数据将是C:\path\to\proj\ClientApp\....。

@（DistFiles->'％（FullPath）'“箭头符号”是什么意思？

虽然可以使用$()语法访问属性，但使用引用项目@()。

当您的商品MyItem带有标识A和B时@(MyItem)（评估为文本时）为A;B。可以再次将其解释为项目规范，因此传递给<OtherItem Include="@(MyItem)" />。

但是@()语法也允许项目转换或调用项目函数（@(MyItem->Count())）。转换是每个项目到另一个项目的投影，​​因此在此示例中，由于两个项目都转换为相同的值，因此@(MyItem->'X')将导致X;X转换。要包含原始项目的一部分，可以通过访问元数据值%()。因此@(MyItem->'Hello %(Identity)')将产生Hello A;Hello B，因为Identity是默认元数据。

在这种情况下，DistFiles包含相对于项目文件的路径的项目将转换为引用完整路径。尽管没有充分记录，但由于发布逻辑期望ResolvedFileToPublish项目包含绝对/完整路径，因此这是必需的，因为它也可以跨项目引用进行流动-例如，库可能包含仅发布的资产，而消耗项目需要在项目复制期间复制它们发布，因此它需要传递完整路径而不是相对路径，而在消费项目中找不到该相对路径。

Exclude =“ @（ResolvedFileToPublish）”是做什么的？

Include="..."可以对项目进行过滤以不添加Exclude定义中的项目。在这种情况下，操作将转换为“添加DistFiles项目的完整路径作为ResolvedFileToPublish项目，除非已经存在ResolvedFileToPublish具有相同标识（即，引用磁盘上的相同文件）的项目”。

这很有用，以免将发布逻辑与重复项混淆。目前尚不确定这是否会真正导致问题，但是为了成为一个好公民，最好不要引起其他文件副本/文件上传（网络部署）等。

文件可能已经存在的原因是，它们可能已被Web SDK中定义的默认项目规范之一包括，其中包括（例如）wwwroot要发布的文件或类似文件，具体取决于您的项目设置。模板只是不想引起冲突。

DistFiles.Identity指的是什么，它在哪里设置？

如上所述，项目具有一些默认元数据，并且Identity是其中之一。在这种情况下，将DistFiles根据相对于项目的文件规范来创建项目，因此项目的标识为项目相对路径（ClientApp\dist\...）。

由于ResolvedFileToPublish项目包含绝对路径，因此RelativePath元数据会告诉发布逻辑在发布过程中将文件放置在何处。您也可以使用它来重命名文件或将其放置在子文件夹中。

在详细日志/结构化日志中，您应该看到要添加的项目C:\path\to\proj\ClientApp\dist\index.html与RelativePath=ClientApp\dist\index.html和CopyToPublishDirectory=PreserveNewest元数据在一起。

物料分批

在上面的代码中，从属性内引用元数据：

<RelativePath>%(DistFiles.Identity)</RelativePath>

虽然这告诉MSBuild将RelativePath元数据设置为源DistFiles项目的元数据Identity，但这也会触发一个称为batching的功能。

对于%(Item.Metadata)MSBuild看到的每一个宽松的规范（请注意，这仅在目标内部有效），MSBuild将引用的项目分组为具有相同属性的“批”。然后，它将为每个批次运行一次用于该批次的任务（在我们的示例中为一个固有项目添加任务），在这种情况下，该@()符号只会产生该特定批次的项目。

仅在批量处理时%(XYZ.Identity)，这并不重要，可以将其视为简单的“所有人”。

确切地说，该<ResolvedFileToPublish Include=...部分将转换为：“对于每个具有相同Identity元数据的DistFiles集，将这些项目转换为它们的完整路径，并且除非ResolvedFileToPublish已经存在具有此文件名的a，否则ResolvedFileToPublish为它们创建一个项目并将元数据RelativePath设置为DistFile项目的Identity值，并且CopyToPublishDirectory元数据设置为PreserveNewest。”