Rework DtmiConventions in models repository SDK (Azure#19427)

Highlights

- Reworked DtmiToQualifiedPath to revolve around Uri. Changed name to GetModelUri.
- Model FileFetcher will use LocalPath from the Uri object.
- Update of tests & samples.

Author: digimaun

sdk/modelsrepository/Azure.Iot.ModelsRepository/api/Azure.Iot.ModelsRepository.netstandard2.0.cs

@@ -2,7 +2,7 @@ namespace Azure.Iot.ModelsRepository
 {
     public static partial class DtmiConventions
     {
-        public static string DtmiToQualifiedPath(string dtmi, string basePath, bool fromExpanded = false) { throw null; }
+        public static System.Uri GetModelUri(string dtmi, System.Uri repositoryUri, bool expanded = false) { throw null; }
         public static bool IsValidDtmi(string dtmi) { throw null; }
     }
     public enum ModelDependencyResolution

sdk/modelsrepository/Azure.Iot.ModelsRepository/samples/ModelsRepositoryClientSamples/DtmiConventionsSamples.cs

@@ -22,29 +22,29 @@ public static void IsValidDtmi()
             #endregion Snippet:ModelsRepositorySamplesDtmiConventionsIsValidDtmi
         }
 
-        public static void GetDtmiToQualifiedPath()
+        public static void GetModelUri()
         {
-            #region Snippet:ModelsRepositorySamplesDtmiConventionsGetDtmiToQualifiedPath
+            #region Snippet:ModelsRepositorySamplesDtmiConventionsGetModelUri
 
             // This snippet shows obtaining a fully qualified path to a model file.
 
             // Local repository example
-            string localRepository = "/path/to/repository";
+            Uri localRepositoryUri = new Uri("file:///path/to/repository/");
             string fullyQualifiedModelPath = 
-                DtmiConventions.DtmiToQualifiedPath("dtmi:com:example:Thermostat;1", localRepository);
+                DtmiConventions.GetModelUri("dtmi:com:example:Thermostat;1", localRepositoryUri).AbsolutePath;
 
             // Prints '/path/to/repository/dtmi/com/example/thermostat-1.json'
             Console.WriteLine(fullyQualifiedModelPath);
 
             // Remote repository example
-            string remoteRepository = "https://contoso.com/models";
+            Uri remoteRepositoryUri = new Uri("https://contoso.com/models/");
             fullyQualifiedModelPath =
-                DtmiConventions.DtmiToQualifiedPath("dtmi:com:example:Thermostat;1", remoteRepository);
+                DtmiConventions.GetModelUri("dtmi:com:example:Thermostat;1", remoteRepositoryUri).AbsoluteUri;
 
             // Prints 'https://contoso.com/models/dtmi/com/example/thermostat-1.json'
             Console.WriteLine(fullyQualifiedModelPath);
 
-            #endregion Snippet:ModelsRepositorySamplesDtmiConventionsGetDtmiToQualifiedPath
+            #endregion Snippet:ModelsRepositorySamplesDtmiConventionsGetModelUri
         }
     }
 }

sdk/modelsrepository/Azure.Iot.ModelsRepository/samples/ModelsRepositoryClientSamples/Program.cs

@@ -35,7 +35,7 @@ public static async Task Main(string[] args)
 
             // DtmiConventions utility samples
             DtmiConventionsSamples.IsValidDtmi();
-            DtmiConventionsSamples.GetDtmiToQualifiedPath();
+            DtmiConventionsSamples.GetModelUri();
         }
     }
 }

sdk/modelsrepository/Azure.Iot.ModelsRepository/samples/readme.md

