Fix error message in xmlization on XML declaration (#25)

When we encountered XML declarations, we threw exceptions with
uninformative messages. Namely, we expect the reader to be moved to the
content, but most users omitted to read that in the documentation.

We refine the error message for this particular situation, and hint at
`MoveToContent` method on the reader.

Fixes #24.

Generated with [aas-core-codegen 28fbd98].

[aas-core-codegen 28fbd98]: aas-core-works/aas-core-codegen@28fbd98

src/AasCore.Aas3_0.Tests/TestXmlizationErrors.cs

@@ -0,0 +1,55 @@
+using Aas = AasCore.Aas3_0; // renamed
+
+using NUnit.Framework; // can't alias
+
+namespace AasCore.Aas3_0.Tests
+{
+    public class TestXmlizationErrors
+    {
+        [Test]
+        public void Test_error_on_unexpected_declaration()
+        {
+            var text = (
+                "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
+                "<environment xmlns=\"https://admin-shell.io/aas/3/0\">" +
+                "<submodels><submodel>" +
+                "<id>some-unique-global-identifier</id>" +
+                "<submodelElements><property><idShort>someProperty</idShort>" +
+                "<valueType>xs:boolean</valueType></property></submodelElements>" +
+                "</submodel></submodels></environment>"
+            );
+
+            using var stringReader = new System.IO.StringReader(
+                text);
+
+            using var xmlReader = System.Xml.XmlReader.Create(
+                stringReader);
+
+            // We intentionally do not call `MoveToContent` to test the error message.
+            // This is a very common situation, see:
+            // https://github.com/aas-core-works/aas-core3.0-csharp/issues/24
+
+            string? message = null;
+
+            try
+            {
+                Aas.Xmlization.Deserialize.EnvironmentFrom(
+                    xmlReader);
+            }
+            catch (AasCore.Aas3_0.Xmlization.Exception exception)
+            {
+                message = exception.Message;
+            }
+
+            if (message == null)
+            {
+                throw new AssertionException("Unexpected no exception");
+            }
+            Assert.AreEqual(
+                "Unexpected XML declaration when reading an instance of " +
+                "class Environment, as we expect the reader to be set at content " +
+                "with MoveToContent at: the beginning",
+                message);
+        }
+    }
+}

src/aas-core3.0-csharp.sln.DotSettings.user

@@ -1,8 +1,31 @@
 <wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:String x:Key="/Default/Environment/UnitTesting/UnitTestSessionStore/Sessions/=2dc3e0f3_002Dd11c_002D43a0_002Da69b_002D36aeb637f0cd/@EntryIndexedValue">&lt;SessionState ContinuousTestingMode="0" Name="Test_error_on_unexpected_declaration" xmlns="urn:schemas-jetbrains-com:jetbrains-ut-session"&gt;&#xD;
+  &lt;TestAncestor&gt;&#xD;
+    &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestXmlizationErrors.Test_error_on_unexpected_declaration&lt;/TestId&gt;&#xD;
+  &lt;/TestAncestor&gt;&#xD;
+&lt;/SessionState&gt;</s:String>
 	<s:String x:Key="/Default/Environment/UnitTesting/UnitTestSessionStore/Sessions/=bd994a3b_002D4a4e_002D4b0b_002D90d4_002Ddfcb614164d9/@EntryIndexedValue">&lt;SessionState ContinuousTestingMode="0" IsActive="True" Name="Test_XML_serialization" xmlns="urn:schemas-jetbrains-com:jetbrains-ut-session"&gt;&#xD;
+  &lt;Or&gt;&#xD;
+    &lt;ProjectFile&gt;BDA0E5A2-D48D-4888-9D52-44BD529F8108/f:TestXmlizationOfConcreteClasses.cs&lt;/ProjectFile&gt;&#xD;
+    &lt;ProjectFile&gt;BDA0E5A2-D48D-4888-9D52-44BD529F8108/f:TestXmlizationOfConcreteClassesOutsideContainer.cs&lt;/ProjectFile&gt;&#xD;
+    &lt;ProjectFile&gt;BDA0E5A2-D48D-4888-9D52-44BD529F8108/f:TestXmlizationOfInterfaces.cs&lt;/ProjectFile&gt;&#xD;
+    &lt;TestAncestor&gt;&#xD;
+      &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestExamples.Test_XML_serialization&lt;/TestId&gt;&#xD;
+      &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestExamples.Test_JSON_deserialization&lt;/TestId&gt;&#xD;
+      &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestExamples.Test_selective_enhancing&lt;/TestId&gt;&#xD;
+      &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestXmlizationErrors.Test_error_on_unexpected_declaration&lt;/TestId&gt;&#xD;
+    &lt;/TestAncestor&gt;&#xD;
+  &lt;/Or&gt;&#xD;
+&lt;/SessionState&gt;</s:String>
+	<s:String x:Key="/Default/Environment/UnitTesting/UnitTestSessionStore/Sessions/=d08349d0_002D1d79_002D48ae_002D9b89_002D73f1b5254923/@EntryIndexedValue">&lt;SessionState ContinuousTestingMode="0" Name="Test_XML_serialization #2" xmlns="urn:schemas-jetbrains-com:jetbrains-ut-session"&gt;&#xD;
   &lt;TestAncestor&gt;&#xD;
     &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestExamples.Test_XML_serialization&lt;/TestId&gt;&#xD;
     &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestExamples.Test_JSON_deserialization&lt;/TestId&gt;&#xD;
     &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestExamples.Test_selective_enhancing&lt;/TestId&gt;&#xD;
+    &lt;TestId&gt;NUnit3x::BDA0E5A2-D48D-4888-9D52-44BD529F8108::net6.0::AasCore.Aas3_0.Tests.TestXmlizationErrors.Test_error_on_unexpected_declaration&lt;/TestId&gt;&#xD;
   &lt;/TestAncestor&gt;&#xD;
-&lt;/SessionState&gt;</s:String></wpf:ResourceDictionary>
+&lt;/SessionState&gt;</s:String>
+
+	<s:String x:Key="/Default/Housekeeping/UnitTestingMru/UnitTestRunner/EnvironmentVariablesIndexed/=AAS_005FCORE_005FAAS3_005F0_005FTESTS_005FRECORD_005FMODE/@EntryIndexedValue">true</s:String>
+	<s:String x:Key="/Default/Housekeeping/UnitTestingMru/UnitTestRunner/EnvironmentVariablesIndexed/=AAS_005FCORE_005FAAS3_005F0_005FTESTS_005FTEST_005FDATA_005FDIR/@EntryIndexedValue">C:\Users\rist\workspace\aas-core-works\aas-core3.0-csharp\test_data</s:String>
+	<s:String x:Key="/Default/Housekeeping/UnitTestingMru/UnitTestRunner/RunConfigurationFilename/@EntryValue">C:\Users\rist\workspace\aas-core-works\aas-core3.0-cli-swiss-knife\mristin.runsettings</s:String></wpf:ResourceDictionary>

test_data/Xml/SelfContained/Unexpected/RequiredViolation/eventPayload/observableReference.xml.exception

@@ -1 +1 @@
-The required property ObservableReference has not been given in the XML representation of an instance of class EventPayload at: 
+The required property ObservableReference has not been given in the XML representation of an instance of class EventPayload at: the beginning

test_data/Xml/SelfContained/Unexpected/RequiredViolation/eventPayload/source.xml.exception

@@ -1 +1 @@
-The required property Source has not been given in the XML representation of an instance of class EventPayload at: 
+The required property Source has not been given in the XML representation of an instance of class EventPayload at: the beginning

test_data/Xml/SelfContained/Unexpected/RequiredViolation/eventPayload/timeStamp.xml.exception

@@ -1 +1 @@
-The required property TimeStamp has not been given in the XML representation of an instance of class EventPayload at: 
+The required property TimeStamp has not been given in the XML representation of an instance of class EventPayload at: the beginning

test_data/Xml/SelfContained/Unexpected/TypeViolation/environment/assetAdministrationShells.xml.exception

@@ -1 +1 @@
-Expected an XML end element to conclude a property of class Environment with the element name assetAdministrationShells, but got the node of type Text with the value Unexpected string value at: 
+Expected an XML end element to conclude a property of class Environment with the element name assetAdministrationShells, but got the node of type Text with the value Unexpected string value at: the beginning

test_data/Xml/SelfContained/Unexpected/TypeViolation/environment/conceptDescriptions.xml.exception

@@ -1 +1 @@
-Expected an XML end element to conclude a property of class Environment with the element name conceptDescriptions, but got the node of type Text with the value Unexpected string value at: 
+Expected an XML end element to conclude a property of class Environment with the element name conceptDescriptions, but got the node of type Text with the value Unexpected string value at: the beginning

test_data/Xml/SelfContained/Unexpected/TypeViolation/environment/submodels.xml.exception

@@ -1 +1 @@
-Expected an XML end element to conclude a property of class Environment with the element name submodels, but got the node of type Text with the value Unexpected string value at: 
+Expected an XML end element to conclude a property of class Environment with the element name submodels, but got the node of type Text with the value Unexpected string value at: the beginning

test_data/Xml/SelfContained/Unexpected/TypeViolation/eventPayload/payload.xml.exception

@@ -1 +1 @@
-Expected an XML end element to conclude a property of class EventPayload with the element name payload, but got the node of type Element with the value  at: 
+Expected an XML end element to conclude a property of class EventPayload with the element name payload, but got the node of type Element with the value  at: the beginning

test_data/Xml/SelfContained/Unexpected/TypeViolation/eventPayload/timeStamp.xml.exception

@@ -1 +1 @@
-Expected an XML end element to conclude a property of class EventPayload with the element name timeStamp, but got the node of type Element with the value  at: 
+Expected an XML end element to conclude a property of class EventPayload with the element name timeStamp, but got the node of type Element with the value  at: the beginning

test_data/Xml/SelfContained/Unexpected/TypeViolation/eventPayload/topic.xml.exception

@@ -1 +1 @@
-Expected an XML end element to conclude a property of class EventPayload with the element name topic, but got the node of type Element with the value  at: 
+Expected an XML end element to conclude a property of class EventPayload with the element name topic, but got the node of type Element with the value  at: the beginning

test_data/Xml/SelfContained/Unexpected/UnexpectedAdditionalProperty/environment/invalid.xml.exception

@@ -1 +1 @@
-We expected properties of the class Environment, but got an unexpected element with the name unexpectedAdditionalProperty at: 
+We expected properties of the class Environment, but got an unexpected element with the name unexpectedAdditionalProperty at: the beginning

test_data/Xml/SelfContained/Unexpected/UnexpectedAdditionalProperty/eventPayload/invalid.xml.exception

@@ -1 +1 @@
-We expected properties of the class EventPayload, but got an unexpected element with the name unexpectedAdditionalProperty at: 
+We expected properties of the class EventPayload, but got an unexpected element with the name unexpectedAdditionalProperty at: the beginning