TOC Reorg - Get Started

snooty.toml

@@ -8,7 +8,8 @@ toc_landing_pages = [
     "/fundamentals/crud/write-operations/update-many",
     "/fundamentals/authentication",
     "/upgrade",
-    "/fundamentals/database-collection"
+    "/fundamentals/database-collection",
+    "/get-started"
 ]
 name = "csharp"
 title = "C#/.NET"

source/fundamentals/aggregation.txt

@@ -100,7 +100,7 @@ To perform an aggregation, pass a list of aggregation stages to the
 
   This example uses the ``sample_restaurants.restaurants`` collection
   from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-  free MongoDB Atlas cluster and load the sample datasets, see :ref:`csharp-quickstart`.
+  free MongoDB Atlas cluster and load the sample datasets, see :ref:`csharp-get-started`.
 
 The following code example produces a count of the number of bakeries in each borough
 of New York City. To do so, it uses an aggregation pipeline that contains the following stages:

source/fundamentals/builders.txt

@@ -434,7 +434,7 @@ have a defined Atlas Vector Search index before you can perform a vector search
 
 .. tip::
 
-   To obtain the sample dataset used in the following example, see :ref:`csharp-quickstart`.
+   To obtain the sample dataset used in the following example, see :ref:`csharp-get-started`.
    To create the sample Atlas Vector Search index used in the following example, see
    :atlas:`Create an Atlas Vector Search Index </atlas-vector-search/create-index>` in the
    Atlas manual.

source/fundamentals/crud/read-operations/change-streams.txt

@@ -30,7 +30,7 @@ Sample Data
 
 The examples in this guide use the ``sample_restaurants.restaurants`` collection
 from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
+free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-get-started>`.
 
 The examples on this page use the following ``Restaurant``, ``Address``, and ``GradeEntry`` 
 classes as models:

source/fundamentals/crud/read-operations/distinct.txt

@@ -34,7 +34,7 @@ Sample Data
 
 The examples in this guide use the ``sample_restaurants.restaurants`` collection
 from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
+free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-get-started>`.
 
 The examples on this page uses the following ``Restaurant`` class to model
 the documents in the collection:

source/fundamentals/crud/read-operations/project.txt

@@ -29,7 +29,7 @@ Sample Data
 
 The examples in this guide use the ``sample_restaurants.restaurants`` collection
 from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
+free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-get-started>`.
 
 Projection Types
 ----------------

source/fundamentals/crud/read-operations/retrieve.txt

@@ -39,7 +39,7 @@ Sample Data
 
 The examples in this guide use the ``sample_restaurants.restaurants`` collection
 from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
+free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-get-started>`.
 
 The examples on this page use the following ``Restaurant``, ``Address``, and ``GradeEntry`` 
 classes as models:

source/fundamentals/crud/write-operations/bulk-write.txt

@@ -32,7 +32,7 @@ Sample Data
 The examples in this guide use the ``sample_restaurants.restaurants`` collection
 from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
 free MongoDB Atlas cluster and load the sample datasets, see the
-:ref:`<csharp-quickstart>` tutorial.
+:ref:`<csharp-get-started>` tutorial.
 
 Define the Write Operations
 ---------------------------

source/fundamentals/crud/write-operations/delete.txt

@@ -44,7 +44,7 @@ classes as models:
 .. include:: /includes/convention-pack-note.rst
 
 This collection is from the :atlas:`sample datasets </sample-data>` provided
-by Atlas. See the :ref:`<csharp-quickstart>` to learn how to create a free MongoDB cluster
+by Atlas. See the :ref:`<csharp-get-started>` to learn how to create a free MongoDB cluster
 and load this sample data.
 
 Delete Operations

source/fundamentals/crud/write-operations/insert.txt

@@ -71,7 +71,7 @@ classes as models:
 .. include:: /includes/convention-pack-note.rst
 
 This collection is from the :atlas:`sample datasets </sample-data>` provided
-by Atlas. See the :ref:`<csharp-quickstart>` to learn how to create a free MongoDB cluster
+by Atlas. See the :ref:`<csharp-get-started>` to learn how to create a free MongoDB cluster
 and load this sample data.
 
 The ``_id`` Field

source/fundamentals/databases-collections/run-command.txt

@@ -45,7 +45,7 @@ Sample Data
 
 The examples in this guide use the ``sample_restaurants.restaurants`` collection
 from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
