Update version and Trigger CI

Author: MathoMathiasCamara

Directory.Build.targets

@@ -32,7 +32,6 @@
 
     <PackageReference Update="MQTTnet" Version="4.3.1.873"/>
     <PackageReference Update="MQTTnet.Extensions.ManagedClient"   Version="4.3.1.873"/>
-    <!--<PackageReference Update="MQTTnet.AspNetCore"  Version="4.3.1.873"/>-->
 
 	  <FrameworkReference Update="Microsoft.AspNetCore.App" Version="$(dotnetVersion)"/>
     <PackageReference Update="Microsoft.Extensions.Logging" Version="$(dotnetVersion)" />

VERSION

@@ -1 +1 @@
-8.5.1
+8.6.0

src/Moryx.Communication.Mqtt.Endpoints/Moryx.Communication.Mqtt.Endpoints.csproj

@@ -4,10 +4,14 @@
     <TargetFramework>net8.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\Moryx.Communication.Mqtt\Moryx.Communication.Mqtt.csproj" />
   </ItemGroup>
 
-</Project>
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="" />
+  </ItemGroup>
+</Project>

src/Moryx.Communication.Mqtt.Endpoints/README.md

@@ -1,8 +1,66 @@
 # ResourceRpcEndpoint
-- Endpoint to remote call a procedure/method on a resource
+- Endpoint to remote call a procedure/method on a resource. 
 
 When the endpoint receives a request(Message) the response will be sent to :
  1. `MqttApplicationMessage.ResponseTopic` if the  request (message) has a response topic.
  2. `resources/{identifier}/invoked/{methodName}` when the request (Message) doesn't have a ResponseTopic
 
-When a client sends a message to the following topic : `"resources/{identifier}/invoke/{methodName}"` , for example `resources/1236545/invoke/ChangeCapabilities`. The `ResourceRpcEndpoint`will be triggered and the matching Resource with the `Identifier` or `Name` `1236545` and the method that matches the name `ChangeCapabilities` will be invoked.
+## Why do we need a ResourceRpcEndpoint ?
+
+### Scenario :
+Here is a scenario where i need the `ResourceRpcEndpoint`. We have 2 Moryx instances running on different machine. One is a Raspberry pi and one is a desktop, both on the same WiFi network. The Raspberry pi only has one moryx resource called `Camera` with a physical camera connected. And the desktop has all the station of the `Machine` (Note: the physical machine is an entire factory floor). At one particular station `Printing` we need to take pictures. For that the `Printing` station needs to send a `Take a picture and send it to me` command to the `Camera` (Which is on the Raspberry pi).
+
+## Example:
+Given the following Resource:
+
+```cs
+public IMyPublicMethods
+{
+    void MethodWithParams(int value){
+        //code
+    }
+
+    int MethodWithResult()
+    {
+        return 1;
+    }
+}
+
+[ResourceAvailableAs(typeof(IMyPublicMethod)))]
+public class ExampleResource : Resource, IMyPublicMethods 
+{
+    public long Id => 1; // example
+    public void MethodWithParams(int value)
+    {
+        //code
+    }
+
+    public int MethodWithResult()
+    {
+        return 1
+    }
+    // codes...
+}
+```
+
+- When a client sends a message to the following topic : `resources/1/invoke/MethodWithParams` with this payload
+```json
+{
+    "Value" : 152
+}
+``` 
+    - The `ResourceRpcEndpoint` will be triggered and the method `MethodWithParams` will be invoked. The payload inside the message is used as value for the method parameters , in this case `Value = 123` the name matches the parameter name (not case sensitif). The response message has the following structure:
+```json
+    {
+    "Value" = object,
+    "ValueType" = EntityEntryValueType //   EntryConvert.TransformType(methodToInvoke.ReturnType)
+    }
+```
+
+- When a client sends a message to the following topic : `resources/1/invoke/MethodWithResult` with an empty payload
+and a response topic `device-125/resources/1/MethodWithResult/response`
+
+    - The `ResourceRpcEndpoint` will be triggered and the method `MethodWithResult` will be invoked. And the return value `1` will be sent back to the broker using the topic `device-125/resources/1/MethodWithResult/response`.
+
+
+Note : All serialization a done via `MqttMessageSerialization`

