Remove ResolverException in favor of RequestFailedException

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/DtmiConventions.cs

@@ -7,6 +7,10 @@
 
 namespace Azure.Iot.ModelsRepository
 {
+    /// <summary>
+    /// DtmiConventions implements the core aspects of the IoT model repo conventions
+    /// which includes DTMI validation and calculating a URI path from a DTMI.
+    /// </summary>
     internal static class DtmiConventions
     {
         private static readonly Regex s_validDtmiRegex = new Regex(@"^dtmi:[A-Za-z](?:[A-Za-z0-9_]*[A-Za-z0-9])?(?::[A-Za-z](?:[A-Za-z0-9_]*[A-Za-z0-9])?)*;[1-9][0-9]{0,8}$");

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/Fetchers/FetchResult.cs

@@ -3,6 +3,11 @@
 
 namespace Azure.Iot.ModelsRepository.Fetchers
 {
+    /// <summary>
+    /// The FetchResult class has the purpose of containing key elements of
+    /// an IModelFetcher Fetch() operation including model definition, path and whether
+    /// it was from an expanded (pre-calculated) fetch.
+    /// </summary>
     internal class FetchResult
     {
         public string Definition { get; set; }

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/Fetchers/IModelFetcher.cs

@@ -7,6 +7,10 @@
 
 namespace Azure.Iot.ModelsRepository.Fetchers
 {
+    /// <summary>
+    /// The IModelFetcher is an abstraction that supports fetching
+    /// model content via a particular protocol or mechanism of interaction.
+    /// </summary>
     internal interface IModelFetcher
     {
         Task<FetchResult> FetchAsync(string dtmi, Uri repositoryUri, CancellationToken cancellationToken = default);

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/Fetchers/LocalModelFetcher.cs

@@ -12,6 +12,10 @@
 
 namespace Azure.Iot.ModelsRepository.Fetchers
 {
+    /// <summary>
+    /// The LocalModelFetcher is an implementation of IModelFetcher
+    /// for supporting local filesystem based model content fetching.
+    /// </summary>
     internal class LocalModelFetcher : IModelFetcher
     {
         private readonly bool _tryExpanded;
@@ -65,7 +69,9 @@ public FetchResult Fetch(string dtmi, Uri repositoryUri, CancellationToken cance
                     fnfError = string.Format(CultureInfo.CurrentCulture, ServiceStrings.ErrorFetchingModelContent, tryContentPath);
                 }
 
-                throw new FileNotFoundException(fnfError);
+                throw new RequestFailedException(
+                    $"{string.Format(CultureInfo.CurrentCulture, ServiceStrings.GenericResolverError, dtmi)} {fnfError}",
+                    new FileNotFoundException(fnfError));
             }
             catch (Exception ex)
             {

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/Fetchers/RemoteModelFetcher.cs

@@ -13,6 +13,10 @@
 
 namespace Azure.Iot.ModelsRepository.Fetchers
 {
+    /// <summary>
+    /// The RemoteModelFetcher is an implementation of IModelFetcher
+    /// for supporting http[s] based model content fetching.
+    /// </summary>
     internal class RemoteModelFetcher : IModelFetcher
     {
         private readonly HttpPipeline _pipeline;
@@ -54,7 +58,9 @@ public FetchResult Fetch(string dtmi, Uri repositoryUri, CancellationToken cance
                     }
                     catch (Exception)
                     {
-                        remoteFetchError = string.Format(CultureInfo.CurrentCulture, StandardStrings.ErrorFetchingModelContent, tryContentPath);
+                        remoteFetchError =
+                            $"{string.Format(CultureInfo.CurrentCulture, ServiceStrings.GenericResolverError, dtmi)} " +
+                            string.Format(CultureInfo.CurrentCulture, StandardStrings.ErrorFetchingModelContent, tryContentPath);
                     }
                 }
 
@@ -95,7 +101,9 @@ public async Task<FetchResult> FetchAsync(string dtmi, Uri repositoryUri, Cancel
                     }
                     catch (Exception)
                     {
-                        remoteFetchError = string.Format(CultureInfo.CurrentCulture, StandardStrings.ErrorFetchingModelContent, tryContentPath);
+                        remoteFetchError =
+                            $"{string.Format(CultureInfo.CurrentCulture, ServiceStrings.GenericResolverError, dtmi)} " +
+                            string.Format(CultureInfo.CurrentCulture, StandardStrings.ErrorFetchingModelContent, tryContentPath);
                     }
                 }
 

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/ModelMetadata.cs

@@ -6,6 +6,9 @@
 
 namespace Azure.Iot.ModelsRepository
 {
+    /// <summary>
+    /// ModelMetadata is designated to store KPIs from model parsing.
+    /// </summary>
     internal class ModelMetadata
     {
         public ModelMetadata(string id, IList<string> extends, IList<string> componentSchemas)

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/ModelQuery.cs

@@ -8,8 +8,8 @@
 namespace Azure.Iot.ModelsRepository
 {
     /// <summary>
-    /// The <c>ModelQuery</c> class is responsible for parsing DTDL v2 models to produce key metadata.
-    /// In the current form <c>ModelQuery</c> is focused on determining model dependencies recursively
+    /// The ModelQuery class is responsible for parsing DTDL v2 models to produce key metadata.
+    /// In the current form ModelQuery is focused on determining model dependencies recursively
     /// via extends and component schemas.
     /// </summary>
     internal class ModelQuery

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/ModelRepositoryConstants.cs

@@ -15,8 +15,8 @@ internal static class ModelRepositoryConstants
         public const string ExpandedJsonFileExtension = ".expanded.json";
 
         /// <summary>
-        /// The <c>ModelRepositoryConstants.ModelProperties</c> class contains DTDL v2 property names and property values
-        /// used by the <c>ModelQuery</c> class to parse DTDL model key indicators.
+        /// The ModelRepositoryConstants.ModelProperties class contains DTDL v2 property names and property values
+        /// used by the ModelQuery class to parse DTDL model key indicators.
         /// </summary>
         internal static class ModelProperties
         {

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/ModelsRepoClient.cs

@@ -12,69 +12,69 @@
 namespace Azure.Iot.ModelsRepository
 {
     /// <summary>
-    /// The <c>ModelsRepoClient</c> class supports DTDL model resolution providing functionality to
-    /// resolve models by retrieving model definitions and their dependencies.
+    /// The ModelsRepoClient class supports operations against DTDL model repositories following the
+    /// conventions of the Azure IoT Plug and Play Models repository.
     /// </summary>
     public class ModelsRepoClient
     {
         private readonly RepositoryHandler _repositoryHandler;
         private readonly ClientDiagnostics _clientDiagnostics;
 
         /// <summary>
-        /// Initializes the <c>ModelsRepoClient</c> with default client options while pointing to
-        /// the Azure IoT Plug and Play Model repository https://devicemodels.azure.com for resolution.
+        /// Initializes the ModelsRepoClient with default client options while pointing to
+        /// the Azure IoT Plug and Play Models repository https://devicemodels.azure.com for resolution.
         /// </summary>
         public ModelsRepoClient() : this(new Uri(DefaultModelsRepository), new ModelsRepoClientOptions()) { }
 
         /// <summary>
-        /// Initializes the <c>ModelsRepoClient</c> with default client options while pointing to
+        /// Initializes the ModelsRepoClient with default client options while pointing to
         /// a custom <paramref name="repositoryUri"/> for resolution.
         /// </summary>
         /// <param name="repositoryUri">
-        /// The model repository <c>Uri</c> value. This can be a remote endpoint or local directory.
+        /// The model repository Uri value. This can be a remote endpoint or local directory.
         /// </param>
         public ModelsRepoClient(Uri repositoryUri) : this(repositoryUri, new ModelsRepoClientOptions()) { }
 
         /// <summary>
-        /// Initializes the <c>ModelsRepoClient</c> with custom client <paramref name="options"/> while pointing to
+        /// Initializes the ModelsRepoClient with custom client <paramref name="options"/> while pointing to
         /// the Azure IoT Plug and Play Model repository https://devicemodels.azure.com for resolution.
         /// </summary>
         /// <param name="options">
-        /// <c>ModelsRepoClientOptions</c> to configure resolution and client behavior.
+        /// ModelsRepoClientOptions to configure resolution and client behavior.
         /// </param>
         public ModelsRepoClient(ModelsRepoClientOptions options) : this(new Uri(DefaultModelsRepository), options) { }
 
         /// <summary>
-        /// Initializes the <c>ModelsRepoClient</c> with default client options while pointing to
+        /// Initializes the ModelsRepoClient with default client options while pointing to
         /// a custom <paramref name="repositoryUriStr"/> for resolution.
         /// </summary>
         /// <param name="repositoryUriStr">
-        /// The model repository <c>Uri</c> in string format. This can be a remote endpoint or local directory.
+        /// The model repository Uri in string format. This can be a remote endpoint or local directory.
         /// </param>
         public ModelsRepoClient(string repositoryUriStr) : this(repositoryUriStr, new ModelsRepoClientOptions()) { }
 
         /// <summary>
-        /// Initializes the <c>ModelsRepoClient</c> with custom client <paramref name="options"/> while pointing to
+        /// Initializes the ModelsRepoClient with custom client <paramref name="options"/> while pointing to
         /// a custom <paramref name="repositoryUriStr"/> for resolution.
         /// </summary>
         /// <param name="repositoryUriStr">
-        /// The model repository <c>Uri</c> in string format. This can be a remote endpoint or local directory.
+        /// The model repository Uri in string format. This can be a remote endpoint or local directory.
         /// </param>
         /// <param name="options">
-        /// <c>ModelsRepoClientOptions</c> to configure resolution and client behavior.
+        /// ModelsRepoClientOptions to configure resolution and client behavior.
         /// </param>
         public ModelsRepoClient(string repositoryUriStr, ModelsRepoClientOptions options)
             : this(new Uri(repositoryUriStr), options) { }
 
         /// <summary>
-        /// Initializes the <c>ModelsRepoClient</c> with custom client <paramref name="options"/> while pointing to
+        /// Initializes the ModelsRepoClient with custom client <paramref name="options"/> while pointing to
         /// a custom <paramref name="repositoryUri"/> for resolution.
         /// </summary>
         /// <param name="repositoryUri">
-        /// The model repository <c>Uri</c>. This can be a remote endpoint or local directory.
+        /// The model repository Uri. This can be a remote endpoint or local directory.
         /// </param>
         /// <param name="options">
-        /// <c>ModelsRepoClientOptions</c> to configure resolution and client behavior.
+        /// ModelsRepoClientOptions to configure resolution and client behavior.
         /// </param>
         public ModelsRepoClient(Uri repositoryUri, ModelsRepoClientOptions options)
         {
@@ -90,10 +90,10 @@ public ModelsRepoClient(Uri repositoryUri, ModelsRepoClientOptions options)
         /// Resolves a model definition identified by <paramref name="dtmi"/> and optionally its dependencies.
         /// </summary>
         /// <returns>
-        /// An <c>IDictionary</c> containing the model definition(s) where the key is the dtmi
+        /// An IDictionary containing the model definition(s) where the key is the dtmi
         /// and the value is the raw model definition string.
         /// </returns>
-        /// <exception cref="ResolverException">Thrown when a resolution failure occurs.</exception>
+        /// <exception cref="RequestFailedException">Thrown when a resolution failure occurs.</exception>
         /// <param name="dtmi">A well-formed DTDL model Id. For example 'dtmi:com:example:Thermostat;1'.</param>
         /// <param name="cancellationToken">The cancellationToken.</param>
         [SuppressMessage(
@@ -119,10 +119,10 @@ public virtual async Task<IDictionary<string, string>> ResolveAsync(string dtmi,
         /// Resolves a model definition identified by <paramref name="dtmi"/> and optionally its dependencies.
         /// </summary>
         /// <returns>
-        /// An <c>IDictionary</c> containing the model definition(s) where the key is the dtmi
+        /// An IDictionary containing the model definition(s) where the key is the dtmi
         /// and the value is the raw model definition string.
         /// </returns>
-        /// <exception cref="ResolverException">Thrown when a resolution failure occurs.</exception>
+        /// <exception cref="RequestFailedException">Thrown when a resolution failure occurs.</exception>
         /// <param name="dtmi">A well-formed DTDL model Id. For example 'dtmi:com:example:Thermostat;1'.</param>
         /// <param name="cancellationToken">The cancellationToken.</param>
         [SuppressMessage(
@@ -149,10 +149,10 @@ public virtual IDictionary<string, string> Resolve(string dtmi, CancellationToke
         /// Resolves a collection of model definitions identified by <paramref name="dtmis"/> and optionally their dependencies.
         /// </summary>
         /// <returns>
-        /// An <c>IDictionary</c> containing the model definition(s) where the key is the dtmi
+        /// An IDictionary containing the model definition(s) where the key is the dtmi
         /// and the value is the raw model definition string.
         /// </returns>
-        /// <exception cref="ResolverException">Thrown when a resolution failure occurs.</exception>
+        /// <exception cref="RequestFailedException">Thrown when a resolution failure occurs.</exception>
         /// <param name="dtmis">A collection of well-formed DTDL model Ids.</param>
         /// <param name="cancellationToken">The cancellationToken.</param>
         [SuppressMessage("Usage", "AZC0015:Unexpected client method return type.", Justification = "<Pending>")]
@@ -176,10 +176,10 @@ public virtual async Task<IDictionary<string, string>> ResolveAsync(IEnumerable<
         /// Resolves a collection of model definitions identified by <paramref name="dtmis"/> and optionally their dependencies.
         /// </summary>
         /// <returns>
-        /// An <c>IDictionary</c> containing the model definition(s) where the key is the dtmi
+        /// An IDictionary containing the model definition(s) where the key is the dtmi
         /// and the value is the raw model definition string.
         /// </returns>
-        /// <exception cref="ResolverException">Thrown when a resolution failure occurs.</exception>
+        /// <exception cref="RequestFailedException">Thrown when a resolution failure occurs.</exception>
         /// <param name="dtmis">A collection of well-formed DTDL model Ids.</param>
         /// <param name="cancellationToken">The cancellationToken.</param>
         [SuppressMessage("Usage", "AZC0015:Unexpected client method return type.", Justification = "<Pending>")]
@@ -205,17 +205,17 @@ public virtual IDictionary<string, string> Resolve(IEnumerable<string> dtmis, Ca
         public static bool IsValidDtmi(string dtmi) => DtmiConventions.IsDtmi(dtmi);
 
         /// <summary>
-        /// Gets the <c>Uri</c> associated with the ModelsRepoClient instance.
+        /// Gets the Uri associated with the ModelsRepoClient instance.
         /// </summary>
         public Uri RepositoryUri { get; }
 
         /// <summary>
-        /// Gets the <c>ModelsRepoClientOptions</c> associated with the ModelsRepoClient instance.
+        /// Gets the ModelsRepoClientOptions associated with the ModelsRepoClient instance.
         /// </summary>
         public ModelsRepoClientOptions ClientOptions { get; }
 
         /// <summary>
-        /// Azure Device Models Repository used by default.
+        /// The global Azure IoT Models Repository endpoint used by default.
         /// </summary>
         public static string DefaultModelsRepository => ModelRepositoryConstants.DefaultModelsRepository;
     }

sdk/modelsrepository/Azure.Iot.ModelsRepository/src/RepositoryHandler.cs

@@ -114,8 +114,11 @@ private async Task<IDictionary<string, string>> ProcessAsync(IEnumerable<string>
                 if (!parsedDtmi.Equals(targetDtmi, StringComparison.Ordinal))
                 {
                     ModelsRepoEventSource.Instance.IncorrectDtmiCasing(targetDtmi, parsedDtmi);
-                    string formatErrorMsg = string.Format(CultureInfo.CurrentCulture, ServiceStrings.IncorrectDtmiCasing, targetDtmi, parsedDtmi);
-                    throw new ResolverException(targetDtmi, formatErrorMsg, new FormatException(formatErrorMsg));
+                    string formatErrorMsg =
+                        $"{string.Format(CultureInfo.CurrentCulture, ServiceStrings.GenericResolverError, targetDtmi)} " +
+                        string.Format(CultureInfo.CurrentCulture, ServiceStrings.IncorrectDtmiCasing, targetDtmi, parsedDtmi);
+
+                    throw new RequestFailedException(formatErrorMsg, new FormatException(formatErrorMsg));
                 }
 
                 processedModels.Add(targetDtmi, result.Definition);
@@ -124,28 +127,14 @@ private async Task<IDictionary<string, string>> ProcessAsync(IEnumerable<string>
             return processedModels;
         }
 
-        private async Task<FetchResult> FetchAsync(string dtmi, CancellationToken cancellationToken)
+        private Task<FetchResult> FetchAsync(string dtmi, CancellationToken cancellationToken)
         {
-            try
-            {
-                return await _modelFetcher.FetchAsync(dtmi, _repositoryUri, cancellationToken).ConfigureAwait(false);
-            }
-            catch (Exception ex)
-            {
-                throw new ResolverException(dtmi, ex.Message, ex);
-            }
+            return _modelFetcher.FetchAsync(dtmi, _repositoryUri, cancellationToken);
         }
 
         private FetchResult Fetch(string dtmi, CancellationToken cancellationToken)
         {
-            try
-            {
-                return _modelFetcher.Fetch(dtmi, _repositoryUri, cancellationToken);
-            }
-            catch (Exception ex)
-            {
-                throw new ResolverException(dtmi, ex.Message, ex);
-            }
+            return _modelFetcher.Fetch(dtmi, _repositoryUri, cancellationToken);
         }
 
         private static Queue<string> PrepareWork(IEnumerable<string> dtmis)
@@ -156,8 +145,12 @@ private static Queue<string> PrepareWork(IEnumerable<string> dtmis)
                 if (!DtmiConventions.IsDtmi(dtmi))
                 {
                     ModelsRepoEventSource.Instance.InvalidDtmiInput(dtmi);
-                    string invalidArgMsg = string.Format(CultureInfo.CurrentCulture, ServiceStrings.InvalidDtmiFormat, dtmi);
-                    throw new ResolverException(dtmi, invalidArgMsg, new ArgumentException(invalidArgMsg));
+
+                    string invalidArgMsg =
+                        $"{string.Format(CultureInfo.CurrentCulture, ServiceStrings.GenericResolverError, dtmi)} " +
+                        string.Format(CultureInfo.CurrentCulture, ServiceStrings.InvalidDtmiFormat, dtmi);
+
+                    throw new RequestFailedException(invalidArgMsg, new ArgumentException(invalidArgMsg));
                 }
 
                 toProcessModels.Enqueue(dtmi);