Mirror
/
mongo-csharp-driver
mirror of https://github.com/mongodb/mongo-csharp-driver.git
2
0
Fork 0
Code Issues Releases Wiki Activity
Browse Source

upgraded docs for pending release.

pull/216/head
Craig Wilson 10 years ago
parent
ef59532e78
commit
188c3ed05f
12 changed files with 116 additions and 252 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 27
      Docs/landing/data/releases.toml
  2. 4
      Docs/landing/layouts/partials/features.html
  3. 2
      Docs/landing/static/versions.json
  4. 4
      Docs/reference/config.toml
  5. 6
      Docs/reference/content/index.md
  6. 160
      Docs/reference/content/upgrading.md
  7. 84
      Docs/reference/content/what_is_new.md
  8. 4
      Docs/reference/data/mongodb.toml
  9. 44
      Release Notes/Release Notes v2.1.0.md
  10. 4
      build/MongoDB.Driver-Build.nuspec
  11. 25
      build/MongoDB.Driver.GridFS.nuspec
  12. 4
      build/build.fsx

27
Docs/landing/data/releases.toml
View File

@ -1,12 +1,18 @@
current = "2.0.0"
current = "2.0.1"
[[versions]]
version = "2.0.0"
version = "2.1.0-rc0"
status = "rc"
docs = "http://mongodb.github.io/mongo-csharp-driver/2.1/"
api = "http://api.mongodb.org/csharp/2.1"
[[versions]]
version = "2.0.1"
status = "current"
docs = "http://mongodb.github.io/mongo-csharp-driver/2.0/"
api = "http://api.mongodb.org/csharp/2.0"
[[versions]]
version = "1.10.0"
version = "1.10.1"
status = "current"
docs = "http://mongodb.github.io/mongo-csharp-driver/1.10"
api = "http://api.mongodb.org/csharp/1.10"
@ -16,25 +22,32 @@ current = "2.0.0"
package = "MongoDB.Driver"
description = "The driver."
dependencies = ".NET Core Driver,.NET BSON Library"
versions = "2.0.0"
versions = "2.1.0-rc0,2.0.1"
[[drivers]]
name = ".NET GridFS"
package = "MongoDB.Driver.GridFS"
description = "The GridFS library."
dependencies = ".NET Driver,.NET Core Driver,.NET BSON Library"
versions = "2.1.0-rc0"
[[drivers]]
name = ".NET Core Driver"
package = "MongoDB.Driver.Core"
description = "The core driver."
dependencies = ".NET BSON Library"
versions = "2.0.0"
versions = "2.1.0-rc0,2.0.1"
[[drivers]]
name = ".NET BSON Library"
package = "MongoDB.Bson"
description = "The BSON library."
dependencies = ""
versions = "2.0.0"
versions = "2.1.0-rc0,2.0.1"
[[drivers]]
name = ".NET Legacy Driver"
package = "mongocsharpdriver"
description = "The legacy driver."
dependencies = ".NET Driver,.NET Core Driver,.NET BSON Library"
versions = "2.0.0,1.10.0"
versions = "2.1.0-rc0,2.0.1,1.10.1"

4
Docs/landing/layouts/partials/features.html
View File

@ -3,7 +3,9 @@
<dl>
<dt>Driver</dt>
<dd>A completely async driver to talk with MongoDB.</dd>
<dt>Core driver</dt>
<dt>GridFS</dt>
<dd>A distributed file system built on MongoDB.</dd>
<dt>Core Driver</dt>
<dd>The MongoDB Driver is built on top of a new Core library which anyone can use to build alternative or experimental high-level APIs.</dd>
<dt>BSON Library</dt>
<dd>A standalone BSON library, with a serialization infrastructure that you can use to build high-performance serializers.</dd>

2
Docs/landing/static/versions.json
View File

@ -1 +1 @@
[{"version": "2.0"}, {"version": "1.10"}]
[{"version": "2.1"},{"version": "2.0"}, {"version": "1.10"}]

4
Docs/reference/config.toml
View File

@ -1,4 +1,4 @@
baseurl = "/mongo-csharp-driver/2.0"
baseurl = "/mongo-csharp-driver/2.1"
languageCode = "en-us"
title = "MongoDB .NET Driver"
theme = "mongodb"
@ -12,7 +12,7 @@ canonifyurls = false
pre = "<i class='fa fa-file-text-o'></i>"
weight = 800
identifier = "apiDocs"
url = "http://api.mongodb.org/csharp/2.0"
url = "http://api.mongodb.org/csharp/2.1"
[[menu.main]]
name = "Source Code"

