dss_sharp.Error.UseExceptions: Toggle mapping Error.Number to C# exceptions

PMeira · PMeira · commit 9fdd75e932d8 · 2023-03-31T00:36:05.000-03:00
Previously, we forced the use of exceptions. Now users can easily toggle the behavior. The default will still be to use exceptions for the safety of new users, besides the added convenience. **Usage:** set `dss_sharp.Error.UseExceptions = false` to deactivate the automatic mapping. Other toggles as `Error.EarlyAbort` and the upcoming `DSS.CompatFlags` should be enough to more closely match the logic of older programs using the official COM DLL behavior even for the more lax usage of OpenDSS. Closes #15
diff --git a/src/dss_capi_lib.cs b/src/dss_capi_lib.cs
@@ -6,7 +6,7 @@
 // See LICENSE for more information.
 //
 // NOTE: This file is partially generated from other files. If you would like to contribute 
-//       a patch // or suggestion, please open a issue ticket on:
+//       a patch or suggestion, please open an issue ticket on:
 //       https://github.com/dss-extensions/dss_sharp/issues/
 
 using System;
diff --git a/src/dss_sharp.cs b/src/dss_sharp.cs
@@ -6,11 +6,10 @@
 // See LICENSE for more information.
 //
 // NOTE: This file is partially generated from other files. If you would like to contribute 
-//       a patch // or suggestion, please open a issue ticket on:
+//       a patch or suggestion, please open an issue ticket on:
 //       https://github.com/dss-extensions/dss_sharp/issues/
         
 using System;
-using System.Runtime.InteropServices;
 using dss_sharp.detail;
 using dss_sharp.native;
 
@@ -76,7 +75,7 @@ public enum ActionCodes {
         dssActionOpen = 1, // Open a switch
         dssActionClose = 2, // Close a switch
         dssActionReset = 3, // Reset to the shelf state (unlocked, closed for a switch)
-        dssActionLock = 4, // Lock a switch, prventing both manual and automatic operation
+        dssActionLock = 4, // Lock a switch, preventing both manual and automatic operation
         dssActionUnlock = 5, // Unlock a switch, permitting both manual and automatic operation
         dssActionTapUp = 6, // Move a regulator tap up
         dssActionTapDown = 7 // Move a regulator tap down
@@ -7276,14 +7275,7 @@ public string Description
         {
             get
             {
-                try
-                {
-                    return APIUtil.get_string(DSS_CAPI.ctx_Error_Get_Description(ctx));
-                }
-                finally
-                {
-                    CheckForError();
-                }
+                return APIUtil.get_string(DSS_CAPI.ctx_Error_Get_Description(ctx));
             }
         }
 
@@ -7294,14 +7286,7 @@ public int Number
         {
             get
             {
-                try
-                {
-                    return DSS_CAPI.ctx_Error_Get_Number(ctx);
-                }
-                finally
-                {
-                    CheckForError();
-                }
+                return DSS_CAPI.ctx_Error_Get_Number(ctx);
             }
         }
 
@@ -7348,9 +7333,8 @@ public bool EarlyAbort
         /// 
         /// Extended errors use the Error interface to provide a more clear message
         /// and should help users, especially new users, to find usage issues earlier.
-        /// 
-        /// At Python level, an exception is raised when an error is detected through
-        /// the Error interface.
+        /// Combined with the automatic exception mapping mechanism (see `UseExceptions`),
+        /// a more modern and safe experience is achieved in dss_sharp.
         /// 
         /// The current default state is ON. For compatibility, the user can turn it
         /// off to restore the previous behavior.
@@ -7382,6 +7366,31 @@ public bool ExtendedErrors
                 }
             }
         }
+
+        /// <summary>
+        /// UseExceptions controls whether the error numbers from the DSS engine are
+        /// automatically mapped to .NET exceptions. The default and recommended state
+        /// is `true`, but users can disable this to achieve better compatibility with
+        /// old, COM-based code. Note that most code from OpenDSS users "in the wild" 
+        /// do not check for errors, so the exception mapping can unearth hidden errors
+        /// that were being ignored in old code.
+        /// 
+        /// NOTE: This is a global, static setting. Affects all DSS instances in the process.
+        /// 
+        /// (API Extension)
+        /// </summary>
+        public static bool UseExceptions
+        {
+            get
+            {
+                return APIUtil.exceptionsAllowed;
+            }
+            set
+            {
+                APIUtil.exceptionsAllowed = value;
+            }
+        }
+
     }
 
     public class Fuses : ContextState
diff --git a/src/dss_sharp_util.cs b/src/dss_sharp_util.cs
@@ -63,6 +63,7 @@ public IntPtr GetContextHandle()
         /// </summary>
         public class APIUtil
         {
+            public static bool exceptionsAllowed = true;
             private static bool MOLoaded = false;
             public delegate void StringArrayDelegate1(IntPtr ctx, ref IntPtr resultPtr, int[] resultCount);
             public delegate void StringArrayDelegate2(IntPtr ctx, ref IntPtr resultPtr, int[] resultCount, int param1);
@@ -210,8 +211,17 @@ public string[] get_string_array(StringArrayDelegate3 fn, string param1)
                 return result;
             }
 
+            /// <summary>
+            /// If the exception mapping mechanism is enabled, the DSS.Error.Number code is inspected.
+            /// If non-zero, the matching DSS.Error.Description message is read and a DSSException is
+            /// thrown. This is called internally after most of the dss_sharp DSS C-API calls to ensure
+            /// most engine errors are being handled as early as possible.
+            ///
+            /// If exceptions cannot be used, check `DSS.Error.Number` directly.
+            /// </summary>
             public void CheckForError()
             {
+                if (!exceptionsAllowed) return;
                 var error_num = Marshal.ReadInt32(errorPtr);
                 if (error_num != 0)
                 {

Original file line number	Diff line number	Diff line change
`@@ -63,6 +63,7 @@ public IntPtr GetContextHandle()`
`63`	`63`	`/// </summary>`
`64`	`64`	`public class APIUtil`
`65`	`65`	`{`
	`66`	`+ public static bool exceptionsAllowed = true;`
`66`	`67`	`private static bool MOLoaded = false;`
`67`	`68`	`public delegate void StringArrayDelegate1(IntPtr ctx, ref IntPtr resultPtr, int[] resultCount);`
`68`	`69`	`public delegate void StringArrayDelegate2(IntPtr ctx, ref IntPtr resultPtr, int[] resultCount, int param1);`
`@@ -210,8 +211,17 @@ public string[] get_string_array(StringArrayDelegate3 fn, string param1)`
`210`	`211`	`return result;`
`211`	`212`	`}`
`212`	`213`
	`214`	`+ /// <summary>`
	`215`	`+ /// If the exception mapping mechanism is enabled, the DSS.Error.Number code is inspected.`
	`216`	`+ /// If non-zero, the matching DSS.Error.Description message is read and a DSSException is`
	`217`	`+ /// thrown. This is called internally after most of the dss_sharp DSS C-API calls to ensure`
	`218`	`+ /// most engine errors are being handled as early as possible.`
	`219`	`+ ///`
	`220`	+ /// If exceptions cannot be used, check `DSS.Error.Number` directly.
	`221`	`+ /// </summary>`
`213`	`222`	`public void CheckForError()`
`214`	`223`	`{`
	`224`	`+ if (!exceptionsAllowed) return;`
`215`	`225`	`var error_num = Marshal.ReadInt32(errorPtr);`
`216`	`226`	`if (error_num != 0)`
`217`	`227`	`{`