Release 1.0.0-rc1

Initial release candidate of the SDK targeting v3.1 of the AAS specification.

The code is generated with:
* [aas-core-meta 899add10] and
* [aas-core-codegen 754e167].

[aas-core-meta 899add10]: aas-core-works/aas-core-meta@899add10
[aas-core-codegen 754e167]: aas-core-works/aas-core-codegen@754e167

Author: empwilli

dev_scripts/codegen/snippets/Types/Data_element/category_or_default.cs

@@ -0,0 +1,129 @@
+using Aas = AasCore.Aas3_1; // renamed
+
+using System.Collections.Generic; // can't alias
+using System.Linq; // can't alias
+using NUnit.Framework; // can't alias
+
+namespace AasCore.Aas3_1.Tests
+{
+    /// <summary>
+    /// Provide common functionality to be re-used across different tests
+    /// such as reading of environment variables.
+    /// </summary>
+    public static class Common
+    {
+        public static readonly string RecordModeEnvironmentVariableName = (
+            "AAS_CORE_AAS3_1_TESTS_RECORD_MODE"
+        );
+
+        // NOTE (mristin, 2023-03-16):
+        // It is tedious to record manually all the expected error messages. Therefore we include this variable
+        // to steer the automatic recording. We intentionally inter-twine the recording code with the test code
+        // to keep them close to each other so that they are easier to maintain.
+        public static readonly bool RecordMode = (
+            System.Environment.GetEnvironmentVariable(RecordModeEnvironmentVariableName)?.ToLower()
+                == "true"
+            || System
+                .Environment.GetEnvironmentVariable(RecordModeEnvironmentVariableName)
+                ?.ToLower() == "on"
+            || System
+                .Environment.GetEnvironmentVariable(RecordModeEnvironmentVariableName)
+                ?.ToLower() == "1"
+            || System
+                .Environment.GetEnvironmentVariable(RecordModeEnvironmentVariableName)
+                ?.ToLower() == "yes"
+        );
+
+        public static readonly string TestDataDir = (
+            System.Environment.GetEnvironmentVariable("AAS_CORE_AAS3_1_TESTS_TEST_DATA_DIR")
+            ?? throw new System.InvalidOperationException(
+                "The path to the test data directory is missing in the environment: "
+                    + "AAS_CORE_AAS3_1_TESTS_TEST_DATA_DIR"
+            )
+        );
+
+        /// <summary>
+        /// Find the first instance of <typeparamref name="T"/> in the <paramref name="container" />,
+        /// including the <paramref name="container" /> itself.
+        /// </summary>
+        public static T MustFind<T>(Aas.IClass container)
+            where T : Aas.IClass
+        {
+            var instance = (
+                (container is T)
+                    ? container
+                    : container.Descend().First(something => something is T)
+                    ?? throw new System.InvalidOperationException(
+                            $"No instance of {nameof(T)} could be found"
+                        )
+            );
+
+            return (T)instance;
+        }
+
+        public static void AssertNoVerificationErrors(List<Aas.Reporting.Error> errors, string path)
+        {
+            if (errors.Count > 0)
+            {
+                var builder = new System.Text.StringBuilder();
+                builder.Append(
+                    $"Expected no errors when verifying the instance de-serialized from {path}, "
+                        + $"but got {errors.Count} error(s):\n"
+                );
+                for (var i = 0; i < errors.Count; i++)
+                {
+                    builder.Append(
+                        $"Error {i + 1}:\n"
+                            + $"{Reporting.GenerateJsonPath(errors[i].PathSegments)}: {errors[i].Cause}\n"
+                    );
+                }
+
+                Assert.Fail(builder.ToString());
+            }
+        }
+
+        public static void AssertEqualsExpectedOrRerecordVerificationErrors(
+            List<Aas.Reporting.Error> errors,
+            string path
+        )
+        {
+            if (errors.Count == 0)
+            {
+                Assert.Fail(
+                    $"Expected at least one verification error when verifying {path}, but got none"
+                );
+            }
+
+            string got = string.Join(
+                ";\n",
+                errors.Select(error =>
+                    $"{Reporting.GenerateJsonPath(error.PathSegments)}: {error.Cause}"
+                )
+            );
+
+            string errorsPath = path + ".errors";
+            if (RecordMode)
+            {
+                System.IO.File.WriteAllText(errorsPath, got);
+            }
+            else
+            {
+                if (!System.IO.File.Exists(errorsPath))
+                {
+                    throw new System.IO.FileNotFoundException(
+                        "The file with the recorded errors does not "
+                            + $"exist: {errorsPath}; maybe you want to set the environment "
+                            + $"variable {Aas.Tests.Common.RecordModeEnvironmentVariableName}?"
+                    );
+                }
+
+                string expected = System.IO.File.ReadAllText(errorsPath);
+                Assert.AreEqual(
+                    expected.Replace("\r\n", "\n"),
+                    got.Replace("\r\n", "\n"),
+                    $"The expected verification errors do not match the actual ones for the file {path}"
+                );
+            }
+        }
+    }
+}

