Add new resource naming article

docs/core/project-sdk/msbuild-props.md

@@ -1,12 +1,12 @@
 ---
 title: MSBuild properties for Microsoft.NET.Sdk
-description: Reference for the MSBuild properties that are understood by the .NET Core SDK.
+description: Reference for the MSBuild properties and items that are understood by the .NET Core SDK.
 ms.date: 02/14/2020
 ms.topic: reference
 ---
-# MSBuild properties for .NET Core SDK projects
+# MSBuild reference for .NET Core SDK projects
 
-This page describes MSBuild properties for configuring .NET Core projects. You can specify *metadata* for each property as child elements of the property.
+This page is a reference for the MSBuild properties and items that you can use to configure .NET Core projects.
 
 > [!NOTE]
 > This page is a work in progress and does not list all of the useful MSBuild properties for the .NET Core SDK. For a list of common MSBuild properties, see [Common MSBuild properties](/visualstudio/msbuild/common-msbuild-project-properties).
@@ -72,7 +72,7 @@ You can specify properties such as `PackageId`, `PackageVersion`, `PackageIcon`,
 </PropertyGroup>
 ```
 
-## Publish properties
+## Publish properties and items
 
 - [RuntimeIdentifier](#runtimeidentifier)
 - [RuntimeIdentifiers](#runtimeidentifiers)
@@ -130,8 +130,24 @@ For more information about deployment, see [.NET Core application deployment](..
 
 ## Compile properties
 
+- [EmbeddedResourceUseDependentUponConvention](#embeddedresourceusedependentuponconvention)
 - [LangVersion](#langversion)
 
+### EmbeddedResourceUseDependentUponConvention
+
+The `EmbeddedResourceUseDependentUponConvention` property defines whether resource manifest file names are generated from type information in source files that are colocated with resource files. For example, if *Form1.resx* is in the same folder as *Form1.cs*, and `EmbeddedResourceUseDependentUponConvention` is set to `true`, the generated *.resources* file takes its name from the first type that's defined in *Form1.cs*. For example, if `MyNamespace.Form1` is the first type defined in *Form1.cs*, the generated file name is *MyNamespace.Form1.resources*.
+
+> [!NOTE]
+> If `LogicalName`, `ManifestResourceName`, or `DependentUpon` metadata is specified for an `EmbeddedResource` item, the generated manifest file name for that resource file is based on that metadata instead.
+
+By default, in a new .NET Core project, this property is set to `true`. If set to `false`, and no `LogicalName`, `ManifestResourceName`, or `DependentUpon` metadata is specified for the `EmbeddedResource` item in the project file, the resource manifest file name is based off the root namespace for the project and the relative file path to the *.resx* file. For more information, see [How resource manifest files are named](../resources/manifest-file-names.md).
+
+```xml
+<PropertyGroup>
+  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
+</PropertyGroup>
+```
+
 ### LangVersion
 
 The `LangVersion` property lets you specify a specific programming language version. For example, if you want access to C# preview features, set `LangVersion` to `preview`.
@@ -248,7 +264,7 @@ The `TieredCompilationQuickJitForLoops` property configures whether the JIT comp
 </PropertyGroup>
 ```
 
