Skip to content

Commit 6350b58

Browse files
(DOCSP-19708) Configuration (#4)
1 parent ca979d7 commit 6350b58

File tree

3 files changed

+183
-10
lines changed

3 files changed

+183
-10
lines changed

snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ title = "Visual Studio Extension"
55
product = "MongoDB Analyzer"
66
product-home-page = "TODO: Insert homepage link when available"
77
product-source-repo = "https://github.com/mongodb/mongo-csharp-analyzer"
8+
product-settings-file-constant = "mongodb.analyzer.json"
89
query-api = "MongoDB Query API"
910

1011
driver-long = "MongoDB .NET driver"

source/configuration.txt

Lines changed: 171 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,177 @@
1-
TODO: write
1+
.. _mongodb-analyzer-configuration:
22

3-
TODO: Incorporate Telemetery Information
3+
==============================
4+
Configure the {+product+}
5+
==============================
46

5-
.. important:: Telemetry
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
Learn how to configure the {+product+} in your .NET project and what
19+
configuration options are available.
20+
21+
Configuration
22+
-------------
23+
24+
To configure the {+product+}, perform the following actions:
25+
26+
#. Install the {+product+} as described in
27+
`the installation guide <TODO: ref link to the install guide once it's written>`__.
28+
29+
#. Create a file specifying your configuration for the {+product+} named
30+
``{+product-settings-file-constant+}``.
631

7-
When the {+product+} analyzes your source code, the extension
8-
sends the following information to MongoDB:
32+
.. important:: Naming
33+
34+
You must name your configuration file ``{+product-settings-file-constant+}``.
35+
36+
#. Add your configuration to your ``{+product-settings-file-constant+}`` file.
37+
38+
The following sample configuration makes the {+product+} use the
39+
`LINQ3 <{+driver-docs+}reference/driver/crud/linq3/>`__
40+
provider.
41+
42+
.. code-block:: json
43+
44+
{ "DefaultLinqVersion": "V3" }
45+
46+
#. Add the following to the ``.csproj`` file for your .NET application within the ``Project`` tag:
47+
48+
.. code-block:: xml
49+
50+
<ItemGroup>
51+
<AdditionalFiles Include="<path to your {+product-settings-file-constant+} file>" />
52+
</ItemGroup>
53+
54+
.. note:: Configuration is Optional
55+
56+
If you do not specify a configuration file, the {+product+} uses
57+
the default value for all
58+
:ref:`configuration options <mongodb-analyzer-configuration-options>`.
59+
60+
To learn more about .NET project files, see
61+
`Understanding the Project File <https://docs.microsoft.com/en-us/aspnet/web-forms/overview/deployment/web-deployment-in-the-enterprise/understanding-the-project-file>`__
62+
from Microsoft.
63+
64+
To learn more about the ``AdditionalFiles`` tag, see
65+
:github:`Using Additional Files </dotnet/roslyn/blob/main/docs/analyzers/Using%20Additional%20Files.md>`
66+
in the Roslyn documentation.
67+
68+
.. _mongodb-analyzer-configuration-options:
69+
70+
Options
71+
-------
72+
73+
The following is a description of all configuration options supported
74+
by the {+product+}:
75+
76+
.. list-table::
77+
:header-rows: 1
78+
:widths: 35 65
79+
80+
* - Name
81+
- Description
82+
83+
* - | **DefaultLinqVersion**
84+
- | **Type:** string
85+
|
86+
| **Description:**
87+
| The LINQ provider the {+product+} uses.
88+
89+
.. tip::
90+
91+
To learn more about LINQ, see the
92+
:ref:`Analyze Your Code <analyzer-analyze-linq>`
93+
page.
94+
95+
| **Default**: ``"V2"``
96+
| **Accepted Values**: ``"V2"`` or ``"V3"``
97+
98+
* - | **OutputDriverVersion**
99+
- | **Type:** boolean
100+
|
101+
| **Description:**
102+
| Specifies if the {+product+} includes your {+driver-short+} version in diagnostic messages.
103+
|
104+
| **Default**: ``false``
105+
| **Accepted Values**: ``true`` or ``false``
106+
107+
* - | **OutputInternalExceptions**
108+
- | **Type:** boolean
109+
|
110+
| **Description:**
111+
| Specifies if the {+product+} includes internal exceptions in diagnostic messages.
112+
|
113+
| **Default**: ``false``
114+
| **Accepted Values**: ``true`` or ``false``
115+
116+
* - | **OutputInternalLogsToFile**
117+
- | **Type:** boolean
118+
|
119+
| **Description:**
120+
| Specifies if the {+product+} writes its internal logs to a file.
121+
122+
.. include:: includes/logging-admonition.rst
123+
124+
| **Default**: ``false``
125+
| **Accepted Values**: ``true`` or ``false``
126+
127+
* - | **LogFileName**
128+
- | **Type:** string
129+
|
130+
| **Description:**
131+
| Specifies the path to which the {+product+} writes its internal logs.
132+
133+
.. include:: includes/logging-admonition.rst
134+
135+
| **Default**: ``""``
136+
| **Accepted Values**: A valid file path
137+
* - | **SendTelemetry**
138+
- | **Type:** boolean
139+
|
140+
| **Description:**
141+
| Specifies if the {+product+} collects and sends anonymized information
142+
to MongoDB Inc. to improve products.
143+
144+
.. tip::
145+
146+
To learn more about telemetry in the {+product+}, see the
147+
:ref:`<mongodb-analyzer-configuration-telemetry>`
148+
section of this guide.
149+
150+
| **Default**: ``true``
151+
| **Accepted Values**: ``true`` or ``false``
152+
153+
154+
To learn more about the configuration options the {+product+} supports,
155+
see the :github:`{+product+} source code </master/src/MongoDB.Analyzer/Core/Settings/SettingsHelper.cs>`.
156+
157+
.. _mongodb-analyzer-configuration-telemetry:
158+
159+
Telemetry
160+
~~~~~~~~~
161+
162+
When the {+product+} analyzes your source code, the tool by default
163+
collects and sends anonymized information to MongoDB Inc. to improve
164+
products.
165+
166+
To disable this feature, specify the following option in your configuration file:
167+
168+
.. code-block:: json
9169

10-
- Your .NET version installed in Visual Studio
11-
- Your operating system
12-
- TODO: Make sure this list is exhaustive
170+
"SendTelemetry": false
13171

14-
To disable this feature, TODO: Include how to disable.
172+
To view a complete list of all information collected by the {+product+} when you
173+
have enabled telemetry, see the `FAQ <TODO: link to this question in FAQ>`__
174+
page.
15175

16-
PREVIOUS DRAFT OF TELEMETRY STATEMENT ^
176+
To learn more about how MongoDB Inc. uses collected data, see the
177+
`Privacy Policy <https://www.mongodb.com/legal/privacy-policy>`__.
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. important::
2+
3+
To output logs, you must specify both a logfile and the ``OutputInternalLogsToFile`` option.
4+
5+
Use the following sample configuration to make the {+product+} output information to a logfile:
6+
7+
.. code-block:: json
8+
9+
"OutputInternalLogsToFile": true,
10+
"LogFileName": "<path to your logfile>"
11+

0 commit comments

Comments
 (0)