Merge pull request #13364 from JanKrivanek/patch-4

Document Culture/WithCulture metadata in common-msbuild-project-items.md

Author: prmerger-automator[bot]

docs/msbuild/common-msbuild-project-items.md

@@ -104,6 +104,8 @@ Represents resources to be embedded in the generated assembly.
 
 | Item metadata name | Description |
 |-----------------------| - |
+| Culture | Optional string. Specifies the culture of the resource file. If specified, the build process doesn't auto-infer the culture based on file extension (which is dependent on the cultures available to .NET/OS on the machine hosting the build). Setting either `Culture={culture identifier}` or `WithCulture=false` metadata is highly recommended. |
+| WithCulture | Optional bool. Specifies that the file is culture neutral and culture detection by [`AssignCulture`](./assignculture-task.md) task should be skipped. Setting either `Culture={culture identifier}` or `WithCulture=false` metadata is highly recommended. |
 | DependentUpon | Optional string. Specifies the file this file depends on to compile correctly |
 | Generator | Optional string. The name of any file generator that is run on this item. |
 | LastGenOutput | Optional string. The name of the file that was created by any file generator that ran on this item. |

docs/msbuild/generateresource-task.md

@@ -34,33 +34,33 @@ The following table describes the parameters of the `GenerateResource` task.
 |`EnvironmentVariables`|Optional `String[]` parameter.<br /><br /> Specifies an array of name-value pairs of environment variables that should be passed to the spawned *resgen.exe*, in addition to (or selectively overriding) the regular environment block.|
 |`ExcludedInputPaths`|Optional <xref:Microsoft.Build.Framework.ITaskItem>`[]` parameter.<br /><br /> Specifies an array of items that specify paths from which tracked inputs will be ignored during Up-to-date checking.|
 |`ExecuteAsTool`|Optional `Boolean` parameter.<br /><br /> If `true`, runs *tlbimp.exe* and *aximp.exe* from the appropriate target framework out-of-proc to generate the necessary wrapper assemblies. This parameter allows multi-targeting of `ResolveComReferences`.|
-|`FilesWritten`|Optional <xref:Microsoft.Build.Framework.ITaskItem>`[]` output parameter.<br /><br /> Contains the names of all files written to disk. This includes the cache file, if any. This parameter is useful for implementations of Clean.|
+|`FilesWritten`|Optional <xref:Microsoft.Build.Framework.ITaskItem>`[]` output parameter.<br /><br /> Contains the names of all files written to disk, including the cache file, if any. This parameter is useful for implementations of Clean.|
 |`MinimalRebuildFromTracking`|Optional `Boolean` parameter.<br /><br /> Gets or sets a switch that specifies whether tracked incremental build will be used. If `true`, incremental build is turned on; otherwise, a rebuild will be forced.|
-|`NeverLockTypeAssemblies`|Optional `Boolean` parameter.<br /><br /> Gets or sets a Boolean value that specifies whether to create a new [AppDomain](/dotnet/api/system.appdomain) to evaluate the resources (*.resx*) files (true) or to create a new [AppDomain](/dotnet/api/system.appdomain) only when the resources files reference a user's assembly (false).|
+|`NeverLockTypeAssemblies`|Optional `Boolean` parameter.<br /><br /> Gets or sets a Boolean value that specifies whether to create a new [AppDomain](/dotnet/api/system.appdomain) to evaluate the resources (`.resx`) files (true) or to create a new [AppDomain](/dotnet/api/system.appdomain) only when the resources files reference a user's assembly (false).|
 |`OutputResources`|Optional <xref:Microsoft.Build.Framework.ITaskItem>`[]` output parameter.<br /><br /> Specifies the name of the generated files, such as `.resources` files. If you do not specify a name, the name of the matching input file is used and the `.resources` file that is created is placed in the directory that contains the input file.|
 |`PublicClass`|Optional `Boolean` parameter.<br /><br /> If `true`, creates a strongly typed resource class as a public class.|
-|`References`|Optional `String[]` parameter.<br /><br /> References to load types in `.resx` files from. `.resx` file data elements may have a .NET type. When the *.resx* file is read, this type must be resolved. Typically, it is resolved successfully by using standard type loading rules. If you provide assemblies in `References`, they take precedence.<br /><br /> This parameter is not required for strongly typed resources.|
+|`References`|Optional `String[]` parameter.<br /><br /> References to load types in `.resx` files from. `.resx` file data elements may have a .NET type. When the *.resx* file is read, this type must be resolved. Typically, it is resolved successfully by using standard type loading rules. If you provide assemblies in `References`, they take precedence.<br /><br /> This parameter isn't required for strongly typed resources.|
 |`SdkToolsPath`|Optional `String` parameter.<br /><br /> Specifies the path to the SDK tools, such as *resgen.exe*.|
