Add TryGetInstance (#3569)

Author: dvoituron

examples/Demo/Shared/Microsoft.FluentUI.AspNetCore.Components.xml

@@ -4915,7 +4915,7 @@
         </member>
         <member name="T:Microsoft.FluentUI.AspNetCore.Components.CustomIcon">
             <summary>
-            Custom icon loaded from <see cref="M:Microsoft.FluentUI.AspNetCore.Components.IconsExtensions.GetInstance(Microsoft.FluentUI.AspNetCore.Components.IconInfo)"/>
+            Custom icon loaded from <see cref="!:IconsExtensions.GetInstance(IconInfo)"/>
             </summary>
         </member>
         <member name="M:Microsoft.FluentUI.AspNetCore.Components.CustomIcon.#ctor">
@@ -5125,11 +5125,12 @@
         <member name="T:Microsoft.FluentUI.AspNetCore.Components.IconsExtensions">
             <summary />
         </member>
-        <member name="M:Microsoft.FluentUI.AspNetCore.Components.IconsExtensions.GetInstance(Microsoft.FluentUI.AspNetCore.Components.IconInfo)">
+        <member name="M:Microsoft.FluentUI.AspNetCore.Components.IconsExtensions.GetInstance(Microsoft.FluentUI.AspNetCore.Components.IconInfo,System.Nullable{System.Boolean})">
             <summary>
             Returns a new instance of the icon.
             </summary>
             <param name="icon">The <see cref="T:Microsoft.FluentUI.AspNetCore.Components.IconInfo"/> to instantiate.</param>
+            <param name="throwOnError">true to throw an exception if the type is not found (default); false to return null.</param>
             <remarks>
             This method requires dynamic access to code. This code may be removed by the trimmer.
             If the assembly is not yet loaded, it will be loaded by the method `Assembly.Load`.
@@ -5138,6 +5139,19 @@
             <returns></returns>
             <exception cref="T:System.ArgumentException">Raised when the <see cref="P:Microsoft.FluentUI.AspNetCore.Components.IconInfo.Name"/> is not found in predefined icons.</exception>
         </member>
+        <member name="M:Microsoft.FluentUI.AspNetCore.Components.IconsExtensions.TryGetInstance(Microsoft.FluentUI.AspNetCore.Components.IconInfo,Microsoft.FluentUI.AspNetCore.Components.CustomIcon@)">
+            <summary>
+            Tries to return a new instance of the icon.
+            </summary>
+            <param name="icon">The <see cref="T:Microsoft.FluentUI.AspNetCore.Components.IconInfo"/> to instantiate.</param>
+            <param name="result">When this method returns, contains the <see cref="T:Microsoft.FluentUI.AspNetCore.Components.CustomIcon"/> value if the conversion succeeded, or null if the conversion failed. This parameter is passed uninitialized; any value originally supplied in result will be overwritten.</param>
+            <remarks>
+            This method requires dynamic access to code. This code may be removed by the trimmer.
+            If the assembly is not yet loaded, it will be loaded by the method `Assembly.Load`.
+            To avoid any issues, the assembly must be loaded before calling this method (e.g. adding an icon in your code).
+            </remarks>
+            <returns>True if the icon was found and created; otherwise, false.</returns>
+        </member>
         <member name="M:Microsoft.FluentUI.AspNetCore.Components.IconsExtensions.GetAllIcons">
             <summary>
             Returns a new instance of the icon.

src/Core/Components/Icons/IconsExtensions.cs

@@ -17,6 +17,7 @@ public static partial class IconsExtensions
     /// Returns a new instance of the icon.
     /// </summary>
     /// <param name="icon">The <see cref="IconInfo"/> to instantiate.</param>
+    /// <param name="throwOnError">true to throw an exception if the type is not found (default); false to return null.</param>
     /// <remarks>
     /// This method requires dynamic access to code. This code may be removed by the trimmer.
     /// If the assembly is not yet loaded, it will be loaded by the method `Assembly.Load`.
@@ -25,7 +26,7 @@ public static partial class IconsExtensions
     /// <returns></returns>
     /// <exception cref="ArgumentException">Raised when the <see cref="IconInfo.Name"/> is not found in predefined icons.</exception>
     [RequiresUnreferencedCode("This method requires dynamic access to code. This code may be removed by the trimmer.")]
-    public static CustomIcon GetInstance(this IconInfo icon)
+    public static CustomIcon GetInstance(this IconInfo icon, bool? throwOnError = true)
     {
         var assemblyName = string.Format(LibraryName, icon.Variant);
         var assembly = GetAssembly(assemblyName);
@@ -49,7 +50,30 @@ public static CustomIcon GetInstance(this IconInfo icon)
             }
         }
 
-        throw new ArgumentException($"Icon 'Icons.{icon.Variant}.Size{(int)icon.Size}.{icon.Name}' not found.");
+        if (throwOnError == true || throwOnError == null)
+        {
+            throw new ArgumentException($"Icon 'Icons.{icon.Variant}.Size{(int)icon.Size}.{icon.Name}' not found.");
+        }
+
+        return default!;
+    }
+
+    /// <summary>
+    /// Tries to return a new instance of the icon.
+    /// </summary>
+    /// <param name="icon">The <see cref="IconInfo"/> to instantiate.</param>
+    /// <param name="result">When this method returns, contains the <see cref="CustomIcon"/> value if the conversion succeeded, or null if the conversion failed. This parameter is passed uninitialized; any value originally supplied in result will be overwritten.</param>
+    /// <remarks>
+    /// This method requires dynamic access to code. This code may be removed by the trimmer.
+    /// If the assembly is not yet loaded, it will be loaded by the method `Assembly.Load`.
+    /// To avoid any issues, the assembly must be loaded before calling this method (e.g. adding an icon in your code).
+    /// </remarks>
+    /// <returns>True if the icon was found and created; otherwise, false.</returns>
+    [RequiresUnreferencedCode("This method requires dynamic access to code. This code may be removed by the trimmer.")]
+    public static bool TryGetInstance(this IconInfo icon, out CustomIcon? result)
+    {
+        result = GetInstance(icon, throwOnError: false);
+        return result != null;
     }
 
     /// <summary>