ResXGenerator

ResXGenerator is a C# source generator to generate strongly-typed resource classes for looking up localized strings.

NOTE: This is an independent fork of VocaDb/ResXFileCodeGenerator.

Usage

Install the Aigamo.ResXGenerator package:

dotnet add package Aigamo.ResXGenerator

Generated source from ActivityEntrySortRuleNames.resx:

// ------------------------------------------------------------------------------
//	<auto-generated>
//		This code was generated by a tool.
//
//		Changes to this file may cause incorrect behavior and will be lost if
//		the code is regenerated.
//	</auto-generated>
// ------------------------------------------------------------------------------
#nullable enable
namespace Resources
{
	using System.Globalization;
	using System.Resources;

	public static class ActivityEntrySortRuleNames
	{
		private static ResourceManager? s_resourceManager;
		public static ResourceManager ResourceManager => s_resourceManager ??= new ResourceManager("VocaDb.Web.App_GlobalResources.ActivityEntrySortRuleNames", typeof(ActivityEntrySortRuleNames).Assembly);
		public static CultureInfo? CultureInfo { get; set; }

		/// <summary>
		/// Looks up a localized string similar to Oldest.
		/// </summary>
		public static string? CreateDate => ResourceManager.GetString(nameof(CreateDate), CultureInfo);

		/// <summary>
		/// Looks up a localized string similar to Newest.
		/// </summary>
		public static string? CreateDateDescending => ResourceManager.GetString(nameof(CreateDateDescending), CultureInfo);
	}
}

New in version 3

The generator now utilizes the IIncrementalGenerator API to instantly update the generated code, thus giving you instant intellisense.
Added error handling for multiple members of same name, and members that have same name as class. These are clickable in visual studio to lead you to the source of the error, unlike before where they resulted in broken builds and you had to figure out why.
Namespace naming fixed for resx files in the top level folder.
Resx files can now be named with multiple extensions, e.g. myresources.cshtml.resx and will result in class being called myresources.
Added the ability to generate inner classes, partial outer classes and non-static members. Very useful if you want to ensure that only a particular class can use those resources instead of being spread around the codebase.
Use same 'Link' setting as msbuild uses to determine embedded file name.
Can set a class postfix name

New in version 3.1

The generator can now generate code to lookup translations instead of using the 20 year old System.Resources.ResourceManager

New in version 4

The generator now include support for IStringLocalizer and static method to register in IServiceCollection (no more need of "magic string" 😊

var local = provider.GetService<IArtistCategoriesNames>();
local.Actor // return the value string

or

var myViewModel = provider.GetService<IMyViewModel>();

public class MyViewModel(IArtistCategoriesNames resources) : IMyViewModel
{
	public string Value => resources.Actor // return also the value string
}

Options

GenerationType (per file or globally)

Use cases: ycanardeau#6.

Because the dependency injection on somes frameworks like Blazor. Uses the IStringLocalizer to get resources string. And to keep actual functionality. It now possible to choose the gerneration type by setting 'GenerationType'.

This paramerter is optional The default value is 'ResourceManager' to keep the actual behavior by default.

AllowedValues :

ResourceManager
- When this option chosen the generator will use the classic System.Resources.ResourceManager to get resources string.
CodeGeneration (You can chose this option to replace the GenerateCode option)
- When this option chosen the generator will generate code to get resources string. See Generate Code for more details))
StringLocalizer
- When this option chosen the generator will generate interface and class to use with Microsoft.Extensions.Localization IStringLocalizer<T>. To see how to use it see Using IStringLocalizer
SameAsOuter
- When this option chosen the generator will use the same generation type as the outer class if any. If no outer class exist it will fall back to 'ResourceManager'.

<ItemGroup>
	<EmbeddedResource Update="Resources\ArtistCategoriesNames.resx">
		<GenerationType>StringLocalizer</GenerationType>
	</EmbeddedResource>
</ItemGroup>

or

