v4.0.0 release preparations (#389)

* Update release notes * Move API changes to PublicAPI.Shipped.txt * Update version number * Bump Bootstrap version in template * Update simple MQTT tutorial * Update README.md
intelligentplant · Apr 17, 2024 · 00fce6c · 00fce6c
1 parent d1a5191
commit 00fce6c
Show file tree

Hide file tree

Showing 112 changed files with 687 additions and 84,903 deletions.
diff --git a/.gitignore b/.gitignore
@@ -31,6 +31,9 @@ bld/
 # Uncomment if you have tasks that create the project's static files in wwwroot
 #wwwroot/
 
+# Ignore libraries restored via LibMan
+wwwroot/lib
+
 # Visual Studio 2017 auto generated files
 Generated\ Files/
 

diff --git a/Directory.Build.props b/Directory.Build.props
@@ -27,7 +27,7 @@
     building via build.ps1 or build.sh. It is defined here to allow Visual Studio to build with 
     the solution with the correct version number.
     -->
-    <Version>4.0.0-pre.0</Version>
+    <Version>4.0.0</Version>
   </PropertyGroup>
 
   <Choose>

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 Industrial processes generate a variety of different types of data, such as real-time instrument readings, messages from alarm & event systems, and so on. Real-time data typically needs to be archived to a time-based data store for long-term storage, from where it can be visualized, aggregated, and monitored to ensure that the process remains healthy.
 
-Intelligent Plant's [Industrial App Store](https://appstore.intelligentplant.com) securely connects your industrial plant historian and alarm & event systems to apps using [App Store Connect](https://appstore.intelligentplant.com/Welcome/AppProfile?appId=a73c453df5f447a6aa8a08d2019037a5). App Store Connect comes with built-in drivers for many 3rd party systems (including OSIsoft PI and Asset Framework, OPC DA/HDA/AE, MQTT, and more). App Store Connect can also integrate with 3rd party systems using an adapter.
+Intelligent Plant's [Industrial App Store](https://appstore.intelligentplant.com) securely connects your industrial plant historian and alarm & event systems to apps using [App Store Connect](https://appstore.intelligentplant.com/Welcome/AppProfile?appId=a73c453df5f447a6aa8a08d2019037a5). App Store Connect comes with built-in drivers for many 3rd party systems (including AVEVA OSIsoft PI and Asset Framework, AVEVA Wonderware, Microsoft Azure IoT Hubs/Event Hubs, Modbus, MQTT, OPC UA, OPC Classic DA/HDA/AE, and more). App Store Connect can also integrate with 3rd party systems using an adapter.
 
 ## What is an Adapter?
 

diff --git a/build/version.json b/build/version.json
@@ -2,5 +2,5 @@
   "Major": 4,
   "Minor": 0,
   "Patch": 0,
-  "PreRelease": "pre"
+  "PreRelease": ""
 }
diff --git a/docs/release-notes/v4.0.0.md b/docs/release-notes/v4.0.0.md
@@ -2,6 +2,7 @@
 
 Welcome to version 4.0.0 of the adapter toolkit for App Store Connect!
 
+
 # Breaking Changes
 
 This release contains the following breaking changes:
@@ -35,6 +36,11 @@ The [TagValueBucket](../../src/DataCore.Adapter/RealTimeData/Utilities/TagValueB
 Custom aggregate functions registered with `AggregationHelper` may need to be rewritten to account for these changes.
 
 
+## `TagValueBuilder` changes
+
+The [TagValueBuilder](../../src/DataCore.Adapter/RealTimeData/TagValueBuilder.cs) class has been modified so that most methods for adding properties to a tag value have been moved to extension methods. No changes to source code are required, but code must be recompiled to prevent binary incompatibilities.
+
+
 ## Logging changes in `AdapterCore` and `AdapterBase<TOptions>`
 
 The [AdapterCore](../../src/DataCore.Adapter.Abstractions/AdapterCore.cs) base class now requires an `ILoggerFactory` constructor parameter instead of an `ILogger` parameter and its `Logger` property has been deprecated in favour of creating `ILogger` instances using the new `LoggerFactory` property instead.
@@ -105,11 +111,18 @@ The adapter host template project now sets the ID of the hosted adapter to `$def
 Additionally, the identifier that the adapter host uses in its OpenTelemetry traces is now set via the project's `appsettings.json` file (or any other configuration source that the project uses). This allows for tracing systems such as Jaeger to distinguish between multiple instances of an adapter host.
 
 
+## Full gRPC support on .NET Framework on Windows 11
+
+The gRPC implementation used in the gRPC Proxy Adapter on .NET Framework relies on the HTTP/2 implementation supplied by the underlying WinHTTP library. Prior to Windows 11, gRPC clients on .NET Framework did not support client- or bidirectional streaming. Adapter host methods such as snapshot tag value subscriptions rely on being able to add tags to and remove tags from active subscriptions, which uses bidirectional streaming in the gRPC interface implementation. On .NET Framework, clients worked around this limitation by making separate subscription calls for each tag. In version 4.0, the gRPC adapter proxy now detects the underlying Windows version when it is running on .NET Framework and will use bidirectional streaming if it is supported by the OS.
+
+Note that Windows Server 2019 and Windows Server 2022 do not have full gRPC support at this time.
+
+
 # Upgrading from v3.0.0 to 4.0.0
 
 To upgrade from v3.0.0 to v4.0.0, you need to update your adapter toolkit package references to version 4.0.0.
 
-Your adapter implementations should be updated to use the `AdapterBase<TOptions>` constructors that accept an `ILoggerFactory` instead of an `ILogger`.
+Your adapter implementations should be updated to use the `AdapterBase<TOptions>` constructors that accept an `ILoggerFactory` instead of an `ILogger`. The constructors that use `ILogger` will be removed in version 5.
 
 When constructing adapter feature helper classes, use the `LoggerFactory` property inherited from `AdapterCore` to create strongly-typed `ILogger<T>` instances for the helper.
 

diff --git a/docs/tutorials/mqtt-adapter/README.md b/docs/tutorials/mqtt-adapter/README.md
@@ -31,7 +31,7 @@ Click `Next` to configure the project settings:
 
 ![Visual Studio template parameters window](../../../src/DataCore.Adapter.Templates/img/template_parameters.png)
 
-You can choose to target .NET 8 or .NET 6 (the current and previous long-term support version respectively at time of writing). You can accept the default values for the other settings; they can be changed in code later if desired.
+Choose .NET 8 as the target version (the current long-term support version of .NET at time of writing). You can accept the default values for the other settings; they can be changed in code later if desired.
 
 Click `Create` to create the project.
 
@@ -59,7 +59,7 @@ Click "Create" to create the data source. You will be taken to the data source's
 
 # Add Required Package References
 
-Add a NuGet package reference to [MQTTnet.Extensions.ManagedClient @ v4.1.4.563](https://www.nuget.org/packages/MQTTnet.Extensions.ManagedClient/4.1.4.563) to the adapter project. You can reference a more recent version of this package if preferred, but you may have to tweak some of the remaining steps if a newer version contains any breaking changes.
+Add a NuGet package reference to [MQTTnet.Extensions.ManagedClient @ v4.3.3.952](https://www.nuget.org/packages/MQTTnet.Extensions.ManagedClient/4.3.3.952) to the adapter project. You can reference a more recent version of this package if preferred, but you may have to tweak some of the remaining steps if a newer version contains any breaking changes.
 
 
 # Update the Adapter Options Class
@@ -275,7 +275,7 @@ namespace MqttAdapter {
                 LogInitialisingClient();
             }
             else {
-                LogReinitialisingClient;
+                LogReinitialisingClient();
             }
 
             _mqttClient = _factory.CreateManagedMqttClient();

diff --git a/examples/ExampleHostedAdapter/Pages/Shared/_Layout.cshtml b/examples/ExampleHostedAdapter/Pages/Shared/_Layout.cshtml
@@ -1,81 +1,81 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>@ViewData["Title"] - App Store Connect Adapter Host</title>
-    <link rel="stylesheet" href="~/lib/bootstrap/css/bootstrap.min.css" />
-    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
-    <link rel="stylesheet" href="~/ExampleHostedAdapter.styles.css" asp-append-version="true" />
-    <script defer src="~/lib/font-awesome/js/all.min.js" data-auto-replace-svg="nest"></script>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>@ViewData["Title"] - App Store Connect Adapter Host</title>
+  <link rel="stylesheet" href="~/lib/bootstrap/css/bootstrap.min.css" />
+  <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
+  <link rel="stylesheet" href="~/ExampleHostedAdapter.styles.css" asp-append-version="true" />
+  <script defer src="~/lib/font-awesome/js/all.min.js" data-auto-replace-svg="nest"></script>
 </head>
 <body>
-    <header>
-        <nav class="navbar navbar-expand-sm navbar-toggleable-sm border-bottom box-shadow mb-3">
-            <div class="container-fluid">
-                <a class="navbar-brand" asp-area="" asp-page="/Index">ASC Adapter Host</a>
-                <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target=".navbar-collapse" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
-                    <span class="navbar-toggler-icon"></span>
-                </button>
-                <div class="navbar-collapse collapse d-sm-inline-flex justify-content-between">
-                    <ul class="navbar-nav d-flex">
-                        <li class="nav-item">
-                            <a class="nav-link" asp-area="" asp-page="/Index" title="Home">
-                              <i class="fa-solid fa-house fa-fw"></i>
-                              Home
-                            </a>
-                        </li>
-                        <li class="nav-item">
-                            <a class="nav-link" asp-area="" asp-page="/Settings" title="Modify adapter settings">
-                              <i class="fa-solid fa-gears fa-fw"></i>
-                              Settings
-                            </a>
-                        </li>
-                    </ul>
-                    <ul class="navbar-nav d-flex">
-                        <li class="nav-item dropdown">
-                            <button class="btn btn-link nav-link dropdown-toggle" id="theme-toggle" type="button" aria-expanded="false" data-bs-toggle="dropdown" title="Select theme">
-                                <i class="fa-solid fa-circle-half-stroke fa-fw"></i>
-                            </button>
-                            <ul class="dropdown-menu dropdown-menu-end" aria-labelledby="theme-toggle">
-                                <li>
-                                  <button type="button" class="dropdown-item d-flex align-items-center" data-bs-theme-value="light" title="Light mode">
-                                    <i class="fa-solid fa-sun fa-fw me-2"></i>
-                                    Light
-                                    <i class="fa-solid fa-check fa-fw ms-auto d-none" data-active-indicator></i>
-                                  </button>
-                                </li>
-                                <li>
-                                  <button type="button" class="dropdown-item d-flex align-items-center" data-bs-theme-value="dark" title="Dark mode">
-                                    <i class="fa-solid fa-moon fa-fw me-2"></i>
-                                    Dark
-                                    <i class="fa-solid fa-check fa-fw ms-auto d-none" data-active-indicator></i>
-                                  </button>
-                                </li>
-                                <li>
-                                  <button type="button" class="dropdown-item d-flex align-items-center" data-bs-theme-value="auto" title="Use system theme">
-                                    <i class="fa-solid fa-circle-half-stroke fa-fw me-2"></i>
-                                    Auto
-                                    <i class="fa-solid fa-check fa-fw ms-auto d-none" data-active-indicator></i>
-                                  </button>
-                                </li>
-                            </ul>
-                        </li>
-                    </ul>
-                </div>
-            </div>
-        </nav>
-    </header>
-    <div class="container-fluid">
-        <main role="main" class="pb-3">
-            @RenderBody()
-        </main>
-    </div>
+  <header>
+    <nav class="navbar navbar-expand-sm navbar-toggleable-sm border-bottom box-shadow mb-3">
+      <div class="container-fluid">
+        <a class="navbar-brand" asp-area="" asp-page="/Index">ASC Adapter Host</a>
+        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target=".navbar-collapse" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
+          <span class="navbar-toggler-icon"></span>
+        </button>
+        <div class="navbar-collapse collapse d-sm-inline-flex justify-content-between">
+          <ul class="navbar-nav d-flex">
+            <li class="nav-item">
+              <a class="nav-link" asp-area="" asp-page="/Index" title="Home">
+                <i class="fa-solid fa-house fa-fw"></i>
+                Home
+              </a>
+            </li>
+            <li class="nav-item">
+              <a class="nav-link" asp-area="" asp-page="/Settings" title="Modify adapter settings">
+                <i class="fa-solid fa-gears fa-fw"></i>
+                Settings
+              </a>
+            </li>
+          </ul>
+          <ul class="navbar-nav d-flex">
+            <li class="nav-item dropdown">
+              <button class="btn btn-link nav-link dropdown-toggle" id="theme-toggle" type="button" aria-expanded="false" data-bs-toggle="dropdown" title="Select theme">
+                <i class="fa-solid fa-circle-half-stroke fa-fw"></i>
+              </button>
+              <ul class="dropdown-menu dropdown-menu-end" aria-labelledby="theme-toggle">
+                <li>
+                  <button type="button" class="dropdown-item d-flex align-items-center" data-bs-theme-value="light" title="Light mode">
+                    <i class="fa-solid fa-sun fa-fw me-2"></i>
+                    Light
+                    <i class="fa-solid fa-check fa-fw ms-auto d-none" data-active-indicator></i>
+                  </button>
+                </li>
+                <li>
+                  <button type="button" class="dropdown-item d-flex align-items-center" data-bs-theme-value="dark" title="Dark mode">
+                    <i class="fa-solid fa-moon fa-fw me-2"></i>
+                    Dark
+                    <i class="fa-solid fa-check fa-fw ms-auto d-none" data-active-indicator></i>
+                  </button>
+                </li>
+                <li>
+                  <button type="button" class="dropdown-item d-flex align-items-center" data-bs-theme-value="auto" title="Use system theme">
+                    <i class="fa-solid fa-circle-half-stroke fa-fw me-2"></i>
+                    Auto
+                    <i class="fa-solid fa-check fa-fw ms-auto d-none" data-active-indicator></i>
+                  </button>
+                </li>
+              </ul>
+            </li>
+          </ul>
+        </div>
+      </div>
+    </nav>
+  </header>
+  <div class="container-fluid">
+    <main role="main" class="pb-3">
+      @RenderBody()
+    </main>
+  </div>
 
-    <script src="~/lib/jquery/jquery.min.js"></script>
-    <script src="~/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
-    <script src="~/js/site.js" asp-append-version="true"></script>
+  <script src="~/lib/jquery/jquery.min.js"></script>
+  <script src="~/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
+  <script src="~/js/site.js" asp-append-version="true"></script>
 
-    @await RenderSectionAsync("Scripts", required: false)
+  @await RenderSectionAsync("Scripts", required: false)
 </body>
 </html>
diff --git a/examples/ExampleHostedAdapter/libman.json b/examples/ExampleHostedAdapter/libman.json
@@ -5,7 +5,7 @@
 
     {
       "provider": "cdnjs",
-      "library": "[email protected].2",
+      "library": "[email protected].3",
       "destination": "wwwroot/lib/bootstrap/",
       "files": [
         "js/*",

diff --git a/examples/SimpleMqttExample/MqttAdapter/Constants.cs b/examples/SimpleMqttExample/MqttAdapter/Constants.cs
@@ -12,7 +12,7 @@ internal static class Constants {
         ///   The adapter ID is used in all API calls made to the adapter host. If you change the 
         ///   value here, remember to change it in App Store Connect as well!
         /// </remarks>
-        public const string AdapterId = "3a7a9d24-8211-45bc-8241-45472dcaca95";
+        public const string AdapterId = "$default";
 
         /// <summary>
         /// The path to the adapter settings JSON file.

diff --git a/examples/SimpleMqttExample/MqttAdapter/MqttAdapter.csproj b/examples/SimpleMqttExample/MqttAdapter/MqttAdapter.csproj
@@ -10,20 +10,25 @@
     <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter" Version="4.0.0" />
     <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter.AspNetCore.Grpc" Version="4.0.0" />
     <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter.AspNetCore.HealthChecks" Version="4.0.0" />
-    <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter.AspNetCore.Mvc" Version="4.0.0" />
+    <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter.AspNetCore.MinimalApi" Version="4.0.0" />
     <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter.AspNetCore.SignalR" Version="4.0.0" />
     <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter.KeyValueStore.Sqlite" Version="4.0.0" />
     <PackageReference Include="IntelligentPlant.AppStoreConnect.Adapter.OpenTelemetry" Version="4.0.0" />
     <PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="2.1.175" />
-    <PackageReference Include="MQTTnet.Extensions.ManagedClient" Version="4.1.4.563" />
-    <PackageReference Include="OpenTelemetry" Version="1.7.0" />
-    <PackageReference Include="OpenTelemetry.Api" Version="1.7.0" />
-    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.7.0" />
-    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.7.0" />
-    <PackageReference Include="OpenTelemetry.Exporter.Prometheus.AspNetCore" Version="1.7.0-rc.1" />
-    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.7.0" />
-    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.7.0" />
-    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.7.0" />
+    <PackageReference Include="MQTTnet.Extensions.ManagedClient" Version="4.3.3.952" />
+    <PackageReference Include="OpenTelemetry" Version="1.8.0" />
+    <PackageReference Include="OpenTelemetry.Api" Version="1.8.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.8.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.8.0" />
+    <PackageReference Include="OpenTelemetry.Exporter.Prometheus.AspNetCore" Version="1.8.0-rc.1" />
+    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.8.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.8.1" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.GrpcNetClient" Version="1.8.0-beta.1" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.8.1" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.8.0" />
+    <PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" Version="1.8.0-beta.1" />
+    <PackageReference Include="Serilog.AspNetCore" Version="8.0.1" />
+    <PackageReference Include="Serilog.Expressions" Version="4.0.0" />
   </ItemGroup>
 
 </Project>
diff --git a/examples/SimpleMqttExample/MqttAdapter/MyAdapter.cs b/examples/SimpleMqttExample/MqttAdapter/MyAdapter.cs
@@ -146,7 +146,7 @@ private async Task InitMqttClientAsync(CancellationToken cancellationToken) {
                 LogInitialisingClient();
             }
             else {
-                LogReinitialisingClient;
+                LogReinitialisingClient();
             }
 
             _mqttClient = _factory.CreateManagedMqttClient();