-|`Sources`|Required <xref:Microsoft.Build.Framework.ITaskItem>`[]` parameter.<br /><br /> Specifies the items to convert. Items passed to this parameter must have one of the following file extensions:<br /><br /> -   `.txt`: Specifies the extension for a text file to convert. Text files can only contain string resources.<br />-   *.resx*: Specifies the extension for an XML-based resource file to convert.<br />-   *.restext*: Specifies the same format as *.txt*. This different extension is useful if you want to clearly distinguish source files that contain resources from other source files in your build process.<br />-   *.resources*: Specifies the extension for a resource file to convert.|
-|`StateFile`|Optional <xref:Microsoft.Build.Framework.ITaskItem> parameter.<br /><br /> Specifies the path to an optional cache file that is used to speed up dependency checking of links in *.resx* input files.|
-|`StronglyTypedClassName`|Optional `String` parameter.<br /><br /> Specifies the class name for the strongly typed resource class. If this parameter is not specified, the base name of the resource file is used.|
-|`StronglyTypedFilename`|Optional <xref:Microsoft.Build.Framework.ITaskItem> parameter.<br /><br /> Specifies the filename for the source file. If this parameter is not specified, the name of the class is used as the base filename, with the extension dependent on the language. For example: *MyClass.cs*.|
+|`Sources`|Required <xref:Microsoft.Build.Framework.ITaskItem>`[]` parameter.<br /><br /> Specifies the items to convert. Items passed to this parameter must have one of the following file extensions:<br /><br /> -   `.txt`: Specifies the extension for a text file to convert. Text files can only contain string resources.<br />-   `.resx`: Specifies the extension for an XML-based resource file to convert.<br />-   `.restext`: Specifies the same format as `.txt`. This different extension is useful if you want to clearly distinguish source files that contain resources from other source files in your build process.<br />-   `.resources`: Specifies the extension for a resource file to convert.|
+|`StateFile`|Optional <xref:Microsoft.Build.Framework.ITaskItem> parameter.<br /><br /> Specifies the path to an optional cache file that is used to speed up dependency checking of links in `.resx` input files.|
+|`StronglyTypedClassName`|Optional `String` parameter.<br /><br /> Specifies the class name for the strongly typed resource class. If this parameter isn't specified, the base name of the resource file is used.|
+|`StronglyTypedFilename`|Optional <xref:Microsoft.Build.Framework.ITaskItem> parameter.<br /><br /> Specifies the filename for the source file. If this parameter isn't specified, the name of the class is used as the base filename, with the extension dependent on the language. For example: *MyClass.cs*.|
 |`StronglyTypedLanguage`|Optional `String` parameter.<br /><br /> Specifies the language to use when generating the class source for the strongly typed resource. This parameter must match exactly one of the languages used by the CodeDomProvider. For example: `VB` or `C#`.<br /><br /> By passing a value to this parameter, you instruct the task to generate strongly typed resources.|
 |`StronglyTypedManifestPrefix`|Optional `String` parameter.<br /><br /> Specifies the resource namespace or manifest prefix to use in the generated class source for the strongly typed resource.|
-|`StronglyTypedNamespace`|Optional `String` parameter.<br /><br /> Specifies the namespace to use for the generated class source for the strongly typed resource. If this parameter is not specified, any strongly typed resources are in the global namespace.|
+|`StronglyTypedNamespace`|Optional `String` parameter.<br /><br /> Specifies the namespace to use for the generated class source for the strongly typed resource. If this parameter isn't specified, any strongly typed resources are in the global namespace.|
 |`TLogReadFiles`|Optional <xref:Microsoft.Build.Framework.ITaskItem>`[]` read-only parameter.<br /><br /> Gets an array of items that represent the read tracking logs.|
 |`TLogWriteFiles`|Optional <xref:Microsoft.Build.Framework.ITaskItem>`[]` read-only parameter.<br /><br /> Gets an array of items that represent the write tracking logs.|