<ItemGroup>
	<EmbeddedResource Update="Resources\ArtistCategoriesNames.resx" GenerationType="StringLocalizer" />
</ItemGroup>

If you want to apply this globally, use

<PropertyGroup>
	<ResXGenerator_GenerationType>StringLocalizer</ResXGenerator_GenerationType>
</PropertyGroup>

PublicClass (per file or globally)

Use cases: VocaDB/ResXFileCodeGenerator#2.

Since version 2.0.0, ResXGenerator generates internal classes by default. You can change this behavior by setting PublicClass to true.

<ItemGroup>
	<EmbeddedResource Update="Resources\ArtistCategoriesNames.resx">
	<PublicClass>true</PublicClass>
	</EmbeddedResource>
</ItemGroup>

or

<ItemGroup>
	<EmbeddedResource Update="Resources\ArtistCategoriesNames.resx" PublicClass="true" />
</ItemGroup>

If you want to apply this globally, use

<PropertyGroup>
	<ResXGenerator_PublicClass>true</ResXGenerator_PublicClass>
</PropertyGroup>

NullForgivingOperators (globally)

Use cases: VocaDB/ResXFileCodeGenerator#1.

<PropertyGroup>
	<ResXGenerator_NullForgivingOperators>true</ResXGenerator_NullForgivingOperators>
</PropertyGroup>

By setting ResXGenerator_NullForgivingOperators to true, ResXGenerator generates

public static string CreateDate => ResourceManager.GetString(nameof(CreateDate), CultureInfo)!;

instead of

public static string? CreateDate => ResourceManager.GetString(nameof(CreateDate), CultureInfo);

Non-static classes (per file or globally)

To use generated resources with Microsoft.Extensions.Localization IStringLocalizer<T> and resource manager, the resolved type cannot be a static class. You can disable default behavior per file by setting the value to false.

<ItemGroup>
	<EmbeddedResource Update="Resources\ArtistCategoriesNames.resx">
	<StaticClass>false</StaticClass>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_StaticClass>false</ResXGenerator_StaticClass>
</PropertyGroup>

With global non-static class you can also reset StaticClass per file by setting the value to anything but false.

Partial classes (per file or globally)

To extend an existing class, you can make your classes partial. Not suitable for StringLocalizer.

<ItemGroup>
	<EmbeddedResource Update="Resources\ArtistCategoriesNames.resx">
	<PartialClass>true</PartialClass>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_PartialClass>true</ResXGenerator_PartialClass>
</PropertyGroup>

Static Members (per file or globally)

In some rare cases it might be useful for the members to be non-static. Not suitable for StringLocalizer.

<ItemGroup>
	<EmbeddedResource Update="Resources\ArtistCategoriesNames.resx">
	<StaticMembers>false</StaticMembers>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_StaticMembers>false</ResXGenerator_StaticMembers>
</PropertyGroup>

Postfix class name (per file or globally)

In some cases the it is useful if the name of the generated class doesn't follow the filename.

A clear example is Razor pages that always generates a class for the code-behind named "-Model". This example configuration allows you to use Resources.MyResource in your model, or @Model.Resources.MyResource in your cshtml file.

<ItemGroup>
	<EmbeddedResource Update="**/Pages/*.resx">
	<ClassNamePostfix>Model</ClassNamePostfix>
	<StaticMembers>false</StaticMembers>
	<StaticClass>false</StaticClass>
	<PartialClass>true</PartialClass>
	<PublicClass>true</PublicClass>
	<InnerClassVisibility>public</InnerClassVisibility>
	<PartialClass>false</PartialClass>
	<InnerClassInstanceName>Resources</InnerClassInstanceName>
	<InnerClassName>_Resources</InnerClassName>
	</EmbeddedResource>
</ItemGroup>

or just the postfix globally

<PropertyGroup>
	<ResXGenerator_ClassNamePostfix>Model</ResXGenerator_ClassNamePostfix>
</PropertyGroup>

Inner classes (per file or globally)

