126 new feature add swapping methods to i twin object interface (#128)

* Create draft PR for #126

* [ixc] adds type agnostic methods for swapping data

* asp

* swapping methods (docu and create empty pocos)

* [DOCU] docfx update to 2.63.0, adds note about type agnostic methods for swapping in the documentation.

---------

Co-authored-by: PTKu <PTKu@users.noreply.github.com>

.config/dotnet-tools.json

@@ -9,7 +9,7 @@
       ]
     },
     "docfx": {
-      "version": "2.60.0",
+      "version": "2.63.0",
       "commands": [
         "docfx"
       ]

docfx/articles/connectors/README.md

@@ -179,7 +179,7 @@ See also
 
 ## Using POCO / Plain object
 
-Onliners are a somewhat heavy objects that are well suited for communication with the controller, but they carry too much information that are a burden in some use cases. IX compiler, therefore, creates `Plain/POCO` objects that are light CLR (C#) objects that can retrieve and send data from and to the controller.
+Onliners are somewhat heavy objects that are well suited for communication with the controller, but they carry too much information that are a burden in some use cases. IX compiler, therefore, creates `Plain/POCO` objects that are light CLR (C#) objects that can retrieve and send data from and to the controller.
 
 ### Getting POCO object
 
@@ -201,6 +201,9 @@ await monster.PlainToOnlineAsync(plainOnline);
 await monster.PlainToShadowAsync(plainShadow);
 ~~~
 
+>[!NOTE]
+> There are also type agnostic methods available over [ITwinObject](~/api/Ix.Connector.ITwinObject.yml) interface.
+
 ----
 ## Other useful properties of Primitive Twins
 

src/ix.connectors/src/Ix.Connector/ITwinObject.cs

@@ -72,22 +72,41 @@ public interface ITwinObject : ITwinElement
     /// <returns>Connector</returns>
     Connector GetConnector();
 
+    /// <summary>
+    /// Reads online data and retrieved POCO object populated with actual online data.
+    /// </summary>
+    /// <returns>POCO with online data of this object</returns>
+    /// <exception cref="NotImplementedException"></exception>
     public object OnlineToPlain()
     {
         throw new NotImplementedException();
     }
 
+    /// <summary>
+    /// Writes data from POCO object to online data (PLC)
+    /// </summary>
+    /// <param name="plain">POCO object to be written to the controller.</param>
+    /// <exception cref="NotImplementedException"></exception>
     public void PlainToOnline(object plain)
     {
         throw new NotImplementedException();
     }
 
-
+    /// <summary>
+    /// Read data from shadows of this object to a new instance of a POCO object.
+    /// </summary>
+    /// <returns>POCO object populated by data from the shadows of this object.</returns>
+    /// <exception cref="NotImplementedException"></exception>
     public object ShadowToPlain()
     {
         throw new NotImplementedException();
     }
 
+    /// <summary>
+    /// Writes data from POCO object to shadow data of this object.
+    /// </summary>
+    /// <param name="plain">POCO object to be written to the shadows of this object.</param>
+    /// <exception cref="NotImplementedException"></exception>
     public void PlainToShadow(object plain)
     {
         throw new NotImplementedException();

src/ix.connectors/src/Ix.Connector/TwinObjectExtensions.cs

@@ -282,4 +282,18 @@ public static void StopPolling(this ITwinElement obj)
     {
         Polling.Remove(obj);
     }
+
+    /// <summary>
+    /// Creates new unpopulated instance of POCO object for this twin object.
+    /// <remarks type="important">
+    /// This method uses reflections. It is not suitable for operations where performance matters.
+    /// </remarks>
+    /// </summary>
+    /// <param name="obj"></param>
+    /// <returns>New empty instance of POCO object for this twin object</returns>
+    public static object CreatePoco(this ITwinObject obj)
+    {
+        var createEmptyPocoMethod = obj.GetType().GetMethod("CreateEmptyPoco");
+        return createEmptyPocoMethod.Invoke(obj, null);
+    }
 }

src/ix.connectors/tests/Ix.ConnectorTests/Ix.ConnectorTests/TwinObjectExtensionsTests.cs

@@ -371,5 +371,84 @@ public static async Task CannotCallShadowToOnlineAsyncWithNullObj()
         {
             await Assert.ThrowsAsync<ArgumentNullException>(() => default(ITwinObject).ShadowToOnlineAsync());
         }
+
+        private class MyTestPoco
+        {
+
+        }
+
+        private class CreatePocoTestClass : ITwinObject
+        {
+            public string Symbol { get; }
+            public string AttributeName { get; }
+            public string HumanReadable { get; }
+            public ITwinObject GetParent()
+            {
+                throw new NotImplementedException();
+            }
+
+            public string GetSymbolTail()
+            {
+                throw new NotImplementedException();
+            }
+
+            public void Poll()
+            {
+                throw new NotImplementedException();
+            }
+
+            public IEnumerable<ITwinObject> GetChildren()
+            {
+                throw new NotImplementedException();
+            }
+
+            public IEnumerable<ITwinElement> GetKids()
+            {
+                throw new NotImplementedException();
+            }
+
+            public IEnumerable<ITwinPrimitive> GetValueTags()
+            {
+                throw new NotImplementedException();
+            }
+
+            public void AddChild(ITwinObject twinObject)
+            {
+                throw new NotImplementedException();
+            }
+
+            public void AddValueTag(ITwinPrimitive twinPrimitive)
+            {
+                throw new NotImplementedException();
+            }
+
+            public void AddKid(ITwinElement kid)
+            {
+                throw new NotImplementedException();
+            }
+
+            public Connector GetConnector()
+            {
+                throw new NotImplementedException();
+            }
+
+            public MyTestPoco CreateEmptyPoco()
+            {
+                return new MyTestPoco();
+            }
+        }
+
+        [Fact]
+        public static void CanCallCreatePOCO()
+        {
+            // Arrange
+            var obj = new CreatePocoTestClass();
+
+            // Act
+            var result = obj.CreatePoco();
+
+            // Assert
+            Assert.IsType<MyTestPoco>(result);
+        }
     }
 }