src/Moryx.Communication.Mqtt.Endpoints/ResourceRpcEndpoint.cs

@@ -1,6 +1,7 @@
 // Copyright (c) 2025, Phoenix Contact GmbH & Co. KG
 // Licensed under the Apache License, Version 2.0
 
+using System.Reflection;
 using Microsoft.Extensions.Logging;
 using Moryx.AbstractionLayer.Identity;
 using Moryx.AbstractionLayer.Resources;
@@ -21,6 +22,7 @@ public class ResourceRpcEndpoint(
     MqttClientUserOptions options)
     : IMqttEndpoint
 {
+    private const string message = "No resource or method found with the given Identifier:`{id}`, method:`{method}`. Task and Task<T> are not supported return types.";
     public void Map(IMqttRouteBuilder routeBuilder)
     {
         routeBuilder.MapGet("resources/{identifier}/invoke/{methodName}", context =>
@@ -33,29 +35,39 @@ public void Map(IMqttRouteBuilder routeBuilder)
             var resource = resourceManagement.GetResource<IResource>(x =>
                 x is IIdentifiableObject obj && obj.Identity.Identifier == identifier
                 || x.Name == identifier);
-            return FindAndInvokeMethod(context, messageBuilder, identifier, methodName, resource);
+            var methodToInvoke = FindMethod(resource, methodName, identifier);
+            return methodToInvoke is null
+                ? GetExceptionMessage(messageBuilder, string.Format(message, identifier, methodName))
+                : InvokeMethod(context, messageBuilder, resource, methodToInvoke);
         });
     }
 
-    private MqttApplicationMessage? FindAndInvokeMethod(
-        MqttEndpointContext context,
-        MqttApplicationMessageBuilder responseBuilder,
-        string? identifier,
-        string methodName,
-        IResource? resource)
+    private MethodInfo? FindMethod(IResource resource, string methodName, string? identifier)
     {
         var methodToInvoke = resource
-                        ?.GetType()
-                        .GetInterfaces()
-                        .Select(i => i.GetMethod(methodName))
-                        .FirstOrDefault(x => x is not null);
-
+                      ?.GetType()
+                      .GetInterfaces()
+                      .Select(i =>
+                        i.GetMethods()
+                        .Where(m =>
+                            m.ReturnType == typeof(Task)
+                            || (m.ReturnType.IsGenericType && m.ReturnType.GetGenericTypeDefinition() == typeof(Task<>)))
+                        .FirstOrDefault(x => x.Name.Equals(methodName, StringComparison.OrdinalIgnoreCase)))
+                      .FirstOrDefault(x => x is not null);
         if (resource is null || methodToInvoke is null)
         {
-            logger.Log(LogLevel.Error, "No resource or method found with the given Identifier:`{id}`, method:`{method}`.", identifier, methodName);
+            logger.Log(LogLevel.Error, message, identifier, methodName);
             return null;
         }
+        return methodToInvoke;
+    }
 
+    private MqttApplicationMessage InvokeMethod(
+        MqttEndpointContext context,
+        MqttApplicationMessageBuilder responseBuilder,
+        IResource resource,
+        MethodInfo methodToInvoke)
+    {
         var methodToInvokeParameters = methodToInvoke.GetParameters();
         var parameters = new object?[methodToInvokeParameters.Length];
 
@@ -66,16 +78,27 @@ public void Map(IMqttRouteBuilder routeBuilder)
                 // get the values of the method's parameters from the body of the message
                 parameters[i] = context.FromBody(methodToInvokeParameters[i].Name!, methodToInvokeParameters[i].ParameterType);
             }
