NetEscapades.EnumGenerators
1.0.0-beta06
See the version list below for details.
dotnet add package NetEscapades.EnumGenerators --version 1.0.0-beta06
NuGet\Install-Package NetEscapades.EnumGenerators -Version 1.0.0-beta06
<PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta06" />
paket add NetEscapades.EnumGenerators --version 1.0.0-beta06
#r "nuget: NetEscapades.EnumGenerators, 1.0.0-beta06"
// Install NetEscapades.EnumGenerators as a Cake Addin #addin nuget:?package=NetEscapades.EnumGenerators&version=1.0.0-beta06&prerelease // Install NetEscapades.EnumGenerators as a Cake Tool #tool nuget:?package=NetEscapades.EnumGenerators&version=1.0.0-beta06&prerelease
NetEscapades.EnumGenerators
A Source Generator package that generates extension methods for enums, to allow fast "reflection".
This source generator requires the .NET 7 SDK. You can target earlier frameworks like .NET Core 3.1 etc, but the SDK must be at least 7.0.100
Add the package to your application using
dotnet add package NetEscapades.EnumGenerators
This adds a <PackageReference>
to your project. You can additionally mark the package as PrivateAssets="all"
and ExcludeAssets="runtime"
.
Setting
PrivateAssets="all"
means any projects referencing this one won't get a reference to the NetEscapades.EnumGenerators package. SettingExcludeAssets="runtime"
ensures the NetEscapades.EnumGenerators.Attributes.dll file is not copied to your build output (it is not required at runtime).
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net6.0</TargetFramework>
</PropertyGroup>
<PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta04"
PrivateAssets="all" ExcludeAssets="runtime" />
</Project>
Adding the package will automatically add a marker attribute, [EnumExtensions]
, to your project.
To use the generator, add the [EnumExtensions]
attribute to an enum. For example:
[EnumExtensions]
public enum MyEnum
{
First,
[Display(Name = "2nd")]
Second,
}
This will generate a class called MyEnumExtensions
(by default), which contains a number of helper methods. For example:
public static partial class MyEnumExtensions
{
public const int Length = 2;
public static string ToStringFast(this MyEnum value)
=> value switch
{
MyEnum.First => nameof(MyEnum.First),
MyEnum.Second => "2nd",
_ => value.ToString(),
};
public static bool IsDefined(MyEnum value)
=> value switch
{
MyEnum.First => true,
MyEnum.Second => true,
_ => false,
};
public static bool IsDefined(string name)
=> name switch
{
nameof(MyEnum.First) => true,
nameof(MyEnum.Second) => true,
_ => false,
};
public static bool TryParse(
[System.Diagnostics.CodeAnalysis.NotNullWhen(true)] string? name,
bool ignoreCase,
out MyEnum value)
=> ignoreCase ? TryParseIgnoreCase(name, out value) : TryParse(name, out value);
private static bool TryParseIgnoreCase(
[System.Diagnostics.CodeAnalysis.NotNullWhen(true)] string? name,
out MyEnum value)
{
switch (name)
{
case { } s when s.Equals(nameof(MyEnum.First), System.StringComparison.OrdinalIgnoreCase):
value = MyEnum.First;
return true;
case { } s when s.Equals(nameof(MyEnum.Second), System.StringComparison.OrdinalIgnoreCase):
value = MyEnum.Second;
return true;
case { } s when int.TryParse(name, out var val):
value = (MyEnum)val;
return true;
default:
value = default;
return false;
}
}
public static bool TryParse(
[System.Diagnostics.CodeAnalysis.NotNullWhen(true)] string? name,
out MyEnum value)
{
switch (name)
{
case nameof(MyEnum.First):
value = MyEnum.First;
return true;
case nameof(MyEnum.Second):
value = MyEnum.Second;
return true;
case { } s when int.TryParse(name, out var val):
value = (MyEnum)val;
return true;
default:
value = default;
return false;
}
}
public static MyEnum[] GetValues()
{
return new[]
{
MyEnum.First,
MyEnum.Second,
};
}
public static string[] GetNames()
{
return new[]
{
nameof(MyEnum.First),
nameof(MyEnum.Second),
};
}
}
If you create a "Flags" enum
by decorating it with the [Flags]
attribute, an additional method is created, which provides a bitwise alternative to the Enum.HasFlag(flag)
method:
public static bool HasFlagFast(this MyEnum value, MyEnum flag)
=> flag == 0 ? true : (value & flag) == flag;
Note that if you provide a [Display]
or [Description]
attribute, the value you provide for this attribute can be used by methods like ToStringFast()
and TryParse()
by passing the argument allowMatchingMetadataAttribute: true
. Adding both attributes to an enum member is not supported, though conventionally the "first" attribute will be used.
You can override the name of the extension class by setting ExtensionClassName
in the attribute and/or the namespace of the class by setting ExtensionClassNamespace
. By default, the class will be public if the enum is public, otherwise it will be internal.
Embedding the attributes in your project
By default, the [EnumExtensions]
attributes referenced in your application are contained in an external dll. It is also possible to embed the attributes directly in your project, so they appear in the dll when your project is built. If you wish to do this, you must do two things:
- Define the MSBuild constant
NETESCAPADES_ENUMGENERATORS_EMBED_ATTRIBUTES
. This ensures the attributes are embedded in your project - Add
compile
to the list of excluded assets in your<PackageReference>
element. This ensures the attributes in your project are referenced, instead of the NetEscapades.EnumGenerators.Attributes.dll library.
Your project file should look something like this:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net6.0</TargetFramework>
<DefineConstants>$(DefineConstants);NETESCAPADES_ENUMGENERATORS_EMBED_ATTRIBUTES</DefineConstants>
</PropertyGroup>
<PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta04"
PrivateAssets="all"
ExcludeAssets="compile;runtime" />
</Project>
Preserving usages of the [EnumExtensions]
attribute
The [EnumExtensions]
attribute is decorated with the [Conditional]
attribute, so their usage will not appear in the build output of your project. If you use reflection at runtime on one of your enum
s, you will not find [EnumExtensions]
in the list of custom attributes.
If you wish to preserve these attributes in the build output, you can define the NETESCAPADES_ENUMGENERATORS_USAGES
MSBuild variable. Note that this means your project will have a runtime-dependency on NetEscapades.EnumGenerators.Attributes.dll so you need to ensure this is included in your build output.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net6.0</TargetFramework>
<DefineConstants>$(DefineConstants);NETESCAPADES_ENUMGENERATORS_USAGES</DefineConstants>
</PropertyGroup>
<PackageReference Include="NetEscapades.EnumGenerators" Version="1.0.0-beta05" PrivateAssets="all" />
</Project>
Error CS0436 and [InternalsVisibleTo]
In the latest version of NetEscapades.EnumGenerators, you should not experience error CS0436 by default.
In previous versions of the NetEscapades.EnumGenerators generator, the [EnumExtensions]
attributes were added to your compilation as internal
attributes by default. If you added the source generator package to multiple projects, and used the [InternalsVisibleTo]
attribute, you could experience errors when you build:
warning CS0436: The type 'EnumExtensionsAttribute' in 'NetEscapades.EnumGenerators\NetEscapades.EnumGenerators\EnumExtensionsAttribute.cs' conflicts with the imported type 'EnumExtensionsAttribute' in 'MyProject, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'.
In the latest version of StronglyTypedId, the attributes are not embedded by default, so you should not experience this problem. If you see this error, compare your installation to the examples in the installation guide.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net451 is compatible. net452 was computed. net46 was computed. net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- No dependencies.
NuGet packages (5)
Showing the top 5 NuGet packages that depend on NetEscapades.EnumGenerators:
Package | Downloads |
---|---|
DSharpPlus
A C# API for Discord based off DiscordSharp, but rewritten to fit the API standards. |
|
Indrivo.FileStorage.Accessor.Contracts
Package Description |
|
apex.net-Entities
Models for apex.net |
|
FileStorage.Accessor.Contracts
Package Description |
|
Starnight.Shared
Shared type library for Starnight assemblies |
GitHub repositories (3)
Showing the top 3 popular GitHub repositories that depend on NetEscapades.EnumGenerators:
Repository | Stars |
---|---|
Nexus-Mods/NexusMods.App
Home of the development of the Nexus Mods App
|
|
andrewlock/NetEscapades.EnumGenerators
A source generator for generating fast "reflection" methods for enums
|
|
SteveDunn/Intellenum
Intelligent Enums
|
Version | Downloads | Last updated |
---|---|---|
1.0.0-beta11 | 6,865 | 10/24/2024 |
1.0.0-beta09 | 86,725 | 5/15/2024 |
1.0.0-beta08 | 164,104 | 6/5/2023 |
1.0.0-beta07 | 73,108 | 3/10/2023 |
1.0.0-beta06 | 28,779 | 12/20/2022 |
1.0.0-beta05 | 254 | 12/19/2022 |
1.0.0-beta04 | 134,742 | 11/30/2021 |
1.0.0-beta03 | 1,905 | 11/26/2021 |
1.0.0-beta02 | 182 | 11/22/2021 |
1.0.0-beta01 | 372 | 11/18/2021 |
Features
- Add support for overriding ToStringFast() and related methods by adding [Description] attribute to members #46
- Add support for overriding ToStringFast() and related methods by adding [Display] attribute to members #13 (thanks @adamradocz)
- Add a .NET 4.5.1 target to the attributes dll, to reduce dependencies introduced by .NET Standard #45
- Add parsing overloads for ReadOnlySpan<T> #16 (thanks @adamradocz)
- Add Length extension method #7 (thanks @tothalexlaszlo)
Fixes
- Fix HasFlagsFast() implementation #44
- Add XML documentation for attributes 9a38580cdc9e
- Add XML comments to public generated members and fix formatting #42, #49
- Fixed spelling of isDisplayAttributeUsed property #17 (thanks @JasonLautzenheiser)
Refactoring
- Use DotNet.ReproducibleBuilds #35 (thanks @HavenDV)
- Switch to ForAttributeWithMetadataName #41
- Update README #8 #20 #1 (thanks @tothalexlaszlo, @Rekkonnect)
- Fix typo #5
See https://github.com/andrewlock/NetEscapades.EnumGenerators/blob/main/CHANGELOG.md#v100-beta06 for more details.