usage-examples.txt

.. _csharp-usage-examples:

==============
Usage Examples
==============

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: code, .NET, operation
   :description: Explore C# usage examples for MongoDB operations, including synchronous and asynchronous code snippets, using sample datasets and custom serialization.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. toctree::

   Find a Document </usage-examples/findOne>
   Find Multiple Documents </usage-examples/findMany>
   Insert a Document </usage-examples/insertOne>
   Insert Multiple Documents </usage-examples/insertMany>
   Update a Document </usage-examples/updateOne>
   Update Many Documents </usage-examples/updateMany>
   Replace a Document </usage-examples/replaceOne>
   Delete a Document </usage-examples/deleteOne>
   Delete Many Documents </usage-examples/deleteMany>

Overview
--------

Usage examples provide convenient starting points for popular MongoDB
operations. Each example provides the following information:

- A code snippet that shows how to perform the operation in synchronous and
  asynchronous frameworks

- A link to a fully runnable console application using the operation

- The expected result after running the example

.. tip::

   Whether you use a synchronous or asynchronous framework in your application depends
   on your use case. Synchronous calls are more suitable for simple query workflows or
   when you must implement sequential logic. Consider using asynchronous calls if
   your application relies on multiple concurrent database requests or if your
   program doesn't require an immediate response from the database to continue
   executing.
   
   We encourage experimenting with both approaches to determine the most
   suitable framework for your purposes.

How to Use the Usage Examples
-----------------------------

These examples use the :atlas:`sample datasets </sample-data>`
provided by Atlas. You can load them into your database on the free tier of
MongoDB Atlas by following the
:atlas:`Get Started with Atlas Guide </getting-started/#atlas-getting-started>`
or you can
:guides:`import the sample dataset into a local MongoDB instance
</server/import/>`.

Once you have imported the dataset, you can copy and paste a usage
example into your development environment of choice. You can follow the
:ref:`csharp-quickstart` to learn more about getting
started with the {+driver-long+}. Once you've copied a usage example,
you'll need to edit the connection URI to get the example connected to
your MongoDB instance:

.. code-block:: csharp

   // Replace the following with your MongoDB deployment's connection string.
   private static string _mongoConnectionString = "<connection string>";

For more information about connecting to your MongoDB instance, see the
:ref:`Connection Guide <csharp-connection>`.

Example Classes
---------------

The usage examples in this section show how to perform operations on documents
in the ``restaurants`` collection. The examples use the following ``Restaurant``,
``Address``, and ``GradeEntry`` classes to model the data in this collection:

.. literalinclude:: /includes/code-examples/Restaurant.cs
   :language: csharp
   :copyable:
   :dedent:

.. literalinclude:: /includes/code-examples/Address.cs
   :language: csharp
   :copyable:
   :dedent:

.. literalinclude:: /includes/code-examples/GradeEntry.cs
   :language: csharp
   :copyable:
   :dedent:

.. include:: /includes/convention-pack-note.rst