Merge pull request #2 from mongoKart/quickstart

mongoKart · web-flow · commit 21a2fc3a94f9 · 2022-08-29T12:53:43.000-05:00
[DOCSP-24527] Quick Start page
diff --git a/snooty.toml b/snooty.toml
@@ -14,7 +14,10 @@ intersphinx = [
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 
 [constants]
-driver-long = "MongoDB C#/.NET Driver"
+driver-long = "MongoDB .NET/C# Driver"
+driver-short = ".NET/C# Driver"
+lang-framework = ".NET/C#"
+language = "C#"
 docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
 version = "v2.17" # always set this to the driver branch (i.e. v1.7.0, v1.8.0, etc.)
 example = "https://raw.githubusercontent.com/mongodb/docs-csharp/{+docs-branch+}/source/includes/usage-examples/code-snippets"
diff --git a/source/includes/figures/atlas_connection_copy_string.png b/source/includes/figures/atlas_connection_copy_string.png
diff --git a/source/includes/figures/atlas_connection_select_cluster.png b/source/includes/figures/atlas_connection_select_cluster.png
diff --git a/source/includes/language-compatibility-table-csharp.rst b/source/includes/language-compatibility-table-csharp.rst
@@ -1,10 +1,9 @@
-
 .. list-table::
    :header-rows: 1
    :stub-columns: 1
    :class: compatibility-large no-padding
 
-   * - C#/.NET Driver Version
+   * - {+driver-short+} Version
      - .NET 5/6 [#atlas-connection]_
      - .NET Core 3.1
      - .NET Core 3.0
@@ -262,8 +261,8 @@ through 4.8 only.
 
 .. [#atlas-connection] When using .NET 5/6, you can't connect to Atlas clusters running MongoDB 4.0 due to a certificate issue. This does not impact clusters running MongoDB 4.2+.
 
-.. [#2.14-note] .NET/C# driver versions 2.14 or later requires .NET Framework 4.7.2 or
+.. [#2.14-note] {+driver-short+} versions 2.14 or later requires .NET Framework 4.7.2 or
    later.
 
-.. [#4.5.2] .NET/C# driver versions 2.8 to 2.13 requires .NET Framework 4.5.2 or later.
+.. [#4.5.2] {+driver-short+} versions 2.8 to 2.13 requires .NET Framework 4.5.2 or later.
 
diff --git a/source/includes/mongodb-compatibility-table-csharp.rst b/source/includes/mongodb-compatibility-table-csharp.rst
@@ -1,10 +1,9 @@
-.. include:: /includes/compatibility-table-legend.rst
 .. list-table::
    :header-rows: 1
    :stub-columns: 1
    :class: compatibility-large
 
-   * - C#/.NET Driver Version
+   * - {+driver-short+} Version
      - MongoDB 6.0
      - MongoDB 5.0
      - MongoDB 4.4
diff --git a/source/includes/quick-start/Program.cs b/source/includes/quick-start/Program.cs
@@ -0,0 +1,19 @@
+using MongoDB.Driver;
+using MongoDB.Bson;
+
+string? connectionString = System.Environment.GetEnvironmentVariable("MONGODB_URI");
+if (connectionString == null)
+{
+    Console.WriteLine("You must set your 'MONGODB_URI' environmental variable. See\n\t https://www.mongodb.com/docs/drivers/go/current/usage-examples/#environment-variable");
+    Environment.Exit(0);
+}
+
+var client = new MongoClient(connectionString);
+
+var collection = client.GetDatabase("sample_mflix").GetCollection<BsonDocument>("movies");
+
+var filter = Builders<BsonDocument>.Filter.Eq("title", "Back to the Future");
+
+var document = collection.Find(filter).First();
+
+Console.WriteLine(document);
diff --git a/source/includes/quick-start/atlas-setup.rst b/source/includes/quick-start/atlas-setup.rst
@@ -0,0 +1,46 @@
+Set up a Free Tier Cluster in Atlas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After setting up your .NET project dependencies, create a MongoDB cluster
+where you can store and manage your data. Complete the
+:atlas:`Get Started with Atlas </getting-started>` guide to set up a new
+Atlas account and free tier MongoDB cluster, load datasets, and
+interact with the data.
+
+After completing the steps in the Atlas guide, you have a new MongoDB
+cluster deployed in Atlas, a new database user, and
+:atlas:`sample datasets loaded </sample-data/>` into your cluster.
+
+.. _csharp-connect-to-your-cluster:
+
+Connect to Your Cluster
+-----------------------
+
+In this step, you'll create and run an application that uses the {+driver-short+} to connect to your MongoDB cluster and run a query on the sample data.
+
+You pass instructions to the driver on where and how to connect to your
+MongoDB cluster in a string called the *connection string*. This string
+includes information on the hostname or IP address and port of your
+cluster, authentication mechanism, user credentials (when applicable), and
+other connection options.
+
+To retrieve your connection string for the cluster and user you created in
+the previous step, log into your Atlas account and navigate to the
+**Clusters** section, then click the **Connect** button for the cluster that you
+want to connect to, as shown below.
+
+.. figure:: /includes/figures/atlas_connection_select_cluster.png
+   :alt: Atlas Connection GUI cluster selection screen
+
+Proceed to the **Connect Your Application** step and select the {+driver-short+}. Then, click the **Copy** button to copy the *connection string*
+to your clipboard as shown below.
+
+.. figure:: /includes/figures/atlas_connection_copy_string.png
+   :alt: Atlas Connection GUI connection string screen
+
+Save your Atlas connection string in a safe location that you can access
+for the next step.
+
+To learn more about connecting to the {+driver-short+} through Atlas, see
+the :atlas:`Atlas driver connection guide </driver-connection>`
+and select **C#** from the *Select your language* dropdown.
diff --git a/source/includes/quick-start/next-steps.rst b/source/includes/quick-start/next-steps.rst
@@ -0,0 +1,3 @@
+Learn how to read and modify data using the {+driver-short+} in our Fundamentals
+CRUD guide or how to perform common operations from our
+:ref:`csharp-usage-examples`.
diff --git a/source/includes/quick-start/overview.rst b/source/includes/quick-start/overview.rst
@@ -0,0 +1,14 @@
+This guide shows you how to create an application that uses the **.NET/C# Driver**
+to connect to a **MongoDB Atlas cluster**. If you prefer to connect to MongoDB
+using a different driver or programming language, see our
+:driver:`list of official MongoDB drivers <>`.
+
+The .NET/C# driver lets you connect to and communicate with MongoDB clusters
+from a .NET application.
+
+MongoDB Atlas is a fully-managed cloud database service that hosts your data
+on MongoDB clusters. In this guide, we show you how to get started with your
+own free (no credit card required) cluster.
+
+Follow the steps below to connect your .NET application with a MongoDB Atlas
+cluster.
diff --git a/source/includes/quick-start/query-output.rst b/source/includes/quick-start/query-output.rst
@@ -0,0 +1,11 @@
+When you run ``Program.cs``, it should output the details of the following movie from
+the sample dataset:
+
+.. code-block:: json
+
+   {
+       "_id": "573a1398f29313caabce9682",
+       ...
+       "title": "Back to the Future",
+       ...
+   }
diff --git a/source/quick-start.txt b/source/quick-start.txt
@@ -0,0 +1,87 @@
+.. _csharp-quickstart:
+
+===========
+Quick Start
+===========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. include:: /includes/quick-start/overview.rst
+
+Set Up Your Project
+-------------------
+
+Create the Project
+~~~~~~~~~~~~~~~~~~
+
+Create a new directory and initialize your project with the ``dotnet new`` command, as follows:
+
+.. code-block:: shell
+
+   mkdir csharp-quickstart
+   cd csharp-quickstart
+   dotnet new console --framework net6.0
+
+.. _csharp-add-mongodb-dependency:
+
+Add MongoDB as a Dependency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the ``dotnet add`` command to add the {+driver-short+} to your project as a dependency.
+
+.. code-block:: shell
+
+   dotnet add package MongoDB.Driver
+
+Create a MongoDB Cluster
+------------------------
+
+.. include:: /includes/quick-start/atlas-setup.rst
+
+Query Your MongoDB Cluster from Your Application
+------------------------------------------------
+
+First, save your Atlas connection string to an environment variable named ``MONGODB_URI``. This prevents potential security issues caused by including your credentials in the source code.
+
+.. code-block:: bash
+
+   export MONGODB_URI='<your atlas connection string>'
+
+.. important::
+
+   Make sure to replace the "<username>" and "<password>" sections of the connection string with the username and password of your Atlas user.
+
+Next, open the file named ``Program.cs`` in the base directory of your project. Copy the
+following sample code into ``Program.cs`` 
+
+.. literalinclude:: /includes/quick-start/Program.cs
+   :language: csharp
+   :dedent:
+
+The sample code runs a query against your sample dataset in MongoDB Atlas. Run the sample code with the following command from your command line:
+
+.. code-block:: bash
+
+   dotnet run csharp-quickstart.csproj
+
+.. include:: /includes/quick-start/query-output.rst
+
+.. tip::
+
+   If your output is empty, ensure you have loaded the
+   :atlas:`sample datasets </sample-data/>` into your cluster.
+
+After completing this step, you should have a working application that uses
+the {+driver-short+} to connect to your MongoDB cluster, run a query on the
+sample data, and print out the result.
+
+Next steps
+----------
+
+.. include:: /includes/quick-start/next-steps.rst

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Learn how to read and modify data using the {+driver-short+} in our Fundamentals`
	`2`	`+CRUD guide or how to perform common operations from our`
	`3`	+:ref:`csharp-usage-examples`.