If your resx files are organized along with code files, it can be quite useful to ensure that the resources are not accessible outside the specific class the resx file belong to. Not suitable for StringLocalizer

<ItemGroup>
	<EmbeddedResource Update="**/*.resx">
		<DependentUpon>$([System.String]::Copy('%(FileName).cs'))</DependentUpon>
		<InnerClassName>MyResources</InnerClassName>
		<InnerClassVisibility>private</InnerClassVisibility>
		<InnerClassInstanceName>EveryoneLikeMyNaming</InnerClassInstanceName>
		<StaticMembers>false</StaticMembers>
		<StaticClass>false</StaticClass>
		<PartialClass>true</PartialClass>
	</EmbeddedResource>
	<EmbeddedResource Update="**/*.??.resx;**/*.??-??.resx">
		<DependentUpon>$([System.IO.Path]::GetFileNameWithoutExtension('%(FileName)')).resx</DependentUpon>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_InnerClassName>MyResources</ResXGenerator_InnerClassName>
	<ResXGenerator_InnerClassVisibility>private</ResXGenerator_InnerClassVisibility>
	<ResXGenerator_InnerClassInstanceName>EveryoneLikeMyNaming</InnerClassInstanceName>
	<ResXGenerator_StaticMembers>false</ResXGenerator_StaticMembers>
	<ResXGenerator_StaticClass>false</ResXGenerator_StaticClass>
	<ResXGenerator_PartialClass>true</ResXGenerator_PartialClass>
</PropertyGroup>

This example would generate files like this:

// ------------------------------------------------------------------------------
// <auto-generated>
//	This code was generated by a tool.
//
//	Changes to this file may cause incorrect behavior and will be lost if
//	the code is regenerated.
// </auto-generated>
// ------------------------------------------------------------------------------
#nullable enable
namespace Resources
{
	using System.Globalization;
	using System.Resources;

	public partial class ActivityEntryModel
	{
		public MyResources EveryoneLikeMyNaming { get; } = new();

		private class MyResources
		{
			private static ResourceManager? s_resourceManager;
			public static ResourceManager ResourceManager => s_resourceManager ??= new ResourceManager("VocaDb.Web.App_GlobalResources.ActivityEntryModel", typeof(ActivityEntryModel).Assembly);
			public CultureInfo? CultureInfo { get; set; }

			/// <summary>
			/// Looks up a localized string similar to Oldest.
			/// </summary>
			public string? CreateDate => ResourceManager.GetString(nameof(CreateDate), CultureInfo);

			/// <summary>
			/// Looks up a localized string similar to Newest.
			/// </summary>
			public string? CreateDateDescending => ResourceManager.GetString(nameof(CreateDateDescending), CultureInfo);
		}
	}
}

Inner Class Visibility (per file or globally)

By default inner classes are not generated, unless this setting is one of the following:

Public
Internal
Private
Protected
SameAsOuter

Case is ignored, so you could use "private".

It is also possible to use "NotGenerated" to override on a file if the global setting is to generate inner classes.

<ItemGroup>
	<EmbeddedResource Update="**/*.resx">
		<InnerClassVisibility>private</InnerClassVisibility>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_InnerClassVisibility>private</ResXGenerator_InnerClassVisibility>
</PropertyGroup>

Inner Class name (per file or globally)

By default the inner class is named "Resources", which can be overridden with this setting:

<ItemGroup>
	<EmbeddedResource Update="**/*.resx">
		<InnerClassName>MyResources</InnerClassName>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_InnerClassName>MyResources</ResXGenerator_InnerClassName>
</PropertyGroup>

Inner Class instance name (per file or globally)

By default no instance is available of the class, but that can be made available if this setting is given.

<ItemGroup>
	<EmbeddedResource Update="**/*.resx">
		<InnerClassInstanceName>EveryoneLikeMyNaming</InnerClassInstanceName>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_InnerClassInstanceName>EveryoneLikeMyNaming</ResXGenerator_InnerClassInstanceName>
</PropertyGroup>