-## Reference properties
+## Reference properties and items
 
 - [AssetTargetFallback](#assettargetfallback)
 - [PackageReference](#packagereference)
@@ -270,7 +286,7 @@ You can set the `AssetTargetFallback` property to one or more [target framework
 
 ### PackageReference
 
-The `PackageReference` defines a reference to a NuGet package. For example, you may want to reference a single package instead of a [metapackage](../packages.md#metapackages).
+The `PackageReference` item defines a reference to a NuGet package. For example, you may want to reference a single package instead of a [metapackage](../packages.md#metapackages).
 
 The `Include` attribute specifies the package ID. The `Version` attribute specifies the version or version range. For information about how to specify a minimum version, maximum version, range, or exact match, see [Version ranges](/nuget/concepts/package-versioning#version-ranges). You can also add the following metadata to a project reference: `IncludeAssets`, `ExcludeAssets`, and `PrivateAssets`.
 
@@ -302,7 +318,7 @@ The project file snippet in the following example references a project named `Pr
 
 The `Reference` item defines a reference to an assembly file.
 
-The `Include` attribute specifies the name of the file, and the `HintPath` child element specifies the path to the assembly.
+The `Include` attribute specifies the name of the file, and the `HintPath` metadata specifies the path to the assembly.
 
 ```xml
 <ItemGroup>

docs/core/project-sdk/overview.md

@@ -1,5 +1,6 @@
 ---
 title: .NET Core project SDK overview
+titleSuffix: ""
 description: Learn about the .NET Core project SDKs.
 ms.date: 02/02/2020
 ms.topic: conceptual
@@ -125,7 +126,7 @@ To resolve the errors, do one of the following:
 
 ## Customize the build
 
-There are various ways to [customize a build](/visualstudio/msbuild/customize-your-build). You may want to override a property by passing it as an argument to an [msbuild](/visualstudio/msbuild/msbuild-command-line-reference) or [dotnet](../tools/index.md) command. You can also add the property to the project file or to a *Directory.Build.props* file. For a list of useful properties for .NET Core projects, see [MSBuild properties for .NET Core SDK projects](msbuild-props.md).
+There are various ways to [customize a build](/visualstudio/msbuild/customize-your-build). You may want to override a property by passing it as an argument to an [msbuild](/visualstudio/msbuild/msbuild-command-line-reference) or [dotnet](../tools/index.md) command. You can also add the property to the project file or to a *Directory.Build.props* file. For a list of useful properties for .NET Core projects, see [MSBuild reference for .NET Core SDK projects](msbuild-props.md).
 
 ### Custom targets
 

docs/core/resources/manifest-file-names.md

@@ -0,0 +1,84 @@
+---
+title: How MSBuild generates manifest file names
+description: Describes the factors that influence the name of a resource manifest file name that's generated by MSBuild at compile time.
+ms.date: 05/08/2020
+ms.topic: conceptual
+---
+# How resource manifest files are named
+
+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 <xref:System.Resources.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](../project-sdk/overview.md#default-compilation-includes), 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](../project-sdk/msbuild-props.md#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*.
+
+```xml
+<EmbeddedResource Include="X.resx" LogicalName="SomeName.resources" />
+```
+
+-or-
+
+```xml
+<EmbeddedResource Include="X.fr-FR.resx" LogicalName="SomeName.resources" />
+```
+
+## 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*.
+
+```xml
+<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*.
+
+```xml
+<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*).
+
+```xml
+<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*).
+
+```xml
+<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.
+
+> [!NOTE]
+>
+> - If `RootNamespace` is not defined, it defaults to the project name.
+> - If `LogicalName`, `ManifestResourceName`, or `DependentUpon` metadata is specified for an `EmbeddedResource` item in the project file, this naming rule does not apply to that resource file.
+
+## See also
+
+- [How Manifest Resource Naming Works](https://gist.github.com/BenVillalobos/041673b9a73bec60fdc3bf0f86fae62a)
+- [MSBuild properties for .NET Core SDK projects](../project-sdk/msbuild-props.md)
+- [MSBuild breaking changes](../compatibility/msbuild.md)

docs/core/toc.yml

@@ -401,6 +401,8 @@
     href: versions/selection.md
 - name: Runtime Identifier (RID) catalog
   href: rid-catalog.md
+- name: Resource manifest names
+  href: resources/manifest-file-names.md
 - name: Dependency management and loading
   items:
   - name: Dependency management

docs/core/tools/dependencies.md

@@ -69,5 +69,5 @@ dotnet remove package Microsoft.EntityFrameworkCore
 
 ## See also
 
-* [Package references in project files](../project-sdk/msbuild-props.md#reference-properties)
+* [Package references in project files](../project-sdk/msbuild-props.md#reference-properties-and-items)
 * [dotnet list package command](dotnet-remove-package.md)