-|`ToolArchitecture`|Optional <xref:System.String?displayProperty=fullName> parameter.<br /><br /> Used to determine whether or not *Tracker.exe* needs to be used to spawn *ResGen.exe*.<br /><br /> Should be parsable to a member of the <xref:Microsoft.Build.Utilities.ExecutableType> enumeration. If `String.Empty`, uses a heuristic to determine a default architecture. Should be parsable to a member of the Microsoft.Build.Utilities.ExecutableType enumeration.|
+|`ToolArchitecture`|Optional <xref:System.String?displayProperty=fullName> parameter.<br /><br /> Used to determine whether or not *Tracker.exe* needs to be used to spawn *ResGen.exe*.<br /><br /> Should be parsable to a member of the <xref:Microsoft.Build.Utilities.ExecutableType> enumeration. If `String.Empty`, uses a heuristic to determine a default architecture. Should be parsable to a member of the `Microsoft.Build.Utilities.ExecutableType` enumeration.|
 |`TrackerFrameworkPath`|Optional `String` parameter.<br /><br /> Specifies the path to the appropriate .NET Framework location that contains *FileTracker.dll*.<br /><br /> If set, the user takes responsibility for making sure that the bitness of the *FileTracker.dll* that they pass matches the bitness of the *ResGen.exe* that they intend to use. If not set, the task decides the appropriate location based on the current .NET Framework version.|
 |`TrackerLogDirectory`|Optional `String` parameter.<br /><br /> Specifies the intermediate directory into which the tracking logs from running this task will be placed.|
 |`TrackerSdkPath`|Optional `String` parameter.<br /><br /> Specifies the path to the appropriate Windows SDK location that contains *Tracker.exe*.<br /><br /> If set, the user takes responsibility for making sure that the bitness of the *Tracker.exe* that they pass matches the bitness of the *ResGen.exe* that they intend to use. If not set, the task decides the appropriate location based on the current Windows SDK.|
 |`TrackFileAccess`|Optional <xref:System.Boolean> parameter.<br /><br /> If true, the directory of the input file is used for resolving relative file paths.|
-|`UsePreserializedResources`|Optional `Boolean` parameter.<br /><br /> If `true`, specifies that non-String resources are to be serialized using <xref:System.Resources.Extensions.PreserializedResourceWriter> instead of <xref:System.Resources.ResourceWriter>, which is not supported on .NET Core or .NET 5 or later.|
+|`UsePreserializedResources`|Optional `Boolean` parameter.<br /><br /> If `true`, specifies that non-String resources are to be serialized using <xref:System.Resources.Extensions.PreserializedResourceWriter> instead of <xref:System.Resources.ResourceWriter>, which isn't supported on .NET Core or .NET 5 or later.|
 |`UseSourcePath`|Optional `Boolean` parameter.<br /><br /> If `true`, specifies that the input file's directory is to be used for resolving relative file paths.|
 
 ## Remarks
 
-Because `.resx` files may contain links to other resource files, it is not sufficient to simply compare `.resx` and `.resources` file timestamps to see if the outputs are up to date. Instead, the `GenerateResource` task follows the links in the `.resx` files and checks the timestamps of the linked files as well. This means that you should not generally use `Inputs` and `Outputs` attributes on the target containing the `GenerateResource` task, as this may cause it to be skipped when it should actually run.
+Because `.resx` files may contain links to other resource files, it isn't sufficient to simply compare `.resx` and `.resources` file timestamps to see if the outputs are up to date. Instead, the `GenerateResource` task follows the links in the `.resx` files and checks the timestamps of the linked files as well. This means that you should not generally use `Inputs` and `Outputs` attributes on the target containing the `GenerateResource` task, as this may cause it to be skipped when it should actually run.
 
 In addition to the parameters listed above, this task inherits parameters from the <xref:Microsoft.Build.Tasks.TaskExtension> class, which itself inherits from the <xref:Microsoft.Build.Utilities.Task> class. For a list of these additional parameters and their descriptions, see [TaskExtension base class](../msbuild/taskextension-base-class.md).
 
@@ -90,6 +90,7 @@ Assuming that the assembly is named myAssembly, the following code generates an
 <ItemGroup>
     <EmbeddedResource Include="myResource.resx">
         <LogicalName>someQualifier.someResource.resources</LogicalName>
+        <WithCulture>false</WithCulture>
     </EmbeddedResource>
 </ItemGroup>
 ```