docsp-32855 - poco analysis (#53)

Author: mongoKart

source/analyze-code.txt

@@ -14,15 +14,17 @@ Analyze Your Code
 
    /code-type/builders
    /code-type/linq
+   /code-type/pocos
 
 Overview
 --------
 
 Learn how to use the {+product+} to analyze your {+driver-long+} code.
-The {+product+} can analyze expressions created with the following frameworks:
+The {+product+} can analyze expressions created with the following patterns:
 
 - :ref:`Builders Class <mongodb-analyzer-analyze-builders>`
 - :ref:`Language Integrated Query (LINQ) <mongodb-analyzer-analyze-linq>`
+- :ref:`Plain Old CLR/Class Objects (POCOs) <mongodb-analyzer-analyze-pocos>`
 
 Use the {+product+} From the Command Line
 ----------------------------------------------

source/code-type/pocos.txt

@@ -0,0 +1,108 @@
+.. _mongodb-analyzer-analyze-pocos:
+
+=============
+Analyze POCOs
+=============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+Plain old CLR objects, or plain old class objects (POCOs), are
+simple class objects that don't
+inherit features from any framework-specific base classes or interfaces.
+If your application uses POCOs, you can use the {+product+} to preview them as JSON
+objects.
+
+To learn more about POCOs, see the :wikipedia:`POCOs page on Wikipedia <Plain_old_CLR_object>`
+and the `Work with POCOs <{+driver-docs+}/fundamentals/data-formats/poco/>`__ page in the
+{+driver-short+} documentation.
+
+Preview as JSON
+---------------
+
+The following code sample shows an example of a POCO class definition
+and its corresponding JSON translation. By previewing your
+POCOs in JSON, you can see how BSON serialization attributes, such as ``BsonId`` and
+``BsonElement``, change the shape of the resulting BSON during serialization.
+
+.. io-code-block::
+   :copyable: false
+
+   .. input::
+      :language: csharp
+
+      class Order
+      {
+        [BsonId]
+        public int OrderNumber { get; set; }
+
+        [BsonElement("customer_id")]
+        public int CustomerId { get; set; }
+
+        public string Date { get; set; }
+
+        [BsonIgnore]
+        public string Email { get; set; }
+      }
+
+   .. output::
+      :language: json
+
+      {
+        "_id": 6783456,
+        "customer_id": 678234,
+        "Date": "06/03/2023"
+      }
+
+.. tip:: Sample Data
+
+   The {+product+} includes predefined sample values for certain common property names.
+   If you use
+   these property names in your POCO, the Analyzer uses the sample values in the JSON
+   output. For any property names without predefined sample values, the Analyzer uses a
+   random value that matches the property's data type.
+
+   For a list of property names with sample values, see the
+   `JSON sample value file <{+product-source-repo+}/blob/main/src/MongoDB.Analyzer/Core/Poco/Data/data.json>`__
+   in the {+product+} GitHub repo.
+
+Preview POCOs in Visual Studio
+------------------------------
+
+To preview your POCOs in Visual Studio, perform the following actions:
+
+1. Install the {+product+} as described in the :ref:`mongodb-analyzer-install`
+   guide.
+#. Define a POCO class.
+#. Move your cursor over the :guilabel:`...` ellipsis annotation beneath the first
+   word of your class definition to display an information message that contains
+   the JSON translation.
+
+Click on the following corresponding tab to see a POCO class definition
+with or without an information message displayed:
+
+.. tabs::
+
+   .. tab:: Without Information Message
+      :tabid: no-message
+
+      .. figure:: /includes/images/poco.png
+         :alt: Screenshot of POCO definition with an ellipsis annotation in Visual Studio
+
+   .. tab:: With Information Message
+      :tabid: message
+
+      .. figure:: /includes/images/poco-popup.png
+         :alt: Screenshot of POCO definition with an information message displayed in Visual Studio
+
+      .. tip:: Rule ID
+
+         The information message begins with the {+product+} Rule ID that generated the 
+         popup. In the previous example, the Rule ID is ``MAPoco1001``, indicating
+         the POCO is valid.

source/configuration.txt

@@ -81,88 +81,99 @@ by the {+product+}:
    * - | **DefaultLinqVersion**
      - | **Type:** string
        |
-       | **Description:**
-       | The LINQ provider the {+product+} uses.
+       | **Description:** The LINQ provider the {+product+} uses.
 
        .. tip::
 
           To learn more about LINQ, see the
           :ref:`Analyze Your Code <mongodb-analyzer-analyze-linq>`
           page.
 
-       | **Default**: ``"V2"``
        | **Accepted Values**: ``"V2"`` or ``"V3"``
+       | **Default**: ``"V2"``
 
    * - | **EnableVariableTracking**
      - | **Type:** boolean
        |
-       | **Description:**
-       | Specifies if the {+product+} tracks and composes builder expression variables.
+       | **Description:** Specifies if the {+product+} tracks and composes builder
+         expression variables.
 
        .. tip::
 
           To learn more about builder expressions, see the
           :ref:`Analyze Your Code <mongodb-analyzer-analyze-builders>`
           page.
 
-       | **Default**: ``true``
        | **Accepted Values**: ``true`` or ``false``
+       | **Default**: ``true``
+
+   * - | **LogFileName**
+     - | **Type:** string
+       |
+       | **Description:** Specifies the path to which the {+product+} writes its
+         internal logs.
+       
+       .. include:: includes/logging-admonition.rst       
+
+       | **Accepted Values**: A valid file path
+       | **Default**: ``""``
 
    * - | **OutputDriverVersion**
      - | **Type:** boolean
        |
-       | **Description:**
-       | Specifies if the {+product+} includes your {+driver-short+} version in diagnostic messages.
+       | **Description:** Specifies if the {+product+} includes your {+driver-short+}
+         version in diagnostic messages.
        |
-       | **Default**: ``false``
        | **Accepted Values**: ``true`` or ``false``
+       | **Default**: ``false``
 
    * - | **OutputInternalExceptions**
      - | **Type:** boolean
        |
-       | **Description:**
-       | Specifies if the {+product+} includes internal exceptions in diagnostic messages.
+       | **Description:** Specifies if the {+product+} includes internal exceptions in
+         diagnostic messages.
        |
-       | **Default**: ``false``
        | **Accepted Values**: ``true`` or ``false``
+       | **Default**: ``false``
 
    * - | **OutputInternalLogsToFile**
      - | **Type:** boolean
        |
-       | **Description:**
-       | Specifies if the {+product+} writes its internal logs to a file.
+       | **Description:** Specifies if the {+product+} writes its internal logs to a file.
 
        .. include:: includes/logging-admonition.rst       
 
-       | **Default**: ``false``
        | **Accepted Values**: ``true`` or ``false``
+       | **Default**: ``false``
 
-   * - | **LogFileName**
+   * - | **PocoAnalysisVerbosity**
      - | **Type:** string
        |
-       | **Description:**
-       | Specifies the path to which the {+product+} writes its internal logs.
+       | **Description:** Specifies which POCOs the {+product+} previews as JSON. You can
+         set this option to one of the following values:
 
-       .. include:: includes/logging-admonition.rst       
-
-       | **Default**: ``""``
-       | **Accepted Values**: A valid file path
+       - ``"All"``: Preview all POCOs
+       - ``"Medium"``: Preview only POCOs that are part of a LINQ or builders expression
+         or have BSON attributes
+       - ``"None"``: Do not preview POCOs
+       
+       | **Accepted Values**: ``"All"``, ``"Medium"``, or ``"None"``
+       | **Default**: ``"Medium"``
+   
    * - | **SendTelemetry**
      - | **Type:** boolean
        |
-       | **Description:**
-       | Specifies if the {+product+} collects and sends anonymized information
-         to MongoDB Inc. to improve products.
+       | **Description:** Specifies if the {+product+} collects and sends anonymized
+         information to MongoDB Inc. to improve products.
 
        .. tip::
 
           To learn more about telemetry in the {+product+}, see the
           :ref:`<mongodb-analyzer-configuration-telemetry>`
           section of this guide.
 
-       | **Default**: ``true``
        | **Accepted Values**: ``true`` or ``false``
-
+       | **Default**: ``true``
 
 To learn more about the configuration options the {+product+} supports,
 see the :github:`{+product+} source code </master/src/MongoDB.Analyzer/Core/Settings/SettingsHelper.cs>`.

source/includes/images/poco-popup.png

@@ -28,11 +28,14 @@ code:
 
 - How your code translates into the {+query-api+}
 - If your code includes unsupported LINQ or builder expressions
+- How your POCOs serialize to JSON 
 
-The {+product+} can analyze the following groups of {+driver-short+} expressions:
+The {+product+} can analyze the following groups of {+driver-short+} expressions and 
+classes:
 
 - `Builders <{+driver-docs+}/fundamentals/builders/>`__
 - `LINQ <{+driver-docs+}/fundamentals/linq/>`__
+- `POCOs <{+driver-docs+}/fundamentals/data-formats/poco/>`__
 
 Read the following sections of this guide to learn how to install the
 {+product+}, how to use its features, and how to configure it:

source/includes/images/poco.png

@@ -22,13 +22,13 @@ command from the root directory of your .NET project:
 
 .. code-block:: shell
 
-   Install-Package {+product-package-name+} -Version {+product-version-full+}
+   dotnet add package {+product-package-name+} -v {+product-version-full+} 
 
 To view the NuGet page for the {+product+}, see 
 `{+product-package-name+} <{+product-nuget-link+}>`__ on NuGet Gallery.
 
 To learn more about installing NuGet packages from the command line, see
-`NuGet Powershell Reference <https://docs.microsoft.com/en-us/nuget/reference/powershell-reference>`__
+`NuGet CLI Reference <https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli>`__
 from Microsoft.
 
 To learn more about installing NuGet packages from Visual Studio, see