.NET Core on Connector/NET updates.

Hello MySQL Connector/NET community,

Consistent with our ongoing effort to power MySQL products with the top technologies, we are pleased to announce the latest updates regarding MySQL Connector/NET and .NET Core.

And while we move forward, we also want to shape the product to maximize supportability. To achieve these two goals, we will deprecate the support for .NET Core 1.X to align with Microsoft’s end-of-life schedule (EOL May 14, 2019). But it’s not all about bad news, we also want to talk to you about the inclusion of .NET Core 2.2 support in the Connector/NET8.0.17 release. As you might know, .NET Core 2.2 is the latest GA release of .NET Core to provide a cross-platform framework that lets you build applications for Windows, Linux and macOS.

Our product, MySQL Connector/NET, is built against .NET Standard 2.0 that allows you to use it as a library in any of the .NET implementations compatible with that version of .NET Standard. For more details related to frameworks compatibility, you can go to the official .NET Standard versions web page. Given this, you can build a .NET Core 2.2 application using MySQL Connector/NET 8.0.17 and take advantage of all the new features and improvements this framework has to offer you.

To use Connector/NET in your .NET Core 2.2 project, simply make a reference to the library. There are two ways of achieving this:

  • First, by using NuGet to download a compatible version automatically.
  • Secondly, by downloading the MySQL Connector/NET source code and building it to ensure the corresponding DLLs are created. Then you can make use of the .NET Standard 2.0 version in your project.

Remember to include the element TargetFramework in your project file and to set the version of .NET Core desired, as shown in the example below:

<TargetFramework>netcoreapp2.2</TargetFramework>

If you are new to this framework, Microsoft offers a very useful guide to get you started with .NET Core (see Microsoft .NET Core guide).

We hope you find this information useful so you could start using MySQL Connector/NET with the most recent technologies. Your feedback is always welcome and all your comments inspire us to keep improving so that we offer you a product with top quality.

Finally, here are some links that could be useful for you:

We hope to hear from you!

MySQL Connector/NET 8.0.17 has been released

Dear MySQL users,

MySQL Connector/NET 8.0.17 is the fifth version to support Entity Framework Core 2.1 and the sixth general availability release of MySQL Connector/NET to add support for the new X DevAPI, which enables application developers to write code that combines the
strengths of the relational and document models using a modern, NoSQL-like syntax that does not assume previous experience writing traditional SQL.

To learn more about how to write applications using the X DevAPI, see http://dev.mysql.com/doc/x-devapi-userguide/en/index.html. For more information about how the X DevAPI is implemented in Connector/NET, see http://dev.mysql.com/doc/dev/connector-net. NuGet packages provide functionality at a project level. To get the
full set of features available in Connector/NET such as availability in the GAC, integration with Visual Studio’s Entity Framework Designer and integration with MySQL for Visual Studio, installation through the MySQL Installer or the stand-alone MSI is required.

Please note that the X DevAPI requires at least MySQL Server version 8.0 or higher with the X Plugin enabled. For general documentation about how to get started using MySQL as a document store, see http://dev.mysql.com/doc/refman/8.0/en/document-store.html.

To download MySQL Connector/NET 8.0.17, see http://dev.mysql.com/downloads/connector/net/

Installation instructions can be found at https://dev.mysql.com/doc/connector-net/en/connector-net-installation.html


Changes in MySQL Connector/NET 8.0.17 (2019-07-22, General
Availability)


     * Functionality Added or Changed

     * Bugs Fixed

