visual-studio - 有关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/en-us/aspnet/core/host-and-deploy/visual-studio-publish-profiles?view=aspnetcore-2.2#selective-file-inclusion

Answer 1

SpaRoot在哪里设置？


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

请注意，属性就像全局键值字典（只要PropertyGroup中的XML节点定义属性，它就会覆盖具有相同名称的现有属性）。
但是项目就像列表。您可以添加（<MyItem Include="..."/>），删除（... Remove="..."）甚至更新项目（仅在静态部分中的... Update="..."，在目标内部不包括/删除）意味着“全部更新”，您只能使用Condition属性进行过滤）。项目就像对象，它们具有一个称为“ Identity”的“ ID”，并且可以具有称为“元数据”的其他属性。 “身份”是在Include中指定的部分，它可以是也可以不是文件名。如果引用了文件，则会自动添加一些众所周知的元数据（例如文件修改日期和FullPath）。也可以在项目XML元素上将元数据定义为属性（例如，如PackageReference项目中的Version="1.2.3"所示）或项目元素的子元素（例如，如上所示的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中提供的）对这些属性或项进行配置。模板。因此，我们打算添加被认为是“公共API”的ResolvedFileToPublish项，而不是_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，否则创建将元数据 ResolvedFileToPublish设置为DistFile项的 RelativePath值并将 Identity元数据设置为 CopyToPublishDirectory的 PreserveNewest项。”