6
Docs/reference/content/index.md
View File

@ -10,14 +10,14 @@ type = "index"
The [Getting Started]({{< relref "getting_started\index.md" >}}) guide contains information about system requirements, installation, and a simple tutorial to get up and running quickly.
## What's new in 2.0
## What's new in 2.1
The [What's New]({{< relref "what_is_new.md" >}}) contains the major new features of the driver, the most important of which is full async support.
The [What's New]({{< relref "what_is_new.md" >}}) contains the major new features of the driver.
## Upgrading
If you are coming from the 1.x series of the driver, consult the [upgrading]({{< relref "upgrading.md" >}}) documentation on major changes.
If you are coming from the 2.0.x series of the driver, consult the [upgrading]({{< relref "upgrading.md" >}}) documentation on changes.
## Reference

160
Docs/reference/content/upgrading.md
View File

@ -11,162 +11,4 @@ title = "Upgrading"
## Breaking Changes
As 2.0 is a major revision, there are some breaking changes when coming from the 1.x assemblies. We've tried our best to mitigate those breaking changes, but some were inevitable. These changes may not affect everyone, but take a moment to review the list of known changes below:
### System Requirements
- .NET 3.5 and .NET 4.0 are no longer supported. If you still must use these platforms, the 1.x series of the driver will continue to be developed.
- [CSHARP-952](https://jira.mongodb.org/browse/CSHARP-952): We've removed support for partially trusted callers.
### Packaging
- The nuget package [mongocsharpdriver](http://nuget.org/packages/mongocsharpdriver) now includes the legacy driver. It depends on 3 new nuget packages, [MongoDB.Bson](http://nuget.org/packages/MongoDB.Bson), [MongoDB.Driver.Core](http://nuget.org/packages/MongoDB.Driver.Core), and [MongoDB.Driver](http://nuget.org/packages/MongoDB.Driver). [MongoDB.Driver](http://nuget.org/packages/MongoDB.Driver) is the replacement for [mongocsharpdriver](http://nuget.org/packages/mongocsharpdriver).
- [CSHARP-616](https://jira.mongodb.org/browse/CSHARP-616): We are no longer strong naming our assemblies. Our previous strong naming was signed with a key in our public repository. This did nothing other than satisfy certain tools. If you need MongoDB assemblies to be strongly named, it is relatively straight-forward to build the assemblies yourself.
### BSON
- [CSHARP-933](https://jira.mongodb.org/browse/CSHARP-933): Improved the BSON Serializer infrastructure. Anyone who has written a custom serializer will be affected by this. The changes are minor, but were necessary to support dynamic serializers as well as offering great speed improvements and improved memory management.
- Certain methods, such as `BsonMemberMap.SetRepresentation` have been removed. The proper way to set a representation, for instance, would be to use `SetSerializer` and configure the serializer with the appropriate representation.
- [CSHARP-939](https://jira.mongodb.org/browse/CSHARP-939): Dynamic DictionaryRepresentation has been removed. Its intent was to store, in some manner, anything in a .NET dictionary. In practice, this leads to the same values getting stored in different ways depending on factors such as a "." inside the key name. We made the decision to eliminate this variability. This means that documents that used to serialize correctly may start throwing a BsonSerializationException with a message indicating the key must be a valid string. [CSHARP-1165](https://jira.mongodb.org/browse/CSHARP-1165) has a solution to this problem. It should be noted that we will continue to read these disparate representations without error.
- `null` is no longer ignored in BsonValue-derived constructors. Anyone relying on null getting ignored will now receive an `ArgumentNullException`.
### Driver
- [CSHARP-979](https://jira.mongodb.org/browse/CSHARP-979): `MongoConnectionStringBuilder` has been removed. Use the documented mongodb connection string format and/or `MongoUrlBuilder`.
- `MongoServer` is a deprecated class. Anyone using `MongoClient.GetServer()` will encounter a deprecation warning and, depending on how your build is setup, may receive an error. It is still safe to use this API until your code is ported to the new API. *Note that this API requires the use of the [mongocsharpdriver](http://nuget.org/packages/mongocsharpdriver) to include the legacy API.
- [CSHARP-1043](https://jira.mongodb.org/browse/CSHARP-1043) and [CSHARP-1044](https://jira.mongodb.org/browse/CSHARP-1044): `ReadPreference` and `WriteConcern` were rewritten. These classes are now immutable. Any current application code that sets values on these classes will no longer function. Instead, you should use the With method to alter a `ReadPreference` or `WriteConcern`.
``` csharp
var writeConcern = myCurrentWriteConcern.With(journal: true);
```
## Migrating
Below are some common actions in the old API and their counterpart in the new API.
### Builders
_[More information.]({{< relref "reference\driver\definitions.md" >}})_
The old builders (`Query`, `Update`, etc...) have all been replaced by `Builders<T>.Filter`, `Builders<T>.Update`, etc...
```csharp
// old API
var query = Query.And(
Query<Person>.EQ(x => x.FirstName, "Jack"),
Query<Person>.LT(x => x.Age, 21));
// new API
var builder = Builders<Person>.Filter;
var filter = builder.Eq(x => x.FirstName, "Jack") & builder.Lt(x => x.Age, 21);
```
```csharp
// old API
var update = Update.Combine(
Update<Person>.Set(x => x.LastName, "McJack"),
Update<Person>.Inc(x => x.Age, 1));
// new API
var update = Builders<Person>.Update
.Set(x => x.LastName, "McJack")
.Inc(x => x.Age, 1);
```
### Finding All Documents
_[More information.]({{< relref "reference\driver\crud\reading.md#finding-documents" >}})_
To match all documents, you must specify an empty filter.
```csharp
// old API
var list = collection.FindAll().ToList();
// new API
var list = await collection.Find(new BsonDocument()).ToListAsync();
```
### Finding One Document
_[More information.]({{< relref "reference\driver\crud\reading.md#single-results" >}})_
To match all documents, you must specify an empty filter.
```csharp
// old API
var document = collection.FindOne();
// new API
var document = await collection.Find(new BsonDocument()).FirstOrDefaultAsync();
```
### Iteration
_[More information.]({{< relref "reference\driver\crud\reading.md#iteration" >}})_
You cannot iterate synchronously using a foreach loop without first getting a list. However, there are alternative methods provided to loop over all the documents in an asynchronous manner.
```csharp
// old API
foreach (var document in collection.Find(new QueryDocument("Name", "Jack")))
{
// do something
}
// new API
await collection.Find(new BsonDocument("Name", "Jack"))
.ForEachAsync(document =>
{
// do something
});
await collection.Find(new BsonDocument("Name", "Jack"))
.ForEachAsync(async document =>
{
// do something with await
});
```
### Counting All Documents
_[More information.]({{< relref "reference\driver\crud\reading.md#counting-documents" >}})_
To match all documents, you must specify an empty filter.
```csharp
// old API
var count = collection.Count();
// new API
var count = await collection.CountAsync(new BsonDocument());
```
### Mapping - SetRepresentation
_[More information.]({{< relref "reference\bson\mapping\index.md#representation" >}})_
You can still use attributes as you have done before. To set the representation via code:
```csharp
class Test
{
public char RepresentAsInt32 { get; set; }
}
// old API
BsonClassMap.RegisterClassMap<Person>(cm =>
{
// snip...
cm.MapMember(x => x.RepresentAsInt32).SetRepresentation(BsonType.Int32);
});
// new API
BsonClassMap.RegisterClassMap<Person>(cm =>
{
// snip...
cm.MapMember(x => x.RepresentAsInt32).SetSerializer(new CharSerializer(BsonType.Int32));
});
```
As 2.1 is a minor revision that comes with new features. There should not be any backwards breaking changes.

84
Docs/reference/content/what_is_new.md
View File

@ -8,89 +8,23 @@ title = "What's New"
pre = "<i class='fa fa-star'></i>"
+++
## What's New in the MongoDB .NET 2.0 Driver
## What's New in the MongoDB .NET 2.1 Driver
The 2.0 driver ships with a host of new features. The most notable are discussed below.
The 2.1 driver ships with a number of new features. The most notable are discussed below.
## Async
## GridFS
As has been requested for a while now, the driver now offers a full async stack. Since it uses Tasks, it is fully usable
with async and await.
[CSHARP-1191](https://jira.mongodb.org/browse/CSHARP-1191) - GridFS support has been implemented.
While we offer a mostly backwards-compatible sync API, it is calling into the async stack underneath. Until you are ready
to move to async, you should measure against the 1.x versions to ensure performance regressions don't enter your codebase.
All new applications should utilize the New API.
## LINQ
[CSHARP-935](https://jira.mongodb.org/browse/CSHARP-935) LINQ support has been rewritten and now targets the aggregation framework. It is a more natural translation and enables many features of LINQ that were previously not able to be translated.
## New API
Simply use the new [`AsQueryable`]({{< apiref "M_MongoDB_Driver_IMongoCollectionExtensions_AsQueryable__1" >}}) method to work with LINQ.
Because of our async nature, we have rebuilt our entire API. The new API is accessible via MongoClient.GetDatabase.
- Interfaces are used ([`IMongoClient`]({{< apiref "T_MongoDB_Driver_IMongoClient" >}}), [`IMongoDatabase`]({{< apiref "T_MongoDB_Driver_IMongoDatabase" >}}), [`IMongoCollection<TDocument>`]({{< apiref "T_MongoDB_Driver_IMongoCollection_1" >}})) to support easier testing.
- A fluent Find API is available with full support for expression trees including projections.
## Eventing
``` csharp
var names = await db.GetCollection<Person>("people")
.Find(x => x.FirstName == "Jack")
.SortBy(x => x.Age)
.Project(x => x.FirstName + " " + x.LastName)
.ToListAsync();
```
- A fluent Aggregation API is available with mostly-full support for expression trees.
``` csharp
var totalAgeByLastName = await db.GetCollection<Person>("people")
.Aggregate()
.Match(x => x.FirstName == "Jack")
.GroupBy(x => x.LastName, g => new { _id = g.Key, TotalAge = g.Sum(x => x.Age)})
.ToListAsync();
```
- Support for dynamic.
``` csharp
var person = new ExpandoObject();
person.FirstName = "Jane";
person.Age = 12;
person.PetNames = new List<dynamic> { "Sherlock", "Watson" }
await db.GetCollection<dynamic>("people").InsertOneAsync(person);
```
## Experimental Features
We've also include some experimental features which are subject to change. These are both based on the Listener API.
### Logging
It is possible to see what is going on deep down in the driver by listening to core events. We've included a simple text logger as an example:
``` csharp
var settings = new MongoClientSettings
{
ClusterConfigurator = cb =>
{
var textWriter = TextWriter.Synchronized(new StreamWriter("mylogfile.txt"));
cb.AddListener(new LogListener(textWriter));
}
};
```
### Performance Counters
Windows Performance Counters can be enabled to track statistics like average message size, number of connections in the pool, etc...
``` csharp
var settings = new MongoClientSettings
{
ClusterConfigurator = cb =>
{
cb.UsePeformanceCounters("MyApplicationName");
}
};
```
Blurb on eventing once APM is pushed.

4
Docs/reference/data/mongodb.toml
View File

@ -1,5 +1,5 @@
githubRepo = "mongo-csharp-driver"
githubBranch = "master"
currentVersion = "2.0"
currentVersion = "2.1"
highlightTheme = "idea.css"
apiUrl = "http://api.mongodb.org/csharp/2.0/html"
apiUrl = "http://api.mongodb.org/csharp/2.1/html"

44
Release Notes/Release Notes v2.1.0.md
View File

@ -1,3 +1,43 @@
# .NET Driver Version 2.1.0 Release Notes
# .NET Driver Version 2.1.0-rc0 Release Notes
Placeholder
(Preliminary)
This is a minor release which supports all MongoDB server versions since 2.4.
An online version of these release notes is available at:
https://github.com/mongodb/mongo-csharp-driver/blob/master/Release%20Notes/Release%20Notes%20v2.1.0.md
The full list of JIRA issues resolved in this release is available at:
https://jira.mongodb.org/issues/?filter=18283
Documentation on the .NET driver can be found at:
http://mongodb.github.io/mongo-csharp-driver/
## New Features
Notable new features are listed below. For a full list, see the full list of JIRA issues linked above.
### GridFS
[CSHARP-1191](https://jira.mongodb.org/browse/CSHARP-1191) - GridFS support has been implemented.
### LINQ
[CSHARP-935](https://jira.mongodb.org/browse/CSHARP-935) LINQ support has been rewritten and now targets the aggregation framework. It is a more natural translation and enables many features of LINQ that were previously not able to be translated.
Simply use the new [`AsQueryable`]({{< apiref "M_MongoDB_Driver_IMongoCollectionExtensions_AsQueryable__1" >}}) method to work with LINQ.
### Eventing
Blurb on eventing once APM is pushed.
## Upgrading
There are no known backwards breaking changes in this release.

4
build/MongoDB.Driver-Build.nuspec
View File

@ -23,10 +23,14 @@
<file src="artifacts\bin\net45\MongoDB.Driver.dll" target="lib\net45" />
<file src="artifacts\bin\net45\MongoDB.Driver.pdb" target="lib\net45" />
<file src="artifacts\bin\net45\MongoDB.Driver.XML" target="lib\net45" />
<file src="artifacts\bin\net45\MongoDB.Driver.GridFS.dll" target="lib\net45" />
<file src="artifacts\bin\net45\MongoDB.Driver.GridFS.pdb" target="lib\net45" />
<file src="artifacts\bin\net45\MongoDB.Driver.GridFS.XML" target="lib\net45" />
<file src="License.rtf" target ="" />
<file src="src\MongoDB.Bson\**\*.cs" target="src\MongoDB.Bson" />
<file src="src\MongoDB.Driver.Core\**\*.cs" target="src\MongoDB.Driver.Core" />
<file src="src\MongoDB.Driver\**\*.cs" target="src\MongoDB.Driver" />
<file src="src\MongoDB.Driver.GridFS\**\*.cs" target="src\MongoDB.Driver" />
<file src="src\MongoDB.Shared\**\*.cs" target="src\MongoDB.Shared" />
</files>
</package>

25
build/MongoDB.Driver.GridFS.nuspec
View File

@ -0,0 +1,25 @@
<?xml version="1.0" encoding="utf-8"?>
<package>
<metadata>
<id>MongoDB.Driver.GridFS</id>
<version>@build.number@</version>
<authors>MongoDB, Inc.</authors>
<owners>rstam, craiggwilson</owners>
<iconUrl>http://jobs.mongodb.org/files/logos/889002/889002.png</iconUrl>
<requireLicenseAcceptance>true</requireLicenseAcceptance>
<description>GridFS Component of the Official MongoDB .NET Driver.</description>
<projectUrl>http://www.mongodb.org/display/DOCS/CSharp+Language+Center</projectUrl>
<licenseUrl>http://www.apache.org/licenses/LICENSE-2.0</licenseUrl>
<tags>mongodb mongo nosql gridfs</tags>
<language>en-US</language>
@dependencies@
</metadata>
<files>
<file src="artifacts\bin\net45\MongoDB.Driver.GridFS.dll" target="lib\net45" />
<file src="artifacts\bin\net45\MongoDB.Driver.GridFS.pdb" target="lib\net45" />
<file src="artifacts\bin\net45\MongoDB.Driver.GridFS.XML" target="lib\net45" />
<file src="License.rtf" target ="" />
<file src="src\MongoDB.Driver.GridFS\**\*.cs" target="src\MongoDB.Driver" />
<file src="src\MongoDB.Shared\**\*.cs" target="src\MongoDB.Shared" />
</files>
</package>

4
build/build.fsx
View File

@ -53,6 +53,7 @@ let nuspecFiles =
[ { File = buildDir @@ "MongoDB.Bson.nuspec"; Dependencies = []; Symbols = true; }
{ File = buildDir @@ "MongoDB.Driver.Core.nuspec"; Dependencies = ["MongoDB.Bson"]; Symbols = true; }
{ File = buildDir @@ "MongoDB.Driver.nuspec"; Dependencies = ["MongoDB.Bson"; "MongoDB.Driver.Core"]; Symbols = true; }
{ File = buildDir @@ "MongoDB.Driver.GridFS.nuspec"; Dependencies = ["MongoDB.Bson"; "MongoDB.Driver.Core"; "MongoDB.Driver"]; Symbols = true; }
{ File = buildDir @@ "mongocsharpdriver.nuspec"; Dependencies = ["MongoDB.Bson"; "MongoDB.Driver.Core"; "MongoDB.Driver"]; Symbols = true; }]
let nuspecBuildFile = buildDir @@ "MongoDB.Driver-Build.nuspec"
@ -210,6 +211,9 @@ Target "Zip" (fun _ ->
binDir45 @@ "MongoDB.Driver.dll"
binDir45 @@ "MongoDB.Driver.pdb"
binDir45 @@ "MongoDB.Driver.xml"
binDir45 @@ "MongoDB.Driver.GridFS.dll"
binDir45 @@ "MongoDB.Driver.GridFS.pdb"
binDir45 @@ "MongoDB.Driver.GridFS.xml"
binDir45 @@ "MongoDB.Driver.Legacy.dll"
binDir45 @@ "MongoDB.Driver.Legacy.pdb"
binDir45 @@ "MongoDB.Driver.Legacy.xml"

Write Preview
Loading…
Cancel
Save