fix: use specific exception types in ArmClientExtensions (#1578) (#1689)

Replace generic Exception throws with specific, descriptive exceptions:

- AzureResourceNotFoundException: Thrown when a resource cannot be found
  in the resource group. Inherits from InvalidOperationException and
  includes the ResourceIdentifier for debugging.

- UnsupportedAzureScopeException: Thrown when an unsupported scope type
  is encountered. Inherits from NotSupportedException and includes the
  Scope object for debugging.

Added XML documentation for GetResourceIdentifierAsync explaining when
each exception is thrown.

Note: Issue #1574 (SuccessHttpHandler) was already fixed in commit
828c5b5 which removed the SuccessHttpHandler class entirely.

Fixes #1578

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: thomhurst

src/ModularPipelines.Azure/Exceptions/AzureResourceNotFoundException.cs

@@ -0,0 +1,35 @@
+using ModularPipelines.Azure.Scopes;
+
+namespace ModularPipelines.Azure.Exceptions;
+
+/// <summary>
+/// Exception thrown when an Azure resource cannot be found.
+/// </summary>
+public class AzureResourceNotFoundException : InvalidOperationException
+{
+    /// <summary>
+    /// Gets the Azure resource identifier that was not found.
+    /// </summary>
+    public AzureResourceIdentifier ResourceIdentifier { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AzureResourceNotFoundException"/> class.
+    /// </summary>
+    /// <param name="resourceIdentifier">The Azure resource identifier that was not found.</param>
+    public AzureResourceNotFoundException(AzureResourceIdentifier resourceIdentifier)
+        : base($"Azure resource not found: {resourceIdentifier}")
+    {
+        ResourceIdentifier = resourceIdentifier;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AzureResourceNotFoundException"/> class.
+    /// </summary>
+    /// <param name="resourceIdentifier">The Azure resource identifier that was not found.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
+    public AzureResourceNotFoundException(AzureResourceIdentifier resourceIdentifier, Exception? innerException)
+        : base($"Azure resource not found: {resourceIdentifier}", innerException)
+    {
+        ResourceIdentifier = resourceIdentifier;
+    }
+}

src/ModularPipelines.Azure/Exceptions/UnsupportedAzureScopeException.cs

@@ -0,0 +1,35 @@
+using ModularPipelines.Azure.Scopes;
+
+namespace ModularPipelines.Azure.Exceptions;
+
+/// <summary>
+/// Exception thrown when an unsupported Azure scope type is encountered.
+/// </summary>
+public class UnsupportedAzureScopeException : NotSupportedException
+{
+    /// <summary>
+    /// Gets the Azure scope that is not supported.
+    /// </summary>
+    public AzureScope Scope { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UnsupportedAzureScopeException"/> class.
+    /// </summary>
+    /// <param name="scope">The Azure scope that is not supported.</param>
+    public UnsupportedAzureScopeException(AzureScope scope)
+        : base($"Unsupported Azure scope type: {scope.GetType().Name}. Scope value: {scope}")
+    {
+        Scope = scope;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UnsupportedAzureScopeException"/> class.
+    /// </summary>
+    /// <param name="scope">The Azure scope that is not supported.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
+    public UnsupportedAzureScopeException(AzureScope scope, Exception? innerException)
+        : base($"Unsupported Azure scope type: {scope.GetType().Name}. Scope value: {scope}", innerException)
+    {
+        Scope = scope;
+    }
+}

src/ModularPipelines.Azure/Extensions/ArmClientExtensions.cs

@@ -1,11 +1,27 @@
 using Azure.Core;
 using Azure.ResourceManager;
+using ModularPipelines.Azure.Exceptions;
 using ModularPipelines.Azure.Scopes;
 
 namespace ModularPipelines.Azure.Extensions;
 
+/// <summary>
+/// Extension methods for <see cref="ArmClient"/>.
+/// </summary>
 public static class ArmClientExtensions
 {
+    /// <summary>
+    /// Gets the <see cref="ResourceIdentifier"/> for the specified Azure scope.
+    /// </summary>
+    /// <param name="armClient">The ARM client.</param>
+    /// <param name="azureScope">The Azure scope to resolve.</param>
+    /// <returns>The resolved <see cref="ResourceIdentifier"/>.</returns>
+    /// <exception cref="AzureResourceNotFoundException">
+    /// Thrown when the specified <see cref="AzureResourceIdentifier"/> cannot be found in the resource group.
+    /// </exception>
+    /// <exception cref="UnsupportedAzureScopeException">
+    /// Thrown when the <paramref name="azureScope"/> is of an unsupported type.
+    /// </exception>
     public static async Task<ResourceIdentifier> GetResourceIdentifierAsync(this ArmClient armClient, AzureScope azureScope)
     {
         switch (azureScope)
@@ -26,7 +42,7 @@ public static async Task<ResourceIdentifier> GetResourceIdentifierAsync(this Arm
                         }
                     }
 
-                    throw new Exception($"Unknown Resource: {azureResourceIdentifier}");
+                    throw new AzureResourceNotFoundException(azureResourceIdentifier);
                 }
 
             case AzureResourceGroupIdentifier azureResourceGroupIdentifier:
@@ -37,8 +53,8 @@ public static async Task<ResourceIdentifier> GetResourceIdentifierAsync(this Arm
                 return azureManagementGroupIdentifier.ToManagementGroupIdentifier();
             default:
                 {
-                    throw new Exception($"Unknown Resource: {azureScope}");
+                    throw new UnsupportedAzureScopeException(azureScope);
                 }
         }
     }
-}
+}