-            catch (Exception ex)
+            catch (InvalidCastException ex)
             {
                 logger.LogError(ex,
                     "Impossible to get Method '{method}' parameter '{parameter}' from the Payload.",
-                    methodName,
+                    methodToInvoke.Name,
                     methodToInvokeParameters[i].Name);
-                continue;
+                return GetExceptionMessage(responseBuilder, ex.Message);
             }
         }
-        var methodResult = methodToInvoke.Invoke(resource, parameters);
+
+        object? methodResult;
+
+        try
+        {
+            methodResult = methodToInvoke.Invoke(resource, parameters);
+        }
+        catch (Exception ex)
+        {
+            return GetExceptionMessage(responseBuilder, ex.Message);
+        }
+
         if (methodResult?.GetType() == typeof(void))
         {
             responseBuilder.WithPayload(MqttMessageSerialization.GetJsonPayload(new { }, options.JsonSerializerOptions));
@@ -95,5 +118,16 @@ public void Map(IMqttRouteBuilder routeBuilder)
         }, options.JsonSerializerOptions) ?? string.Empty;
         return responseBuilder.WithPayload(jsonPayload).Build();
     }
+
+    private MqttApplicationMessage GetExceptionMessage(MqttApplicationMessageBuilder builder, string exception)
+    {
+        var payload = new MethodInvocationResult
+        {
+            Value = new { Message = exception },
+            ValueType = EntryValueType.Exception
+        };
+        var json = MqttMessageSerialization.GetJsonPayload(payload, options.JsonSerializerOptions);
+        return builder.WithPayload(json).Build();
+    }
 }
 

src/Moryx.Communication.Mqtt.Services/Moryx.Communication.Mqtt.Services.csproj

@@ -4,10 +4,14 @@
     <TargetFramework>net8.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\Moryx.Communication.Mqtt\Moryx.Communication.Mqtt.csproj" />
   </ItemGroup>
 
-</Project>
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="" />
+  </ItemGroup>
+</Project>

src/Moryx.Communication.Mqtt/Moryx.Communication.Mqtt.csproj

@@ -4,20 +4,23 @@
     <TargetFramework>net8.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>
 
   <ItemGroup>
-	  <FrameworkReference Include="Microsoft.AspNetCore.App" />
-	  <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
-	  <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
 
-	  <PackageReference Include="MQTTnet" />
-	  <PackageReference Include="MQTTnet.Extensions.ManagedClient" />
+    <PackageReference Include="MQTTnet" />
+    <PackageReference Include="MQTTnet.Extensions.ManagedClient" />
   </ItemGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\Moryx.AbstractionLayer\Moryx.AbstractionLayer.csproj" />
     <ProjectReference Include="..\Moryx.Runtime\Moryx.Runtime.csproj" />
   </ItemGroup>
-
-</Project>
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="" />
+  </ItemGroup>
+</Project>

src/Moryx.Communication.Mqtt/README.md

@@ -65,6 +65,22 @@ Add your configuration file `Moryx.Mqtt.Config.json`, inside the default MORYX C
 }
 ```
 
+## Serialization
+The serialization of payload is done via `MqttMessageSerialization` helper class, serialization and deserialization methods requires `JsonSerializerOptions` that is configured during setup of the Mqtt client.
+
+- JsonSerializationOptions
+
+```cs
+// Program.cs
+builder.Services.AddMqttClient(builder: (provider, options) => 
+{
+    options.JsonSerializerOptions.Converters.Add(new MyCustomConverter()) // here you add your custom converter
+    options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles; // change how references are handled
+    //etc..
+})
+//.. other code
+```
+
 if you want to implement your custom service based on the   `IManagedMqttClient` the recommended way is as follow :
  - In your `program.cs` add the following:
 
@@ -244,3 +260,6 @@ route.MapGet("/my-topic/{id:int}", ctx => {
 });
 ...
 ```
+
+
+