src/AasCore.Aas3_1.Tests/Common.cs

@@ -0,0 +1,235 @@
+using Aas = AasCore.Aas3_1; // renamed
+using FileMode = System.IO.FileMode;
+using FileStream = System.IO.FileStream;
+using JsonException = System.Text.Json.JsonException;
+using Nodes = System.Text.Json.Nodes;
+
+using System.Collections.Generic; // can't alias
+using System.Linq; // can't alias
+
+namespace AasCore.Aas3_1.Tests
+{
+    public static class CommonJson
+    {
+        public static Nodes.JsonNode ReadFromFile(string path)
+        {
+            using var stream = new FileStream(path, FileMode.Open);
+            Nodes.JsonNode? node;
+            try
+            {
+                node = Nodes.JsonNode.Parse(stream);
+            }
+            catch (JsonException exception)
+            {
+                throw new System.InvalidOperationException(
+                    $"Expected the file to be a valid JSON, but it was not: {path}; "
+                        + $"exception was: {exception}"
+                );
+            }
+
+            if (node is null)
+            {
+                throw new System.InvalidOperationException(
+                    "Expected the file to be a non-null JSON value, " + $"but it was null: {path}"
+                );
+            }
+
+            return node;
+        }
+
+        /// <summary>
+        /// Serialize <paremref name="something" /> to a uniform JSON text
+        /// such that we can use it for comparisons in the tests.
+        /// </summary>
+        public static Nodes.JsonNode ToJson(object something)
+        {
+            switch (something)
+            {
+                case bool aBool:
+                    return Nodes.JsonValue.Create(aBool);
+                case long aLong:
+                    return Nodes.JsonValue.Create(aLong);
+                case double aDouble:
+                    return Nodes.JsonValue.Create(aDouble);
+                case string aString:
+                    return Nodes.JsonValue.Create(aString)
+                        ?? throw new System.InvalidOperationException(
+                            $"Could not convert {something} " + "to a JSON string"
+                        );
+                case byte[] someBytes:
+                    return Nodes.JsonValue.Create(System.Convert.ToBase64String(someBytes))
+                        ?? throw new System.InvalidOperationException(
+                            $"Could not convert {something} to " + "a base64-encoded JSON string"
+                        );
+                case Aas.IClass instance:
+                    return Aas.Jsonization.Serialize.ToJsonObject(instance);
+                default:
+                    throw new System.ArgumentException(
+                        $"The conversion of type {something.GetType()} "
+                            + $"to a JSON node has not been defined: {something}"
+                    );
+            }
+        }
+
+        /// <summary>
+        /// Infer the node kind of the JSON node.
+        /// </summary>
+        /// <remarks>
+        /// This function is necessary since NET6 does not fully support node kinds yet.
+        /// See:
+        /// <ul>
+        /// <li>https://github.com/dotnet/runtime/issues/53406</li>
+        /// <li>https://github.com/dotnet/runtime/issues/55827</li>
+        /// <li>https://github.com/dotnet/runtime/issues/56592</li>
+        /// </ul>
+        /// </remarks>
+        private static string GetNodeKind(Nodes.JsonNode node)
+        {
+            switch (node)
+            {
+                case Nodes.JsonArray _:
+                    return "array";
+                case Nodes.JsonObject _:
+                    return "object";
+                case Nodes.JsonValue _:
+                    return "value";
+                default:
+                    throw new System.InvalidOperationException(
+                        $"Unhandled JsonNode: {node.GetType()}"
+                    );
+            }
+        }
+
+        public static void CheckJsonNodesEqual(
+            Nodes.JsonNode that,
+            Nodes.JsonNode other,
+            out Reporting.Error? error
+        )
+        {
+            error = null;
+
+            var thatNodeKind = GetNodeKind(that);
+            var otherNodeKind = GetNodeKind(other);
+
+            if (thatNodeKind != otherNodeKind)
+            {
+                error = new Reporting.Error(
+                    $"Mismatch in node kinds : {thatNodeKind} != {otherNodeKind}"
+                );
+                return;
+            }
+
+            switch (that)
+            {
+                case Nodes.JsonArray thatArray:
+                    {
+                        var otherArray = (other as Nodes.JsonArray)!;
+                        if (thatArray.Count != otherArray.Count)
+                        {
+                            error = new Reporting.Error(
+                                $"Unequal array lengths: {thatArray.Count} != {otherArray.Count}"
+                            );
+                            return;
+                        }
+
+                        for (int i = 0; i < thatArray.Count; i++)
+                        {
+                            CheckJsonNodesEqual(thatArray[i]!, otherArray[i]!, out error);
+                            if (error != null)
+                            {
+                                error.PrependSegment(new Reporting.IndexSegment(i));
+                                return;
+                            }
+                        }
+
+                        break;
+                    }
+                case Nodes.JsonObject thatObject:
+                    {
+                        var thatDictionary = thatObject as IDictionary<string, Nodes.JsonNode>;
+                        var otherDictionary = (other as IDictionary<string, Nodes.JsonNode>)!;
+
+                        var thatKeys = thatDictionary.Keys.ToList();
+                        thatKeys.Sort();
+
+                        var otherKeys = otherDictionary.Keys.ToList();
+                        otherKeys.Sort();
+
+                        if (!thatKeys.SequenceEqual(otherKeys))
+                        {
+                            error = new Reporting.Error(
+                                "Objects with different properties: "
+                                    + $"{string.Join(", ", thatKeys)} != "
+                                    + $"{string.Join(", ", otherKeys)}"
+                            );
+                            return;
+                        }
+
+                        foreach (var key in thatKeys)
+                        {
+                            CheckJsonNodesEqual(thatDictionary[key], otherDictionary[key], out error);
+                            if (error != null)
+                            {
+                                error.PrependSegment(new Reporting.NameSegment(key));
+                                return;
+                            }
+                        }
+
+                        break;
+                    }
+                case Nodes.JsonValue thatValue:
+                    {
+                        string thatAsJsonString = thatValue.ToJsonString();
+
+                        // NOTE (mristin, 2023-03-16):
+                        // This is slow, but there is no way around it at the moment with NET6.
+                        // See:
+                        // * https://github.com/dotnet/runtime/issues/56592
+                        // * https://github.com/dotnet/runtime/issues/55827
+                        // * https://github.com/dotnet/runtime/issues/53406
+                        var otherValue = (other as Nodes.JsonValue)!;
+                        string otherAsJsonString = otherValue.ToJsonString();
+
+                        if (thatAsJsonString != otherAsJsonString)
+                        {
+                            error = new Reporting.Error(
+                                $"Unequal values: {thatAsJsonString} != {otherAsJsonString}"
+                            );
+                            // ReSharper disable once RedundantJumpStatement
+                            return;
+                        }
+
+                        break;
+                    }
+                default:
+                    throw new System.InvalidOperationException(
+                        $"Unhandled JSON node: {that.GetType()}"
+                    );
+            }
+        }
+
+        /// <summary>
+        /// Load an instance from a JSON file.
+        /// </summary>
+        public static Aas.IClass LoadInstance(string path)
+        {
+            Aas.IClass? instance;
+
+            {
+                using var stream = new FileStream(path, FileMode.Open);
+                var node =
+                    Nodes.JsonNode.Parse(stream)
+                    ?? throw new System.InvalidOperationException("node unexpectedly null");
+
+                instance = AasCore.Aas3_1.Jsonization.Deserialize.EnvironmentFrom(node);
+            }
+
+            if (instance == null)
+            {
+                throw new System.InvalidOperationException("environment unexpectedly null");
+            }
+
+            return instance;
+        }
+    }
+}