diff --git a/docs/core/compatibility/2.2-3.0.md b/docs/core/compatibility/2.2-3.0.md index 25fb35d667895..56e2e29f48dd3 100644 --- a/docs/core/compatibility/2.2-3.0.md +++ b/docs/core/compatibility/2.2-3.0.md @@ -363,6 +363,14 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, *** +## MSBuild + +- [Resource manifest file name change](#resource-manifest-file-names) + +[!INCLUDE[Resource file names](~/includes/core-changes/msbuild/3.0/resource-manifest-name.md)] + +*** + ## Networking - [Default value of HttpRequestMessage.Version changed to 1.1](#default-value-of-httprequestmessageversion-changed-to-11) diff --git a/docs/core/compatibility/2.2-3.1.md b/docs/core/compatibility/2.2-3.1.md index 3385cc953c4f3..df4563b0ea0a2 100644 --- a/docs/core/compatibility/2.2-3.1.md +++ b/docs/core/compatibility/2.2-3.1.md @@ -366,6 +366,14 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core, *** +## MSBuild + +- [Resource manifest file name change](#resource-manifest-file-names) + +[!INCLUDE[Resource file names](~/includes/core-changes/msbuild/3.0/resource-manifest-name.md)] + +*** + ## Networking - [Default value of HttpRequestMessage.Version changed to 1.1](#default-value-of-httprequestmessageversion-changed-to-11) diff --git a/docs/core/compatibility/msbuild.md b/docs/core/compatibility/msbuild.md new file mode 100644 index 0000000000000..5a9a77d1e4eb6 --- /dev/null +++ b/docs/core/compatibility/msbuild.md @@ -0,0 +1,16 @@ +--- +title: MSBuild breaking changes +description: Lists the breaking changes in MSBuild for .NET Core. +ms.date: 02/10/2020 +--- +# MSBuild breaking changes + +The following breaking changes are documented on this page: + +- [Resource manifest file name change](#resource-manifest-file-names) + +## .NET Core 3.0 + +[!INCLUDE[Resource file names](~/includes/core-changes/msbuild/3.0/resource-manifest-name.md)] + +*** diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index d2aa1b78cba2f..a58c3e3f38a46 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -36,6 +36,8 @@ href: /ef/core/what-is-new/ef-core-3.0/breaking-changes?toc=/dotnet/core/compatibility/toc.json&bc=/dotnet/breadcrumb/toc.json - name: Globalization href: globalization.md + - name: MSBuild + href: msbuild.md - name: Networking href: networking.md - name: Visual Basic diff --git a/includes/core-changes/msbuild/3.0/resource-manifest-name.md b/includes/core-changes/msbuild/3.0/resource-manifest-name.md new file mode 100644 index 0000000000000..6d7656c7e90c5 --- /dev/null +++ b/includes/core-changes/msbuild/3.0/resource-manifest-name.md @@ -0,0 +1,82 @@ +### Resource manifest file names + +Starting in .NET Core 3.0, the generated resource manifest file name has changed. + +#### Version introduced + +3.0 + +#### Change description + +Prior to .NET Core 3.0, when [DependentUpon](/visualstudio/msbuild/common-msbuild-project-items#compile) metadata was set for a resource (*.resx*) file in the MSBuild project file, the generated manifest name was *Namespace.Classname.resources*. When [DependentUpon](/visualstudio/msbuild/common-msbuild-project-items#compile) was not set, the generated manifest name was *Namespace.Classname.FolderPathRelativeToRoot.Culture.resources*. + +Starting in .NET Core 3.0, when a *.resx* file is colocated with a source file of the same name, for example, in Windows Forms apps, the resource manifest name is generated from the full name of the first type in the source file. For example, if *Type.cs* is colocated with *Type.resx*, the generated manifest name is *Namespace.Classname.resources*. However, if you modify any of the attributes on the `EmbeddedResource` property for the *.resx* file, the generated manifest file name may be different: + +- If the `LogicalName` attribute on the `EmbeddedResource` property is set, that value is used as the resource manifest file name. + + Examples: + + ```xml + + -or- + + ``` + + **Generated resource manifest file name**: *SomeName.resources* (regardless of the *.resx* file name or culture or any other metadata). + +- If `LogicalName` is not set, but the `ManifestResourceName` attribute on the `EmbeddedResource` property is set, its value, combined with the file extension *.resources*, is used as the resource manifest file name. + + Examples: + + ```xml + + -or- + + ``` + + **Generated resource manifest file name**: *SomeName.resources* or *SomeName.fr-FR.resources*. + +- If the previous rules don't apply, and the `DependentUpon` attribute on the `EmbeddedResource` element is set to a source file, the type name of the first class in the source file is used in the resource manifest file name. More specifically, the generated file name is *Namespace.Classname\[.Culture].resources*. + + Examples: + + ```xml + + -or- + + ``` + + **Generated resource manifest file name**: *Namespace.Classname.resources* or *Namespace.Classname.fr-FR.resources* (where `Namespace.Classname` is the name of the first class in *MyTypes.cs*). + +- If the previous rules don't apply, `EmbeddedResourceUseDependentUponConvention` is `true` (the default for .NET Core), and there's a source file colocated with a *.resx* file that has the same base file name, the *.resx* file is made dependent upon the matching source file, and the generated name is the same as in the previous rule. This is the "default settings" rule for .NET Core projects. + + Examples: + + Files *MyTypes.cs* and *MyTypes.resx* or *MyTypes.fr-FR.resx* exist in the same folder. + + **Generated resource manifest file name**: *Namespace.Classname.resources* or *Namespace.Classname.fr-FR.resources* (where `Namespace.Classname` is the name of the first class in *MyTypes.cs*). + +- If none of the previous rules apply, the generated resource manifest file name is *RootNamespace.RelativePathWithDotsForSlashes.\[Culture.]resources*. The relative path is the value of the `Link` attribute of the `EmbeddedResource` element if it's set. Otherwise, the relative path is the value of the `Identity` attribute of the `EmbeddedResource` element. In Visual Studio, this is the path from the project root to the file in Solution Explorer. + +#### Recommended action + +If you're unsatisfied with the generated manifest names, you can: + +- Modify your resource file metadata according to one of the previously described naming rules. + +- Set `EmbeddedResourceUseDependentUponConvention` to `false` in your project file to opt out of the new convention entirely: + + ```xml + false + ``` + + > [!NOTE] + > If the `LogicalName` or `ManifestResourceName` attributes are present, their values will still be used for the generated file name. + +#### Category + +MSBuild + +#### Affected APIs + +N/A diff --git a/includes/core-changes/networking/3.0/httprequestmessage-version-change.md b/includes/core-changes/networking/3.0/httprequestmessage-version-change.md index 38c181e4b6dbd..1c1c48c806cfb 100644 --- a/includes/core-changes/networking/3.0/httprequestmessage-version-change.md +++ b/includes/core-changes/networking/3.0/httprequestmessage-version-change.md @@ -4,7 +4,7 @@ The default value of the