csharplang
csharplang copied to clipboard
dotnet
String-based enums
We've noticed a trend, especially in cloud services, that there is a need for extensible enums. While enums can in principle be extended by casting any int to the enum, it has the risk for conflicts. Using strings has a much lower risk of conflicts.
In the BCL, we've called this concept "strongly typed strings". Examples are:
It would be nice if we could make this a language feature so that instead of this:
public readonly struct OSPlatform : IEquatable<OSPlatform>
{
private string _value;
public static OSPlatform FreeBSD { get; } = new OSPlatform("Free BSD");
public static OSPlatform Linux { get; } = new OSPlatform(nameof(Linux));
public static OSPlatform Windows { get; } = new OSPlatform(nameof(Windows));
public OSPlatform(string value)
{
_value = value;
}
public override bool Equals(object obj)
{
return obj is OSPlatform p && Equals(p);
}
public bool Equals(OSPlatform other)
{
return _value == other._value;
}
public static bool operator ==(OSPlatform left, OSPlatform right) => Equals(left, right);
public static bool operator !=(OSPlatform left, OSPlatform right) => !Equals(left, right);
public static explicit operator string(OSPlatform value) => value.ToString();
public static explicit operator OSPlatform(string value) => new OSPlatform(value);
public override string? ToString() => _value;
}
one only has to type this:
public enum OSPlatform : string
{
FreeBSD = "Free BSD",
Linux,
Windows
}
/cc @pakrym @heaths @JoshLove-msft
Discriminated Unions
As was pointed out by @DavidArno, this won't be solved by discriminated unions because those are about completeness. The primary value of string-based enums is that they are extensible without changing the type definition:
OSPlatform platform = (OSPlatform)"Apple Toaster with Siri Support";
This is vital for things like cloud services where the server and the client can be on different versions.
HttpMethod is another example. It also has to be possible to set values different from identifier names
public enum OSPlatform : string
{
FreeBSD = "free bsd",
Linux = "linux",
Windows = "windows"
}
Seems like something that could be hammered out alongside DUs, which also feel like enums.
IMO, the syntax in this case should also allow for the named member to reference a different string in the case that the string either doesn't fit with the naming conventions of C# members or doesn't fit the rules for being an identifier.
I've always wanted this, and would further want the equality check/deserialization to be case-insensitive, or at least configurable for that. For example, "Linux" and "linux" could both deserialize to OSPlatform.Linux.
HttpMethod as you say and HeaderNames also. HeaderNames having non-C# values in the actual string values such as - in Content-Length; so being able to specify the string much like the actual numeric value can be specified on current enums would be good.
In Azure SDK for .NET, so far we've settled on a structure defined like in https://gist.github.com/heaths/d105148428fe09a2631322b656f04ebb. The main problem comes from a lack of IntelliSense built into VS or VSCode/OmniSharp. If there were a way to enabled this - perhaps through Roslyn - such that MyStruct x = would pop visible static readonly fields or properties, that would satisfy much of the concern around discoverability.
Another question is if [Flags] should be somehow supported for these.
And switch statement/expression support.
Yes for [Flags] support! Not entirely sure how to represent it from an API perspective, but it seems natural to have string enums implement IEnumerable<string> to yield all of the set "bits".
Also, and without giving it much thought, what if tuples could be used to specify multiple acceptable variations of the string value:
[Flags]
public enum OSPlatform : string
{
Linux = ("Linux", "linux", "LINUX")
}
I'd also like to see something that interops well with Xamarin.iOS/Mac. String enums are a large part of the native API surface of macOS and iOS. Swift's enums were designed with this in mind as well.
I'm not sold on flags support. This would either require string parsing with some separator or storing them as a collection, which seems unnecessarily heavyweight for the general case.
@abock
I'd also like to see something that interops well with Xamarin.iOS/Mac. String enums are a large part of the native API surface of macOS and iOS. Swift's enums were designed with this in mind as well.
Could you describe what this would entail?
One thing I love doing with enum-ish strings in C# is to emulate Ruby symbols like this:
namespace StringSymbols
{
public static class OSPlatform
{
public const string FreeBSD = nameof(FreeBSD);
public const string Linux = nameof(Linux);
public const string Windows = nameof(Windows);
}
}
Then use it like this:
using System;
using static StringSymbols.OSPlatform;
namespace StringSymbols
{
class Program
{
static void Main(string[] args)
{
var os = Windows;
if( os == Linux ){
Console.WriteLine("Hello Linux, command line ninja");
}
else if( os == Windows ){
Console.WriteLine("Hello Windows, seattle sunshine");
}
else if( os == FreeBSD ){
Console.WriteLine("Hello FreeBSD, go cal bears, go");
}
}
}
}
Output:
Hello Windows, seattle sunshine
:mount_fuji: :man_playing_water_polo: Creedence Clearwater Revival - Green River
Here is an example of what we do in the AWS .NET SDK to solve this problem. Our main requirement is to be forward compatible with enum values that a service might return in the future.
/// <summary>
/// Constants used for properties of type ContainerCondition.
/// </summary>
public class ContainerCondition : ConstantClass
{
/// <summary>
/// Constant COMPLETE for ContainerCondition
/// </summary>
public static readonly ContainerCondition COMPLETE = new ContainerCondition("COMPLETE");
/// <summary>
/// Constant HEALTHY for ContainerCondition
/// </summary>
public static readonly ContainerCondition HEALTHY = new ContainerCondition("HEALTHY");
/// <summary>
/// Constant START for ContainerCondition
/// </summary>
public static readonly ContainerCondition START = new ContainerCondition("START");
/// <summary>
/// Constant SUCCESS for ContainerCondition
/// </summary>
public static readonly ContainerCondition SUCCESS = new ContainerCondition("SUCCESS");
/// <summary>
/// This constant constructor does not need to be called if the constant
/// you are attempting to use is already defined as a static instance of
/// this class.
/// This constructor should be used to construct constants that are not
/// defined as statics, for instance if attempting to use a feature that is
/// newer than the current version of the SDK.
/// </summary>
public ContainerCondition(string value)
: base(value)
{
}
/// <summary>
/// Finds the constant for the unique value.
/// </summary>
/// <param name="value">The unique value for the constant</param>
/// <returns>The constant for the unique value</returns>
public static ContainerCondition FindValue(string value)
{
return FindValue<ContainerCondition>(value);
}
/// <summary>
/// Utility method to convert strings to the constant class.
/// </summary>
/// <param name="value">The string value to convert to the constant class.</param>
/// <returns></returns>
public static implicit operator ContainerCondition(string value)
{
return FindValue(value);
}
}
Maybe a more general concept of typed strings, taken from Bosque language?
var code: String<Zipcode> = Zipcode'02-110';
entity PlayerMark provides Parsable {
field mark: String;
override static tryParse(str: String): PlayerMark | None {
return (str == "x" || str == "o") ? PlayerMark{ mark=str } : none;
}
}
So in example scenario from above it would be:
String<OSPlatform> platform = OSPlatform"Linux"
@HaloFour, @aensidhe & @Liminiens,
I don't agree that this proposal is equivalent to DUs. The latter are designed to be closed sets of values, that cannot be extended. Whereas this proposal is specifically requesting that it be a set of values that are open to extension as other enums are.
@DavidArno what do you mean by cannot be extended? To extend enum (both int-based and string-based) we need to write code. Same with DU. I don't get the difference.
String enums in three years are better than discriminated unions in six years.
@dsaf, DUs in one year (C# 9) would be way better than either of your options 😄
@aensidhe, if I declare a DU:
type IntOrBool =
| I of int
| B of bool
I can't then add an S of string to it without changing the type definition. With this proposal though, for the enum:
public enum OSPlatform : string
{
FreeBSD = "Free BSD",
Linux,
Windows
}
I could write var os = (OSPlatform)"Banana"; as legitimate code. DUs can't be extended; enums can.
(At least this is my understanding of "...there is a need for extensible enums. While enums can in principle be extended by casting any int to the enum, it has the risk for conflicts. Using strings has a much lower risk of conflicts.".)
and HeaderNames also.
I think the important distinction is that HeaderNames should not be a "type" anyways e.g. header names are not restricted to those values, so I think it's better off to be defined as a set of predefined constants.
Great idea, I always wanted enum, which is quite neutral type, could inherit from string type.
As I've downvoted this proposal, I feel I should explain why, even though the majority may disagree with me and downvote this...
To my mind, the statement "...there is a need for extensible enums..." is fundamentally flawed. The fact that enums are extensible causes bugs in code and causes me to have to check that the actual value matches one of the defined values. It's on par with the null's "billion dollar mistake". And it makes using enums with switch expressions clunky:
enum Values { ValueA, ValueB }
class C
{
public int Foo(Values value)
=> value switch {
Values.ValueA => 0,
Values.ValueB => 1
};
}
gives me the warning, warning CS8509: The switch expression does not handle all possible values of its input type (it is not exhaustive).. So I need to add a default case to suppress that warning. But if I then add ValueC to the enum, I get no warning/error that I'm not explicitly handling it.
To my mind, allowing enums to be any int value, rather than just the defined values, was a design mistake. Extending that mistake to strings too would be a bad thing to do.
@DavidArno Your objection has nothing to do with string enums per se, but how enums were implemented in C#. Totally different issues.
@DavidArno 's example with casting any string to the string enum is a good reason to downvote this proposal.
public enum OSPlatform : string
{
FreeBSD = "Free BSD",
Linux,
Windows
}
...
var os = (OSPlatform)"Banana";
...
💥
DU, one more time, is the right and proper way to handle "strongly typed string in BCL" situation. And language should not be changed to fix it by allowing string enums (which are not strongly typed at all), but BCL (and others) should adopt DU approach. Otherwise it's kinda like adding one more floor to a sand castle
and HeaderNames also.
I think the important distinction is that HeaderNames should not be a "type" anyways e.g. header names are not restricted to those values, so
Nor are HttpMethods, platforms etc; the point is enums are an open definition.
example with casting any string to the string enum is a good reason to downvote this proposal.
That is why they are enums and not DUs, much like this is valid for enums currently
public enum OSPlatform : int
{
Linux = 1,
Windows = 2
}
// ...
var os = (OSPlatform)3;
Which is the same point with headers or methods
[CaseInsensitive]
public enum HeaderNames : string
{
Accept = "Accept",
AcceptCharset = "Accept-Charset",
AcceptEncoding = "Accept-Encoding",
AcceptLanguage = "Accept-Language",
AcceptRanges = "Accept-Ranges",
// ...
}
// ...
var requestIdName = (HeaderNames)"X-Request-Id";
if ((HeaderNames)"x-request-id" == requestIdName)
{
// is true
}
@benaadams this proposal shows the demand for enums being more complex than just a set of flags or something. When you really have to do want that - you should use DU’s if they exist in a language, which provide compile time checks for exhaustiveness and extensibility via adding methods to type and new cases.
With enums the only way you can provide safety while casting is using TryParse - style methods.
And there is a question: what would guidelines be when eventually DU’s are added to the language? Would string enums become obsolete because casting values to them isn’t “safe”?
If these "String enums" can just be any arbitrary values of string then I'm opposed to them too. I think that a named type should bring with it some degree of type safety. While current enums can be any integral value it's a pretty exceptional case for the value to not be one of the declared members, outside of flags enums.
Taking a page from pretty much HTTP package in Java, you often do have common things like HTTP headers and methods expressed as enums, but any method that accepts such an enum also has an overload that accepts a String.
This sounds like a much better opportunity for proper DUs, where you can have an Other(string value) case.
I've personally had need for something like this when creating a web API client library where a returned objects options are specified as a set of string values. A fixed set of string values mapped from an enum in the client library was inadvisable because if or when more options are added the client library would break upon deserialization.
To address this need for strongly typed string values I created a StringEnumValue<TEnum> type which is implicitly convertible to and from both a string value and a TEnum? value.
A string based enum would have been a much better option if it had been available at the time.
If these "String enums" can just be any arbitrary values of string then I'm opposed to them too. I think that a named type should bring with it some degree of type safety.
That's kinda the point surely, it does introduce a degree of type safety? If you want to use an arbitrary value you have to intentionally cast it to the enum; it encourages the general case to use the values provided by the string enum, but is open enough to allow other types.
you should use DU’s if they exist in a language, which provide compile time checks for exhaustiveness and extensibility via adding methods to type and new cases.
This is problematic because of layering, many of these enums would be defined in the BCL; however if you want to add another value you are then locked out. e.g. one of the other examples provided is HashAlgorithmName which in its definition is:
Asymmetric algorithms implemented using other technologies:
- Must recognize at least "MD5", "SHA1", "SHA256", "SHA384", and "SHA512".
- Should recognize additional CNG identifiers for any additional hash algorithms that they support.
So that would be an enum of type
public enum HashAlgorithmName : string
{
Md5 = "MD5",
Sha1 = "SHA1",
Sha256 = "SHA256",
Sha384 = "SHA384",
Sha512 = "SHA512"
}
The current situation of just accepting arbitrary strings doesn't provide any intention to the parameter or guidance to what the parameter should be via the compiler; which enum strings would provide.
@benaadams
That's kinda the point surely, it does introduce a degree of type safety? If you want to use an arbitrary value you have to intentionally cast it to the enum
IMO those two statements are in direct contradiction to one another. I find the current behavior of (non-flags) enums to be pretty appalling and results in the compiler to be forced to treat any arbitrary integral value as a potential value of that enum. That makes about as much sense as having to treat any arbitrary combination of bits in a bool as something other than true or false.
If the goal is to provide guidance to the user as to common or suggested values for a given parameter I think a better approach would be via attribute and IDE support which wouldn't require any language changes and would also work across any language in the ecosystem.
Otherwise this feature seems to be offering a new type while encouraging users to pass invalid values of that type to methods.