Merge pull request #3939 from PedroDebevere/classLib1.1.2.1RNs

Class library 1.1.2.1 release notes

develop/devguide/ClassLibrary/ClassLibraryVersioning.md

@@ -17,4 +17,4 @@ The different components of a version A.B.C.D represent the following:
 
 ## Released versions
 
-Refer to the [class library release notes](xref:ClassLibrary_Range_1.2) for an overview of the released versions.
+Refer to the [Skyline.DataMiner.Core.DataMinerSystem](xref:Skyline_DataMiner_Core_DataMinerSystem_Range_1.1) release notes for an overview of the released versions.

release-notes/Breaking_changes/Breaking_changes.md

@@ -9,6 +9,7 @@ The following breaking changes have been introduced in recent DataMiner releases
 | Release note ID | Release version(s) | Description |
 |--|--|--|
 | [41195](xref:General_Feature_Release_10.5.1#automation-locking-behavior-of-automation-script-actions-has-been-enhanced-id-41195) | DataMiner 10.4.0 [CU10]/10.5.1 | Changes made to the locking behavior of Automation script actions will affect the behavior of the *Generate Information*, *Log*, *Send Notification*, *Send Report*, *Set State* and *Set Template* actions. |
+| [41178](xref:Skyline_DataMiner_Core_DataMinerSystem_Range_1.1#api-changes-for-improved-performance-id-41178) | Skyline.DataMiner.Core.DataMinerSystem | API changes for improved performance cause some calls to no longer throw an ElementStoppedException but instead an ElementNotFoundException or no exception at all. |
 | [41059](xref:Web_apps_Feature_Release_10.4.12#monitoring-app-alarm-card-urls-now-also-contain-the-element-id-id-41059) | DataMiner 10.3.0 [CU21]/10.4.0 [CU9]/10.4.12 | From DataMiner 10.3.0 [CU21]/10.4.0 [CU9]/10.4.12 onwards, Monitoring app alarm card URLs will also contain the element ID. |
 | [40867](xref:General_Feature_Release_10.4.12#automation-subscriptoptionsskipstartedinfoevent-will-now-by-default-be-set-to-true-id-40867) | DataMiner 10.5.0/10.4.12 | SubScriptOptions.SkipStartedInfoEvent will now by default be set to true. |
 | [40372](xref:General_Feature_Release_10.4.11#gqi---get-alarms-data-source-updated-alarm-id-and-root-alarm-id-columns-id-40372) | DataMiner 10.5.0/10.4.11 | The *Alarm ID* and *Root Alarm ID* columns of the GQI data source *Get alarms* have been updated. |

release-notes/Code_Libraries/Skyline.DataMiner.Core/Skyline.DataMiner.Core.DataMinerSystem/Skyline_DataMiner_Core_DataMinerSystem_Range_1.1.md

@@ -7,6 +7,102 @@ uid: Skyline_DataMiner_Core_DataMinerSystem_Range_1.1
 > [!NOTE]
 > Range 1.1.x.x is supported as from **DataMiner 10.1.11**. It makes use of a change introduced in DataMiner 10.1.11 that makes it possible to obtain table cell data using the primary key. In earlier DataMiner versions, the display key was needed to obtain this data.
 
+### 1.1.2.1
+
+#### API changes for improved performance [ID 41178]
+
+Version 1.1.2.1 introduces changes (some of which are breaking) to the class library API to reduce the number of SLNet calls that are executed in the background.
+
+##### Extended IDms interface
+
+The IDms interface has been extended with additional methods for retrieving an object that represents an existing DataMiner object (without checking whether it actually exists):
+
+- IDma GetAgentReference(int agentId)
+- IDmsElement GetElementReference(DmsElementId dmsElementId)
+- IDmsView GetViewReference(int viewId)
+
+These methods can be used as an alternative to the *IDms.GetElement(DmsElementId)*, *IDms.GetView(int)*, and *IDms.GetAgent(int)* methods. The *IDms.GetElement(DmsElementId)*, *IDms.GetView(int)*, and *IDms.GetAgent(int)* methods will perform an SLNet call in the background to request info about the item. With the new *GetAgentReference*, *GetElementReference*, and *GetViewReference* methods, this additional SLNet call will only be called when information is requested. Therefore if you perform a set, e.g. a parameter set on an element, the *SetParameterMessage* SLNet call is performed in the background without having to request additional data from SLNet.
+
+However, note that if you request a reference to an object that does not exist in the system by providing an invalid ID, an exception will only be thrown when a call to the server is performed. If the *IDms.GetElement(DmsElementId)*, *IDms.GetView(int)* or *IDms.GetAgent(int)* method is used, an exception will already be thrown if the Agent does not exist when the method is executed.
+
+In summary, you can use these methods if you are sure the item exists, and these can result in improved performance because some additional SLNet calls can be avoided. If you do not know whether the item exists, you should use the *IDms.GetElement(DmsElementId)*, *IDms.GetView(int)*, or *IDms.GetAgent(int)* method instead.
+
+Behavior prior to this change:
+
+```csharp
+var dms = protocol.GetDms();
+var element = dms.GetElement(new DmsElementId(346, 100)); // Performs an SLNet call to obtain info about the element.
+var parameter = element.GetStandaloneParameter<double?>(10);
+parameter.SetValue(100); // Throws ElementStoppedException in case the State property of the ElementInfoEvent message obtained in the GetElement call indicates the element is stopped. In this case no server call is executed.
+```
+
+Behavior since this change:
+
+```csharp
+var dms = protocol.GetDms();
+var element = dms.GetElement(new DmsElementId(346, 100)); // Performs an SLNet call to obtain info about the element.
+var parameter = element.GetStandaloneParameter<double?>(10);
+parameter.SetValue(100); // Does not check State property of the ElementInfoEvent message obtained in the GetElement call indicates the element is stopped. Server call is executed.
+```
+
+Alternative to avoid additional SLNet call:
+
+```csharp
+var dms = protocol.GetDms();
+var element = dms.GetElementReference(new DmsElementId(346, 100)); // No SLNet call executed.
+var parameter = element.GetStandaloneParameter<double?>(10);
+parameter.SetValue(100); // Does not check State property of the ElementInfoEvent message obtained in the GetElement call indicates the element is stopped. Server call is executed.
+```
+
+##### Breaking changes
+
+Some breaking changes have been introduced in the API with regard to exceptions that are thrown because the *State* property for an element is no longer checked before a set is executed. This means that some calls no longer throw an ElementStoppedException but instead an ElementNotFoundException or no exception at all.
+
+To see if and when an exception is thrown, refer to the documentation on the methods in the API section (e.g. [GetElement](xref:Skyline.DataMiner.Core.DataMinerSystem.Common.IDma.GetElement*)).
+
+- IDmsElement.GetStandaloneParameter\<T\> no longer throws an ElementNotFoundException.
+- IDmsElement.GetTable no longer throws an ElementNotFoundException.
+- IDmsColumn.GetAlarmLevel no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsColumn.GetDisplayValue no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsColumn\<T\>.GetValue no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsColumn.Lookup no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsColumn\<T\>.SetValue no longer throws an exception.
+- IDmsStandaloneParameter.GetAlarmLevel no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsStandaloneParameter.GetDisplayValue no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsStandaloneParameter\<T\>.GetValue no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsStandaloneParameter\<T\>.SetValue no longer throws an exception.
+- IDmsTable.AddRow no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsTable.DeleteRow no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsTable.DeleteRows no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsTable.GetDisplayKey no longer throws an ElementStoppedException but instead will return null if the element is stopped.
+- IDmsTable.GetDisplayKeys no longer throws an ElementStoppedException but instead will return an empty set if the element is stopped.
+- IDmsTable.GetPrimaryKey no longer throws an ElementStoppedException but instead will return null if the element is stopped.
+- IDmsTable.GetPrimaryKeys no longer throws an ElementStoppedException but instead will return an empty set if the element is stopped.
+- IDmsTable.GetRow no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsTable.GetRows no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsTable.RowExists no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+- IDmsTable.SetRow no longer throws an ElementStoppedException but instead will throw an ElementNotFoundException if the element is stopped.
+
+##### Updated/changed SLNet calls
+
+Additionally, some changes have been made to the SLNet calls that are executed in the background:
+
+- When info for a single view is requested, the *GetInfo* message of type *ViewInfo* will now have the *viewId* mentioned in the *ExtraData* property of the SLNet call. If the request is sent to a DataMiner version that supports this (see [RN 41169](xref:General_Feature_Release_10.5.1#slnet-getinfo-messages-for-the-propertyconfiguration-and-viewinfo-types-now-support-retrieving-information-for-a-specific-item-id-41169)), DataMiner will only provide info in the response for that view instead of for all views.
+- When property configurations are requested, the *GetInfo* message of type *PropertyConfiguration* will now include the requested type (e.g. ELEMENT, SERVICE, or VIEW) so the response only includes the property configurations of the requested type.
+- The *ReferencedVersion* property of *IDmsProtocol* will now be obtained via a *GetInfo* SLNet call of type *Protocols* instead of a *GetProtocolMessage* call. Performance tests indicate that this is a less impacting call.
+
+Note that only in DataMiner versions where [RN 41169](xref:General_Feature_Release_10.5.1#slnet-getinfo-messages-for-the-propertyconfiguration-and-viewinfo-types-now-support-retrieving-information-for-a-specific-item-id-41169) is implemented, DataMiner will respond with only the requested information. If the request is made to an older DataMiner version, all info will be in the response. In that case, the class library will just filter out the needed info.
+
+### 1.1.1.13
+
+#### New feature - SendMessages method added to ICommunications interface
+
+The ICommunications interface has been extended with the following method:
+
+```csharp
+DMSMessage[] SendMessages(DMSMessage[] messages);
+```
+
 ### 1.1.1.12
 
 #### Fix - Breaking change reverted for InterAppCalls