+free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-get-started>`.
 
 
 Execute a Command

source/fundamentals/geo.txt

@@ -187,7 +187,7 @@ Examples
 --------
 
 The following examples uses the MongoDB Atlas sample dataset. To obtain this sample
-dataset, see :ref:`csharp-quickstart`.
+dataset, see :ref:`csharp-get-started`.
 
 The examples use the ``theaters`` collection in the ``sample_mflix`` database
 from the sample dataset. The ``theaters`` collection contains a ``2dsphere`` index

source/fundamentals/indexes.txt

@@ -77,7 +77,7 @@ and provide sample code for creating each index type.
 
   These example uses the ``sample_mflix.movies`` and ``sample_mflix.theaters`` collections
   from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-  free MongoDB Atlas cluster and load the sample datasets, see :ref:`csharp-quickstart`.
+  free MongoDB Atlas cluster and load the sample datasets, see :ref:`csharp-get-started`.
 
 Single Field Indexes
 ~~~~~~~~~~~~~~~~~~~~

source/fundamentals/linq.txt

@@ -36,7 +36,7 @@ The {+driver-short+} automatically translates LINQ queries into
 The examples in this guide use the ``restaurants`` collection
 in the ``sample_restaurants`` database provided in the :atlas:`Atlas sample datasets </sample-data>`.
 To learn how to create a free MongoDB Atlas cluster and load the sample datasets,
-see the :ref:`<csharp-quickstart>`.
+see the :ref:`<csharp-get-started>`.
 
 The following ``Restaurant``, ``Address`` and ``GradeEntry`` classes model the
 documents in this collection:
@@ -635,7 +635,7 @@ defined Atlas Vector Search index before you can perform a vector search on your
 
 .. tip::
 
-   To obtain the sample dataset used in the following example, see :ref:`csharp-quickstart`.
+   To obtain the sample dataset used in the following example, see :ref:`csharp-get-started`.
    To create the sample Atlas Vector Search index used in the following example, see
    :atlas:`Create an Atlas Vector Search Index </atlas-vector-search/create-index>` in the
    Atlas manual.

source/fundamentals/odata.txt

@@ -32,7 +32,7 @@ Sample Data
 
 This tutorial uses the ``sample_restaurants.restaurants`` collection
 from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
-free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
+free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-get-started>`.
 
 Tutorial
 --------

source/get-started.txt

@@ -0,0 +1,44 @@
+.. _csharp-get-started:
+
+===================================
+Get Started with the {+driver-short+}
+===================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :description: Learn how to create an app to connect to MongoDB deployment by using the .NET/C# driver.
+   :keywords: quick start, tutorial, basics
+
+.. toctree::
+
+   Download the Driver </get-started/download-driver/>
+   Deploy a Cluster </get-started/deploy-cluster/>
+   Create a Connection String </get-started/create-connection-string/>
+   Run a Sample Query </get-started/run-sample-query/>
+
+Overview
+--------
+
+The {+driver-short+} is a NuGet package that you can use to connect
+to and communicate with MongoDB. This guide shows you how to create an
+application that uses the {+driver-short+} to connect to a MongoDB cluster hosted on
+MongoDB Atlas.
+
+.. tip:: 
+
+   MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
+   deployments. You can create your own free (no credit card required) MongoDB Atlas 
+   deployment by following the steps in this guide.
+
+Follow this guide to connect a sample {+language+} application to a MongoDB Atlas
+deployment. If you prefer to connect to MongoDB using a different driver or
+programming language, see our :driver:`list of official drivers <>`.

source/get-started/create-connection-string.txt

