From 03c8417f28b867285375798f8ab3329df5b45913 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Thu, 7 May 2020 14:50:19 -0700 Subject: [PATCH 1/7] add embeddedresourceusedependentuponconvention --- docs/core/project-sdk/msbuild-props.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index ba1c37aec31a0..edd95483e485f 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -130,8 +130,19 @@ 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 the namespace and class name of the first type in a source file that's colocated with a resource file. If you omit this property in a .NET Core project, it defaults 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. + +```xml + + false + +``` + ### 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`. From ad047367bbd519781b30fc56737c97761c7adb4b Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Fri, 8 May 2020 17:39:22 -0700 Subject: [PATCH 2/7] add new resource naming article --- docs/core/project-sdk/msbuild-props.md | 11 ++- docs/core/project-sdk/overview.md | 1 + docs/core/resources/manifest-file-names.md | 80 ++++++++++++++++++++++ docs/core/toc.yml | 2 + 4 files changed, 91 insertions(+), 3 deletions(-) create mode 100644 docs/core/resources/manifest-file-names.md diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index edd95483e485f..74dd147b34ec3 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -6,7 +6,7 @@ ms.topic: reference --- # MSBuild properties 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 that you can use to configure .NET Core projects. You can specify *metadata* for each property either as an attribute or a child element of the property. > [!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). @@ -135,11 +135,16 @@ For more information about deployment, see [.NET Core application deployment](.. ### EmbeddedResourceUseDependentUponConvention -The `EmbeddedResourceUseDependentUponConvention` property defines whether resource manifest file names are generated from the namespace and class name of the first type in a source file that's colocated with a resource file. If you omit this property in a .NET Core project, it defaults 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. +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. ```xml - false + true ``` diff --git a/docs/core/project-sdk/overview.md b/docs/core/project-sdk/overview.md index ddca21a5b0bc8..1c30095864a9b 100644 --- a/docs/core/project-sdk/overview.md +++ b/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 diff --git a/docs/core/resources/manifest-file-names.md b/docs/core/resources/manifest-file-names.md new file mode 100644 index 0000000000000..0acc61f19b5d2 --- /dev/null +++ b/docs/core/resources/manifest-file-names.md @@ -0,0 +1,80 @@ +--- +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 can be read by the . This article describes how MSBuild chooses a name for each *.resources* file. + +## 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 + +``` + +-or- + +```xml + +``` + +## 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 + +``` + +The manifest name for the resource file that's defined in the following project file snippet is *SomeName.fr-FR.resources*. + +```xml + +``` + +## 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 + +``` + +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 + +``` + +## 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 + +- [MSBuild properties for .NET Core SDK projects](../project-sdk/msbuild-props.md) +- [MSBuild breaking changes](../compatibility/msbuild.md) diff --git a/docs/core/toc.yml b/docs/core/toc.yml index 410e374fe9b11..03f31693d30cf 100644 --- a/docs/core/toc.yml +++ b/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 From 425fc19092abf43155371aae17ad9f6bd699a54b Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Fri, 8 May 2020 17:40:38 -0700 Subject: [PATCH 3/7] add see also link to gist --- docs/core/resources/manifest-file-names.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/core/resources/manifest-file-names.md b/docs/core/resources/manifest-file-names.md index 0acc61f19b5d2..3d73cafed1ec4 100644 --- a/docs/core/resources/manifest-file-names.md +++ b/docs/core/resources/manifest-file-names.md @@ -76,5 +76,6 @@ If `EmbeddedResourceUseDependentUponConvention` is set to `false` in the project ## 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) From 684c801505e44fd0e7f44faba09f68c503e53981 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Fri, 8 May 2020 18:01:15 -0700 Subject: [PATCH 4/7] add tip for adding resources --- docs/core/resources/manifest-file-names.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/core/resources/manifest-file-names.md b/docs/core/resources/manifest-file-names.md index 3d73cafed1ec4..da90c740933e7 100644 --- a/docs/core/resources/manifest-file-names.md +++ b/docs/core/resources/manifest-file-names.md @@ -8,6 +8,9 @@ ms.topic: conceptual 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 can be read by the . 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: From dfc3f8aac971cbdcace701220e03d8e2749654a5 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 11 May 2020 14:48:11 -0700 Subject: [PATCH 5/7] Apply suggestions from Rainer Co-authored-by: Rainer Sigwald --- docs/core/project-sdk/msbuild-props.md | 2 +- docs/core/resources/manifest-file-names.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index 74dd147b34ec3..0fa4cbb02d10a 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -6,7 +6,7 @@ ms.topic: reference --- # MSBuild properties for .NET Core SDK projects -This page is a reference for the MSBuild properties that you can use to configure .NET Core projects. You can specify *metadata* for each property either as an attribute or a child element of the property. +This page is a reference for the MSBuild properties 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). diff --git a/docs/core/resources/manifest-file-names.md b/docs/core/resources/manifest-file-names.md index da90c740933e7..7f737e34617bb 100644 --- a/docs/core/resources/manifest-file-names.md +++ b/docs/core/resources/manifest-file-names.md @@ -6,7 +6,7 @@ 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 can be read by the . This article describes how MSBuild chooses a name for each *.resources* file. +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 . 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. From 88cdfc7165753134a5ee96c84459c768939945c6 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 11 May 2020 16:11:07 -0700 Subject: [PATCH 6/7] add link to naming article --- docs/core/project-sdk/msbuild-props.md | 16 ++++++++-------- docs/core/project-sdk/overview.md | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index 0fa4cbb02d10a..d0b18a7f87092 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/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 is a reference for the MSBuild properties that you can use to configure .NET Core projects. +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`, ``` -## Publish properties +## Publish properties and items - [RuntimeIdentifier](#runtimeidentifier) - [RuntimeIdentifiers](#runtimeidentifiers) @@ -140,7 +140,7 @@ The `EmbeddedResourceUseDependentUponConvention` property defines whether resour > [!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. +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 @@ -264,7 +264,7 @@ The `TieredCompilationQuickJitForLoops` property configures whether the JIT comp ``` -## Reference properties +## Reference properties and items - [AssetTargetFallback](#assettargetfallback) - [PackageReference](#packagereference) @@ -286,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`. @@ -318,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 diff --git a/docs/core/project-sdk/overview.md b/docs/core/project-sdk/overview.md index 1c30095864a9b..3943af9da4008 100644 --- a/docs/core/project-sdk/overview.md +++ b/docs/core/project-sdk/overview.md @@ -122,7 +122,7 @@ To disable *all* implicit globs, set the `EnableDefaultItems` property to `false ## 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 From 97f4d0007160eefb7ca58dca74e6cf6626085e53 Mon Sep 17 00:00:00 2001 From: Genevieve Warren Date: Mon, 11 May 2020 16:16:52 -0700 Subject: [PATCH 7/7] fix build warning --- docs/core/tools/dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tools/dependencies.md b/docs/core/tools/dependencies.md index 10d376df84ded..d1779a0f61ffd 100644 --- a/docs/core/tools/dependencies.md +++ b/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)