feat(api): Add GetDeviceAsync API and testing

Author: rlabbeptc

Kepware.Api.Test/ApiClient/ProjectApiHandlerTests.cs

@@ -105,7 +105,7 @@ public async Task GetChannelAsync_ShouldReturnChannel_WhenChannelExists()
         }
 
         [Fact]
-        public async Task GetChannelAsync_ShouldCreateChannel_WhenChannelDoesNotExist()
+        public async Task GetChannelAsync_ShouldReturnNull_WhenChannelDoesNotExist()
         {
             // Arrange
             await ConfigureToServeDrivers();
@@ -233,6 +233,57 @@ public async Task GetOrCreateDeviceAsync_ShouldCreateDevice_WhenDeviceDoesNotExi
             Assert.Equal(deviceName, result.Name);
         }
 
+        [Fact]
+        public async Task GetDeviceAsync_ShouldReturnDevice_WhenDeviceExists()
+        {
+            // Arrange
+            await ConfigureToServeDrivers();
+            var channel = new Channel { Name = "ExistingChannel" };
+            var deviceName = "ExistingDevice";
+            var deviceJson = """
+                {
+                    "PROJECT_ID": 676550906,
+                    "common.ALLTYPES_NAME": "ExistingDevice",
+                    "common.ALLTYPES_DESCRIPTION": "Example Device",
+                    "servermain.DEVICE_CHANNEL_ASSIGNMENT": "ExistingChannel"
+                }
+                """;
+
+            _httpMessageHandlerMock.SetupRequest(HttpMethod.Get, TEST_ENDPOINT + $"/config/v1/project/channels/{channel.Name}/devices/{deviceName}")
+                                   .ReturnsResponse(deviceJson, "application/json");
+
+            _httpMessageHandlerMock.SetupRequest(HttpMethod.Get, TEST_ENDPOINT + $"/config/v1/project/channels/{channel.Name}/devices/{deviceName}/tags")
+                                .ReturnsResponse("[]", "application/json");
+
+            _httpMessageHandlerMock.SetupRequest(HttpMethod.Get, TEST_ENDPOINT + $"/config/v1/project/channels/{channel.Name}/devices/{deviceName}/tag_groups")
+                                .ReturnsResponse("[]", "application/json");
+
+            // Act
+            var result = await _projectApiHandler.Devices.GetDeviceAsync(channel, deviceName);
+
+            // Assert
+            Assert.NotNull(result);
+            Assert.Equal(deviceName, result.Name);
+        }
+
+        [Fact]
+        public async Task GetDeviceAsync_ShouldReturnNull_WhenDeviceDoesNotExist()
+        {
+            // Arrange
+            await ConfigureToServeDrivers();
+            var channel = new Channel { Name = "ExistingChannel", DeviceDriver = "Simulator" };
+            var deviceName = "NewDevice";
+
+            _httpMessageHandlerMock.SetupRequest(HttpMethod.Get, TEST_ENDPOINT + $"/config/v1/project/channels/{channel.Name}/devices/{deviceName}")
+                                   .ReturnsResponse(HttpStatusCode.NotFound);
+
+            // Act
+            var result = await _projectApiHandler.Devices.GetDeviceAsync(channel, deviceName);
+
+            // Assert
+            Assert.Null(result);
+        }
+
         [Fact]
         public async Task UpdateDeviceAsync_ShouldReturnTrue_WhenUpdateIsSuccessful()
         {

Kepware.Api.TestIntg/ApiClient/ProjectApiHandlerTests.cs

@@ -75,7 +75,7 @@ public async Task GetChannelAsync_ShouldReturnChannel_WhenChannelExists()
         }
 
         [Fact]
-        public async Task GetChannelAsync_ShouldCreateChannel_WhenChannelDoesNotExist()
+        public async Task GetChannelAsync_ShouldReturnNull_WhenChannelDoesNotExist()
         {
             // Arrange
             var channel = CreateTestChannel();
@@ -163,6 +163,41 @@ public async Task GetOrCreateDeviceAsync_ShouldCreateDevice_WhenDeviceDoesNotExi
             await DeleteAllChannelsAsync();
         }
 
+        [Fact]
+        public async Task GetDeviceAsync_ShouldReturnDevice_WhenDeviceExists()
+        {
+            // Arrange
+            var channel = await AddTestChannel();
+            var device = await AddTestDevice(channel);
+
+            // Act
+            var result = await _projectApiHandler.Devices.GetDeviceAsync(channel, device.Name);
+
+            // Assert
+            Assert.NotNull(result);
+            Assert.Equal(device.Name, result.Name);
+
+            // Clean up
+            await DeleteAllChannelsAsync();
+        }
+
+        [Fact]
+        public async Task GetDeviceAsync_ShouldReturnNull_WhenDeviceDoesNotExist()
+        {
+            // Arrange
+            var channel = await AddTestChannel();
+            var device = CreateTestDevice(channel);
+
+            // Act
+            var result = await _projectApiHandler.Devices.GetDeviceAsync(channel, device.Name);
+
+            // Assert
+            Assert.Null(result);
+
+            // Clean up
+            await DeleteAllChannelsAsync();
+        }
+
         [Fact]
         public async Task UpdateDeviceAsync_ShouldReturnTrue_WhenUpdateIsSuccessful()
         {

Kepware.Api/ClientHandler/DeviceApiHandler.cs

@@ -90,6 +90,41 @@ public async Task<Device> GetOrCreateDeviceAsync(Channel channel, string name, s
         }
         #endregion
 
+        #region GetDeviceAsync
+        /// <summary>
+        /// Gets or creates a device with the specified name and driver in the specified channel.
+        /// </summary>
+        /// <param name="channel">The channel to which the device belongs.</param>
+        /// <param name="name">The name of the device.</param>
+        /// <param name="cancellationToken">The cancellation token.</param>
+        /// <returns>A task that represents the asynchronous operation. The task result contains the loaded <see cref="Device"/> or null if it does not exist.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when the channel is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when the device name is null or empty.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when the device cannot be created or loaded.</exception>
+        public async Task<Device?> GetDeviceAsync(Channel channel, string name, CancellationToken cancellationToken = default)
+        {
+            if (channel == null)
+                throw new ArgumentNullException(nameof(channel));
+            if (string.IsNullOrEmpty(name))
+                throw new ArgumentException("Device name cannot be null or empty", nameof(name));
+
+            var device = await m_kepwareApiClient.GenericConfig.LoadEntityAsync<Device>(name, channel, cancellationToken: cancellationToken);
+
+            if (device != null)
+            {
+                device.Tags = await m_kepwareApiClient.GenericConfig.LoadCollectionAsync<DeviceTagCollection, Tag>(device, cancellationToken: cancellationToken).ConfigureAwait(false);
+                device.TagGroups = await m_kepwareApiClient.GenericConfig.LoadCollectionAsync<DeviceTagGroupCollection, DeviceTagGroup>(device, cancellationToken: cancellationToken).ConfigureAwait(false);
+
+                if (device.TagGroups != null)
+                {
+                    await ProjectApiHandler.LoadTagGroupsRecursiveAsync(m_kepwareApiClient, device.TagGroups, cancellationToken: cancellationToken).ConfigureAwait(false);
+                }
+            }
+
+            return device;
+        }
+        #endregion
+
         #region CreateDeviceAsync
         /// <summary>
         /// Creates a new device with the specified name and driver in the specified channel.