@@ -0,0 +1,86 @@
+.. _csharp-get-started-connection-string:
+
+==========================
+Create a Connection String
+==========================
+
+You can connect to your MongoDB deployment by providing a
+**connection URI**, also called a *connection string*, which
+instructs the driver on how to connect to a MongoDB deployment
+and how to behave while connected.
+
+The connection string includes the hostname or IP address and 
+port of your deployment, the authentication mechanism, user credentials 
+when applicable, and connection options.
+
+.. tip::
+
+   To connect to a self-managed (non-Atlas) deployment, see
+   :ref:`csharp-connect-to-mongodb`.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Find your MongoDB Atlas Connection String
+
+      To retrieve your connection string for the deployment that
+      you created in the :ref:`previous step <csharp-get-started-deploy-cluster>`,
+      log into your Atlas account and navigate to the
+      :guilabel:`Database` section and click the :guilabel:`Connect` button
+      for your new deployment.
+
+      .. figure:: /includes/figures/atlas_connection_select_cluster.png
+         :alt: The connect button in the clusters section of the Atlas UI
+
+      Proceed to the :guilabel:`Connect your application` section and select
+      "C# / .NET" from the :guilabel:`Driver` selection menu and the version
+      that best matches the version you installed from the :guilabel:`Version`
+      selection menu.
+
+      Select the :guilabel:`Password (SCRAM)` authentication mechanism.
+
+      Deselect the :guilabel:`Include full driver code example` option to view
+      the connection string.
+
+   .. step:: Copy your Connection String
+
+      Click the button on the right of the connection string to copy it to
+      your clipboard as shown in the following screenshot:
+
+      .. figure:: /includes/figures/atlas_connection_copy_string.png
+         :alt: The connection string copy button in the Atlas UI
+
+   .. step:: Update the Placeholders
+
+      Paste this connection string into a file in your preferred text editor
+      and replace the ``<db_username>`` and ``<db_password>`` placeholders with
+      your database user's username and password.
+
+      Save this file to a safe location for use in the next step.
+
+   .. step:: Set an Environment Variable
+
+      In your shell, run the following code to save your MongoDB
+      :ref:`connection string <csharp-connect-to-mongodb>` to an 
+      environment variable. Replace ``<your MongoDB URI>`` with the connection
+      string that you saved to a file in the previous step.
+
+      .. code-block:: bash
+
+         export MONGODB_URI="<your MongoDB URI>"
+
+      .. note:: PowerShell
+
+         If you're using Microsoft PowerShell, run the following command instead:
+
+         .. code-block:: bash
+
+            set MONGODB_URI="<your MongoDB URI>"
+
+      Storing your credentials in an environment variable is safer than hardcoding them
+      in your source code.   
+
+After completing these steps, you have a connection string that
+contains your database username and password.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst

source/get-started/deploy-cluster.txt

@@ -0,0 +1,29 @@
+.. _csharp-get-started-deploy-cluster:
+
+==============================
+Deploy a MongoDB Atlas Cluster
+==============================
+
+You can create a free tier MongoDB deployment on MongoDB Atlas
+to store and manage your data. MongoDB Atlas hosts and manages
+your MongoDB database in the cloud.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a Free MongoDB Deployment on Atlas
+
+      Complete the :atlas:`Get Started with Atlas </getting-started>`
+      guide to set up a new Atlas account and load sample data into a new free
+      tier MongoDB deployment.
+
+   .. step:: Save your Credentials
+
+      After you create your database user, save that user's 
+      username and password to a safe location for use in an upcoming step.
+
+After you complete these steps, you have a new free tier MongoDB
+deployment on Atlas, database user credentials, and sample data loaded
+in your database.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst

source/get-started/download-driver.txt

@@ -0,0 +1,34 @@
+.. _csharp-get-started-download-driver:
+
+===========================
+Download the {+driver-short+} 
+===========================
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create a Project Directory
+
+      In your shell, run the following commands to create a 
+      directory called ``csharp-quickstart`` and initialize a {+framework+} project for
+      a new console application:
+
+      .. code-block:: bash
+
+         mkdir csharp-quickstart
+         cd csharp-quickstart
+         dotnet new console
+
+   .. step:: Install the {+driver-short+}
+
+      Run the following command to install the current version of the {+driver-short+}
+      as a dependency of your project:
+
+      .. code-block:: bash
+
+         dotnet add package MongoDB.Driver
+
+After you complete these steps, you have a new {+framework+} project
+and the {+driver-short+} installed.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst

source/get-started/run-sample-query.txt

@@ -0,0 +1,49 @@
+.. _csharp-get-started-run-sample-query:
+
+==================
+Run a Sample Query
+==================
+
+.. procedure::
+   :style: connected
+
+   .. step:: Create your {+lang-framework+} Application
+
+      Copy and paste the following code into the ``Program.cs`` file in your application:
+
+      .. literalinclude:: /includes/quick-start/Program.cs
+         :language: csharp
+         :dedent:
+
+   .. step:: Run your Application
+
+      In your shell, run the following command to start this application:
+
+      .. code-block:: sh
+
+         dotnet run csharp-quickstart.csproj
+
+      The output includes details of the retrieved movie document:
+
+      .. code-block:: none
+
+         {
+           _id: ...,
+           plot: 'A young man is accidentally sent 30 years into the past...',
+           genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ],
+           ...
+           title: 'Back to the Future',
+           ...
+         }
+
+      .. tip::
+
+         If you encounter an error or see no output, ensure that you specified the
+         proper connection string, and that you loaded the
+         sample data.
+
+After you complete these steps, you have a working application that
+uses the driver to connect to your MongoDB deployment, runs a query on
+the sample data, and prints out the result.
+
+.. include:: /includes/get-started/quickstart-troubleshoot.rst