diff --git a/snooty.toml b/snooty.toml index 085ef4b7..61696522 100644 --- a/snooty.toml +++ b/snooty.toml @@ -1,15 +1,7 @@ toc_landing_pages = [ - "/fundamentals/connection", - "/fundamentals/crud", - "/usage-examples", - "/fundamentals", - "/fundamentals/serialization", - "/fundamentals/crud/write-operations/update-one", - "/fundamentals/crud/write-operations/update-many", - "/fundamentals/authentication", - "/upgrade", - "/fundamentals/database-collection", - "/get-started" + "/get-started", + "/connect/connection-options", + "/security/authentication" ] name = "csharp" title = "C#/.NET" @@ -47,5 +39,5 @@ string-data-type = "``string``" int-data-type = "``integer``" not-available = "N/A" analyzer = "MongoDB C# Analyzer" -analyzer-short = "C# Analzyer" +analyzer-short = "C# Analyzer" query-api = "MongoDB Query API" diff --git a/source/fundamentals/linq.txt b/source/aggregation.txt similarity index 80% rename from source/fundamentals/linq.txt rename to source/aggregation.txt index a66598c0..404bf1ea 100644 --- a/source/fundamentals/linq.txt +++ b/source/aggregation.txt @@ -1,15 +1,369 @@ -.. _csharp-linq: +.. _csharp-aggregation: -==== -LINQ -==== +=========== +Aggregation +=========== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, transform, pipeline .. contents:: On this page :local: :backlinks: none - :depth: 3 + :depth: 2 :class: singlecol +Overview +-------- + +In this guide, you can learn how to use the {+driver-long+} to perform +**aggregation operations**. + +Aggregation operations process data in your MongoDB collections and +return computed results. The MongoDB Aggregation framework is modeled on the +concept of data processing pipelines. Documents enter a pipeline comprised of one or +more stages, and this pipeline transforms the documents into an aggregated result. + +Analogy +~~~~~~~ + +Aggregation operations function similarly to car factories with assembly +lines. The assembly lines have stations with specialized tools to +perform specific tasks. For example, when building a car, the assembly +line begins with the frame. Then, as the car frame moves through the +assembly line, each station assembles a separate part. The result is a +transformed final product, the finished car. + +The assembly line represents the *aggregation pipeline*, the individual +stations represent the *aggregation stages*, the specialized tools +represent the *expression operators*, and the finished product +represents the *aggregated result*. + +Compare Aggregation and Find Operations +--------------------------------------- + +The following table lists the different tasks you can perform with find +operations, compared to what you can achieve with aggregation +operations. The aggregation framework provides expanded functionality +that allows you to transform and manipulate your data. + +.. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Find Operations + - Aggregation Operations + + * - | Select *certain* documents to return + | Select *which* fields to return + | Sort the results + | Limit the results + | Count the results + - | Select *certain* documents to return + | Select *which* fields to return + | Sort the results + | Limit the results + | Count the results + | Group the results + | Rename fields + | Compute new fields + | Summarize data + | Connect and merge data sets + +Server Limitations +------------------ + +Consider the following :manual:`limitations ` when +performing aggregation operations: + +- Returned documents must not violate the :manual:`BSON document size limit ` + of 16 megabytes. + +- Pipeline stages have a memory limit of 100 megabytes by default. If required, you can exceed this limit by setting + the `AllowDiskUse <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateOptions.AllowDiskUse.html#MongoDB_Driver_AggregateOptions_AllowDiskUse>`__ + property of the ``AggregateOptions`` object that you pass to the ``Aggregate()`` method. + +- The :manual:`$graphLookup ` stage has + a strict memory limit of 100 megabytes and ignores the ``AllowDiskUse`` property. + +Aggregation Example +------------------- + +To perform an aggregation, pass a list of aggregation stages to the +``IMongoCollection.Aggregate()`` method. + +.. note:: + + This example uses the ``sample_restaurants.restaurants`` collection + from the :atlas:`Atlas sample datasets `. To learn how to create a + 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: + +- A :manual:`$match ` stage to filter for documents whose + ``cuisine`` field contains the value ``"Bakery"``. + +- A :manual:`$group ` stage to group the matching + documents by the ``borough`` field, accumulating a count of documents for each distinct value + of that field. + +The following sections implement this example by using LINQ, Builders, and BsonDocument +approaches to create and combine the aggregation stages used in the example pipeline. + +LINQ Approach +~~~~~~~~~~~~~ + +.. io-code-block:: + + .. input:: /includes/fundamentals/code-examples/LinqAggregation.cs + :language: csharp + :dedent: + :start-after: begin-aggregation + :end-before: end-aggregation + + .. output:: + :language: console + :visible: false + + { _id = Bronx, Count = 71 } + { _id = Brooklyn, Count = 173 } + { _id = Staten Island, Count = 20 } + { _id = Missing, Count = 2 } + { _id = Manhattan, Count = 221 } + { _id = Queens, Count = 204 } + +To learn more about using LINQ to construct aggregation pipelines, see the +:ref:`csharp-linq` guide. + +Builders Approach +~~~~~~~~~~~~~~~~~ + +.. io-code-block:: + + .. input:: /includes/fundamentals/code-examples/BuilderAggregation.cs + :language: csharp + :dedent: + :start-after: begin-aggregation + :end-before: end-aggregation + + .. output:: + :language: console + :visible: false + + { _id = Bronx, Count = 71 } + { _id = Brooklyn, Count = 173 } + { _id = Staten Island, Count = 20 } + { _id = Missing, Count = 2 } + { _id = Manhattan, Count = 221 } + { _id = Queens, Count = 204 } + +To learn more about using builders to construct aggregation pipelines, +see the :ref:`csharp-builders-aggregation` section of the Operations with Builders guide. + +BsonDocument Approach +~~~~~~~~~~~~~~~~~~~~~ + +.. io-code-block:: + + .. input:: /includes/fundamentals/code-examples/Aggregation.cs + :language: csharp + :dedent: + :start-after: begin-aggregation + :end-before: end-aggregation + + .. output:: + :language: console + :visible: false + + { "_id" : "Brooklyn", "count" : 173 } + { "_id" : "Manhattan", "count" : 221 } + { "_id" : "Bronx", "count" : 71 } + { "_id" : "Missing", "count" : 2 } + { "_id" : "Staten Island", "count" : 20 } + { "_id" : "Queens", "count" : 204 } + +Additional Information +---------------------- + +MongoDB Server Manual +~~~~~~~~~~~~~~~~~~~~~ + +To view a full list of expression operators, see +:manual:`Aggregation Operators `. + +To learn more about assembling an aggregation pipeline and view examples, see +:manual:`Aggregation Pipeline `. + +To learn more about creating pipeline stages, see +:manual:`Aggregation Stages `. + +To learn about explaining MongoDB aggregation operations, see +:manual:`Explain Results ` and +:manual:`Query Plans `. + +API Documentation +~~~~~~~~~~~~~~~~~ + +For more information about the aggregation operations discussed in this guide, see the +following API documentation: + +- `Aggregate() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.Aggregate.html>`__ +- `AggregateOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateOptions.html>`__ +- `Group() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineStageDefinitionBuilder.Group.html>`__ +- `Match() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineStageDefinitionBuilder.Match.html>`__ +- `Where() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Where.html>`__ +- `GroupBy() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.GroupBy.html>`__ +- `Select() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Select.html>`__ + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +.. _csharp-builders-aggregation: + +Build an Aggregation Pipeline +----------------------------- + +The ``PipelineDefinitionBuilder`` class provides a type-safe interface for +defining an **aggregation pipeline**. An aggregation pipeline is a series of +stages that are used to transform a document. Suppose you want to create a +pipeline that performs the following operations: + +- Matches all documents with "spring" in the ``Season`` field +- Sorts the results by the ``Category`` field +- Groups the documents by category and shows the average price and total + available for all documents in that category + +Use ``PipelineDefinitionBuilder`` classes to build the pipeline: + +.. code-block:: csharp + + var sortBuilder = Builders.Sort.Ascending(f => f.Category); + var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); + + var pipeline = new EmptyPipelineDefinition() + .Match(matchFilter) + .Sort(sortBuilder) + .Group(f => f.Category, + g => new + { + name = g.Key, + avgPrice = g.Average(f => f.Price), + totalAvailable = g.Sum(f => f.Stock) + } + ); + +The preceding example creates the following pipeline: + +.. code-block:: json + + [{ "$match" : { "season" : "spring" } }, { "$sort" : { "category" : 1 } }, { "$group" : { "_id" : "$category", "avgPrice" : { "$avg" : "$price" }, "totalAvailable" : { "$sum" : "$stock" } } }] + +You can add stages to your pipeline that don't have corresponding type-safe +methods in the ``PipelineDefinitionBuilder`` interface by providing your query +as a ``BsonDocument`` to the `AppendStage() method +<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.AppendStage.html>`__. + +.. code-block:: csharp + + var pipeline = new EmptyPipelineDefinition().AppendStage("{ $set: { field1: '$field2' } }"); + +.. note:: + + When using a ``BsonDocument`` to define your pipeline stage, the driver does + not take into account any ``BsonClassMap``, serialization attributes or + serialization conventions. The field names used in the ``BsonDocument`` must + match those stored on the server. + + For more information on providing a query as a ``BsonDocument``, see our + :ref:`FAQ page `. + +To learn more about the Aggregation Pipeline, see the +:manual:`Aggregation Pipeline ` server manual page. + +.. _csharp-builders-out: + +Write Pipeline Results to a Collection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can write the documents returned from an aggregation pipeline to a +collection by creating an ``$out`` stage at the end of your aggregation +pipeline. To create an ``$out`` stage, call the ``Out()`` method on a +``PipelineStageDefinitionBuilder``. The ``Out()`` method requires the name of +the collection you want to write the documents to. + +The following example builds an aggregation pipeline that matches all documents +with a ``season`` field value of ``"Spring"`` and outputs them to +a ``springFlowers`` collection: + +.. code-block:: csharp + + var outputCollection = database.GetCollection("springFlowers"); + var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); + + // Creates an aggregation pipeline and outputs resulting documents to a new collection. + var pipeline = new EmptyPipelineDefinition() + .Match(matchFilter) + .Out(outputCollection); + +You can write the results of an aggregation pipeline to a time series collection +by specifying a ``TimeSeriesOption`` object and passing it as the second +parameter to the ``Out()`` method. + +Imagine that the documents in the ``plants.flowers`` collection contain a ``datePlanted`` field that +holds BSON date values. You can store the documents in this collection in a time +series collection by using the ``datePlanted`` field as the time field. + +The following example creates a ``TimeSeriesOptions`` object and specifies +``datePlanted`` as the ``timeField``. It then builds an aggregation pipeline that matches all documents +with a ``season`` field value of ``"Spring"`` and outputs them to a +time series collection called ``springFlowerTimes``. + +.. code-block:: csharp + + var timeSeriesOptions = new TimeSeriesOptions("datePlanted"); + var collectionName = "springFlowerTimes" + var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); + + // Creates an aggregation pipeline and outputs resulting documents to a time series collection. + var pipeline = new EmptyPipelineDefinition() + .Match(matchFilter) + .Out(collectionName, timeSeriesOptions); + +To learn more about time series collections, see :ref:`csharp-time-series`. + + +- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__ + +.. TODO: integrate into existing page + +.. _csharp-linq: + +==== +LINQ +==== + .. facet:: :name: genre :values: reference diff --git a/source/fundamentals/atlas-search.txt b/source/atlas-search.txt similarity index 96% rename from source/fundamentals/atlas-search.txt rename to source/atlas-search.txt index 4dae38c5..770674ef 100644 --- a/source/fundamentals/atlas-search.txt +++ b/source/atlas-search.txt @@ -683,3 +683,33 @@ The search returns the following document: To learn more about the ``wildcard`` operator, see the :atlas:`wildcard ` Atlas guide. + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Build an Atlas Search Query +--------------------------- + +The ``Search`` class provides a type-safe interface for creating a +:manual:`$search ` +pipeline stage. + +To learn how to construct search queries with the ``Search`` class, see +:ref:`csharp-atlas-search`. diff --git a/source/fundamentals/builders.txt b/source/atlas-vector-search.txt similarity index 62% rename from source/fundamentals/builders.txt rename to source/atlas-vector-search.txt index 4ccf6189..73e37027 100644 --- a/source/fundamentals/builders.txt +++ b/source/atlas-vector-search.txt @@ -1,48 +1,21 @@ -.. _csharp-builders: +.. _csharp-atlas-vector-search: -======================== -Operations with Builders -======================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol +=================== +Atlas Vector Search +=================== .. facet:: :name: genre :values: reference - + .. meta:: - :keywords: aggregation, query, code example - -Overview --------- - -.. include:: /includes/linq-vs-builders.rst - -In this guide, you can learn about the helper classes, or **builders**, that -the {+driver-short+} provides to create types used in your operations. -Using builders helps you identify errors at compile time and avoid them -at runtime. This guide provides information on builder classes that you -can use for the following tasks: + :keywords: semantic -- Creating a filter definition -- Creating a projection -- Defining a sort order -- Defining an update operation -- Selecting index keys - -.. tip:: {+analyzer+} - - The {+analyzer-short+} is a tool that helps you analyze your - builders definitions and understand how your {+lang-framework+} code - translates into the {+query-api+}. For more information and - installation instructions, see the `{+analyzer-short+} reference page `__. - -You should read this guide if you want to learn more about how to -construct definitions and build up syntax using builders. +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol Sample Class ------------ @@ -62,371 +35,6 @@ Each builder class takes a generic type parameter with. In this guide, the ``Flower`` class is the document type used in each builder class example. -Construct a Filter ------------------- - -The ``FilterDefinitionBuilder`` class provides a type-safe interface for -building up queries. Suppose you want to query your collection for -documents matching the following criteria: - -- ``Price`` field value less than 20 -- ``Category`` field value is "Perennial" - -Use builders to create the filter definition with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt(f => f.Price, 20) & builder.Eq(f => f.Category, "Perennial"); - -Using the typed variant form provides compile-time safety. Additionally, -your IDE can provide refactoring support. - -Alternatively, you can use string-based field names to contruct the filter: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); - -If you are using LINQ, you can also use the ``Inject()`` method to apply the filter -to a LINQ query: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); - var query = collection.AsQueryable().Where(f => filter.Inject()); - -Array Operators -~~~~~~~~~~~~~~~ - -If your document has properties or fields that serialize to arrays, -you can use the methods beginning with ``Any``, such as ``AnyEq()`` or -``AnyLt()``, to compare the entire array against a single item. - -Use builders to check which documents in the collection have a -``Season`` array that includes "winter": - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.AnyEq(f => f.Season, "winter"); - -You can also call the ``ElemMatch()`` method to find documents that have an -array field that contains at least one element that matches a specified search -criteria. The following example returns documents that contain the value -``"Summer"`` in their ``Season`` array: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.ElemMatch(f => f.Season, s => s == "Summer"); - -To learn more about array operators, see the :manual:`Array Query Operators -` guide in the {+mdb-server+} manual. - -.. _csharp-builders-projection: - -Create a Projection -------------------- - -The ``ProjectionDefinitionBuilder`` class provides a type-safe interface for -defining a projection. Suppose you want to create a projection on the -``Name`` and ``Price`` fields, but exclude the ``Id`` field. - -Use builders to create the projection definition with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Include(f => f.Name).Include(f => f.Price).Exclude(f => f.Id); - -You can also use string-based field names to define the projection: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Include("Name").Include("Price").Exclude("Id"); - -Finally, you can use the ``Expression()`` method to define the -projection: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Expression(f => new { Name = f.Name, Price = f.Price }); - -This definition has a return type of ``ProjectionDefinition`` whereas the others return a -``ProjectionDefinition``. - -Lambda Expressions -~~~~~~~~~~~~~~~~~~ - -The driver supports using lambda expressions to render projections. When -you define a ``Find()`` projection with the ``Expression()`` method to -create a lambda expression, the driver inspects the expression -to determine which fields are referenced and automatically constructs a -server-side projection to return only those fields. - -You can also use lambda expressions to create new fields by performing -operations on values in your documents. The following example shows how -you can use a lambda expression to project a new ``Profit`` field -using the ``Price`` and ``Stock`` fields: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Expression(f => new { Profit = f.Price * f.Stock }); - -.. note:: ``Id`` Field Exclusion - - When you create a projection using a lambda expression, the output - automatically excludes the ``Id`` field unless you explicitly include - is as a projection field. - -Define a Sort -------------- - -The ``SortDefinitionBuilder`` class provides a type-safe interface for -building up sort syntax. Suppose you want to define a sort with the -following order: - -- Ascending on ``Price`` -- Descending on ``Category`` - -Use builders to create the sort definition with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Sort; - var sort = builder.Ascending(f => f.Price).Descending(f => f.Category); - -Alternatively, you can use string-based field names to define the sort: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Sort; - var sort = builder.Ascending("Price").Descending("Category"); - -Define an Update ----------------- - -The ``UpdateDefinitionBuilder`` class provides a type-safe interface for -building up an update specification. Suppose you want to create an -update specification with the following criteria: - -- Create the new field ``SunRequirement`` -- Multiply the ``Price`` field value by 0.9 - -Use builders to create the update specification with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Update; - var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9); - -Alternatively, you can use string-based field names to define the update: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Update; - var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9); - -.. _csharp-builders-indexes: - -Define Index Keys ------------------ - -The ``IndexKeysDefinitionBuilder`` class provides a type-safe interface for -defining index keys. Suppose you want to select ``Category`` as an -ascending index key. - -Use builders to select the index key with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - var keys = builder.Ascending(f => f.Category); - -Alternatively, you can use string-based field names to select the index key: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - var keys = builder.Ascending("Category"); - -The ``IndexKeysDefinitionBuilder`` class also provides methods to build -a wildcard index. You can create a wildcard index using ``All field paths`` or ``A -single field path``, in this case using ``Category``: - -.. tabs:: - - .. tab:: ``All field paths`` - :tabid: all-wildcard-index - - .. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - var keys = builder.Wildcard(); - - .. tab:: ``A single field path`` - :tabid: single-wildcard-index - - .. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - - // Using the typed variant - var keys = builder.Wildcard(f => f.Category); - - // Using string-based field names - var keys = builder.Wildcard("Category"); - -For more information about how to use wildcard indexes, see -:manual:`Wildcard Indexes `. - -.. _csharp-builders-aggregation: - -Build an Aggregation Pipeline ------------------------------ - -The ``PipelineDefinitionBuilder`` class provides a type-safe interface for -defining an **aggregation pipeline**. An aggregation pipeline is a series of -stages that are used to transform a document. Suppose you want to create a -pipeline that performs the following operations: - -- Matches all documents with "spring" in the ``Season`` field -- Sorts the results by the ``Category`` field -- Groups the documents by category and shows the average price and total - available for all documents in that category - -Use ``PipelineDefinitionBuilder`` classes to build the pipeline: - -.. code-block:: csharp - - var sortBuilder = Builders.Sort.Ascending(f => f.Category); - var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); - - var pipeline = new EmptyPipelineDefinition() - .Match(matchFilter) - .Sort(sortBuilder) - .Group(f => f.Category, - g => new - { - name = g.Key, - avgPrice = g.Average(f => f.Price), - totalAvailable = g.Sum(f => f.Stock) - } - ); - -The preceding example creates the following pipeline: - -.. code-block:: json - - [{ "$match" : { "season" : "spring" } }, { "$sort" : { "category" : 1 } }, { "$group" : { "_id" : "$category", "avgPrice" : { "$avg" : "$price" }, "totalAvailable" : { "$sum" : "$stock" } } }] - -You can add stages to your pipeline that don't have corresponding type-safe -methods in the ``PipelineDefinitionBuilder`` interface by providing your query -as a ``BsonDocument`` to the `AppendStage() method -<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.AppendStage.html>`__. - -.. code-block:: csharp - - var pipeline = new EmptyPipelineDefinition().AppendStage("{ $set: { field1: '$field2' } }"); - -.. note:: - - When using a ``BsonDocument`` to define your pipeline stage, the driver does - not take into account any ``BsonClassMap``, serialization attributes or - serialization conventions. The field names used in the ``BsonDocument`` must - match those stored on the server. - - For more information on providing a query as a ``BsonDocument``, see our - :ref:`FAQ page `. - -To learn more about the Aggregation Pipeline, see the -:manual:`Aggregation Pipeline ` server manual page. - -.. _csharp-builders-out: - -Write Pipeline Results to a Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can write the documents returned from an aggregation pipeline to a -collection by creating an ``$out`` stage at the end of your aggregation -pipeline. To create an ``$out`` stage, call the ``Out()`` method on a -``PipelineStageDefinitionBuilder``. The ``Out()`` method requires the name of -the collection you want to write the documents to. - -The following example builds an aggregation pipeline that matches all documents -with a ``season`` field value of ``"Spring"`` and outputs them to -a ``springFlowers`` collection: - -.. code-block:: csharp - - var outputCollection = database.GetCollection("springFlowers"); - var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); - - // Creates an aggregation pipeline and outputs resulting documents to a new collection. - var pipeline = new EmptyPipelineDefinition() - .Match(matchFilter) - .Out(outputCollection); - -You can write the results of an aggregation pipeline to a time series collection -by specifying a ``TimeSeriesOption`` object and passing it as the second -parameter to the ``Out()`` method. - -Imagine that the documents in the ``plants.flowers`` collection contain a ``datePlanted`` field that -holds BSON date values. You can store the documents in this collection in a time -series collection by using the ``datePlanted`` field as the time field. - -The following example creates a ``TimeSeriesOptions`` object and specifies -``datePlanted`` as the ``timeField``. It then builds an aggregation pipeline that matches all documents -with a ``season`` field value of ``"Spring"`` and outputs them to a -time series collection called ``springFlowerTimes``. - -.. code-block:: csharp - - var timeSeriesOptions = new TimeSeriesOptions("datePlanted"); - var collectionName = "springFlowerTimes" - var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); - - // Creates an aggregation pipeline and outputs resulting documents to a time series collection. - var pipeline = new EmptyPipelineDefinition() - .Match(matchFilter) - .Out(collectionName, timeSeriesOptions); - -To learn more about time series collections, see :ref:`csharp-time-series`. - -Build an Atlas Search Query ---------------------------- - -The ``Search`` class provides a type-safe interface for creating a -:manual:`$search ` -pipeline stage. - -To learn how to construct search queries with the ``Search`` class, see -:ref:`csharp-atlas-search`. - Perform an Atlas Vector Search ------------------------------ @@ -488,28 +96,4 @@ The results of the preceding example contain the following documents: { "_id" : ObjectId("573a13e5f29313caabdc40c9"), "plot" : "A dimension-traveling wizard gets stuck in the 21st century because cell-phone radiation interferes with his magic. With his home world on the brink of war, he seeks help from a jaded ...", "title" : "The Portal" } To learn more about Atlas Vector Search, see :atlas:`Atlas Vector Search Overview ` -in the Atlas manual. - -Troubleshooting ---------------- - -.. include:: /includes/troubleshooting/unsupported-filter-expression.rst - -Additional Information ----------------------- - -Find runnable examples using builders for various operations under -:ref:`Usage Examples `. - -API Documentation -~~~~~~~~~~~~~~~~~ - -To learn more about any of the methods or types discussed in this -guide, see the following API Documentation: - -- `FilterDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinitionBuilder-1.html>`__ -- `ProjectionDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.html>`__ -- `SortDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinitionBuilder-1.html>`__ -- `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__ -- `IndexKeysDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IndexKeysDefinitionBuilder-1.html>`__ -- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__ \ No newline at end of file +in the Atlas manual. \ No newline at end of file diff --git a/source/connect.txt b/source/connect.txt new file mode 100644 index 00000000..6f15db31 --- /dev/null +++ b/source/connect.txt @@ -0,0 +1,28 @@ +.. _csharp-connect: + +================== +Connect to MongoDB +================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use the {+driver-short+} to connect to MongoDB. + :keywords: client, ssl + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Create a MongoClient + Choose a Connection Target + Specify Connection Options + Connection Troubleshooting \ No newline at end of file diff --git a/source/fundamentals/connection/connection-options.txt b/source/connect/connection-options.txt similarity index 97% rename from source/fundamentals/connection/connection-options.txt rename to source/connect/connection-options.txt index 21c26c7f..2d4198e0 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/source/connect/connection-options.txt @@ -17,6 +17,16 @@ Connection Options :depth: 2 :class: singlecol +.. toctree:: + :caption: Specify Connection Options + + Compress Network Traffic + Customize Server Selection + Stable API + Limit Server Execution Time + Connection Pools + Connect from AWS Lambda + This section describes the MongoDB connection and authentication options available in the {+driver-short+}. You can configure your connection using either the connection URI or a ``MongoClientSettings`` object. diff --git a/source/fundamentals/connection/connection-pools.txt b/source/connect/connection-options/connection-pools.txt similarity index 100% rename from source/fundamentals/connection/connection-pools.txt rename to source/connect/connection-options/connection-pools.txt diff --git a/source/connect/connection-options/csot.txt b/source/connect/connection-options/csot.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/fundamentals/connection/network-compression.txt b/source/connect/connection-options/network-compression.txt similarity index 100% rename from source/fundamentals/connection/network-compression.txt rename to source/connect/connection-options/network-compression.txt diff --git a/source/fundamentals/connection/server-selection.txt b/source/connect/connection-options/server-selection.txt similarity index 100% rename from source/fundamentals/connection/server-selection.txt rename to source/connect/connection-options/server-selection.txt diff --git a/source/fundamentals/stable-api.txt b/source/connect/connection-options/stable-api.txt similarity index 100% rename from source/fundamentals/stable-api.txt rename to source/connect/connection-options/stable-api.txt diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt similarity index 99% rename from source/connection-troubleshooting.txt rename to source/connect/connection-troubleshooting.txt index 6e0877a6..6c914198 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -18,8 +18,6 @@ using the {+driver-long+} to connect to a MongoDB deployment. This page addresses only connection issues. If you encounter any other issues with MongoDB or the driver, visit the following resources: - - The :ref:`Frequently Asked Questions (FAQ) ` for the - {+driver-short+} - The :ref:`Issues & Help ` page, which has information about reporting bugs, contributing to the driver, and finding additional resources diff --git a/source/fundamentals/connection/connect.txt b/source/connect/mongoclient.txt similarity index 97% rename from source/fundamentals/connection/connect.txt rename to source/connect/mongoclient.txt index 2e8b8625..99dbfde5 100644 --- a/source/fundamentals/connection/connect.txt +++ b/source/connect/mongoclient.txt @@ -1,8 +1,9 @@ .. _csharp-connect-to-mongodb: +.. _csharp-create-mongoclient: -================ -Connection Guide -================ +==================== +Create a MongoClient +==================== .. facet:: :name: genre @@ -18,7 +19,7 @@ Connection Guide :class: singlecol This guide shows you how to connect to a MongoDB instance or replica set -deployment using the {+driver-short+}. +deployment by using the {+driver-short+}. .. _csharp_connection_uri: diff --git a/source/crud.txt b/source/crud.txt new file mode 100644 index 00000000..e18b8ec5 --- /dev/null +++ b/source/crud.txt @@ -0,0 +1,24 @@ +.. _csharp-crud: + +=============== +CRUD Operations +=============== + +.. meta:: + :description: Learn how to run create, read, update, delete (CRUD) MongoDB operations by using the {+driver-long+}. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Insert Documents + Query Documents + Update One Document + Update Many Documents + Replace Documents + Delete Documents + Bulk Write Operations + Transactions + Store Large Files + Configure CRUD Operations + Geospatial Queries diff --git a/source/fundamentals/crud/write-operations/bulk-write.txt b/source/crud/bulk-write.txt similarity index 100% rename from source/fundamentals/crud/write-operations/bulk-write.txt rename to source/crud/bulk-write.txt diff --git a/source/fundamentals/read-write-configuration.txt b/source/crud/configure.txt similarity index 100% rename from source/fundamentals/read-write-configuration.txt rename to source/crud/configure.txt diff --git a/source/fundamentals/crud/write-operations/delete.txt b/source/crud/delete.txt similarity index 100% rename from source/fundamentals/crud/write-operations/delete.txt rename to source/crud/delete.txt diff --git a/source/fundamentals/geo.txt b/source/crud/geo.txt similarity index 100% rename from source/fundamentals/geo.txt rename to source/crud/geo.txt diff --git a/source/fundamentals/gridfs.txt b/source/crud/gridfs.txt similarity index 100% rename from source/fundamentals/gridfs.txt rename to source/crud/gridfs.txt diff --git a/source/fundamentals/crud/write-operations/insert.txt b/source/crud/insert.txt similarity index 99% rename from source/fundamentals/crud/write-operations/insert.txt rename to source/crud/insert.txt index e7f3e53f..0530e7df 100644 --- a/source/fundamentals/crud/write-operations/insert.txt +++ b/source/crud/insert.txt @@ -228,8 +228,8 @@ The following code uses the ``InsertMany()`` method to insert five new The ``InsertMany()`` method has no return value. You can verify that your documents were successfully inserted by executing a ``Find()`` -operation on the collection. For an example on how to find a document, -see :ref:`csharp-find-one`. +operation on the collection. For an example of how to find a document, +see :ref:`csharp-find`. .. _csharp-ordered-behavior: diff --git a/source/crud/query.txt b/source/crud/query.txt new file mode 100644 index 00000000..93468c74 --- /dev/null +++ b/source/crud/query.txt @@ -0,0 +1,21 @@ +.. _csharp-crud-read-operations: +.. _csharp-crud-query: + +=============== +Read Operations +=============== + +.. meta:: + :description: Learn about the commands for running MongoDB read operations by using the {+driver-long+}. + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Specify a Query + Find Documents + Specify Documents to Return + Specify Fields to Return + Count Documents + Distinct Field Values + Access Data from a Cursor \ No newline at end of file diff --git a/source/fundamentals/crud/read-operations/count.txt b/source/crud/query/count.txt similarity index 99% rename from source/fundamentals/crud/read-operations/count.txt rename to source/crud/query/count.txt index 53dcede1..cc2e4aa1 100644 --- a/source/fundamentals/crud/read-operations/count.txt +++ b/source/crud/query/count.txt @@ -231,7 +231,6 @@ guides: - :ref:`csharp-specify-query` - :ref:`csharp-bson` - :ref:`csharp-guids` -- :ref:`csharp-builders` - :ref:`csharp-poco` API Documentation diff --git a/source/crud/query/cursors.txt b/source/crud/query/cursors.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/fundamentals/crud/read-operations/distinct.txt b/source/crud/query/distinct.txt similarity index 100% rename from source/fundamentals/crud/read-operations/distinct.txt rename to source/crud/query/distinct.txt diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/crud/query/find.txt similarity index 99% rename from source/fundamentals/crud/read-operations/retrieve.txt rename to source/crud/query/find.txt index 4527d807..f5f2526e 100644 --- a/source/fundamentals/crud/read-operations/retrieve.txt +++ b/source/crud/query/find.txt @@ -1,4 +1,4 @@ -.. _csharp-retrieve: +.. _csharp-find: ============= Retrieve Data diff --git a/source/fundamentals/crud/read-operations/project.txt b/source/crud/query/project.txt similarity index 66% rename from source/fundamentals/crud/read-operations/project.txt rename to source/crud/query/project.txt index 6ad03656..cd24ad2d 100644 --- a/source/fundamentals/crud/read-operations/project.txt +++ b/source/crud/query/project.txt @@ -142,4 +142,90 @@ guide, see the following API Documentation: - `Find() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`_ - `Projection <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Builders-1.Projection.html>`_ - `Include() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Include.html>`_ -- `Exclude() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Exclude.html>`_ \ No newline at end of file +- `Exclude() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Exclude.html>`_ + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +.. _csharp-builders-projection: + +Create a Projection +------------------- + +The ``ProjectionDefinitionBuilder`` class provides a type-safe interface for +defining a projection. Suppose you want to create a projection on the +``Name`` and ``Price`` fields, but exclude the ``Id`` field. + +Use builders to create the projection definition with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Include(f => f.Name).Include(f => f.Price).Exclude(f => f.Id); + +You can also use string-based field names to define the projection: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Include("Name").Include("Price").Exclude("Id"); + +Finally, you can use the ``Expression()`` method to define the +projection: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Expression(f => new { Name = f.Name, Price = f.Price }); + +This definition has a return type of ``ProjectionDefinition`` whereas the others return a +``ProjectionDefinition``. + +Lambda Expressions +~~~~~~~~~~~~~~~~~~ + +The driver supports using lambda expressions to render projections. When +you define a ``Find()`` projection with the ``Expression()`` method to +create a lambda expression, the driver inspects the expression +to determine which fields are referenced and automatically constructs a +server-side projection to return only those fields. + +You can also use lambda expressions to create new fields by performing +operations on values in your documents. The following example shows how +you can use a lambda expression to project a new ``Profit`` field +using the ``Price`` and ``Stock`` fields: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Expression(f => new { Profit = f.Price * f.Stock }); + +.. note:: ``Id`` Field Exclusion + + When you create a projection using a lambda expression, the output + automatically excludes the ``Id`` field unless you explicitly include + is as a projection field. + +- `ProjectionDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/fundamentals/crud/read-operations/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt similarity index 89% rename from source/fundamentals/crud/read-operations/specify-documents-to-return.txt rename to source/crud/query/specify-documents-to-return.txt index 99e7d85f..54a3b1c7 100644 --- a/source/fundamentals/crud/read-operations/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -203,7 +203,7 @@ skipping the first ``10`` documents: Additional Information ---------------------- -For more information about retrieving documents, see the :ref:`csharp-retrieve` guide. +For more information about retrieving documents, see the :ref:`csharp-find` guide. For more information about specifying a query, see the :ref:`csharp-specify-query` guide. @@ -217,4 +217,26 @@ guide, see the following API documentation: - `IFindFluent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.html>`_ - `Limit() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Limit.html>`_ - `Sort() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Sort.html>`_ -- `Skip() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Skip.html>`_ \ No newline at end of file +- `Skip() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Skip.html>`_ + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +- `SortDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/fundamentals/specify-query.txt b/source/crud/query/specify-query.txt similarity index 77% rename from source/fundamentals/specify-query.txt rename to source/crud/query/specify-query.txt index 22bfa38b..bf508679 100644 --- a/source/fundamentals/specify-query.txt +++ b/source/crud/query/specify-query.txt @@ -109,8 +109,6 @@ same documents as the preceding example: var result = _guitarsCollection.Find(Builders.Filter.Empty).ToList(); -To learn more about using builders, see :ref:`csharp-builders`. - Comparison Operators -------------------- @@ -171,9 +169,6 @@ same documents as the preceding example: { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null } - -To learn more about using builders, see :ref:`csharp-builders`. - Logical Operators ----------------- @@ -232,8 +227,6 @@ same documents as the preceding example: { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 } -To learn more about using builders, see :ref:`csharp-builders`. - Array Operators --------------- @@ -285,8 +278,6 @@ documents that have 3 elements in the ``models`` field: { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 } { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null } -To learn more about using builders, see :ref:`csharp-builders`. - Element Operators ----------------- @@ -313,8 +304,6 @@ documents that have a ``rating`` field: { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 } { "_id" : 5, "make" : "Ibanez", "models" : ["RG", "AZ"], "establishedYear" : 1957, "rating" : 7 } -To learn more about using builders, see :ref:`csharp-builders`. - Evaluation Operators -------------------- @@ -332,7 +321,7 @@ documents that have a value in the ``make`` field that starts with the letter .. io-code-block:: :copyable: - .. input:: ../../../includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs + .. input:: /includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs :language: csharp .. output:: @@ -341,8 +330,6 @@ documents that have a value in the ``make`` field that starts with the letter { "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 } -To learn more about using builders, see :ref:`csharp-builders`. - Additional Information ---------------------- @@ -355,6 +342,95 @@ following Server Manual Entries: - :manual:`Element Query Operators ` - :manual:`Evaluation Query Operators ` -To learn more about using Builders, see :ref:`csharp-builders`. - To learn how to specify queries using LINQ, see :ref:`csharp-linq`. + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Construct a Filter +------------------ + +The ``FilterDefinitionBuilder`` class provides a type-safe interface for +building up queries. Suppose you want to query your collection for +documents matching the following criteria: + +- ``Price`` field value less than 20 +- ``Category`` field value is "Perennial" + +Use builders to create the filter definition with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.Lt(f => f.Price, 20) & builder.Eq(f => f.Category, "Perennial"); + +Using the typed variant form provides compile-time safety. Additionally, +your IDE can provide refactoring support. + +Alternatively, you can use string-based field names to contruct the filter: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); + +If you are using LINQ, you can also use the ``Inject()`` method to apply the filter +to a LINQ query: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); + var query = collection.AsQueryable().Where(f => filter.Inject()); + +Array Operators +~~~~~~~~~~~~~~~ + +If your document has properties or fields that serialize to arrays, +you can use the methods beginning with ``Any``, such as ``AnyEq()`` or +``AnyLt()``, to compare the entire array against a single item. + +Use builders to check which documents in the collection have a +``Season`` array that includes "winter": + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.AnyEq(f => f.Season, "winter"); + +You can also call the ``ElemMatch()`` method to find documents that have an +array field that contains at least one element that matches a specified search +criteria. The following example returns documents that contain the value +``"Summer"`` in their ``Season`` array: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.ElemMatch(f => f.Season, s => s == "Summer"); + +To learn more about array operators, see the :manual:`Array Query Operators +` guide in the {+mdb-server+} manual. + +- `FilterDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/fundamentals/crud/write-operations/replace.txt b/source/crud/replace.txt similarity index 100% rename from source/fundamentals/crud/write-operations/replace.txt rename to source/crud/replace.txt diff --git a/source/fundamentals/transactions.txt b/source/crud/transactions.txt similarity index 100% rename from source/fundamentals/transactions.txt rename to source/crud/transactions.txt diff --git a/source/fundamentals/crud/write-operations/update-many.txt b/source/crud/update-many.txt similarity index 67% rename from source/fundamentals/crud/write-operations/update-many.txt rename to source/crud/update-many.txt index 7d46dfce..d4db84ef 100644 --- a/source/fundamentals/crud/write-operations/update-many.txt +++ b/source/crud/update-many.txt @@ -20,8 +20,8 @@ Update Many .. toctree:: :caption: Update Documents - Fields - Arrays + Fields + Arrays .. include:: /includes/page-templates/update/update.rst @@ -126,4 +126,50 @@ Update Many :start-after: // start-pipeline-async :end-before: // end-pipeline-async +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Define an Update +---------------- + +The ``UpdateDefinitionBuilder`` class provides a type-safe interface for +building up an update specification. Suppose you want to create an +update specification with the following criteria: + +- Create the new field ``SunRequirement`` +- Multiply the ``Price`` field value by 0.9 + +Use builders to create the update specification with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9); + +Alternatively, you can use string-based field names to define the update: +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9); + +- `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/fundamentals/crud/write-operations/update-many/arrays.txt b/source/crud/update-many/arrays.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-many/arrays.txt rename to source/crud/update-many/arrays.txt diff --git a/source/fundamentals/crud/write-operations/update-many/fields.txt b/source/crud/update-many/fields.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-many/fields.txt rename to source/crud/update-many/fields.txt diff --git a/source/fundamentals/crud/write-operations/update-one.txt b/source/crud/update-one.txt similarity index 61% rename from source/fundamentals/crud/write-operations/update-one.txt rename to source/crud/update-one.txt index 9afb9fd3..5bdd1db7 100644 --- a/source/fundamentals/crud/write-operations/update-one.txt +++ b/source/crud/update-one.txt @@ -20,8 +20,8 @@ Update One .. toctree:: :caption: Update Documents - Fields - Arrays + Fields + Arrays .. include:: /includes/page-templates/update/update.rst @@ -112,4 +112,52 @@ Update One :copyable: true :dedent: :start-after: // start-pipeline-async - :end-before: // end-pipeline-async \ No newline at end of file + :end-before: // end-pipeline-async + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Define an Update +---------------- + +The ``UpdateDefinitionBuilder`` class provides a type-safe interface for +building up an update specification. Suppose you want to create an +update specification with the following criteria: + +- Create the new field ``SunRequirement`` +- Multiply the ``Price`` field value by 0.9 + +Use builders to create the update specification with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9); + +Alternatively, you can use string-based field names to define the update: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9); + +- `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/fundamentals/crud/write-operations/update-one/arrays.txt b/source/crud/update-one/arrays.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-one/arrays.txt rename to source/crud/update-one/arrays.txt diff --git a/source/fundamentals/crud/write-operations/update-one/fields.txt b/source/crud/update-one/fields.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-one/fields.txt rename to source/crud/update-one/fields.txt diff --git a/source/data-formats.txt b/source/data-formats.txt new file mode 100644 index 00000000..7bd3b913 --- /dev/null +++ b/source/data-formats.txt @@ -0,0 +1,41 @@ +.. _csharp-data-formats: + +======================== +Specialized Data Formats +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: bson, guid, serialization, extended json, custom types, time series + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + BSON + Extended JSON + Custom Types + GUIDs + Time Series Data + +Overview +-------- + +You can use several types of specialized data formats in your {+driver-short+} +application. To learn how to work with these data formats, see the following +sections: + +- Learn how to work with BSON documents in the :ref:`csharp-bson` guide. +- Learn how to translate BSON to Extended JSON in the :ref:`csharp-extended-json` guide. +- Learn how to serialize custom types in the :ref:`csharp-custom-types` guide. +- Learn about globally unique identifiers (GUIDs) and how to maintain cross-language + compatibility while working with them in the :ref:`csharp-guids` guide. \ No newline at end of file diff --git a/source/fundamentals/bson.txt b/source/data-formats/bson.txt similarity index 100% rename from source/fundamentals/bson.txt rename to source/data-formats/bson.txt diff --git a/source/data-formats/custom-types.txt b/source/data-formats/custom-types.txt new file mode 100644 index 00000000..d05e1fc3 --- /dev/null +++ b/source/data-formats/custom-types.txt @@ -0,0 +1,26 @@ +.. _csharp-custom-types: + +============ +Custom Types +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: polymorphism, serialization, deserialization, poco + +.. toctree:: + :caption: Custom Types + + Class Mapping + POCOs + Polymorphic Objects + Serialization \ No newline at end of file diff --git a/source/fundamentals/serialization/class-mapping.txt b/source/data-formats/custom-types/class-mapping.txt similarity index 100% rename from source/fundamentals/serialization/class-mapping.txt rename to source/data-formats/custom-types/class-mapping.txt diff --git a/source/fundamentals/serialization/poco.txt b/source/data-formats/custom-types/poco.txt similarity index 99% rename from source/fundamentals/serialization/poco.txt rename to source/data-formats/custom-types/poco.txt index 143d3059..196249ad 100644 --- a/source/fundamentals/serialization/poco.txt +++ b/source/data-formats/custom-types/poco.txt @@ -728,9 +728,6 @@ Additional Information For a full list of serialization-related attributes, see the `Serialization.Attributes API documentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Attributes.html>`__. -For additional read and write operation examples using POCOs, see the :ref:`Usage Examples -` or the :ref:`CRUD Fundamentals Pages `. - To learn more about how the driver maps BSON documents to POCOs, see :ref:`csharp-class-mapping`. diff --git a/source/fundamentals/serialization/polymorphic-objects.txt b/source/data-formats/custom-types/polymorphic-objects.txt similarity index 100% rename from source/fundamentals/serialization/polymorphic-objects.txt rename to source/data-formats/custom-types/polymorphic-objects.txt diff --git a/source/fundamentals/serialization.txt b/source/data-formats/custom-types/serialization.txt similarity index 96% rename from source/fundamentals/serialization.txt rename to source/data-formats/custom-types/serialization.txt index a144c98a..af352a0b 100644 --- a/source/fundamentals/serialization.txt +++ b/source/data-formats/custom-types/serialization.txt @@ -17,14 +17,6 @@ Serialization :depth: 2 :class: singlecol -.. toctree:: - :caption: Serialization - - Class Mapping - POCOs - Polymorphic Objects - GUIDs - Overview -------- diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt new file mode 100644 index 00000000..c2a69aa8 --- /dev/null +++ b/source/data-formats/extended-json.txt @@ -0,0 +1,11 @@ +.. _csharp-extended-json: + +============= +Extended JSON +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol \ No newline at end of file diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/data-formats/guids.txt similarity index 100% rename from source/fundamentals/serialization/guid-serialization.txt rename to source/data-formats/guids.txt diff --git a/source/fundamentals/time-series.txt b/source/data-formats/time-series.txt similarity index 99% rename from source/fundamentals/time-series.txt rename to source/data-formats/time-series.txt index b1b2e6c0..78384c13 100644 --- a/source/fundamentals/time-series.txt +++ b/source/data-formats/time-series.txt @@ -90,7 +90,7 @@ Query a Time Series Collection ------------------------------ To query a time series collection, follow the conventions for retrieving and aggregating -data. For more information about these conventions, see the :ref:`csharp-retrieve` and +data. For more information about these conventions, see the :ref:`csharp-find` and :ref:`csharp-aggregation` guides. Additional Information diff --git a/source/fundamentals/database-collection.txt b/source/databases-collections.txt similarity index 99% rename from source/fundamentals/database-collection.txt rename to source/databases-collections.txt index 919d9e03..9cf8ad93 100644 --- a/source/fundamentals/database-collection.txt +++ b/source/databases-collections.txt @@ -1,4 +1,5 @@ .. _csharp-db-coll: +.. _csharp-databases-collections: ========================= Databases and Collections @@ -17,9 +18,6 @@ Databases and Collections :depth: 2 :class: singlecol -.. toctree:: - /fundamentals/databases-collections/run-command - Overview -------- diff --git a/source/fundamentals.txt b/source/fundamentals.txt deleted file mode 100644 index fe326063..00000000 --- a/source/fundamentals.txt +++ /dev/null @@ -1,58 +0,0 @@ -.. _csharp-fundamentals: - -============ -Fundamentals -============ - -.. meta:: - :description: Learn how to use the (+driver-long+} to run commands on MongoDB. - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Connection - Databases & Collections - CRUD Operations - Operations with Builders - Atlas Search - Stable API - Authentication - Aggregation - LINQ - BSON Operations - Query - Serialization - Transactions - Indexes - Logging - Time Series Collections - In-Use Encryption - Search Geospatially - Store Large Files - Replica Set Operations - OData - Monitoring - -- :ref:`Connecting to MongoDB ` -- :ref:`csharp-db-coll` -- :ref:`csharp-crud` -- :ref:`csharp-builders` -- :ref:`csharp-atlas-search` -- :ref:`csharp-stable-api` -- :ref:`csharp-authentication-mechanisms` -- :ref:`csharp-aggregation` -- :ref:`csharp-linq` -- :ref:`csharp-bson` -- :ref:`csharp-specify-query` -- :ref:`csharp-serialization` -- :ref:`csharp-transactions` -- :ref:`csharp-indexes` -- :ref:`csharp-logging` -- :ref:`csharp-time-series` -- :ref:`Encrypt Fields ` -- :ref:`csharp-geo` -- :ref:`csharp-gridfs` -- :ref:`csharp-read-write-config` -- :ref:`csharp-odata` -- :ref:`csharp-monitoring` \ No newline at end of file diff --git a/source/fundamentals/aggregation.txt b/source/fundamentals/aggregation.txt deleted file mode 100644 index 96169dd5..00000000 --- a/source/fundamentals/aggregation.txt +++ /dev/null @@ -1,221 +0,0 @@ -.. _csharp-aggregation: - -=========== -Aggregation -=========== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, transform, pipeline - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn how to use the {+driver-long+} to perform -**aggregation operations**. - -Aggregation operations process data in your MongoDB collections and -return computed results. The MongoDB Aggregation framework is modeled on the -concept of data processing pipelines. Documents enter a pipeline comprised of one or -more stages, and this pipeline transforms the documents into an aggregated result. - -Analogy -~~~~~~~ - -Aggregation operations function similarly to car factories with assembly -lines. The assembly lines have stations with specialized tools to -perform specific tasks. For example, when building a car, the assembly -line begins with the frame. Then, as the car frame moves through the -assembly line, each station assembles a separate part. The result is a -transformed final product, the finished car. - -The assembly line represents the *aggregation pipeline*, the individual -stations represent the *aggregation stages*, the specialized tools -represent the *expression operators*, and the finished product -represents the *aggregated result*. - -Compare Aggregation and Find Operations ---------------------------------------- - -The following table lists the different tasks you can perform with find -operations, compared to what you can achieve with aggregation -operations. The aggregation framework provides expanded functionality -that allows you to transform and manipulate your data. - -.. list-table:: - :header-rows: 1 - :widths: 50 50 - - * - Find Operations - - Aggregation Operations - - * - | Select *certain* documents to return - | Select *which* fields to return - | Sort the results - | Limit the results - | Count the results - - | Select *certain* documents to return - | Select *which* fields to return - | Sort the results - | Limit the results - | Count the results - | Group the results - | Rename fields - | Compute new fields - | Summarize data - | Connect and merge data sets - -Server Limitations ------------------- - -Consider the following :manual:`limitations ` when -performing aggregation operations: - -- Returned documents must not violate the :manual:`BSON document size limit ` - of 16 megabytes. - -- Pipeline stages have a memory limit of 100 megabytes by default. If required, you can exceed this limit by setting - the `AllowDiskUse <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateOptions.AllowDiskUse.html#MongoDB_Driver_AggregateOptions_AllowDiskUse>`__ - property of the ``AggregateOptions`` object that you pass to the ``Aggregate()`` method. - -- The :manual:`$graphLookup ` stage has - a strict memory limit of 100 megabytes and ignores the ``AllowDiskUse`` property. - -Aggregation Example -------------------- - -To perform an aggregation, pass a list of aggregation stages to the -``IMongoCollection.Aggregate()`` method. - -.. note:: - - This example uses the ``sample_restaurants.restaurants`` collection - from the :atlas:`Atlas sample datasets `. To learn how to create a - 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: - -- A :manual:`$match ` stage to filter for documents whose - ``cuisine`` field contains the value ``"Bakery"``. - -- A :manual:`$group ` stage to group the matching - documents by the ``borough`` field, accumulating a count of documents for each distinct value - of that field. - -The following sections implement this example by using LINQ, Builders, and BsonDocument -approaches to create and combine the aggregation stages used in the example pipeline. - -LINQ Approach -~~~~~~~~~~~~~ - -.. io-code-block:: - - .. input:: /includes/fundamentals/code-examples/LinqAggregation.cs - :language: csharp - :dedent: - :start-after: begin-aggregation - :end-before: end-aggregation - - .. output:: - :language: console - :visible: false - - { _id = Bronx, Count = 71 } - { _id = Brooklyn, Count = 173 } - { _id = Staten Island, Count = 20 } - { _id = Missing, Count = 2 } - { _id = Manhattan, Count = 221 } - { _id = Queens, Count = 204 } - -To learn more about using LINQ to construct aggregation pipelines, see the -:ref:`csharp-linq` guide. - -Builders Approach -~~~~~~~~~~~~~~~~~ - -.. io-code-block:: - - .. input:: /includes/fundamentals/code-examples/BuilderAggregation.cs - :language: csharp - :dedent: - :start-after: begin-aggregation - :end-before: end-aggregation - - .. output:: - :language: console - :visible: false - - { _id = Bronx, Count = 71 } - { _id = Brooklyn, Count = 173 } - { _id = Staten Island, Count = 20 } - { _id = Missing, Count = 2 } - { _id = Manhattan, Count = 221 } - { _id = Queens, Count = 204 } - -To learn more about using builders to construct aggregation pipelines, -see the :ref:`csharp-builders-aggregation` section of the Operations with Builders guide. - -BsonDocument Approach -~~~~~~~~~~~~~~~~~~~~~ - -.. io-code-block:: - - .. input:: /includes/fundamentals/code-examples/Aggregation.cs - :language: csharp - :dedent: - :start-after: begin-aggregation - :end-before: end-aggregation - - .. output:: - :language: console - :visible: false - - { "_id" : "Brooklyn", "count" : 173 } - { "_id" : "Manhattan", "count" : 221 } - { "_id" : "Bronx", "count" : 71 } - { "_id" : "Missing", "count" : 2 } - { "_id" : "Staten Island", "count" : 20 } - { "_id" : "Queens", "count" : 204 } - -Additional Information ----------------------- - -MongoDB Server Manual -~~~~~~~~~~~~~~~~~~~~~ - -To view a full list of expression operators, see -:manual:`Aggregation Operators `. - -To learn more about assembling an aggregation pipeline and view examples, see -:manual:`Aggregation Pipeline `. - -To learn more about creating pipeline stages, see -:manual:`Aggregation Stages `. - -To learn about explaining MongoDB aggregation operations, see -:manual:`Explain Results ` and -:manual:`Query Plans `. - -API Documentation -~~~~~~~~~~~~~~~~~ - -For more information about the aggregation operations discussed in this guide, see the -following API documentation: - -- `Aggregate() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.Aggregate.html>`__ -- `AggregateOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateOptions.html>`__ -- `Group() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineStageDefinitionBuilder.Group.html>`__ -- `Match() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineStageDefinitionBuilder.Match.html>`__ -- `Where() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Where.html>`__ -- `GroupBy() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.GroupBy.html>`__ -- `Select() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Select.html>`__ diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt deleted file mode 100644 index 3b0ec89a..00000000 --- a/source/fundamentals/connection.txt +++ /dev/null @@ -1,31 +0,0 @@ -.. _csharp-connection: - -========== -Connection -========== - -.. default-domain:: mongodb - -.. toctree:: - - Connection Guide - Connection Options - Configure TLS - Network Compression - Connect with AWS Lambda - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -Overview --------- - -In this section, you'll learn how to use the {+driver-short+} to connect your application to a MongoDB deployment. Click a link in the following list to jump to a topic: - -- :ref:`How to Connect to MongoDB ` -- :ref:`Connection Options ` -- :ref:`Enable TLS on a Connection ` -- :atlas:`Connect to MongoDB Atlas from AWS Lambda ` \ No newline at end of file diff --git a/source/fundamentals/crud.txt b/source/fundamentals/crud.txt deleted file mode 100644 index 9e3275dc..00000000 --- a/source/fundamentals/crud.txt +++ /dev/null @@ -1,17 +0,0 @@ -.. _csharp-crud: - -=============== -CRUD Operations -=============== - -.. meta:: - :description: Learn how to run create, read, update, delete (CRUD) MongoDB operations by using the {+driver-long+}. - -.. toctree:: - :caption: CRUD Operations - - Write - Read - -- :ref:`csharp-crud-read-operations` -- :ref:`csharp-crud-write-operations` diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt deleted file mode 100644 index 6938a56a..00000000 --- a/source/fundamentals/crud/read-operations.txt +++ /dev/null @@ -1,25 +0,0 @@ -.. _csharp-crud-read-operations: - -=============== -Read Operations -=============== - -.. meta:: - :description: Learn about the commands for running MongoDB read operations by using the {+driver-long+}. - -.. toctree:: - :caption: Read Operations - - Retrieve Data - Specify Fields to Return - Count Documents - List Distinct Values - Monitor Data Changes - Specify Query Results - -- :ref:`csharp-retrieve` -- :ref:`csharp-project` -- :ref:`csharp-count-documents` -- :ref:`csharp-distinct` -- :ref:`csharp-change-streams` -- :ref:`csharp-specify-documents-to-return` diff --git a/source/fundamentals/crud/write-operations.txt b/source/fundamentals/crud/write-operations.txt deleted file mode 100644 index bb946729..00000000 --- a/source/fundamentals/crud/write-operations.txt +++ /dev/null @@ -1,25 +0,0 @@ -.. _csharp-crud-write-operations: - -================ -Write Operations -================ - -.. meta:: - :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. - -.. toctree:: - :caption: Write Operations - - Insert - Update One - Update Many - Replace - Delete - Bulk Write Operations - -- :ref:`csharp-insert-guide` -- :ref:`csharp-update-one` -- :ref:`csharp-update-many` -- :ref:`csharp-replace-documents` -- :ref:`csharp-delete-guide` -- :ref:`csharp-bulk-write` diff --git a/source/get-started.txt b/source/get-started.txt index bab7ee64..2642c9ea 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -18,13 +18,6 @@ Get Started with the {+driver-short+} :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 - Deploy a Cluster - Create a Connection String - Run a Sample Query - Overview -------- @@ -42,3 +35,214 @@ MongoDB Atlas. 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 <>`. + +.. _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. + +.. _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 ` + 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. + +.. _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 `, + 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 ```` and ```` 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 ` to an + environment variable. Replace ```` with the connection + string that you saved to a file in the previous step. + + .. code-block:: bash + + export MONGODB_URI="" + + .. note:: PowerShell + + If you're using Microsoft PowerShell, run the following command instead: + + .. code-block:: bash + + set 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. + +.. _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. + +.. _csharp-get-started-next-steps: + +Next Steps +---------- + +Congratulations on completing the tutorial! + +In this tutorial, you created a {+language+} application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +Learn more about the {+driver-short+} from the following resources: + +- Learn how to insert documents in the :ref:`` section. +- Learn how to find documents in the :ref:`` section. +- Learn how to update documents in the :ref:`` and + :ref:`` sections. +- Learn how to delete documents in the :ref:`` section. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-connection-string.txt b/source/get-started/create-connection-string.txt deleted file mode 100644 index 1a3524c5..00000000 --- a/source/get-started/create-connection-string.txt +++ /dev/null @@ -1,86 +0,0 @@ -.. _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 `, - 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 ```` and ```` 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 ` to an - environment variable. Replace ```` with the connection - string that you saved to a file in the previous step. - - .. code-block:: bash - - export MONGODB_URI="" - - .. note:: PowerShell - - If you're using Microsoft PowerShell, run the following command instead: - - .. code-block:: bash - - set 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 \ No newline at end of file diff --git a/source/get-started/deploy-cluster.txt b/source/get-started/deploy-cluster.txt deleted file mode 100644 index f3849975..00000000 --- a/source/get-started/deploy-cluster.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. _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 ` - 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 \ No newline at end of file diff --git a/source/get-started/download-driver.txt b/source/get-started/download-driver.txt deleted file mode 100644 index 66aebe51..00000000 --- a/source/get-started/download-driver.txt +++ /dev/null @@ -1,34 +0,0 @@ -.. _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 \ No newline at end of file diff --git a/source/get-started/run-sample-query.txt b/source/get-started/run-sample-query.txt deleted file mode 100644 index 0a79e9d3..00000000 --- a/source/get-started/run-sample-query.txt +++ /dev/null @@ -1,49 +0,0 @@ -.. _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 diff --git a/source/index.txt b/source/index.txt index 0730ca4c..50626999 100644 --- a/source/index.txt +++ b/source/index.txt @@ -1,3 +1,5 @@ +.. _csharp-index: + ================= MongoDB C# Driver ================= @@ -11,143 +13,116 @@ MongoDB C# Driver .. toctree:: - Previous Versions Get Started - Quick Reference - What's New - Usage Examples - Fundamentals - API Documentation <{+new-api-root+}/index.html> - FAQ - Connection Troubleshooting + Connect + Databases & Collections + CRUD Operations + Aggregation + Data Formats + Indexes + Run a Database Command + Atlas Search + Atlas Vector Search + Logging and Monitoring + Security + Integrations + Reference + API Documentation <{+api-root+}> Issues & Help - Compatibility - Upgrade - Entity Framework Provider - {+analyzer-short+} -Introduction ------------- +Overview +-------- Welcome to the documentation site for the official {+driver-long+}. You can add the driver to your application to work with MongoDB in {+language+}. -Download the driver using `NuGet `__, or set up a runnable -project by following our :ref:`Get Started ` guide. - -Previous Versions ------------------ - -For documentation on versions of the driver v2.18 and earlier, see the :ref:`csharp-previous-versions` section. - -Connect to a Compatible MongoDB Deployment ------------------------------------------- - -You can use the {+driver-short+} to connect to MongoDB -deployments running on one of the following hosted services or editions: - -.. include:: /includes/fact-environments.rst Get Started ----------- -Learn how to establish a connection to MongoDB Atlas and begin -working with data in the :ref:`csharp-get-started` section. - -Quick Reference ---------------- - -See driver syntax examples for common MongoDB commands in the -:ref:`Quick Reference ` section. +Learn how to install the driver, establish a connection to MongoDB, and begin +working with data in the :ref:`csharp-get-started` tutorial. -What's New ----------- +Connect to MongoDB +------------------ -For a list of new features and changes in each version, see the :ref:`What's New ` -section. - -Usage Examples --------------- - -For fully runnable code snippets and explanations for common -methods, see :ref:`csharp-usage-examples`. - -Fundamentals ------------- +Learn how to create and configure a connection to a MongoDB deployment +in the :ref:`csharp-connect` section. -For detailed information on key concepts of using the {+driver-short+}, see -:ref:`csharp-fundamentals`. +Databases and Collections +------------------------- -API Documentation ------------------ +Learn how to use the {+driver-short+} to work with MongoDB databases and collections +in the :ref:`csharp-databases-collections` section. -For detailed information about types and methods in the {+driver-short+}, see -the `{+driver-long+} API documentation -<{+new-api-root+}/index.html>`__. +Read and Write Data +------------------- -Take the Free Online Course Taught by MongoDB ---------------------------------------------- +Learn how to find, update, and delete data in the :ref:`csharp-crud` section. -.. list-table:: +Transform Your Data with Aggregation +------------------------------------ - * - .. figure:: /includes/figures/M220N.png - :alt: Banner for the C# MongoDB University Course +Learn how to use the {+driver-short+} to perform aggregation operations in the +:ref:`csharp-aggregation` section. - - `Using MongoDB with C# `__ +Data Formats +------------ - Learn the essentials of C# & ASP.NET application development with MongoDB. +Learn how to work with specialized data formats and custom types in the +:ref:`csharp-data-formats` section. -FAQ ---- +Optimize Queries with Indexes +----------------------------- -For answers to commonly asked questions about the {+driver-long+}, see the :ref:`csharp-faq` +Learn how to work with common types of indexes in the :ref:`csharp-indexes` section. -Connection Troubleshooting --------------------------- +Run a Database Command +---------------------- -For solutions to issues you might encounter when using the driver to connect to -a MongoDB deployment, see the :ref:`csharp-connection-troubleshooting` section. +Learn how to run a database command in the :ref:`csharp-run-command` section. -Issues & Help -------------- +Atlas Search +------------ -Learn how to report bugs, contribute to the driver, and find -additional resources for asking questions in the :ref:`csharp-issues-help` section. +Learn how to use Atlas Search to build full-text search capabilities in the +:ref:`csharp-atlas-search` section. -Compatibility -------------- +Atlas Vector Search +------------------- -For the compatibility charts that show the recommended {+driver-short+} version -for each {+mdb-server+} version, see :ref:`csharp-compatibility-tables`. +Learn how to use Atlas Vector Search to query your Atlas data based on semantic meaning +rather than keyword matches in the +`Atlas Vector Search `__ +documentation. -Upgrade Driver Versions ------------------------ +Logging and Monitoring +---------------------- -Learn what changes you may need to make to your application to upgrade -driver versions in the :ref:`Upgrade Driver Versions ` -section. +Learn how to monitor changes to your application and write them to logs in the +:ref:`csharp-logging-monitoring` section. -Entity Framework Provider -------------------------- +Secure Your Data +---------------- -The MongoDB Entity Framework Provider is an object-relational mapper (ORM) that lets you -use Microsoft's Entity Framework to work with MongoDB data. ORMs provide an -object-oriented interface for data management. +Learn about ways you can authenticate your application and encrypt your data in +the :ref:`csharp-security` section. -The provider includes features such as the following: +Reference +--------- -- Intelligent object tracking -- Entity-based LINQ operations -- Entity Framework modeling and mapping with the fluent API -- Automatic database updates through change tracking +Find more information about {+driver-short+} versions, compatibility, and upgrading driver +versions in the :ref:`csharp-reference` section. -To learn more, see the -`MongoDB Entity Framework Provider documentation `__. +API Documentation +----------------- -{+analyzer+} -------------------- +For detailed information about types and methods in the {+driver-short+}, see +the `{+driver-long+} API documentation +<{+new-api-root+}/index.html>`__. + +Issues & Help +------------- -The {+analyzer-short+} is a tool that helps you understand how your -{+driver-short+} code translates into the {+query-api+} and if your code -includes any unsupported LINQ or builder expressions. To learn more, see the -`{+analyzer-short+} documentation `__. \ No newline at end of file +Learn how to report bugs, contribute to the driver, and find help in the +:ref:`` section. \ No newline at end of file diff --git a/source/fundamentals/indexes.txt b/source/indexes.txt similarity index 86% rename from source/fundamentals/indexes.txt rename to source/indexes.txt index 01643254..62c52fe1 100644 --- a/source/fundamentals/indexes.txt +++ b/source/indexes.txt @@ -432,3 +432,82 @@ all indexes in a collection: :start-after: begin-list-indexes :end-before: end-list-indexes :dedent: + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +.. _csharp-builders-indexes: + +Define Index Keys +----------------- + +The ``IndexKeysDefinitionBuilder`` class provides a type-safe interface for +defining index keys. Suppose you want to select ``Category`` as an +ascending index key. + +Use builders to select the index key with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + var keys = builder.Ascending(f => f.Category); + +Alternatively, you can use string-based field names to select the index key: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + var keys = builder.Ascending("Category"); + +The ``IndexKeysDefinitionBuilder`` class also provides methods to build +a wildcard index. You can create a wildcard index using ``All field paths`` or ``A +single field path``, in this case using ``Category``: + +.. tabs:: + + .. tab:: ``All field paths`` + :tabid: all-wildcard-index + + .. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + var keys = builder.Wildcard(); + + .. tab:: ``A single field path`` + :tabid: single-wildcard-index + + .. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + + // Using the typed variant + var keys = builder.Wildcard(f => f.Category); + + // Using string-based field names + var keys = builder.Wildcard("Category"); + +For more information about how to use wildcard indexes, see +:manual:`Wildcard Indexes `. + +- `IndexKeysDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IndexKeysDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/integrations.txt b/source/integrations.txt new file mode 100644 index 00000000..65fe78ad --- /dev/null +++ b/source/integrations.txt @@ -0,0 +1,62 @@ +.. _csharp-integrations: + +====================== +Integrations and Tools +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn about {+driver-short+} integrations and tools. + :keywords: third-party + +.. toctree:: + :maxdepth: 1 + + OData + Entity Framework Provider + {+analyzer-short+} + +OData +----- + +OData (Open Data Protocol) is a standardized protocol for building and consuming +RESTful APIs that allows for the querying and manipulation of data by using +HTTP requests. It provides a uniform way to expose and interact +with data from multiple sources. + +To learn how to integrate OData with your MongoDB application, see the +:ref:`OData ` tutorial. + +Entity Framework Provider +------------------------- + +The MongoDB Entity Framework Provider is an object-relational mapper (ORM) that lets you +use Microsoft's Entity Framework to work with MongoDB data. ORMs provide an +object-oriented interface for data management. + +The provider includes features such as the following: + +- Intelligent object tracking +- Entity-based LINQ operations +- Entity Framework modeling and mapping with the fluent API +- Automatic database updates through change tracking + +To learn more, see the +`MongoDB Entity Framework Provider documentation `__. + +{+analyzer+} +------------------- + +The {+analyzer-short+} is a tool that helps you understand how your +{+driver-short+} code translates into the {+query-api+} and if your code +includes any unsupported LINQ or builder expressions. To learn more, see the +`{+analyzer-short+} documentation `__. \ No newline at end of file diff --git a/source/fundamentals/odata.txt b/source/integrations/odata.txt similarity index 100% rename from source/fundamentals/odata.txt rename to source/integrations/odata.txt diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt new file mode 100644 index 00000000..f459fe79 --- /dev/null +++ b/source/logging-and-monitoring.txt @@ -0,0 +1,18 @@ +.. _csharp-logging-monitoring: + +====================== +Logging and Monitoring +====================== + +.. facet:: + :name: programming_language + :values: csharp + +.. meta:: + :keywords: dotnet + +.. toctree:: + + Logging + Monitoring + Change Streams \ No newline at end of file diff --git a/source/fundamentals/crud/read-operations/change-streams.txt b/source/logging-and-monitoring/change-streams.txt similarity index 100% rename from source/fundamentals/crud/read-operations/change-streams.txt rename to source/logging-and-monitoring/change-streams.txt diff --git a/source/fundamentals/logging.txt b/source/logging-and-monitoring/logging.txt similarity index 100% rename from source/fundamentals/logging.txt rename to source/logging-and-monitoring/logging.txt diff --git a/source/fundamentals/monitoring.txt b/source/logging-and-monitoring/monitoring.txt similarity index 100% rename from source/fundamentals/monitoring.txt rename to source/logging-and-monitoring/monitoring.txt diff --git a/source/reference.txt b/source/reference.txt new file mode 100644 index 00000000..d1d5e55b --- /dev/null +++ b/source/reference.txt @@ -0,0 +1,25 @@ +.. _csharp-reference: + +========= +Reference +========= + +.. facet:: + :name: programming_language + :values: csharp + +.. meta:: + :keywords: dotnet + +.. toctree:: + + Quick Reference + Release Notes + Compatibility + Upgrade + Versions 2.0 to 2.18 + +Previous Versions +----------------- + +For documentation on versions of the driver v2.18 and earlier, see the :ref:`csharp-previous-versions` section. \ No newline at end of file diff --git a/source/compatibility.txt b/source/reference/compatibility.txt similarity index 100% rename from source/compatibility.txt rename to source/reference/compatibility.txt diff --git a/source/previous-versions.txt b/source/reference/previous-versions.txt similarity index 95% rename from source/previous-versions.txt rename to source/reference/previous-versions.txt index 1fdfc547..a1b74602 100644 --- a/source/previous-versions.txt +++ b/source/reference/previous-versions.txt @@ -1,8 +1,8 @@ .. _csharp-previous-versions: -================= -Previous Versions -================= +==================== +Versions 2.0 to 2.18 +==================== The following links direct you to documentation for previous versions of the driver. diff --git a/source/quick-reference.txt b/source/reference/quick-reference.txt similarity index 95% rename from source/quick-reference.txt rename to source/reference/quick-reference.txt index dc82f454..8b03bd9e 100644 --- a/source/quick-reference.txt +++ b/source/reference/quick-reference.txt @@ -23,7 +23,6 @@ their related reference and API documentation. * - | **Find a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -47,7 +46,6 @@ their related reference and API documentation. * - | **Find a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.FindAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -72,7 +70,6 @@ their related reference and API documentation. * - | **Find Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -100,7 +97,6 @@ their related reference and API documentation. * - | **Find Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -128,7 +124,6 @@ their related reference and API documentation. * - | **Insert a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -139,7 +134,6 @@ their related reference and API documentation. * - | **Insert a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -150,7 +144,6 @@ their related reference and API documentation. * - | **Insert Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertMany.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -165,7 +158,6 @@ their related reference and API documentation. * - | **Insert Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertManyAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -180,7 +172,6 @@ their related reference and API documentation. * - | **Update a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -197,7 +188,6 @@ their related reference and API documentation. * - | **Update a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -214,7 +204,6 @@ their related reference and API documentation. * - | **Update Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateMany.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -231,7 +220,6 @@ their related reference and API documentation. * - | **Update Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateManyAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -270,7 +258,6 @@ their related reference and API documentation. * - | **Replace a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -303,7 +290,6 @@ their related reference and API documentation. * - | **Replace a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -336,7 +322,6 @@ their related reference and API documentation. * - | **Delete a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -350,7 +335,6 @@ their related reference and API documentation. * - | **Delete a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -364,7 +348,6 @@ their related reference and API documentation. * - | **Delete Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteMany.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -378,7 +361,6 @@ their related reference and API documentation. * - | **Delete Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteManyAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp diff --git a/source/whats-new.txt b/source/reference/release-notes.txt similarity index 98% rename from source/whats-new.txt rename to source/reference/release-notes.txt index 263e0fc9..28687c76 100644 --- a/source/whats-new.txt +++ b/source/reference/release-notes.txt @@ -1,8 +1,9 @@ .. _csharp-whats-new: +.. _csharp-release-notes: -========== -What's New -========== +============= +Release Notes +============= .. contents:: On this page :local: @@ -61,7 +62,8 @@ The 3.1 driver release includes the following new features: in the Atlas Search documentation. - Adds support for the ``sort`` option to be passed to update commands. To learn more about - using update commands with the {+driver-short+}, see :ref:`csharp-crud-write-operations`. + using update commands with the {+driver-short+}, see the :ref:`csharp-update-one` and + :ref:`csharp-update-many` guides. For more information about this release, see the :github:`v3.1 release notes `. diff --git a/source/upgrade.txt b/source/reference/upgrade.txt similarity index 92% rename from source/upgrade.txt rename to source/reference/upgrade.txt index fd55892c..d4d41064 100644 --- a/source/upgrade.txt +++ b/source/reference/upgrade.txt @@ -21,8 +21,8 @@ Upgrade Driver Versions :titlesonly: :maxdepth: 1 - Version 2.x - Version 3.0 + Version 2.x + Version 3.0 Overview -------- diff --git a/source/upgrade/v2.txt b/source/reference/upgrade/v2.txt similarity index 100% rename from source/upgrade/v2.txt rename to source/reference/upgrade/v2.txt diff --git a/source/upgrade/v3.txt b/source/reference/upgrade/v3.txt similarity index 100% rename from source/upgrade/v3.txt rename to source/reference/upgrade/v3.txt diff --git a/source/fundamentals/databases-collections/run-command.txt b/source/run-command.txt similarity index 100% rename from source/fundamentals/databases-collections/run-command.txt rename to source/run-command.txt diff --git a/source/security.txt b/source/security.txt new file mode 100644 index 00000000..56e5458a --- /dev/null +++ b/source/security.txt @@ -0,0 +1,18 @@ +.. _csharp-security: + +======== +Security +======== + +.. facet:: + :name: programming_language + :values: csharp + +.. meta:: + :keywords: dotnet + +.. toctree:: + + Authentication + In-Use Encryption + TLS/SSL \ No newline at end of file diff --git a/source/fundamentals/authentication.txt b/source/security/authentication.txt similarity index 85% rename from source/fundamentals/authentication.txt rename to source/security/authentication.txt index e6a52726..c7944be5 100644 --- a/source/fundamentals/authentication.txt +++ b/source/security/authentication.txt @@ -20,12 +20,12 @@ Authentication Mechanisms .. toctree:: :caption: Authentication - SCRAM - X.509 - AWS IAM - OIDC - LDAP (PLAIN) - Kerberos (GSSAPI) + SCRAM + X.509 + AWS IAM + OIDC + LDAP (PLAIN) + Kerberos (GSSAPI) Overview -------- diff --git a/source/fundamentals/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt similarity index 100% rename from source/fundamentals/authentication/aws-iam.txt rename to source/security/authentication/aws-iam.txt diff --git a/source/fundamentals/authentication/kerberos.txt b/source/security/authentication/kerberos.txt similarity index 100% rename from source/fundamentals/authentication/kerberos.txt rename to source/security/authentication/kerberos.txt diff --git a/source/fundamentals/authentication/ldap.txt b/source/security/authentication/ldap.txt similarity index 100% rename from source/fundamentals/authentication/ldap.txt rename to source/security/authentication/ldap.txt diff --git a/source/fundamentals/authentication/oidc.txt b/source/security/authentication/oidc.txt similarity index 100% rename from source/fundamentals/authentication/oidc.txt rename to source/security/authentication/oidc.txt diff --git a/source/fundamentals/authentication/scram.txt b/source/security/authentication/scram.txt similarity index 100% rename from source/fundamentals/authentication/scram.txt rename to source/security/authentication/scram.txt diff --git a/source/fundamentals/authentication/x509.txt b/source/security/authentication/x509.txt similarity index 100% rename from source/fundamentals/authentication/x509.txt rename to source/security/authentication/x509.txt diff --git a/source/fundamentals/encrypt-fields.txt b/source/security/in-use-encryption.txt similarity index 77% rename from source/fundamentals/encrypt-fields.txt rename to source/security/in-use-encryption.txt index f519dca0..1939074c 100644 --- a/source/fundamentals/encrypt-fields.txt +++ b/source/security/in-use-encryption.txt @@ -1,4 +1,5 @@ .. _csharp-fle: +.. _csharp-in-use-encryption: .. sharedinclude:: dbx/encrypt-fields.rst diff --git a/source/fundamentals/connection/tls.txt b/source/security/tls-ssl.txt similarity index 100% rename from source/fundamentals/connection/tls.txt rename to source/security/tls-ssl.txt diff --git a/source/usage-examples.txt b/source/usage-examples.txt deleted file mode 100644 index 1096d1e9..00000000 --- a/source/usage-examples.txt +++ /dev/null @@ -1,105 +0,0 @@ -.. _csharp-usage-examples: - -============== -Usage Examples -============== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code, .NET, operation - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. toctree:: - - Find a Document - Find Multiple Documents - Insert a Document - Insert Multiple Documents - Update a Document - Update Many Documents - Replace a Document - Delete a Document - Delete Many Documents - -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 ` -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 ` -or you can -:guides:`import the sample dataset into a local MongoDB instance -`. - -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-get-started` 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 = ""; - -For more information about connecting to your MongoDB instance, see the -:ref:`Connection Guide `. - -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