如何命名资源清单文件

2025-06-22

当 MSBuild 编译 .NET Core 项目时，XML 资源文件（扩展名 为 .resx ）将转换为二进制 .resources 文件。二进制文件嵌入到编译器的输出中，可由 ResourceManager 读取。本文介绍 MSBuild 如何为每个 .resources 文件选择一个名称。

小窍门

如果将资源项显式添加到项目文件，并且它还包含在 .NET Core 的默认 include globs 中，则会出现生成错误。若要将资源文件手动包含为 EmbeddedResource 项，请将 EnableDefaultEmbeddedResourceItems 属性设置为 false。

默认名称

在 .NET Core 3.0 及更高版本中，满足以下两个条件时，将使用资源清单的默认名称：

资源文件未显式包含在项目文件中，作为具有EmbeddedResource、LogicalName或ManifestResourceName、DependentUpon元数据的项目项。
该 EmbeddedResourceUseDependentUponConvention 属性未在项目文件中设置为 false 。默认情况下，此属性设置为 true。有关详细信息，请参阅 EmbeddedResourceUseDependentUponConvention。

如果资源文件与具有同一根文件名的源文件（.cs 或 .vb）并置，清单文件名便使用源文件中定义的第一种类型的全名。例如，如果MyNamespace.Form1 是 Form1.cs 中定义的第一个类型，且 Form1.cs 与 Form1.resx 并置，则为该资源文件生成的清单名称为 MyNamespace.Form1.resources。

LogicalName 元数据

如果资源文件作为具有 EmbeddedResource 元数据的 LogicalName 项显式包含在项目文件中，则将 LogicalName 值用作清单名称。 LogicalName 优先于任何其他元数据或设置。

例如，以下项目文件代码片段中定义的资源文件的清单名称是 SomeName.resources。

<EmbeddedResource Include="X.resx" LogicalName="SomeName.resources" />

-或-

<EmbeddedResource Include="X.fr-FR.resx" LogicalName="SomeName.resources" />

注释

如果未指定 LogicalName，则文件名中包含两个点的 EmbeddedResource 不会生效，这也就是说，. 不会返回该文件。

以下示例正常工作：
```
<EmbeddedResource Include="X.resx" />
```
以下示例不起作用：
```
<EmbeddedResource Include="X.fr-FR.resx" />
```

ManifestResourceName 元数据

如果资源文件作为具有 EmbeddedResource 元数据（并且 ManifestResourceName 不存在）的 LogicalName 项显式包含在项目文件中，则 ManifestResourceName 值与文件扩展名 .resources 一起用作清单文件名。

例如，以下项目文件代码片段中定义的资源文件的清单名称是 SomeName.resources。

<EmbeddedResource Include="X.resx" ManifestResourceName="SomeName" />

以下项目文件片段中定义的资源文件的清单名称为 SomeName。fr-FR.resources。

<EmbeddedResource Include="X.fr-FR.resx" ManifestResourceName="SomeName.fr-FR" />

DependentUpon 元数据

如果项目文件中显式包含资源文件作为EmbeddedResource项并具备DependentUpon元数据（且LogicalNameManifestResourceName不存在），则使用由DependentUpon定义的源文件中的信息来生成资源清单文件名。具体而言，在源文件中定义的第一种类型的名称用于清单名称，如下所示： Namespace.Classname[。Culture].resources。

例如，以下项目文件代码片段中定义的资源文件的清单名称是 Namespace.Classname.resources （其中 Namespace.Classname 是 MyTypes.cs中定义的第一个类）。

<EmbeddedResource Include="X.resx" DependentUpon="MyTypes.cs">

以下项目文件片段中定义的资源文件的清单名称为 Namespace.Classname.fr-FR.resources（其中 Namespace.Classname 是在 MyTypes.cs 中定义的第一个类）。

<EmbeddedResource Include="X.fr-FR.resx" DependentUpon="MyTypes.cs">

EmbeddedResourceUseDependentUponConvention 属性

如果 EmbeddedResourceUseDependentUponConvention 设置为 false 项目文件中，则每个资源清单文件名都基于项目的根命名空间以及从项目根目录到 .resx 文件的相对路径。更具体地说，生成的资源清单文件名是 RootNamespace.RelativePathWithDotsForSlashes.[Culture.]资源。这也是用于在 3.0 之前的 .NET Core 版本中生成清单名称的逻辑。

注释

如果未 RootNamespace 定义，则默认为项目名称。
如果为项目文件中的LogicalName项指定了ManifestResourceName、DependentUpon或EmbeddedResource元数据，命名规则则不适用于该资源文件。

通过