Functionality Added or Changed


     * Connector/NET supports SSL PEM certificate versions 1, 2,
       and 3 to enable use with the full range of applications
       that generate certificates. (Bug #29756058)

     * Support was added for .NET Core 2.2, which is a
       cross-platform version of .NET for building applications
       that run on Linux, macOS and Windows (see Connector/NET
       Versions
(https://dev.mysql.com/doc/connector-net/en/connector-net-versions.html)).

     * Document Store: The Where() method is deprecated
       (Obsolete attribute applied) and will return a warning
       when called in the following method constructs:
       Find().Where(), Modify().Where(), and Remove().Where().

     * New README.md and CONTRIBUTING.md files now accompany
       MySQL Connector/NET code for compatibility with Git.
       Distribution packages (NuGet, MSI, ZIP) continue to
       include the original README file, but do not include the
       new files.

     * Connector/NET now supports the new utf8mb4_0900_bin
       collation added for the utf8mb4 Unicode character set in
       MySQL 8.0.17. For more information about this collation,
       see Unicode Character Sets
(https://dev.mysql.com/doc/refman/8.0/en/charset-unicode-sets.html).

     * Document Store: Connector/NET now supports the OVERLAPS
       and NOT OVERLAPS operators for expressions on JSON arrays
       or objects:
expr OVERLAPS expr
expr NOT OVERLAPS expr

       Suppose that a collection has these contents:
[{
   “_id”: “1”,
   “list”: [1, 4]
 }, {
   “_id”: “2”,
   “list”: [4, 7]
}]

       This operation:
var res = collection.Find(“[1, 2, 3] OVERLAPS $.list”).Fields(“_id”).E
xecute();
res.FetchAll();

       Should return:
[{ “_id”: “1” }]

       This operation:
var res = collection.Find(“$.list OVERLAPS [4]”).Fields(“_id”).Execute
();
res.FetchAll();

       Should return:
[{ “_id”: “1” }, { “_id”: “2” }]

       An error occurs if an application uses either operator
       and the server does not support it.

     * Document Store: For index specifications passed to the
       Collection.CreateIndex() method, Connector/NET now
       supports indexing array fields. For example, consider a
       collection with this array:
Session session = MySQLX.GetSession(connString);
Schema schema = session.GetSchema(schemaName);
Collection coll = schema.CreateCollection(collectionName);

var docs = new[]
{
  new {  _id = 1, name = “John Smith”, emails = [ “john.smith@mycompan
y.com”, “jsmith@php.net”, “jsmith@mail.com” ] }
};

coll.Add(docs).Execute();

       A single index field description can contain a new member
       name array that takes a Boolean value. If set to true,
       the field is assumed to contain arrays of elements of the
       given type. In addition, the set of possible index field
       data types (used as values of member type in index field
       descriptions) is extended with type CHAR(N), where the
       length N is mandatory. For example, to create the
       emails_idx index with an array field:
coll.CreateIndex(“emails_idx”,
    “{\”fields\”: [{\”field\”: $.emails,
                   \”type\”:\”CHAR(128)\”,
                   \”array\”: true }]}”
);

       To find an element of the array:
collection
   .Find(“:mail IN $.emails”)
   .Bind(“mail”, “jsmith@php.net”)
   .Execute();


     * New support for SSH tunneling enables Connector/NET to
       create secure connections to a remote MySQL server using
       TCP/IP over SSH. With SSH server authorization, an
       application can establish a connection from behind a
       firewall when the MySQL Server port is blocked. The new
       connection-string options (and equivalent class
       properties) for SSH tunneling are supported by both the
       classic MySQL protocol and X Protocol connections.

Bugs Fixed


     * The BouncyCastle assembly was loaded into memory whenever
       a connection attempt was made using any SSL mode type,
       except None. Now the assembly loads only when the SSL
       mode type is VerifyCA or VerifyFull, or when PEM
       certificates are used. (Bug #29611216)

     * Document Store: The MySqlConnection.GetSchema() method
       sometimes returned columns in an unexpected order when
       used with the INFORMATION_SCHEMA.COLUMNS table. This fix
       ensures that returned columns now correspond to the
       ordinal position only. (Bug #29536344)

     * The InvariantCulture property was missing from some data
       types, which created issues during platform migration
       operations. Thanks to Effy Teva for the patch. (Bug
       #29262195, Bug #94045)

     * Connector/NET connections executed SHOW VARIABLES
       unnecessarily. (Bug #28928543, Bug #93202)

     * Connector/NET access to MySQL stopped working after the
       computer hosting the server was started and continued to
       operate uninterrupted for a defined period of time. (Bug
       #26930306, Bug #75604)

On Behalf of Oracle/MySQL Engineering Team
Prashant Tekriwal

MySQL Connector/NET 8.0.16 has been released

Dear MySQL users,

MySQL Connector/NET 8.0.16 is the fourth version to support
Entity Framework Core 2.1 and the sixth general availability release
of MySQL Connector/NET to add support for the new X DevAPI, which
enables application developers to write code that combines the
strengths of the relational and document models using a modern,
NoSQL-like syntax that does not assume previous experience writing traditional SQL.

To learn more about how to write applications using the X DevAPI, see
http://dev.mysql.com/doc/x-devapi-userguide/en/index.html. For more
information about how the X DevAPI is implemented in Connector/NET, see
http://dev.mysql.com/doc/dev/connector-net. NuGet packages provide functionality at a project level. To get the
full set of features available in Connector/NET such as availability
in the GAC, integration with Visual Studio’s Entity Framework Designer
and integration with MySQL for Visual Studio, installation through
the MySQL Installer or the stand-alone MSI is required.

Please note that the X DevAPI requires at least MySQL Server version
8.0 or higher with the X Plugin enabled. For general documentation
about how to get started using MySQL as a document store, see
http://dev.mysql.com/doc/refman/8.0/en/document-store.html.

To download MySQL Connector/NET 8.0.16, see
http://dev.mysql.com/downloads/connector/net/

Installation instructions can be found at
https://dev.mysql.com/doc/connector-net/en/connector-net-installation.html

Changes in MySQL Connector/NET 8.0.16 ( 2019-04-25, General Availability )

* Functionality Added or Changed

* Bugs Fixed

Functionality Added or Changed

* Document Store: Support was added for the -> operator to
be used with JSON document paths in relational
statements. For example:
table.Select().Where("additionalinfo->$.hobbies = 'Reading'");

(Bug #29347028)

* Document Store: The performance for statements that are
executed repeatedly (two or more times) is improved by
using server-side prepared statements for the second and
subsequent executions. This happens internally;
applications need take no action and API behavior should
be the same as previously. For statements that change,
repreparation occurs as needed. Providing different data
values or different OFFSET or LIMIT clause values does
not count as a change. Instead, the new values are passed
to a new invocation of the previously prepared statement.

* Document Store: Connector/NET now supports the ability to
send connection attributes (key-value pairs that
application programs can pass to the server at connect
time). Connector/NET defines a default set of attributes,
which can be disabled or enabled. In addition,
applications can specify attributes to be passed together
with the default attributes. The default behavior is to
send the default attribute set.
The aggregate size of connection attribute data sent by a
client is limited by the value of the
performance_schema_session_connect_attrs_size server
variable. The total size of the data package should be
less than the value of the server variable. For X DevAPI
applications, specify connection attributes as a
connection-attributes parameter in a connection string.
For usage information, see Options for X Protocol Only
(http://dev.mysql.com/doc/connector-net/en/connector-net-8-0-connection-options.html#connector-net-8-0-connection-options-xprotocol).
For general information about connection attributes, see
Performance Schema Connection Attribute Tables
(http://dev.mysql.com/doc/refman/8.0/en/performance-schema-connection-attribute-tables.html).

* Document Store: Connector/NET now has improved support
for resetting sessions in connection pools. Returning a
session to the pool drops session-related objects such as
temporary tables, session variables, and transactions,
but the connection remains open and authenticated so that
reauthentication is not required when the session is
reused.

* Connector/NET applications now can use certificates in
PEM format to validate SSL connections in addition to the
native PFX format (see Tutorial: Using SSL with Connector/NET
(http://dev.mysql.com/doc/connector-net/en/connector-net-tutorials-ssl.html)).
PEM support applies to both classic MySQL protocol
and X Protocol connections.

Bugs Fixed

* Document Store: All methods able to execute a statement
were unable to execute the same statement a second time.
Now, the values and binding parameters remain available
after the method is executed and string parameters are no
longer converted to numbers. Both changes enable a
follow-on execution to reuse the previous parameters.
(Bug #29249857, Bug #29304767)

* An exception was generated when the MySqlDbType
enumeration was given an explicit value and then passed
as a parameter to the MySqlCommand.Prepare method. (Bug
#28834253, Bug #92912)

* Validation was added to ensure that when a column is of
type TIME and the value is 00:00:00, it takes the value
instead of setting NULL. (Bug #28383726, Bug #91752)

On Behalf of MySQL Release Engineering Team,
Surabhi Bhat

MySQL Connector/NET 6.10.8 has been released

Dear MySQL users,

MySQL Connector/NET 6.10.8 is the fifth GA release with .NET Core
now supporting various connection-string options and MySQL 8.0 server
features.

To download MySQL Connector/NET 6.10.8 GA, see the “Generally Available
(GA) Releases” tab at http://dev.mysql.com/downloads/connector/net/

Changes in Connector/NET 6.10.8 (2018-08-14, General Availability)

Functionality Added or Changed

* Optimistic locking for database-generated fields was
improved with the inclusion of the [ConcurrencyCheck,
DatabaseGenerated(DatabaseGeneratedOption.Computed)]
attribute. Thanks to Tony Ohagan for the patch. (Bug
#28095165, Bug #91064)

* All recent additions to .NET Core 2.0 now are compatible
with the Connector/NET 6.10 implementation.

* With the inclusion of the Functions.Like extended method,
scalar-function mapping, and table-splitting
capabilities, Entity Framework Core 2.0 is fully
supported.

Bugs Fixed

* EF Core: An invalid syntax error was generated when a new
property (defined as numeric, has a default value, and is
not a primary key) was added to an entity that already
contained a primary-key column with the AUTO_INCREMENT
attribute. This fix validates that the entity property
(column) is a primary key first before adding the
attribute. (Bug #28293927)

* EF Core: The implementation of some methods required to
scaffold an existing database were incomplete. (Bug
#27898343, Bug #90368)

* The Entity Framework Core implementation did not render
accented characters correctly on bases with different
UTF-8 encoding. Thanks to Kleber kleberksms for the
patch. (Bug #27818822, Bug #90316)

* The Microsoft.EntityFrameworkCore assembly (with EF Core
2.0) was not loaded and the absence generated an error
when the application project was built with any version
of .NET Framework. This fix ensures the following
support:

+ EF Core 1.1 with .NET Framework 4.5.2 only

+ EF Core 2.0 with .NET Framework 4.6.1 or later
(Bug #27815706, Bug #90306)

* Attempts to create a new foreign key from within an
application resulted in an exception when the key was
generated by a server in the MySQL 8.0 release series.
(Bug #27715069)

* A variable of type POINT when used properly within an
application targeting MySQL 8.0 generated an SQL syntax
error. (Bug #27715007)

* The case-sensitive lookup of field ordinals was
initialized using case-insensitive comparison logic. This
fix removes the original case-sensitive lookup. (Bug
#27285641, Bug #88950)

* The TreatTinyAsBoolean connection option was ignored when
the MySqlCommand.Prepare() method was called. (Bug
#27113566, Bug #88472)

* The MySql.Data.Types.MySqlGeometry constructor called
with an array of bytes representing an empty geometry
collection generated an ArgumentOutOfRangeException
exception, rather than creating the type as expected.
Thanks to Peet Whittaker for the patch. (Bug #26421346,
Bug #86974)

* Slow connections made to MySQL were improved by reducing
the frequency and scope of operating system details
required by the server to establish and maintain a
connection. (Bug #22580399, Bug #80030)

* All columns of type TINYINT(1) stopped returning the
expected Boolean value after the connector encountered a
NULL value in any column of this type. Thanks to David
Warner for the patch. (Bug #22101727, Bug #78917)

Nuget packages are available at:

https://www.nuget.org/packages/MySql.Data/6.10.8
https://www.nuget.org/packages/MySql.Web/6.10.8
https://www.nuget.org/packages/MySql.Data.Entity/6.10.8
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore/6.10.8
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore.Design/6.10.8

Enjoy and thanks for the support!

On Behalf of the MySQL/Oracle Release Engineering Team,
Hery Ramilison

MySQL Connector/NET 8.0.11 is available as official MySQL NuGet packages

Dear MySQL Connector/NET users,

We are proud to announce that the open source version of Connector/NET 8.0.11 is also available as official MySQL NuGet packages. Connector/NET 8.0.11 is a GA release that can be used in production environments. Additionally, users with an older version can safely upgrade if preferred.

 

What this means for Connector/NET users?

Installing and upgrading packages couldn’t be easier, plus you need only to install the packages that fit your needs. Also, it’s even easier and more straight forward to develop for MySQL from Visual Studio.

NuGet is the package manager for the Microsoft development platform including .NET. The NuGet client tools provide the ability to produce and consume packages. The NuGet Gallery is the central software package repository populated by various package authors and tied directly to developers for ease of installation and development. For more information on NuGet see: https://github.com/nuget/home

Connector/NET NuGet Packages

Currently there are 5 Connector/NET NuGet packages:

  • MySQL Connector/NET Data
    • Provides the core functionality of Connector/NET including using MySQL as a Document Store through the X DevAPI. It implements the required ADO.NET interfaces and integrates into ADO.NET-aware tools. Provides access to multiple versions of MySQL Server and encapsulates database-specific protocols.
    • Supports .NET Framework 4.5.2, .NET Standard 1.6 & 2.0.
    • Refer to the official documentation for additional details.
    • Refer to the X DevAPI User Guide for details on using MySQL as a Document Store with Connector/NET.
  • MySQL Connector/NET Web providers
    • Includes support for the ASP.NET 2.0 provider model. This model enables application developers to focus on the business logic of their application instead of having to recreate boilerplate items such as membership and roles support.
    • Supported providers:
      • Membership
      • Role
      • Profile
      • Session State
    • Supports .NET Framework 4.5.2.
    • Refer to the ASP.NET Provider Model section of the official documentation for additional details.
  • MySQL Connector/NET for Entity Framework 6
    • Provides ORM capabilities enabling developers to work with MySQL databases using domain-specific objects, thus eliminating the need for most of the data access code.
    • Supports .NET Framework 4.5.2.
    • Refer to the Entity Framework 6 Support section of the official documentation for additional details.
  • MySQL Connector/NET for Entity Framework Core
    • Provides multi-platform support for Entity Framework tasks.
    • Supports .NET Framework 4.5.2, .NET Standard 1.6 & 2.0.
    • Refer to the Entity Framework Core Support section of the official documentation for additional details.
  • MySQL Connector/NET for Entity Framework Core Design
    • Provides shared design-time components for Entity Framework Core tools allowing the scaffolding and migration of databases.
    • Supports .NET Framework 4.5.2, .NET Standard 1.6.
    • Refer to the Entity Framework Core Support section of the official documentation for additional details.

In order to install the NuGet Package you can use the Package Manager Console as follows:

PM> Install-Package MySql.Data.EntityFrameworkCore

PM> Install-Package MySql.Data.Web

Or via Visual Studio’s NuGet Package Manager UI: http://docs.nuget.org/docs/start-here/Managing-NuGet-Packages-Using-The-Dialog

Note that packages for Web Providers and Entity Framework have a dependency with the core package MySql.Data, meaning their installation will also result in the installation of the MySql.Data package. Installation through the standalone MSI is recommended whenever you want to make use of all the functionality provided by Connector/NET E.g. availability in the GAC.

For more information or to go directly to our NuGet Packages review the following links:

For those of you interested in how to use Connector/NET with .NET Core you can refer to the MySQL Connector/NET for .NET Core 1.0 blog post.

If you happen to have any questions about this or any other Connector/NET related topic, you can always post them in the product’s main forum. Additionally, bugs can be reported in MySQL Bugs.

Connector/NET Team

Introducing Connector/NET with full support for MySQL 8.0

Members of the .NET and MySQL communities and anyone interested in the subject, we are glad to announce the release of Connector/NET 8.0.11. This is the first GA release in the 8.0 series and it comes with full support for MySQL 8.0 (also now a GA) including its main feature… the MySQL Document Store!

 

What is new in MySQL 8.0?

X Protocol / X Plugin

The X Protocol is a new, highly extensible protocol optimized for SQL and CRUD API operations. It is based on the popular open source protocol definition language and provides a common interface for connectors to communicate with MySQL server through the X Plugin. The X Plugin serves as the server-side implementation of the document store among other features such as pipelining, protocol buffers, etc.

MySQL Document Store and the X DevAPI

MySQL Document Store is a flexible storage system that allows developers to work with relational tables and schema-less JSON collections in parallel. When being used to create documents you do not need to know and define all possible attributes before storing and operating with them, allowing for future customization with minimal effort.

The document store can be accessed and manipulated with the X DevAPI which is implemented by MySQL connectors that support the X Protocol, including Connector/NET. The X DevAPI is a fluent CRUD API that allows to work with JSON documents and relational data alike.

Implementation of the X DevAPI has been standardized across MySQL connectors allowing to switch to the language of choice with minimal effort. Be sure to check out the following links for additional information on the MySQL Document Store and its benefits:

A new default authentication plugin

MySQL 8.0 also introduces caching_sha2_password as the default authentication plugin. caching_sha2_password implements SHA_256 hashing as opposed to SHA_1 used by the old mysql_native_password. It also results in faster reauthentication for known users. Check out its documentation for additional details.

 

What is new in Connector/NET 8.0.11?

Security changes

Connector/NET comes with important security changes that will prove relevant and useful for newcomers and seasoned users alike:

  • Connections are now secure by default, meaning the default SSL Mode is now set to Required (sslmode=required).
  • Support for the new caching_sha2_password authentication plugin based on SHA_256 has been included. Note that to connect to the server using the caching_sha2_password plugin, a secure connection or an unencrypted connection that supports password exchange using an RSA key pair must be used.
  • Non-SSL connections for users set with the caching_sha2_password or sha256_password authentication plugins require that the AllowPublicKeyRetrieval connection option is set to True. This option will signal the server the need to return its public key required during RSA key encryption.

Connector/NET and the X DevAPI

Connector/NET implements the X DevAPI and exposes its features for .NET Developers. Let’s begin by showcasing how to setup the development environment.

Set Up

Setting up the environment is quick and simple, first make sure that the following requirements are met:

  • Visual Studio 2013+
  • .NET Framework 4.5.2+ / .NET Core 1.1 / .NET Core 2.0
  • MySQL Server 8.0+ with the X Plugin enabled

Then install/obtain Connector/NET 8.0.11+ via one of the following options:

  • MSI Installer
  • No-Install package
  • NuGet Package Manager (only the MySql.Data 8.0.11+ package is required)
  • Source code (for advanced users)

Note: MSI Installer, No-Install package and Source code options are all available in the main downloads page and can be selected through the “Select Operating System” drop down.

When ready to start coding simply create a .NET Framework/ .NET Core project such as a Console Project and reference the relevant assemblies as follows:

  • No-Install Package: Add a reference to the MySql.Data and Google.Protobuf assemblies by browsing to the said files within the downloaded package.
  • MSI Installer: Add a reference to the MySql.Data available in the Assemblies->Extensions section of the Reference Manager. No need to add a reference to Google.Protobuf as this is done automatically.
  • NuGet Package Manager: Simply search and install the MySql.Data package.

CRUD Example

A simple CRUD example will be used to demonstrate CRUD operations being applied to JSON documents through the use of the X DevAPI and to cover the basics:

1. Import the namespaces relevant for this code example:

Typically the MySqlX.XDevAPI and MySqlX.XDevAPI.Common namespaces will be required as they provide the basic functionality. When working on documents and collections use MySqlX.XDevAPI.CRUD, use MySqlX.XDevAPI.Relational for relational data.

2. Create a session

A session in the X DevAPI is a high-level database session concept that is different from working with traditional low-level MySQL connections. Sessions encapsulate one or more actual MySQL connections.

The X Protocol defines the connection URL which is an alternative syntax to the widely known connection strings. Connection strings are also supported when using the MySQLX.GetSession methods or any other methods that accept the connection URL such as the Session’s class constructor.

MySQLX.GetSession initiates a session ready to receive commands, no need to call the Open method as done with classic MySQL connections.

A Schema is used to store collections of documents. It can be considered the counterpart to a database within the relational model.

3. Insert a document into a collection

Collections reside within a Schema and are used to store documents. Documents can be declared in multiple ways, as .NET anonymous objects, plain JSON strings or as DbDoc instances which are the representation of a document within Connector/NET‘s implementation of the X DevAPI. DbDocs have the advantage of providing easier means to set or get properties associated to them.

Calling the Add method on a collection will mark a document as ready to be added into a collection, however it will actually be added into the collection upon calling the Execute method. This allows to keep adding documents to a queue and to add them into the collection via a single and final operation. A similar approach can be used with other CRUD operations. The Add method is overloaded to also support an array of documents.

4. Find a row within a collection

The Find method is used for retrieving documents from a collection and receives the condition for matching documents. The condition can receive parameters which can later be given a value with the Bind method. The Bind method supports receiving a DbDoc instance or a pair of strings signifying the key and value of the property being matched.

The operation returns a DocResult object containing the results of the execution and allowing to iterate through them via the Next, FetchOne, FetchAll and other methods.

5. Modify an existing document

Modify will allow updating documents based on the provided condition. Note that in this case the overload of Bind is being used to provide a value to the name1 parameter. Set method will allow setting the values to modify, in this case a new field is added into matching documents, showcasing the advantages of working with documents as opposed to the relational model! Additionally, notice the method chaining which allows for intuitive and simpler syntax for performing operations.

6. Remove a specific document

The Remove method as expected, will remove matching documents from the collection.

7. Close the session

Finally, be sure to close the session. Alternatively, taking the advantages of .NET into account, you can opt for handling sessions with a using statement which will grant the benefit of not having to explicitly close the session.

Even though this example focuses on collections and documents, similar operations can be applied to relational data as well. Refer to the reference documentation for more details.

Additional features

Raw SQL

Sometimes, you will encounter scenarios where CRUD operations are not the best option, where a specific feature isn’t supported by the X DevAPI or simply where your preference is to use raw SQL. The X DevAPI implements the Session.SQL method allowing exactly that. Method chaining is also supported for multiple Session.SQL method calls in the same statement and upon calling the Execute method the results of the operation are returned:

Transaction Save Points

When data consistency is essential, transactions and transaction save points are the key. Methods pertaining to transaction handling are implemented through the Session class.

Transactions can be initiated with the StartTransaction method and terminated with the Rollback and Commit methods. Transaction save points allow to jump to a specific point within a transaction. Methods SetSavepoint, RollbackTo and ReleaseSavepoint will aid in this regard:

Row Locking

An additional feature for ensuring data consistency and for avoiding deadlocks comes in the form of row locking. The LockShared and LockExclusive methods allow multiple transactions to modify the same set of data concurrently. More info on row locking can be found here.

Above code snippet makes use of the LockShared method to prevent rows from being modified by other transactions. In this case, session 2 isn’t allowed to modify rows locked by session 1 until they are released.

LockShared and LockExclusive are overloaded to also receive a parameter representing the lock mode to use, providing more control over waiting actions for locked rows. Refer to the LockContention enumeration in the reference documentation for the list of lock modes available.

Document Patching

The Patch method is a yet more powerful means for modifying matching documents. By providing a JSON-like object the user can describe the changes to be applied to matching documents, those changes being new fields, removing fields, setting fields by simply providing the value or by defining a calculated value such as the result of a function:

 

These are just a few of the features that MySQL 8.0 and Connector/NET 8.0.11 can offer through the use of the MySQL Document Store and the X DevAPI, more are yet to come. Additional examples, code snippets and features not covered in this blog post can be found in the X DevAPI User Guide as well as in the Developer Guide and Reference documentation.

Feedback is always welcome

We are very excited to find out what our users will be able to accomplish when taking advantage of these new offerings, so please try it out and rest assured that you’ll be guided along the way. If you happen to have any questions about this or any other Connector/NET related topic you can always post them in the product’s main forum. Additionally, bugs can be reported in MySQL Bugs.

We hope to hear from you soon!

Useful links

MySQL Connector/Net 6.9.10 has been released

Dear MySQL users,

MySQL Connector/Net 6.9.10 is a maintenance release for the 6.9.x
series of the .NET driver for MySQL. It can be used for production
environments.

It is appropriate for use with MySQL server versions 5.5-5.7.

It is now available in source and binary form from
http://dev.mysql.com/downloads/connector/net/#downloadsandmirrorsites
(note that not all mirror sites may be up to date at this point-if you
can’t find this version on some mirror, please try again later or choose
another download site.)


Changes in MySQL Connector/Net 6.9.10 (2017-10-23, General Availability)

   Bugs Fixed

     * Executing MySql.Web.Security.CreateUserAndAccount with
       valid arguments returned an out-of-range exception.
       Thanks to Stein Setvik for contributing to the fix.
       (Bug #25046364)

     * The default character set and encoding were not set
       properly when making a connection to MySQL 5.6 and 5.7
       servers configured to use the utf8 character set.
       (Bug #23257011)

The documentation is available at:
http://dev.mysql.com/doc/connector-net/en/

Nuget packages are available at:
https://www.nuget.org/packages/MySql.Data/6.9.10
https://www.nuget.org/packages/MySql.Data.Entity/6.9.10
https://www.nuget.org/packages/MySql.Fabric/6.9.10
https://www.nuget.org/packages/MySql.Web/6.9.10


Enjoy and thanks for the support!

On behalf of the MySQL Connector/NET and the MySQL/ORACLE RE Team
Gipson Pulla

MySQL Connector/Net 8.0.9-dmr has been released

Dear MySQL users,

MySQL Connector/Net 8.0.9 is the sixth development release that expands
cross-platform support to Linux and macOS when using Microsoft’s .NET Core
framework. Now, .NET developers can use the X DevAPI with .NET Core and
Entity Framework Core (EF Core) 1.0 to create server applications that run
on Windows, Linux and macOS. We are very excited about this change and
really look forward to your feedback on it!

MySQL Connector/Net 8.0.9 is also the eighth development release of MySQL
Connector/Net to add support for the new X DevAPI.  The X DevAPI enables
application developers to write code that combines the strengths of the
relational and document models using a modern, NoSQL-like syntax that
does not assume previous experience writing traditional SQL.

To learn more about how to write applications using the X DevAPI, see
http://dev.mysql.com/doc/x-devapi-userguide/en/index.html. For more
information about how the X DevAPI is implemented in Connector/Net, see
http://dev.mysql.com/doc/dev/connector-net.

Please note that the X DevAPI requires at least MySQL Server version
5.7.12 or higher with the X Plugin enabled. For general documentation
about how to get started using MySQL as a document store, see
http://dev.mysql.com/doc/refman/5.7/en/document-store.html.

To download MySQL Connector/Net 8.0.9-dmr, see the “Development
Releases” tab at http://dev.mysql.com/downloads/connector/net/


Changes in MySQL Connector/Net 8.0.9 (2017-09-28, Development Milestone)


* Functionality Added or Changed

* Bugs Fixed

Functionality Added or Changed

* For accuracy, the following Entity Framework 6 items were
renamed:

+ NuGet package - MySql.Data.EntityFramework (was
MySql.Data.Entity)

+ Namespace - MySql.Data.EntityFramework (was
MySql.Data.Entity)

+ Assembly - MySql.Data.EntityFramework.dll (was
MySql.Data.Entity.EF6.dll)
(Bug #26396260)

* X DevAPI: The SessionConfigManager.Update method was
removed and the SessionConfigManager.Save method now
always overwrites the data with the given key. For
example:
SessionConfigManager.Save(
"mysess",
"{ \"uri\": \"mysqlx://myuser@localhost/mysess\", \"appdata\": { \"biz\": \"quux\" } }"
);

SessionConfigManager.Save(
"mysess",
"{ \"uri\": \"mysqlx://test@localhost/mysess\", \"appdata\": { \"tar\": \"zzzz\" } }"
);

The mysess.uri and mysess.appdata values set by the first
statement are replaced with the new values set by the
second statement. (Bug #25829054, Bug #25860579)

* MySQL Connector/Net now supports MySQL servers configured
to use utf8mb4 as the default character set.

* The following methods are available for use with EF Core
in asynchronous command and connection operations:

+ Microsoft.EntityFrameworkCore.DbContext.AddAsync

+ Microsoft.EntityFrameworkCore.DbContext.AddRangeAsync

+ Microsoft.EntityFrameworkCore.DbContext.FindAsync

+ Microsoft.EntityFrameworkCore.DbContext.SaveChangesAsync

+ Microsoft.EntityFrameworkCore.Infrastructure.Databas
eFacade.EnsureDeletedAsync

+ Microsoft.EntityFrameworkCore.Infrastructure.Databas
eFacade.EnsureCreatedAsync

+ Microsoft.EntityFrameworkCore.DbContext.ToListAsync

* X DevAPI: The following methods execute directly, whereas
each method previously required .execute() as the final
item in the method chain:

+ BaseSession.DropSchema

+ Collection.DropIndex

+ Schema.DropCollection

+ Schema.DropView
In addition, the methods now succeed even if the objects
to be dropped do not exist.

* The AutoEnlist and IncludeSecurityAsserts
connection-string options are not appropriate for use by
applications that target .NET Core and now return an
error when used.

* EF Core: Support for explicit loading was added. Explicit
loading is an object-relational mapper (O/RM) pattern
introduced in EF Core 1.1.0, which enables .NET
developers to explicitly load related data from the
database at a later time.

* The following connection-string options are not currently
supported for use by applications that target .NET Core
and now return an error when used:

+ SharedMemoryName

+ IntegratedSecurity

+ PipeName

+ Logging

+ UseUsageAdvisor

+ UsePerformanceMonitor

+ InteractiveSession

+ Replication

* X DevAPI: To provide safe transactional document and row
updates, the following new methods were added:

+ FindStatement.LockShared

+ FindStatement.LockExclusive

+ TableSelectStatement.LockShared

+ TableSelectStatement.LockExclusive
The LockShared() and LockExclusive() methods can be
called any number of times with either the
Collection.Find() or Table.Select() method chains and in
any combination. If multiple calls to the methods are
made, only the final method is invoked. For additional
information about the two types of locking, see Shared
and Exclusive Locks
(http://dev.mysql.com/doc/refman/5.7/en/innodb-locking.html#innodb-shared-exclusive-locks).

* X DevAPI: When creating a new session, multiple hosts can
be tried until a successful connection is established. A
list of hosts can be given in a connection string or as
session creation options, with or without priorities.
var mySession = MySQLX.GetSession(
"mysqlx://dbuser:password@[" +
"(address=localhost:33060, priority=90)," +
"(address=192.1.10.10:33060, priority=100)," +
"(address=[2001:db8:85a3:8d3:1319:8a2e:370:7348]:33060, priority=30)
" +
"]"
);

var mySession = MySQLX.GetSession(
"user=dbuser;" +
"password=dbpassword;" +
"server=" +
"(address=192.1.10.10, priority=90)," +
"(address=server.example.com, priority=100)," +
"(address=localhost, priority=30);" +
"port=33060;"
);


* X DevAPI: The IN and NOT IN operators have been updated
to expand the range of operands that can be evaluated by
the Find(), Modify(), and Remove() methods for
collections and the Select(), Update(), and Delete()
methods for tables. This update provides support for
expressions using the following syntax:
compExpr ["NOT"] "IN" compExpr

The previous syntax used with IN and NOT IN operators is
still valid and it takes precedence over the new syntax
when both are present.

* X DevAPI: Several new direct-execution methods were added
to the Collection class that operate at a single document
level, unlike the other CRUD methods that operate on all
documents that match a filter. The new methods are:
ReplaceOne(), AddOrReplaceOne(), GetOne(), and
RemoveOne().

* Support for connections using Unix domain socket files
was extended to include MySQL servers deployed on Linux
hosts.
X DevAPI connection example:
"server=/path/to/socket;protocol=unix;user=root;password=mypass;ssl-mode=none"

Classic MySQL connection example:
"server=/path/to/socket;protocol=unix;user=root;password=mypass"

* Connections to the MySQL server now can be made using
accounts that authenticate with the sha256_password
plugin. For more information, see SHA-256 Pluggable
Authentication
(http://dev.mysql.com/doc/refman/5.7/en/sha256-pluggable-authentication.html).
In addition, a new connection option was added to extend
authentication support for connections made using the X
Protocol with either basic or URI connection strings and
as an anonymous type. The auth connection option enables
the MYSQL41, PLAIN, or EXTERNAL authentication mechanism
if supported by the server. For a description of the auth
option, see Connector/Net Connection-String Options
Reference
(http://dev.mysql.com/doc/connector-net/en/connector-net-connection-options.html).

Bugs Fixed

* Assemblies within NuGet packages were not fully signed.
(Bug #26739307)

* EF Core: Some methods in the DbContext class were not
supported for use with asynchronous operations. (Bug
#26448321, Bug #84814)

* X DevAPI: Priority assignment when connecting to the
server in client-side failover situations was not
supported in earlier versions of the connector by design.
Priority-based failover is now available. (Bug #26198794)

* EF Core: When attempting to commit a transaction in which
the FirstOrDefaultAsync method was called, the connector
returned "System.InvalidOperationException: Connection
must be valid and open to commit transaction." instead of
committing the transaction. (Bug #26026972, Bug #86199)

* X DevAPI: Passing in a value of 0 or lower to the Limit
method now produces a more relevant error message
indicating that the argument is out of range. (Bug
#24384660)

* X DevAPI: Passing in the NULL value as a parameter to the
DbDoc.SetValue method resulted in an exception. This fix
ensures that NULL is accepted for this method. (Bug
#23542093)

Nuget packages are available at:

https://www.nuget.org/packages/MySql.Data/8.0.9-dmr
https://www.nuget.org/packages/MySql.Web/8.0.9-dmr
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore/8.0.9-dmr
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore.Design/8.0.9-dmr

Enjoy and thanks for the support!

On Behalf of the MySQL/ORACLE RE Team
Gipson Pulla

MySQL Connector/Net 8.0.8-dmr has been released

MySQL Connector/Net 8.0.8 is the fifth development release that expands cross-platform
support to Linux and macOS when using Microsoft’s .NET Core framework. Now, .NET
developers can use the X DevAPI with .NET Core and Entity Framework Core (EF Core)
1.0 to create server applications that run on Windows, Linux and macOS. We are very
excited about this change and really look forward to your feedback on it!

MySQL Connector/Net 8.0.8 is also the seventh development release of MySQL
Connector/Net to add support for the new X DevAPI. The X DevAPI enables application
developers to write code that combines the strengths of the relational and document
models using a modern, NoSQL-like syntax that does not assume previous experience
writing traditional SQL.

To learn more about how to write applications using the X DevAPI, see
http://dev.mysql.com/doc/x-devapi-userguide/en/index.html.
For more information about how the X DevAPI is implemented in Connector/Net, see
http://dev.mysql.com/doc/dev/connector-net.

Note

The X DevAPI requires at least MySQL Server version 5.7.12 or higher with the X
Plugin enabled. For general documentation about how to get started using MySQL
as a document store, see http://dev.mysql.com/doc/refman/5.7/en/document-store.html.

To download MySQL Connector/Net 8.0.8-dmr, see the “Development Releases” tab at
http://dev.mysql.com/downloads/connector/net/

 


Changes in MySQL Connector/Net 8.0.8 (2017-07-10, Development Milestone)

   MySQL Connectors and other MySQL client tools and
   applications now synchronize the first digit of their version
   number with the (highest) MySQL server version they support.
   For example, MySQL Connector/Net 8.0.12 would be designed to
   support all features of MySQL server version 8 (or lower).
   This change makes it easy and intuitive to decide which
   client version to use for which server version.

   MySQL Connector/Net 8.0.8 is the first release to use the new
   numbering. It is the successor to MySQL Connector/Net 7.0.7.

     * Functionality Added or Changed

     * Bugs Fixed

   Functionality Added or Changed

     * X DevAPI: The format of document ID values generated when
       adding documents to a collection has changed. It is still
       a string of 32 hexadecimal digits based on UUID, but the
       order of digits was changed to match the requirement of a
       stable ID prefix.

     * All connections created using MySQL Connector/Net now are
       secure by default. Also, the Ssl-Enable connection option
       has been replaced by Ssl-Mode. Permitted Ssl-Mode values
       are None, Required (the default), VerifyCA, and
       VerifyFull.

       With this change, a non-SSL enabled server now requires
       the Ssl-Mode option be set to None explicitly in the
       connection string or the connection will fail.

     * X DevAPI: It is no longer permitted to pass an empty
       search condition, such as the NULL value or an empty
       string, to the Collection.Modify and Collection.Remove
       methods.
	
     * X DevAPI: The NodeSession class has been renamed to
       Session and the MySQLX.GetNodeSession method has been
       renamed to MySQLX.GetSession. Also, the XSession class
       has been removed.

     * X DevAPI: When creating a new connection, multiple hosts
       now can be specified as part of the connection string,
       which will try each host until a successful connection is
       established or all elements from the host list have been
       tried. The following connection-string formats are
       supported:

	    var mySession = MySQLX.GetSession(
	      "mysqlx://dbuser:password@[" +
	      "localhost:33060," +
	      "192.1.10.10:33060," +
	      "[2001:db8:85a3:8d3:1319:8a2e:370:7348]:33060" +
	      "]"
	    );

	    var mySession = MySQLX.GetSession(
	      "user=dbuser;" +
	      "password=dbpassword;" +
	      "server=" +
	      "192.1.10.10," +
	      "server.example.com," +
	      "localhost;" +
	      "port=33060;"
	    );

   Bugs Fixed

     * EF Core: The Database First feature did not support the
       following data types: BINARY, VARBINARY, MEDIUMBLOB,
       LONGBLOB, SET, DATE, TIME, and YEAR. (Bug #25493209)

     * EF Core: Database First support produced an error when
       the existing MySQL database included one or more views.
       (Bug #25493086)

     * EF Core: Using
       System.ComponentModel.DataAnnotations.Schema.TableAttribu
       te to initialize a new class instance that specified the
       name of an existing MySQL table produced incorrect
       mappings of table and column names.
       (Bug #25394223, Bug #84423)

Nuget

Packages are available at:

https://www.nuget.org/packages/MySql.Data/8.0.8-dmr
https://www.nuget.org/packages/MySql.Web/8.0.8-dmr
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore/8.0.8-dmr
https://www.nuget.org/packages/MySql.Data.EntityFrameworkCore.Design/8.0.8-dmr

Enjoy and thanks for the support!

On Behalf of MySQL/Oracle Release Engineering Team
Prashant Team

MySQL Connector/Net 7.0.2 has been released

Dear MySQL users,

MySQL Connector/Net 7.0.2 M1 is the first development release that adds support for the new X DevAPI.  The X DevAPI enables application developers to write code that combines the strengths of the relational and document models using a modern, NoSQL-like syntax that does not assume previous experience writing traditional SQL.

To learn more about how to write applications using the X DevAPI, see this User Guide. For more information about how the X DevAPI is implemented in Connector/Net, please check the official product documentation.

Also note that the X DevAPI requires at least MySQL Server version 5.7.12 or higher with the X Plugin enabled. For general documentation about how to get started using MySQL as a document store, see this chapter at the reference manual.

Changes in MySQL Connector/Net 7.0.2 (2016-04-11, Milestone 1)

Functionality Added

  • Added support for the new X DevAPI

Nuget packages are available at:

https://www.nuget.org/packages/MySql.Data/7.0.2-DMR

https://www.nuget.org/packages/MySql.Data.Entity/7.0.2-DMR

https://www.nuget.org/packages/MySql.Fabric/7.0.2-DMR

https://www.nuget.org/packages/MySql.Web/7.0.2-DMR

We love to hear your thoughts or any comments you have about our product. Please send us your feedback at our forums, fill a bug at our community site, or leave us any comment at the social media channels.

Enjoy and thanks for the support!

On behalf of the MySQL Connector/Net Team