For brevity, settings to make everything non-static is omitted.

Generate Code (per file or globally)

By default the ancient System.Resources.ResourceManager is used.

Benefits of using System.Resources.ResourceManager:

Supports custom CultureInfo
Languages are only loaded the first time a language is referenced
Only use memory for the languages used
Can ship satellite dlls separately

Disadvantages of using System.Resources.ResourceManager

The satellite dlls are always lazy loaded, so cold start penalty is high
Satellite dlls requires that you can scan the dir for which files are available, which can cause issues in some project types
Loading a satellite dll takes way more memory than just loading the respective strings
Build time for .resources -> satellite dll can be quite slow (~150msec per file)
Linker optimization doesn't work, since it cannot know which resources are referenced

Benefits of using GenerateCode code generation:

All languages are placed in the main dll, no more satellite dlls
Lookup speed is ~600% faster (5ns vs 33ns)
Zero allocations
Very small code footprint (about 10 bytes per language, instead of including the entire System.Resources)
Very fast build time
Because all code is referencing the strings directly, the linker can see which strings are actually used and which are not.
No cold start penalty
Smaller combined size of dll (up to 50%, since it doesn't need to store the keys for every single language)

Disadvantages of using GenerateCode code generation

Since CultureInfo are pre-computed, custom CultureInfo are not supported (or rather, they always return the default language)
Cannot lookup "all" keys (unless using reflection)
Main dll size increased since it contains all language strings (sometimes, the compiler can pack code strings much better than resource strings and it doesn't need to store the keys)

Notice, it is required to set GenerateResource to false for all resx files to prevent the built-in resgen.exe from running.

<ItemGroup>
	<EmbeddedResource Update="**/*.resx">
		<GenerateCode>true</GenerateCode>
		<GenerateResource>false</GenerateResource>
	</EmbeddedResource>
</ItemGroup>

or globally

<PropertyGroup>
	<ResXGenerator_GenerateCode>true</ResXGenerator_GenerateCode>
</PropertyGroup>
<ItemGroup>
	<EmbeddedResource Update="@(EmbeddedResource)">
		<GenerateResource>false</GenerateResource>
	</EmbeddedResource>
</ItemGroup>

If you get build error MSB3030, add this to your csproj to prevent it from trying to copy satellite dlls that no longer exists

<Target Name="PreventMSB3030" DependsOnTargets="ComputeIntermediateSatelliteAssemblies" BeforeTargets="GenerateSatelliteAssemblies" >
	<ItemGroup>
	<IntermediateSatelliteAssembliesWithTargetPath Remove="@(IntermediateSatelliteAssembliesWithTargetPath)"></IntermediateSatelliteAssembliesWithTargetPath>
	</ItemGroup>
</Target>

Resource file namespaces

Linked resources namespace follow Link if it is set. The Link setting is also used by msbuild built-in 'resgen.exe' to determine the embedded filename.

Use-case: Linking .resx files from outside source (e.g. generated in a localization sub-module by translators) and expose them as "Resources" namespace.

<ItemGroup>
	<EmbeddedResource Include="..\..\Another.Project\Translations\*.resx">
	<Link>Resources\%(FileName)%(Extension)</Link>
	<PublicClass>true</PublicClass>
	<StaticClass>false</StaticClass>
	</EmbeddedResource>
	<EmbeddedResource Update="..\..\Another.Project\Translations\*.*.resx">
	<DependentUpon>$([System.IO.Path]::GetFilenameWithoutExtension([System.String]::Copy('%(FileName)'))).resx</DependentUpon>
	</EmbeddedResource>
</ItemGroup>

You can also use the TargetPath to just overwrite the namespace

<ItemGroup>
	<EmbeddedResource Include="..\..\Another.Project\Translations\*.resx">
	<TargetPath>Resources\%(FileName)%(Extension)</TargetPath>
	<PublicClass>true</PublicClass>
	<StaticClass>false</StaticClass>
	</EmbeddedResource>
	<EmbeddedResource Update="..\..\Another.Project\Translations\*.*.resx">
	<DependentUpon>$([System.IO.Path]::GetFilenameWithoutExtension([System.String]::Copy('%(FileName)'))).resx</DependentUpon>
	</EmbeddedResource>
</ItemGroup>

It is also possible to set the namespace using the CustomToolNamespace setting. Unlike the Link and TargetPath, which will prepend the assemblies namespace and includes the filename, the CustomToolNamespace is taken verbatim.

<ItemGroup>
	<EmbeddedResource Update="**\*.resx">
	<CustomToolNamespace>MyNamespace.AllMyResourcesAreBelongToYouNamespace</CustomToolNamespace>
	</EmbeddedResource>
</ItemGroup>

Excluding resx files

Individual resx files can also be excluded from being processed by setting the SkipFile metadata to true.

<ItemGroup>
	<EmbeddedResource Update="ExcludedFile.resx">
		<SkipFile>true</SkipFile>
	</EmbeddedResource>
</ItemGroup>

Alternatively it can be set with the attribute SkipFile="true".

<ItemGroup>
	<EmbeddedResource Update="ExcludedFile.resx" SkipFile="true" />
</ItemGroup>

Using IStringLocalizer

To enablethe génération of interface and classes for your resource yo need to set de GenerationType to StringLocalizer. Note to use this you need to ensure you reference nuget on your project.

Now yous can register singletons for resources, simply using extension methods.

Examples for a file ArtistCategoriesNames.resx :

using ResXGenerator.Registration;

builder.Services
	.AddLogging();
	.AddLocalization()
	.UsingResXGenerator(); //This will register all resx class in one line of code

you can also (if you prefer to load ressources by namespace using individual registrations). A class of registration is created by namespace.

using MyResourceAssembly;

builder.Services
	.AddLogging();
	.AddLocalization()
	.UsingArtistCategoriesNamesResX(); //This will register all resx class of the namespace in one line of code

Now simply use the dependency injection to get your resources classes. All interface is in the same namespase as it's resource file. (or configured namespace)

Name		Name	Last commit message	Last commit date
Latest commit History 115 Commits
.github/workflows		.github/workflows
Aigamo.ResXGenerator.Tests		Aigamo.ResXGenerator.Tests
Aigamo.ResXGenerator		Aigamo.ResXGenerator
DemoLocalization		DemoLocalization
.editorconfig		.editorconfig
.gitignore		.gitignore
Aigamo.ResXGenerator.sln		Aigamo.ResXGenerator.sln
Aigamo.ResXGenerator.sln.DotSettings		Aigamo.ResXGenerator.sln.DotSettings
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

ResXGenerator

Usage

New in version 3

New in version 3.1

New in version 4

Options

GenerationType (per file or globally)

PublicClass (per file or globally)

NullForgivingOperators (globally)

Non-static classes (per file or globally)

Partial classes (per file or globally)

Static Members (per file or globally)

Postfix class name (per file or globally)

Inner classes (per file or globally)

Inner Class Visibility (per file or globally)

Inner Class name (per file or globally)

Inner Class instance name (per file or globally)

Generate Code (per file or globally)

Resource file namespaces

Excluding resx files

Using IStringLocalizer

References

About

Uh oh!

Releases

Packages

Languages

License

FranckSix/ResXGenerator

Folders and files

Latest commit

History

Repository files navigation

ResXGenerator

Usage

New in version 3

New in version 3.1

New in version 4

Options

GenerationType (per file or globally)

PublicClass (per file or globally)

NullForgivingOperators (globally)

Non-static classes (per file or globally)

Partial classes (per file or globally)

Static Members (per file or globally)

Postfix class name (per file or globally)

Inner classes (per file or globally)

Inner Class Visibility (per file or globally)

Inner Class name (per file or globally)

Inner Class instance name (per file or globally)

Generate Code (per file or globally)

Resource file namespaces

Excluding resx files

Using IStringLocalizer

References

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages