fix(csharp): Rename Custom method to FromCustom in String Enums (#6438)

Author: Swimburger

generators/csharp/base/src/asIs/test/Json/StringEnumSerializerTests.Template.cs

@@ -9,27 +9,22 @@ namespace <%= namespace%>.Test.Core.Json;
 [Parallelizable(ParallelScope.All)]
 public class StringEnumSerializerTests
 {
-    private static readonly JsonSerializerOptions JsonOptions = new()
-    {
-        WriteIndented = true,
-    };
+    private static readonly JsonSerializerOptions JsonOptions = new() { WriteIndented = true };
 
     private static readonly DummyEnum KnownEnumValue2 = DummyEnum.KnownValue2;
-    private static readonly DummyEnum UnknownEnumValue = DummyEnum.Custom("unknown_value");
-
-    private static readonly string JsonWithKnownEnum2 =
-        $$"""
-          {
-              "enum_property": "{{KnownEnumValue2}}"
-          }
-          """;
-
-    private static readonly string JsonWithUnknownEnum =
-        $$"""
-          {
-              "enum_property": "{{UnknownEnumValue}}"
-          }
-          """;
+    private static readonly DummyEnum UnknownEnumValue = DummyEnum.FromCustom("unknown_value");
+
+    private static readonly string JsonWithKnownEnum2 = $$"""
+        {
+            "enum_property": "{{KnownEnumValue2}}"
+        }
+        """;
+
+    private static readonly string JsonWithUnknownEnum = $$"""
+        {
+            "enum_property": "{{UnknownEnumValue}}"
+        }
+        """;
 
     [Test]
     public void ShouldParseKnownEnumValue2()
@@ -93,9 +88,9 @@ public DummyEnum(string value)
     /// </summary>
     public string Value { get; }
 
-    public static readonly DummyEnum KnownValue1 = Custom(Values.KnownValue1);
+    public static readonly DummyEnum KnownValue1 = FromCustom(Values.KnownValue1);
 
-    public static readonly DummyEnum KnownValue2 = Custom(Values.KnownValue2);
+    public static readonly DummyEnum KnownValue2 = FromCustom(Values.KnownValue2);
 
     /// <summary>
     /// Constant strings for enum values
@@ -110,7 +105,7 @@ public static class Values
     /// <summary>
     /// Create a string enum with the given value.
     /// </summary>
-    public static DummyEnum Custom(string value)
+    public static DummyEnum FromCustom(string value)
     {
         return new DummyEnum(value);
     }
@@ -133,6 +128,10 @@ public override int GetHashCode()
         return Value.GetHashCode();
     }
 
+    public static explicit operator string(DummyEnum value) => value.Value;
+
+    public static explicit operator DummyEnum(string value) => new(value);
+
     public static bool operator ==(DummyEnum value1, string value2) => value1.Value.Equals(value2);
 
     public static bool operator !=(DummyEnum value1, string value2) => !value1.Value.Equals(value2);

generators/csharp/codegen/src/ast/Class.ts

@@ -361,7 +361,9 @@ export class Class extends AstNode {
         if (operator.type === Class.CastOperator.Type.Explicit || operator.type === Class.CastOperator.Type.Implicit) {
             writer.write(`${operator.type} `);
             writer.write("operator ");
-            writer.write(`${this.name}(`);
+            const to = operator.to ?? this.reference;
+            writer.writeNode(to);
+            writer.write("(");
             operator.parameter.write(writer);
         } else {
             const normalOperator = operator as Class.NormalOperator;
@@ -444,6 +446,7 @@ export namespace Class {
     export interface CastOperator {
         parameter: Parameter;
         type: CastOperator.Type;
+        to?: Type;
         body: CodeBlock;
         useExpressionBody?: boolean;
     }

generators/csharp/model/src/enum/StringEnumGenerator.ts

@@ -9,6 +9,7 @@ import { ModelGeneratorContext } from "../ModelGeneratorContext";
 
 export class StringEnumGenerator extends FileGenerator<CSharpFile, ModelCustomConfigSchema, ModelGeneratorContext> {
     private readonly classReference: csharp.ClassReference;
+    private readonly customMethodName: string;
 
     constructor(
         context: ModelGeneratorContext,
@@ -17,6 +18,12 @@ export class StringEnumGenerator extends FileGenerator<CSharpFile, ModelCustomCo
     ) {
         super(context);
         this.classReference = this.context.csharpTypeMapper.convertToClassReference(this.typeDeclaration.name);
+        this.customMethodName = this.getCustomMethodName(enumDeclaration);
+    }
+
+    private getCustomMethodName(enumDeclaration: EnumTypeDeclaration): string {
+        const d = "FromCustom";
+        return enumDeclaration.values.some((v) => v.name.name.pascalCase.safeName === d) ? "FromCustom_" : d;
     }
 
     protected doGenerate(): CSharpFile {
@@ -106,12 +113,7 @@ export class StringEnumGenerator extends FileGenerator<CSharpFile, ModelCustomCo
                     useRequired: false,
                     static_: true,
                     readonly: true,
-                    initializer: csharp.codeblock((writer) => {
-                        writer.write("Custom(");
-                        writer.write("Values.");
-                        writer.write(fieldName);
-                        writer.write(")");
-                    })
+                    initializer: csharp.codeblock(`new(Values.${fieldName})`)
                 })
             );
         });
@@ -121,7 +123,7 @@ export class StringEnumGenerator extends FileGenerator<CSharpFile, ModelCustomCo
         stringEnum.addMethod(
             csharp.method({
                 access: csharp.Access.Public,
-                name: "Custom",
+                name: this.customMethodName,
                 parameters: [
                     csharp.parameter({
                         name: "value",
@@ -203,6 +205,26 @@ export class StringEnumGenerator extends FileGenerator<CSharpFile, ModelCustomCo
             useExpressionBody: true
         });
 
+        stringEnum.addOperator({
+            type: "explicit",
+            to: csharp.Type.string(),
+            parameter: csharp.parameter({
+                name: "value",
+                type: csharp.Type.reference(this.classReference)
+            }),
+            body: csharp.codeblock("value.Value"),
+            useExpressionBody: true
+        });
+        stringEnum.addOperator({
+            type: "explicit",
+            parameter: csharp.parameter({
+                name: "value",
+                type: csharp.Type.string()
+            }),
+            body: csharp.codeblock("new(value)"),
+            useExpressionBody: true
+        });
+
         return new CSharpFile({
             clazz: stringEnum,
             directory: this.context.getDirectoryForTypeId(this.typeDeclaration.name.typeId),

generators/csharp/sdk/versions.yml

@@ -7,6 +7,24 @@
 #         Set `enable-forward-compatible-enums` to `false` in the configuration to generate the old enums.
 #   irVersion: 53
 
+- version: 1.13.1
+  createdAt: "2025-03-13"
+  irVersion: 57
+  changelogEntry:
+    - type: fix
+      summary: |
+        Forward compatible enums has a static method `Custom(string value)` that allows you to create a new instance of the enum with a custom value.
+        "Custom" is a commonly used enum value, and we want to avoid conflicts with the static method, so we're renaming the static method to `FromCustom(string value)`.
+        This feature is gated behind the `experimental-enable-forward-compatible-enums` configuration option, so we're accepting this as a breaking change without a major version bump.
+    - type: feat
+      summary: |
+        Forward compatible enums can be explicitly casted from and to strings.
+        ```csharp
+        string myEnumAsString = (string)MyEnum.Enum1;
+        MyEnum myEnum = (MyEnum)"custom-value";
+        ```
+        Note: We're not supporting implicit casts here because it could lead to behavior the user doesn't expect.
+
 - version: 1.13.0
   createdAt: "2025-03-13"
   irVersion: 57

packages/cli/fern-definition/ir-to-jsonschema/src/__test__/__snapshots__/enum/type__EnumWithCustom.json

@@ -0,0 +1,8 @@
+{
+  "type": "string",
+  "enum": [
+    "safe",
+    "Custom"
+  ],
+  "definitions": {}
+}

packages/cli/generation/ir-generator-tests/src/dynamic-snippets/__test__/test-definitions/enum.json

@@ -212,6 +212,81 @@
                 }
             ]
         },
+        "type_:EnumWithCustom": {
+            "type": "enum",
+            "declaration": {
+                "name": {
+                    "originalName": "EnumWithCustom",
+                    "camelCase": {
+                        "unsafeName": "enumWithCustom",
+                        "safeName": "enumWithCustom"
+                    },
+                    "snakeCase": {
+                        "unsafeName": "enum_with_custom",
+                        "safeName": "enum_with_custom"
+                    },
+                    "screamingSnakeCase": {
+                        "unsafeName": "ENUM_WITH_CUSTOM",
+                        "safeName": "ENUM_WITH_CUSTOM"
+                    },
+                    "pascalCase": {
+                        "unsafeName": "EnumWithCustom",
+                        "safeName": "EnumWithCustom"
+                    }
+                },
+                "fernFilepath": {
+                    "allParts": [],
+                    "packagePath": [],
+                    "file": null
+                }
+            },
+            "values": [
+                {
+                    "name": {
+                        "originalName": "SAFE",
+                        "camelCase": {
+                            "unsafeName": "safe",
+                            "safeName": "safe"
+                        },
+                        "snakeCase": {
+                            "unsafeName": "safe",
+                            "safeName": "safe"
+                        },
+                        "screamingSnakeCase": {
+                            "unsafeName": "SAFE",
+                            "safeName": "SAFE"
+                        },
+                        "pascalCase": {
+                            "unsafeName": "Safe",
+                            "safeName": "Safe"
+                        }
+                    },
+                    "wireValue": "safe"
+                },
+                {
+                    "name": {
+                        "originalName": "CUSTOM",
+                        "camelCase": {
+                            "unsafeName": "custom",
+                            "safeName": "custom"
+                        },
+                        "snakeCase": {
+                            "unsafeName": "custom",
+                            "safeName": "custom"
+                        },
+                        "screamingSnakeCase": {
+                            "unsafeName": "CUSTOM",
+                            "safeName": "CUSTOM"
+                        },
+                        "pascalCase": {
+                            "unsafeName": "Custom",
+                            "safeName": "Custom"
+                        }
+                    },
+                    "wireValue": "Custom"
+                }
+            ]
+        },
         "type_unknown:Status": {
             "type": "enum",
             "declaration": {

packages/cli/register/src/ir-to-fdr-converter/__test__/__snapshots__/enum.json

@@ -1,7 +1,7 @@
 {
   "types": {
     "type_:Operand": {
-      "description": "Tests enum name and value can be \ndifferent.",
+      "description": "Tests enum name and value can be\ndifferent.",
       "name": "Operand",
       "shape": {
         "type": "enum",
@@ -13,7 +13,7 @@
             "value": "="
           },
           {
-            "description": "The name and value should be similar\nare similar for less than. ",
+            "description": "The name and value should be similar\nare similar for less than.",
             "value": "less_than"
           }
         ]
@@ -55,6 +55,20 @@
         ]
       }
     },
+    "type_:EnumWithCustom": {
+      "name": "EnumWithCustom",
+      "shape": {
+        "type": "enum",
+        "values": [
+          {
+            "value": "safe"
+          },
+          {
+            "value": "Custom"
+          }
+        ]
+      }
+    },
     "type_unknown:Status": {
       "name": "Status",
       "shape": {
@@ -416,7 +430,8 @@
     "types": [
       "type_:Operand",
       "type_:Color",
-      "type_:ColorOrOperand"
+      "type_:ColorOrOperand",
+      "type_:EnumWithCustom"
     ],
     "subpackages": [
       "subpackage_inlined-request",