API to configure object or object types as writer (#2320)

* Fix file system bug on linux * Update dependencies * Documentation updates
Azure · Aug 19, 2024 · 8d87129 · 8d87129
1 parent 54ed422
commit 8d87129
Show file tree

Hide file tree

Showing 97 changed files with 6,093 additions and 1,500 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -489,6 +489,7 @@ csharp_style_allow_blank_line_after_token_in_conditional_expression_experimental
 csharp_style_allow_blank_line_after_token_in_arrow_expression_clause_experimental = true:silent
 dotnet_diagnostic.RCS1055.severity = suggestion
 dotnet_diagnostic.RCS1039.severity = suggestion
+csharp_prefer_static_anonymous_function = true:suggestion
 
 [*.{cs,vb}]
 dotnet_style_coalesce_expression = true:silent
@@ -500,6 +501,8 @@ tab_width = 4
 indent_size = 4
 end_of_line = crlf
 dotnet_style_object_initializer = true:suggestion
+dotnet_style_namespace_match_folder = false:silent
+
 dotnet_diagnostic.CA2007.severity = warning
 dotnet_diagnostic.CA1848.severity = silent
 dotnet_diagnostic.CA1036.severity = suggestion
@@ -524,6 +527,8 @@ dotnet_style_prefer_conditional_expression_over_assignment = true:silent
 
 # IDE0270: Use coalesce expression
 dotnet_diagnostic.IDE0270.severity = silent
+# IDE0130: Namespace does not correspond to file location
+dotnet_diagnostic.IDE0130.severity = silent
 dotnet_diagnostic.CA1031.severity = silent
 dotnet_style_prefer_conditional_expression_over_return = true:silent
 dotnet_style_explicit_tuple_names = true:suggestion

diff --git a/.github/workflows/dotnet.yml b/.github/workflows/dotnet.yml
@@ -1,33 +1,26 @@
 name: Build Solutions
-
 on:
   push:
-    branches:
-      - main
+    branches: [ "main" ]
   pull_request:
-    branches:
-      - main
-
+    branches: [ "main" ]
 jobs:
   build:
     runs-on: ubuntu-latest
-
     strategy:
       matrix:
-        solution: 
+        solution:
           - '**/*.sln'
-
     steps:
     - name: Checkout repository
       uses: actions/checkout@v2
-
+      with:
+        fetch-depth: 0
     - name: Setup .NET
       uses: actions/setup-dotnet@v3
       with:
-        dotnet-version: '8.x'
-
+        dotnet-version: 8.0.x
     - name: Restore dependencies
       run: dotnet restore ${{ matrix.solution }}
-
     - name: Build
       run: dotnet build ${{ matrix.solution }} --configuration Release --no-restore
diff --git a/common.props b/common.props
@@ -34,7 +34,7 @@
   </PropertyGroup>
   <ItemGroup Condition="$(NO_GIT) == ''">
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>
-    <PackageReference Include="Nerdbank.GitVersioning" Version="3.6.139" PrivateAssets="All"/>
+    <PackageReference Include="Nerdbank.GitVersioning" Version="3.6.141" PrivateAssets="All"/>
   </ItemGroup>
   <PropertyGroup>
     <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>

diff --git a/docs/opc-publisher/api.md b/docs/opc-publisher/api.md
@@ -3329,6 +3329,47 @@ This section contains the API to configure data set writers and writer
             name.
 
 
+<a name="expandandcreateorupdatedatasetwriterentries"></a>
+#### ExpandAndCreateOrUpdateDataSetWriterEntries
+```
+POST /v2/writer
+```
+
+
+##### Description
+Create a series of published nodes entries using the provided entry as template. The entry is expanded using expansion configuration provided. Expanded entries are returned one by one with error information if any. The configuration is also saved in the local configuration store. The server must be online and accessible for the expansion to work.
+
+
+##### Parameters
+
+|Type|Name|Description|Schema|
+|---|---|---|---|
+|**Body**|**body**  <br>*required*|The entry to create for the writer and node expansion configuration to use|[PublishedNodeExpansionModelPublishedNodesEntryRequestModel](definitions.md#publishednodeexpansionmodelpublishednodesentryrequestmodel)|
+
+
+##### Responses
+
+|HTTP Code|Description|Schema|
+|---|---|---|
+|**200**|The item was created|[PublishedNodesEntryModelServiceResponseIAsyncEnumerable](definitions.md#publishednodesentrymodelserviceresponseiasyncenumerable)|
+|**400**|The passed in information is invalid|[ProblemDetails](definitions.md#problemdetails)|
+|**403**|A unique item could not be found to update.|[ProblemDetails](definitions.md#problemdetails)|
+|**408**|The operation timed out.|[ProblemDetails](definitions.md#problemdetails)|
+|**500**|An unexpected error occurred|[ProblemDetails](definitions.md#problemdetails)|
+
+
+##### Consumes
+
+* `application/json`
+* `application/x-msgpack`
+
+
+##### Produces
+
+* `application/json`
+* `application/x-msgpack`
+
+
 <a name="createorupdatedatasetwriterentry"></a>
 #### CreateOrUpdateDataSetWriterEntry
 ```
@@ -3337,7 +3378,7 @@ PUT /v2/writer
 
 
 ##### Description
-Create a published nodes entry for a specific writer group and dataset writer. The entry must specify a unique writer group and dataset writer id. A null value is treated as empty string. If the entry is found it is updated, if it is not found, it is created. If more than one entry is found with the same writer group and writer id an error is returned. The writer entry provided must include at least one node which will be the initial set. All nodes must specify a unique dataSetFieldId. A null value is treated as empty string. Publishing intervals at node level are also not supported and generate an error. Publishing intervals must be configured at the data set writer level.
+Create a published nodes entry for a specific writer group and dataset writer. The entry must specify a unique writer group and dataset writer id. A null value is treated as empty string. If the entry is found it is replaced, if it is not found, it is created. If more than one entry is found with the same writer group and writer id an error is returned. The writer entry provided must include at least one node which will be the initial set. All nodes must specify a unique dataSetFieldId. A null value is treated as empty string. Publishing intervals at node level are also not supported and generate an error. Publishing intervals must be configured at the data set writer level.
 
 
 ##### Parameters
@@ -3368,6 +3409,47 @@ Create a published nodes entry for a specific writer group and dataset writer. T
 * `application/x-msgpack`
 
 
+<a name="expandwriter"></a>
+#### ExpandWriter
+```
+POST /v2/writer/expand
+```
+
+
+##### Description
+Expands the provided nodes in the entry to a series of published node entries. The provided entry is used template. The entry is expanded using expansion configuration provided. Expanded entries are returned one by one with error information if any. The configuration is not updated but the resulting entries can be modified and later saved in the configuration using the configuration API. The server must be online and accessible for the expansion to work.
+
+
+##### Parameters
+
+|Type|Name|Description|Schema|
+|---|---|---|---|
+|**Body**|**body**  <br>*required*|The entry to expand and the node expansion configuration to use. If no configuration is provided a default configuration is used which and no error entries are returned.|[PublishedNodeExpansionModelPublishedNodesEntryRequestModel](definitions.md#publishednodeexpansionmodelpublishednodesentryrequestmodel)|
+
+
+##### Responses
+
+|HTTP Code|Description|Schema|
+|---|---|---|
+|**200**|The item was created|[PublishedNodesEntryModelServiceResponseIAsyncEnumerable](definitions.md#publishednodesentrymodelserviceresponseiasyncenumerable)|
+|**400**|The passed in information is invalid|[ProblemDetails](definitions.md#problemdetails)|
+|**403**|A unique item could not be found to update.|[ProblemDetails](definitions.md#problemdetails)|
+|**408**|The operation timed out.|[ProblemDetails](definitions.md#problemdetails)|
+|**500**|An unexpected error occurred|[ProblemDetails](definitions.md#problemdetails)|
+
+
+##### Consumes
+
+* `application/json`
+* `application/x-msgpack`
+
+
+##### Produces
+
+* `application/json`
+* `application/x-msgpack`
+
+
 <a name="getdatasetwriterentry"></a>
 #### GetDataSetWriterEntry
 ```

diff --git a/docs/opc-publisher/commandline.md b/docs/opc-publisher/commandline.md
@@ -19,7 +19,7 @@ Secrets such as `EdgeHubConnectionString`, other connection strings, or the `Api
 ██║   ██║██╔═══╝ ██║         ██╔═══╝ ██║   ██║██╔══██╗██║     ██║╚════██║██╔══██║██╔══╝  ██╔══██╗
 ╚██████╔╝██║     ╚██████╗    ██║     ╚██████╔╝██████╔╝███████╗██║███████║██║  ██║███████╗██║  ██║
  ╚═════╝ ╚═╝      ╚═════╝    ╚═╝      ╚═════╝ ╚═════╝ ╚══════╝╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
-                                                 2.9.11 (.NET 8.0.7/win-x64/OPC Stack 1.5.374.78)
+                                                 2.9.12 (.NET 8.0.8/win-x64/OPC Stack 1.5.374.78)
 General
 -------
 

diff --git a/docs/opc-publisher/definitions.md b/docs/opc-publisher/definitions.md
@@ -1674,6 +1674,56 @@ A monitored and published item
 |**samplingInterval**  <br>*optional*|Sampling interval to use|string (date-span)|
 
 
+<a name="publishednodeexpansionmodel"></a>
+### PublishedNodeExpansionModel
+Node expansion configuration. Configures how an entry should
+            be expanded into configuration. If a node is an object it is
+            expanded to all contained variables.
+
+
+
+            If a node is an object type, all objects of that type are
+            searched from the object root node. These found objects are
+            then expanded into their variables.
+            
+
+
+            If the node is a variable, the variable is expanded to include
+            all contained variables or properties. All entries will have
+            the data set field id configured as data set class id.
+            
+
+
+            If a node is a variable type, then all variables of this type
+            are found and added to a single writer entry. Note: That by
+            themselves these variables are no further expanded.
+
+
+|Name|Description|Schema|
+|---|---|---|
+|**createSingleWriter**  <br>*optional*|By default the api will create a new distinct<br>writer per expanded object. Objects that cannot<br>be expanded are part of the originally provided<br>writer. The writer id is then post fixed with<br>the data set field id of the object node field.<br>If true, all variables of all expanded nodes are<br>added to the originally provided entry.|boolean|
+|**discardErrors**  <br>*optional*|Errors are silently discarded and only<br>successfully expanded nodes are returned.|boolean|
+|**excludeRootIfInstanceNode**  <br>*optional*|If the node is an object or variable instance do<br>not include it but only the instances underneath<br>them.|boolean|
+|**header**  <br>*optional*||[RequestHeaderModel](definitions.md#requestheadermodel)|
+|**maxDepth**  <br>*optional*|Max browse depth for object search operation or<br>when searching for an instance of a type.<br>To only expand an object to its variables set<br>this value to 0. The depth of expansion of a<br>variable itself can be controlled via the<br>Azure.IIoT.OpcUa.Publisher.Models.PublishedNodeExpansionModel.MaxLevelsToExpand" property.<br>If the root object is excluded a value of 0 is<br>equivalent to a value of 1 to get the first level<br>of objects contained in the object but not the<br>object itself, e.g. a folder object.|integer (int64)|
+|**maxLevelsToExpand**  <br>*optional*|Max number of levels to expand an instance node<br>such as an object or variable into resulting<br>variables.<br>If the node is a variable instance to start with<br>but the Azure.IIoT.OpcUa.Publisher.Models.PublishedNodeExpansionModel.ExcludeRootIfInstanceNode<br>property is set to excluded it, then setting this<br>value to 0 is equivalent to a value of 1 to get<br>the first level of variables contained in the<br>variable, but not the variable itself. Otherwise<br>only the variable itelf is returned. If the node<br>is an object instance, 0 is equivalent to<br>infinite and all levels are expanded.|integer (int64)|
+|**noSubTypesOfTypeNodes**  <br>*optional*|Do not consider subtypes of an object type when<br>searching for instances of the type.|boolean|
+|**stopAtFirstFoundInstance**  <br>*optional*|If the depth is not limited and the node is a<br>type definition id set this flag to true to find<br>only the first instance of this type from the<br>object root.|boolean|
+
+
+<a name="publishednodeexpansionmodelpublishednodesentryrequestmodel"></a>
+### PublishedNodeExpansionModelPublishedNodesEntryRequestModel
+Wraps a request and a published nodes entry to bind to a
+body more easily for api that requires an entry and additional
+configuration
+
+
+|Name|Schema|
+|---|---|
+|**entry**  <br>*required*|[PublishedNodesEntryModel](definitions.md#publishednodesentrymodel)|
+|**request**  <br>*optional*|[PublishedNodeExpansionModel](definitions.md#publishednodeexpansionmodel)|
+
+
 <a name="publishednodesentrymodel"></a>
 ### PublishedNodesEntryModel
 Contains the nodes which should be published
@@ -1698,6 +1748,9 @@ Contains the nodes which should be published
 |**DataSetWriterGroup**  <br>*optional*|The Group the writer belongs to.|string|
 |**DataSetWriterId**  <br>*optional*|Name of the data set writer.|string|
 |**DataSetWriterWatchdogBehavior**  <br>*optional*||[SubscriptionWatchdogBehavior](definitions.md#subscriptionwatchdogbehavior)|
+|**DefaultHeartbeatBehavior**  <br>*optional*||[HeartbeatBehavior](definitions.md#heartbeatbehavior)|
+|**DefaultHeartbeatInterval**  <br>*optional*|Default heartbeat interval in milliseconds|integer (int32)|
+|**DefaultHeartbeatIntervalTimespan**  <br>*optional*|Default heartbeat interval for all nodes as duration. Takes<br>precedence over Azure.IIoT.OpcUa.Publisher.Models.PublishedNodesEntryModel.DefaultHeartbeatInterval if<br>defined.|string (date-span)|
 |**DisableSubscriptionTransfer**  <br>*optional*|Disable subscription transfer on reconnect|boolean|
 |**DumpConnectionDiagnostics**  <br>*optional*|Dump server diagnostics for the connection to enable<br>advanced troubleshooting scenarios.|boolean|
 |**EncryptedAuthPassword**  <br>*optional*|encrypted password|string|
@@ -1724,6 +1777,7 @@ Contains the nodes which should be published
 |**Priority**  <br>*optional*|Priority of the writer subscription.|integer (int32)|
 |**QualityOfService**  <br>*optional*||[QoS](definitions.md#qos)|
 |**QueueName**  <br>*optional*|Writer queue overrides the writer group queue name.<br>Network messages are then split across queues with<br>Qos also accounted for.|string|
+|**RepublishAfterTransfer**  <br>*optional*|Republish after transferring the subscription during<br>reconnect handling unless subscription transfer was disabled.|boolean|
 |**SendKeepAliveDataSetMessages**  <br>*optional*|Send a keep alive message when a subscription keep<br>alive notification is received inside the writer. If keep<br>alive messages are not supported by the messaging<br>profile chosen this value is ignored.|boolean|
 |**UseReverseConnect**  <br>*optional*|Use reverse connect to connect ot the endpoint|boolean|
 |**UseSecurity**  <br>*optional*|Secure transport should be used to connect to<br>the opc server.|boolean|
@@ -1734,7 +1788,11 @@ Contains the nodes which should be published
 |**WriterGroupQualityOfService**  <br>*optional*||[QoS](definitions.md#qos)|
 |**WriterGroupQueueName**  <br>*optional*|Writer group queue overrides the default writer group<br>topic template to use.|string|
 |**WriterGroupTransport**  <br>*optional*||[WriterGroupTransport](definitions.md#writergrouptransport)|
-|**republishAfterTransfer**  <br>*optional*|Republish after transferring the subscription during<br>reconnect handling unless subscription transfer was disabled.|boolean|
+
+
+<a name="publishednodesentrymodelserviceresponseiasyncenumerable"></a>
+### PublishedNodesEntryModelServiceResponseIAsyncEnumerable
+*Type* : object
 
 
 <a name="publishednodesresponsemodel"></a>