From a064be87be931e6c531d602b78325a2a5bb511ac Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 6 Jul 2023 11:12:06 +0200
Subject: [PATCH] Create rule S6562: Always set the DateTimeKind when creating
 a new DateTime object (#1712)

---
 rules/S6562/csharp/metadata.json  |  2 ++
 rules/S6562/csharp/rule.adoc      | 29 +++++++++++++++++++++++++++++
 rules/S6562/how-dotnet.adoc       |  3 +++
 rules/S6562/impact-dotnet.adoc    |  4 ++++
 rules/S6562/metadata.json         | 21 +++++++++++++++++++++
 rules/S6562/resources-dotnet.adoc |  7 +++++++
 rules/S6562/vbnet/metadata.json   |  2 ++
 rules/S6562/vbnet/rule.adoc       | 27 +++++++++++++++++++++++++++
 rules/S6562/why-dotnet.adoc       |  4 ++++
 9 files changed, 99 insertions(+)
 create mode 100644 rules/S6562/csharp/metadata.json
 create mode 100644 rules/S6562/csharp/rule.adoc
 create mode 100644 rules/S6562/how-dotnet.adoc
 create mode 100644 rules/S6562/impact-dotnet.adoc
 create mode 100644 rules/S6562/metadata.json
 create mode 100644 rules/S6562/resources-dotnet.adoc
 create mode 100644 rules/S6562/vbnet/metadata.json
 create mode 100644 rules/S6562/vbnet/rule.adoc
 create mode 100644 rules/S6562/why-dotnet.adoc

diff --git a/rules/S6562/csharp/metadata.json b/rules/S6562/csharp/metadata.json
new file mode 100644
index 0000000000..7a73a41bfd
--- /dev/null
+++ b/rules/S6562/csharp/metadata.json
@@ -0,0 +1,2 @@
+{
+}
\ No newline at end of file
diff --git a/rules/S6562/csharp/rule.adoc b/rules/S6562/csharp/rule.adoc
new file mode 100644
index 0000000000..9bad42e8d1
--- /dev/null
+++ b/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[]
\ No newline at end of file
diff --git a/rules/S6562/how-dotnet.adoc b/rules/S6562/how-dotnet.adoc
new file mode 100644
index 0000000000..a46b7b55d3
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/rules/S6562/impact-dotnet.adoc b/rules/S6562/impact-dotnet.adoc
new file mode 100644
index 0000000000..4de35fef5c
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/rules/S6562/metadata.json b/rules/S6562/metadata.json
new file mode 100644
index 0000000000..402eba00bc
--- /dev/null
+++ b/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"
+}
diff --git a/rules/S6562/resources-dotnet.adoc b/rules/S6562/resources-dotnet.adoc
new file mode 100644
index 0000000000..64787401ca
--- /dev/null
+++ b/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]
\ No newline at end of file
diff --git a/rules/S6562/vbnet/metadata.json b/rules/S6562/vbnet/metadata.json
new file mode 100644
index 0000000000..7a73a41bfd
--- /dev/null
+++ b/rules/S6562/vbnet/metadata.json
@@ -0,0 +1,2 @@
+{
+}
\ No newline at end of file
diff --git a/rules/S6562/vbnet/rule.adoc b/rules/S6562/vbnet/rule.adoc
new file mode 100644
index 0000000000..2e9ed1754b
--- /dev/null
+++ b/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[]
\ No newline at end of file
diff --git a/rules/S6562/why-dotnet.adoc b/rules/S6562/why-dotnet.adoc
new file mode 100644
index 0000000000..4f2858a284
--- /dev/null
+++ b/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.
\ No newline at end of file