add GetObjects for root of tree

MetasysServices.Tests/MetasysClientTests.cs

@@ -1,6 +1,7 @@
 using Flurl.Http;
 using JohnsonControls.Metasys.BasicServices;
 using JohnsonControls.Metasys.BasicServices.Enums;
+using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 using Nito.AsyncEx;
 using NUnit.Framework;
@@ -1679,6 +1680,62 @@ public void TestGetNetworkDeviceTypesUnauthorizedThrowsException()
 
         #region GetObjects Tests
 
+        readonly string RootObjects = JsonConvert.SerializeObject(new
+        {
+            self = "https://welch12.go.johnsoncontrols.com/api/v6/objects/0352a3d7-baa2-5eae-b4ab-f20d485045d2/objects?flatten=true&includeExtensions=true&includeInternal=false&depth=1&includeModificationConstraints=false",
+            items = (List<object>)[
+                new
+                {
+                    name = "Site",
+                    label = "Site",
+                    id = "0352a3d7-baa2-5eae-b4ab-f20d485045d2",
+                    itemReference = "welch12:welch12/$site",
+                    parentUrl = (string) null,
+                    items = new[] {
+                        new
+                        {
+                            name = "User Views",
+                            label = "UserTrees",
+                            id = "f0900868-3b53-57b1-987b-f12dd92d7a2d",
+                            itemReference = "welch12:welch12/$site.UserTrees",
+                            parentUrl = "/objects/0352a3d7-baa2-5eae-b4ab-f20d485045d2"
+                        }
+                    }
+                }
+
+            ]
+
+        });
+
+
+        [Test]
+        public void TestGetObjectsRoot()
+        {
+            httpTest.RespondWith(RootObjects);
+
+            var originalApiVersion = client.Version;
+            client.Version = ApiVersion.v4;
+
+            try
+            {
+                var rootObject = client.GetObjects();
+
+                httpTest.ShouldHaveCalled("https://hostname/api/v4/objects")
+                    .WithoutQueryParamValue("flatten", true)
+                    .WithoutQueryParamValue("includeExtensions", false)
+                    .WithVerb(HttpMethod.Get)
+                    .Times(1);
+
+                Assert.That(rootObject.ItemReference, Is.EqualTo("welch12:welch12/$site"));
+                Assert.That(rootObject.ChildrenCount, Is.EqualTo(1));
+            }
+            finally
+            {
+                client.Version = originalApiVersion;
+            }
+        }
+
+
         [Test]
         public void TestGetObjectsNone()
         {

MetasysServices.Tests/MetasysServices.Tests.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFramework>net6.0</TargetFramework>
-
+    <LangVersion>12</LangVersion>
     <IsPackable>false</IsPackable>
 
     <Version>6.0.4</Version>
@@ -28,4 +28,4 @@
     <ProjectReference Include="..\MetasysServices\MetasysServices.csproj" />
   </ItemGroup>
 
-</Project>
+</Project>

MetasysServices/BasicServiceProvider.cs

@@ -174,12 +174,12 @@ protected List<NetworkDevice> ToNetworkDevice(List<JToken> items, ApiVersion ver
         /// <param name="id"></param>
         /// <param name="parameters"></param>
         /// <returns></returns>
-        /// <exception cref="InvalidOperationException">If <see cref="Vers"/> is less than <see cref="ApiVersion.v4"/></exception>
+        /// <exception cref="InvalidOperationException">If <see cref="ApiVersion"/> is less than <see cref="ApiVersion.v4"/></exception>
         /// <returns>
         /// If <paramref name="id"/> is specified then this method returns the children of the specified object (and any of their children if level > 1).
         /// If <c>id</c> is <c>null</c> then this method returns the root object (and it's children; unless level is 0).
         /// </returns>
-        protected async Task<List<MetasysObject>> GetObjectsAsync(Guid? id, Dictionary<string, string> parameters = null)
+        protected async Task<IEnumerable<MetasysObject>> GetObjectsAsync(Guid? id, Dictionary<string, string> parameters = null)
         {
             if (Version <= ApiVersion.v3)
             {
@@ -197,7 +197,7 @@ protected async Task<List<MetasysObject>> GetObjectsAsync(Guid? id, Dictionary<s
             {
                 return [rootObject];
             }
-            return rootObject.Children.ToList();
+            return rootObject.Children;
         }
 
 
@@ -206,7 +206,10 @@ protected async Task<List<MetasysObject>> GetObjectsAsync(Guid? id, Dictionary<s
         /// Level indicates how deep to retrieve objects.
         /// </summary>
         /// <remarks>
+        /// This should only be called when version is 3 or less. Starting with v4 we support depth directly.
+        /// <para>
         /// A level of 1 only retrieves immediate children of the parent object.
+        /// </para>
         /// <para> This should not be called on a site that supports REST API 4 or later as it makes a series of recursive calls that can
         /// be handled in one call to the api</para>
         /// </remarks>

MetasysServices/Interfaces/IMetasysClient.cs

@@ -297,6 +297,27 @@ public interface IMetasysClient : IBasicService
         /// <inheritdoc cref="IMetasysClient.GetNetworkDeviceTypes()"/>
         Task<IEnumerable<MetasysObjectType>> GetNetworkDeviceTypesAsync();
 
+        /// <summary>
+        /// Gets the root object and its direct children
+        /// </summary>
+        /// <remarks>
+        /// This method only works if the site supports Version 4 of the Metasys REST API or later.
+        /// </remarks>
+        /// <param name="includeExtensions">Set it to true to get also the extensions of the object.</param>
+        /// <param name="includeInternal">Set it to true to get the internal objects</param>
+        /// <param name="levels">
+        /// The number of levels to retrieve. This can only be 0 or 1. It defaults to 1.
+        ///
+        /// A value of 0 returns the root object only.
+        ///
+        /// A value of 1 returns the root and its children.
+        /// </param>
+        /// <returns>The root object. If <paramref name="levels"/> is set to 1 the <see cref="MetasysObject.Children"/>
+        /// property of the root object will contain the children.</returns>
+        MetasysObject GetObjects(bool includeExtensions = false, bool includeInternal = false, int levels = 1);
+        /// <inheritdoc cref="GetObjects(bool, bool, int)"/>
+        Task<MetasysObject> GetObjectsAsync(bool includeExtensions = false, bool includeInternal = false, int levels = 1);
+
 
         /// <summary>
         /// Gets all child objects given a parent id.

MetasysServices/MetasysClient.cs

@@ -1,5 +1,6 @@
 using Flurl;
 using Flurl.Http;
+using Flurl.Util;
 using JohnsonControls.Metasys.BasicServices.Utils;
 using Newtonsoft.Json.Linq;
 using System;
@@ -124,7 +125,8 @@
                 if (Spaces != null) { Spaces.Version = version.Value; }
                 if (Streams != null) { Streams.Version = version.Value; }
                 if (Trends != null) { Trends.Version = version.Value; }
-                base.Version = value;
+                // override the base version as well
+                base.Version = version.Value;
             }
         }
 
@@ -491,6 +493,26 @@
         #region "OBJECTS" // ========================================================================================================
 
         // GetObjects ---------------------------------------------------------------------------------------------------------------
+
+        /// <inheritdoc/>
+        public MetasysObject GetObjects(bool includeExtensions = false, bool includeInternal = false, int levels = 1)
+        {
+            return GetObjectsAsync(includeExtensions, includeInternal, levels).GetAwaiter().GetResult();
+        }
+        /// <inheritdoc/>
+        public async Task<MetasysObject> GetObjectsAsync(bool includeExtensions = false, bool includeInternal = false, int levels = 1)
+        {
+            if (levels > 1 || levels < 0) throw new ArgumentOutOfRangeException(nameof(levels), "The only supported values are 0 and 1.");
+            Dictionary<string, string> parameters = new Dictionary<string, string>
+            {
+                ["includeExtensions"] = includeExtensions.ToInvariantString().ToLower(),
+                ["includeInternal"] = includeInternal.ToInvariantString().ToLower(),
+                ["depth"] = levels.ToInvariantString()
+            };
+            return (await base.GetObjectsAsync(null, parameters)).First();
+        }
+
+
         /// <inheritdoc/>
         public IEnumerable<MetasysObject> GetObjects(ObjectId id, int levels = 1, bool includeInternalObjects = false, bool includeExtensions = false)
         {
@@ -519,7 +541,7 @@
                     { "includeInternal", includeInternalObjects.ToString().ToLower() } //This param has different name when version > v3
                 };
 
                 return await GetObjectsAsync(id, parameters);
             }
 
             var objects = await GetObjectChildrenAsync(id, parameters, levels).ConfigureAwait(false);