@@ -134,10 +134,10 @@ IReadOnlyDictionary<Dtmi, DTEntityInfo> parseResult = await parser.ParseAsync(mo
 Console.WriteLine($"{dtmi} resolved in {models.Count} interfaces with {parseResult.Count} entities.");
 ```
 
-## DtmiConventions utility
+## DtmiConventions utility functions
 
-The IoT Models Repository applies a set of conventions for organizing digital twin models. This package exposes a utility class
-called `DtmiConventions` which exposes functions supporting these conventions. These same functions are used throughout the client.
+The IoT Models Repository applies a set of conventions for organizing digital twin models. This package exposes a class
+called `DtmiConventions` which exposes utility functions supporting these conventions. These same functions are used throughout the client.
 
 ```C# Snippet:ModelsRepositorySamplesDtmiConventionsIsValidDtmi
 // This snippet shows how to validate a given DTMI string is well-formed.
@@ -149,21 +149,21 @@ DtmiConventions.IsValidDtmi("dtmi:com:example:Thermostat;1");
 DtmiConventions.IsValidDtmi("dtmi:com:example:Thermostat");
 ```
 
-```C# Snippet:ModelsRepositorySamplesDtmiConventionsGetDtmiToQualifiedPath
+```C# Snippet:ModelsRepositorySamplesDtmiConventionsGetModelUri
 // This snippet shows obtaining a fully qualified path to a model file.
 
 // Local repository example
-string localRepository = "/path/to/repository";
+Uri localRepositoryUri = new Uri("file:///path/to/repository/");
 string fullyQualifiedModelPath = 
-    DtmiConventions.DtmiToQualifiedPath("dtmi:com:example:Thermostat;1", localRepository);
+    DtmiConventions.GetModelUri("dtmi:com:example:Thermostat;1", localRepositoryUri).AbsolutePath;
 
 // Prints '/path/to/repository/dtmi/com/example/thermostat-1.json'
 Console.WriteLine(fullyQualifiedModelPath);
 
 // Remote repository example
-string remoteRepository = "https://contoso.com/models";
+Uri remoteRepositoryUri = new Uri("https://contoso.com/models/");
 fullyQualifiedModelPath =
-    DtmiConventions.DtmiToQualifiedPath("dtmi:com:example:Thermostat;1", remoteRepository);
+    DtmiConventions.GetModelUri("dtmi:com:example:Thermostat;1", remoteRepositoryUri).AbsoluteUri;
 
 // Prints 'https://contoso.com/models/dtmi/com/example/thermostat-1.json'
 Console.WriteLine(fullyQualifiedModelPath);

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

@@ -28,13 +28,13 @@ public static class DtmiConventions
         public static bool IsValidDtmi(string dtmi) => !string.IsNullOrEmpty(dtmi) && s_validDtmiRegex.IsMatch(dtmi);
 
         /// <summary>
-        /// Produces a fully qualified path to a model file.
+        /// Get the URI object representing a digital twin model file in a target model repository.
         /// </summary>
         /// <exception cref="ArgumentException">Thrown when a given DTMI string is malformed.</exception>
         /// <param name="dtmi">A well-formed DTMI. For example 'dtmi:com:example:Thermostat;1'.</param>
-        /// <param name="basePath">The base path in which a transformed DTMI to path will be appended to.</param>
-        /// <param name="fromExpanded">Indicates whether the produced path should be for the expanded model definition.</param>
-        public static string DtmiToQualifiedPath(string dtmi, string basePath, bool fromExpanded = false)
+        /// <param name="repositoryUri">The repository URI in which a transformed DTMI to path will be combined with.</param>
+        /// <param name="expanded">Indicates whether the produced path should be for the expanded model definition.</param>
+        public static Uri GetModelUri(string dtmi, Uri repositoryUri, bool expanded = false)
         {
             string dtmiPath = DtmiToPath(dtmi);
 
@@ -43,24 +43,20 @@ public static string DtmiToQualifiedPath(string dtmi, string basePath, bool from
                 throw new ArgumentException(string.Format(CultureInfo.InvariantCulture, StandardStrings.InvalidDtmiFormat, dtmi));
             }
 
-            // Normalize directory seperators
-            basePath = basePath.Replace("\\", "/");
-
-            if (!basePath.EndsWith("/", StringComparison.InvariantCultureIgnoreCase))
+            if (expanded)
             {
-                basePath += "/";
+                dtmiPath = dtmiPath.Replace(
+                    ModelsRepositoryConstants.JsonFileExtension,
+                    ModelsRepositoryConstants.ExpandedJsonFileExtension);
             }
 
-            string fullyQualifiedPath = $"{basePath}{dtmiPath}";
-
-            if (fromExpanded)
+            UriBuilder repositoryUriBuilder = new UriBuilder(repositoryUri);
+            if (!repositoryUriBuilder.Path.EndsWith("/", StringComparison.InvariantCultureIgnoreCase))
             {
-                fullyQualifiedPath = fullyQualifiedPath.Replace(
-                    ModelsRepositoryConstants.JsonFileExtension,
-                    ModelsRepositoryConstants.ExpandedJsonFileExtension);
+                repositoryUriBuilder.Path += "/";
             }
 
-            return fullyQualifiedPath;
+            return new Uri(repositoryUriBuilder.Uri, dtmiPath);
         }
 
         internal static string DtmiToPath(string dtmi) => IsValidDtmi(dtmi) ? $"{dtmi.ToLowerInvariant().Replace(":", "/").Replace(";", "-")}.json" : null;

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

@@ -40,10 +40,10 @@ public FetchResult Fetch(string dtmi, Uri repositoryUri, ModelDependencyResoluti
                 var work = new Queue<string>();
                 if (dependencyResolution == ModelDependencyResolution.TryFromExpanded)
                 {
-                    work.Enqueue(GetPath(dtmi, repositoryUri, true));
+                    work.Enqueue(DtmiConventions.GetModelUri(dtmi, repositoryUri, true).LocalPath);
                 }
 
-                work.Enqueue(GetPath(dtmi, repositoryUri, false));
+                work.Enqueue(DtmiConventions.GetModelUri(dtmi, repositoryUri, false).LocalPath);
 
                 string fnfError = string.Empty;
                 while (work.Count != 0)
@@ -76,11 +76,5 @@ public FetchResult Fetch(string dtmi, Uri repositoryUri, ModelDependencyResoluti
                 throw;
             }
         }
-
-        private static string GetPath(string dtmi, Uri repositoryUri, bool expanded = false)
-        {
-            string registryPath = repositoryUri.AbsolutePath;
-            return DtmiConventions.DtmiToQualifiedPath(dtmi, registryPath, expanded);
-        }
     }
 }

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

@@ -149,20 +149,14 @@ private static Queue<string> PrepareWork(string dtmi, Uri repositoryUri, bool tr
 
             if (tryExpanded)
             {
-                work.Enqueue(GetPath(dtmi, repositoryUri, true));
+                work.Enqueue(DtmiConventions.GetModelUri(dtmi, repositoryUri, true).AbsoluteUri);
             }
 
-            work.Enqueue(GetPath(dtmi, repositoryUri, false));
+            work.Enqueue(DtmiConventions.GetModelUri(dtmi, repositoryUri, false).AbsoluteUri);
 
             return work;
         }
 
-        private static string GetPath(string dtmi, Uri repositoryUri, bool expanded = false)
-        {
-            string absoluteUri = repositoryUri.AbsoluteUri;
-            return DtmiConventions.DtmiToQualifiedPath(dtmi, absoluteUri, expanded);
-        }
-
         private string EvaluatePath(string path, CancellationToken cancellationToken = default)
         {
             using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(HttpModelFetcher)}.{nameof(EvaluatePath)}");

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

@@ -13,7 +13,7 @@ internal static class ModelsRepositoryConstants
         // File Extensions
         public const string JsonFileExtension = ".json";
         public const string ExpandedJsonFileExtension = ".expanded.json";
-        public const string File = "file";
+        public const string UriFileSchema = "file";
 
         /// <summary>
         /// The ModelRepositoryConstants.ModelProperties class contains DTDL v2 property names and property values

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

@@ -26,7 +26,7 @@ public RepositoryHandler(Uri repositoryUri, ClientDiagnostics clientDiagnostics,
 
             _clientOptions = options;
             _clientDiagnostics = clientDiagnostics;
-            _modelFetcher = repositoryUri.Scheme == ModelsRepositoryConstants.File
+            _modelFetcher = repositoryUri.Scheme == ModelsRepositoryConstants.UriFileSchema
                 ? _modelFetcher = new FileModelFetcher(_clientDiagnostics)
                 : _modelFetcher = new HttpModelFetcher(_clientDiagnostics, _clientOptions);
             _clientId = Guid.NewGuid();

sdk/modelsrepository/Azure.Iot.ModelsRepository/tests/DtmiConventionsTests.cs

@@ -22,28 +22,30 @@ public void DtmiToPath(string dtmi, string expectedPath)
 
         [TestCase("dtmi:com:example:Thermostat;1", "https://localhost/repository/", "https://localhost/repository/dtmi/com/example/thermostat-1.json")]
         [TestCase("dtmi:com:example:Thermostat;1", "https://localhost/REPOSITORY", "https://localhost/REPOSITORY/dtmi/com/example/thermostat-1.json")]
-        [TestCase("dtmi:com:example:Thermostat;1", "/path/to/repository/", "/path/to/repository/dtmi/com/example/thermostat-1.json")]
-        [TestCase("dtmi:com:example:Thermostat;1", "/path/to/RepoSitory", "/path/to/RepoSitory/dtmi/com/example/thermostat-1.json")]
-        [TestCase("dtmi:com:example:Thermostat;1", "C:\\path\\to\\repository", "C:/path/to/repository/dtmi/com/example/thermostat-1.json")]
-        [TestCase("dtmi:com:example:Thermostat:1", "https://localhost/repository", null)]
-        [TestCase("dtmi:com:example:Thermostat:1", "/path/to/repository/", null)]
-        [TestCase("dtmi:com:example:Thermostat;1", "", "/dtmi/com/example/thermostat-1.json")]
-        public void DtmiToQualifiedPath(string dtmi, string repository, string expectedPath)
+        [TestCase("dtmi:com:example:Thermostat;1", "file:///path/to/repository/", "file:///path/to/repository/dtmi/com/example/thermostat-1.json")]
+        [TestCase("dtmi:com:example:Thermostat;1", "file://path/to/RepoSitory", "file://path/to/RepoSitory/dtmi/com/example/thermostat-1.json")]
+        [TestCase("dtmi:com:example:Thermostat;1", "C:\\path\\to\\repository\\", "file:///C:/path/to/repository/dtmi/com/example/thermostat-1.json")]
+        [TestCase("dtmi:com:example:Thermostat:1", "https://localhost/repository/", null)]
+        [TestCase("dtmi:com:example:Thermostat:1", "file://path/to/repository/", null)]
+        [TestCase("dtmi:com:example:Thermostat;1", "\\\\server\\repository", "file://server/repository/dtmi/com/example/thermostat-1.json")]
+        public void GetModelUri(string dtmi, string repository, string expectedUri)
         {
-            if (string.IsNullOrEmpty(expectedPath))
+            Uri repositoryUri = new Uri(repository);
+            if (string.IsNullOrEmpty(expectedUri))
             {
-                Action act = () => DtmiConventions.DtmiToQualifiedPath(dtmi, repository);
+                Action act = () => DtmiConventions.GetModelUri(dtmi, repositoryUri);
                 act.Should().Throw<ArgumentException>().WithMessage(string.Format(StandardStrings.InvalidDtmiFormat, dtmi));
                 return;
             }
 
-            string modelPath = DtmiConventions.DtmiToQualifiedPath(dtmi, repository);
-            modelPath.Should().Be(expectedPath);
+            Uri modelUri = DtmiConventions.GetModelUri(dtmi, repositoryUri);
+            modelUri.AbsoluteUri.Should().Be(expectedUri);
 
-            string expectedExpandedPath = expectedPath.Replace(
+            string expectedExpandedUri = expectedUri.Replace(
                 ModelsRepositoryConstants.JsonFileExtension, ModelsRepositoryConstants.ExpandedJsonFileExtension);
-            string expandedModelPath = DtmiConventions.DtmiToQualifiedPath(dtmi, repository, true);
-            expandedModelPath.Should().Be(expectedExpandedPath);
+
+            Uri expandedModelUri = DtmiConventions.GetModelUri(dtmi, repositoryUri, true);
+            expandedModelUri.Should().Be(expectedExpandedUri);
         }
 
         [TestCase("dtmi:com:example:Thermostat;1", true)]