How resource manifest files are named

Άρθρο
11/03/2021

When MSBuild compiles a .NET Core project, XML resource files, which have the .resx file extension, are converted into binary .resources files. The binary files are embedded into the output of the compiler and can be read by the ResourceManager. This article describes how MSBuild chooses a name for each .resources file.

Tip

If you explicitly add a resource item to your project file, and it's also included with the default include globs for .NET Core, you will get a build error. To manually include resource files as EmbeddedResource items, set the EnableDefaultEmbeddedResourceItems property to false.

Default name

In .NET Core 3.0 and later, the default name for a resource manifest is used when both of the following conditions are met:

The resource file is not explicitly included in the project file as an EmbeddedResource item with LogicalName, ManifestResourceName, or DependentUpon metadata.
The EmbeddedResourceUseDependentUponConvention property is not set to false in the project file. By default, this property is set to true. For more information, see EmbeddedResourceUseDependentUponConvention.

If the resource file is colocated with a source file (.cs or .vb) of the same root file name, the full name of the first type that's defined in the source file is used for the manifest file name. For example, if MyNamespace.Form1 is the first type defined in Form1.cs, and Form1.cs is colocated with Form1.resx, the generated manifest name for that resource file is MyNamespace.Form1.resources.

LogicalName metadata

If a resource file is explicitly included in the project file as an EmbeddedResource item with LogicalName metadata, the LogicalName value is used as the manifest name. LogicalName takes precedence over any other metadata or setting.

For example, the manifest name for the resource file that's defined in the following project file snippet is SomeName.resources.

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

-or-

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

Note

If LogicalName is not specified, an EmbeddedResource with two dots (.) in the file name doesn't work, which means that GetManifestResourceNames doesn't return that file.

The following example works correctly:
```
<EmbeddedResource Include="X.resx" />
```
The following example doesn't work:
```
<EmbeddedResource Include="X.fr-FR.resx" />
```

ManifestResourceName metadata

If a resource file is explicitly included in the project file as an EmbeddedResource item with ManifestResourceName metadata (and LogicalName is absent), the ManifestResourceName value, combined with the file extension .resources, is used as the manifest file name.

For example, the manifest name for the resource file that's defined in the following project file snippet is SomeName.resources.

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

The manifest name for the resource file that's defined in the following project file snippet is SomeName.fr-FR.resources.

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

DependentUpon metadata

If a resource file is explicitly included in the project file as an EmbeddedResource item with DependentUpon metadata (and LogicalName and ManifestResourceName are absent), information from the source file defined by DependentUpon is used for the resource manifest file name. Specifically, the name of the first type that's defined in the source file is used in the manifest name as follows: Namespace.Classname[.Culture].resources.

For example, the manifest name for the resource file that's defined in the following project file snippet is Namespace.Classname.resources (where Namespace.Classname is the first class that's defined in MyTypes.cs).

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

The manifest name for the resource file that's defined in the following project file snippet is Namespace.Classname.fr-FR.resources (where Namespace.Classname is the first class that's defined in MyTypes.cs).

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

EmbeddedResourceUseDependentUponConvention property

If EmbeddedResourceUseDependentUponConvention is set to false in the project file, each resource manifest file name is based off the root namespace for the project and the relative path from the project root to the .resx file. More specifically, the generated resource manifest file name is RootNamespace.RelativePathWithDotsForSlashes.[Culture.]resources. This is also the logic used to generate manifest names in .NET Core versions prior to 3.0.