Create rule S6562: Always set the DateTimeKind when creating a new DateTime object (#1712)

rules/S6562/csharp/metadata.json

@@ -0,0 +1,2 @@
+{
+}

rules/S6562/csharp/rule.adoc

@@ -0,0 +1,29 @@
+include::../why-dotnet.adoc[]
+
+include::../impact-dotnet.adoc[]
+
+include::../how-dotnet.adoc[]
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,csharp,diff-id=1,diff-type=noncompliant]
+----
+void CreateNewTime()
+{
+    var birthDate = new DateTime(1994, 7, 5, 16, 23, 42);
+}
+----
+
+==== Compliant solution
+
+[source,csharp,diff-id=1,diff-type=compliant]
+----
+void CreateNewTime()
+{
+    var birthDate = new DateTime(1994, 7, 5, 16, 23, 42, DateTimeKind.Utc);
+}
+----
+
+include::../resources-dotnet.adoc[]

rules/S6562/how-dotnet.adoc

@@ -0,0 +1,3 @@
+== How to fix it
+
+To fix this issue use a constructor overload that allows specifying the `DateTimeKind` when creating the `DateTime` object.

rules/S6562/impact-dotnet.adoc

@@ -0,0 +1,4 @@
+=== What is the potential impact?
+
+Creating the `DateTime` object without specifying the property `Kind` will set it to the default value of `DateTimeKind.Unspecified`. In this case, calling the method `ToUniversalTime` will assume that `Kind` is `DateTimeKind.Local` and calling the method `ToLocalTime` will assume that it's `DateTimeKind.Utc`.
+As a result, you might have mismatched `DateTime` objects in your application.

rules/S6562/metadata.json

@@ -0,0 +1,21 @@
+{
+  "title": "Always set the \"DateTimeKind\" when creating new \"DateTime\" instances",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "localisation",
+    "pitfall"
+  ],
+  "extra": {
+  },
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-6562",
+  "sqKey": "S6562",
+  "scope": "All",
+  "defaultQualityProfiles": ["Sonar way"],
+  "quickfix": "infeasible"
+}

rules/S6562/resources-dotnet.adoc

@@ -0,0 +1,7 @@
+== Resources
+=== Documentation
+
+* https://learn.microsoft.com/en-us/dotnet/api/system.datetimekind[DateTimeKind documentation]
+* https://learn.microsoft.com/en-us/dotnet/api/system.datetime.-ctor[DateTime documentation]
+* https://learn.microsoft.com/en-us/dotnet/standard/base-types/how-to-round-trip-date-and-time-values[How to round trip date and time values]
+* https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/member-overloading [Member overloading]

rules/S6562/vbnet/metadata.json

@@ -0,0 +1,2 @@
+{
+}

rules/S6562/vbnet/rule.adoc

@@ -0,0 +1,27 @@
+include::../why-dotnet.adoc[]
+
+include::../impact-dotnet.adoc[]
+
+include::../how-dotnet.adoc[]
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,vbnet,diff-id=1,diff-type=noncompliant]
+----
+Private Sub CreateNewTime()
+    Dim birthDate = New DateTime(1994, 7, 5, 16, 23, 42)
+End Sub
+----
+
+==== Compliant solution
+
+[source,vbnet,diff-id=1,diff-type=compliant]
+----
+Private Sub CreateNewTime()
+    Dim birthDate = New DateTime(1994, 7, 5, 16, 23, 42, DateTimeKind.Utc)
+End Sub
+----
+
+include::../resources-dotnet.adoc[]

rules/S6562/why-dotnet.adoc

@@ -0,0 +1,4 @@
+== Why is this an issue?
+
+Not knowing the `Kind` of the `DateTime` object that an application is using can lead to misunderstandings when displaying or comparing them. Explicitly setting the `Kind` property helps the application to stay consistent, and its maintainers understand what kind of date is being managed.
+To achieve this, when instantiating a new `DateTime` object you should always use a constructor overload that allows you to define the `Kind` property.