Chapter 3 Connector/NET Installation

Table of Contents

3.1 Installing Connector/NET on Windows
3.1.1 Installing Connector/NET Using MySQL Installer
3.1.2 Installing Connector/NET Using the Standalone Installer
3.1.3 Installing Connector/NET Using NuGet
3.2 Installing Connector/NET on Unix with Mono
3.3 Installing Connector/NET from the Source Code

MySQL Connector/NET runs on any platform that supports the .NET Standard (.NET Framework, .NET Core, and Mono). The .NET Framework is primarily supported on recent versions of Microsoft Windows and Microsoft Windows Server.

Cross-platform options:

Connector/NET is available for download from the MySQL Installer, as a standalone MSI Installer, or from the NuGet gallery. The source code is available for download from MySQL Download MySQL Connector/NET or at GitHub from the MySQL Connector/NET repository.

3.1 Installing Connector/NET on Windows

On Microsoft Windows, you can install either through a binary installation process using a Connector/NET MSI, choose the MySQL Connector/NET product from the MySQL Installer, using NuGet, or by downloading and using the source code.

Before installing, ensure that your system is up to date, including installing the latest version of the .NET Framework or .NET Core. For additional information, see Chapter 2, Connector/NET Versions.

3.1.1 Installing Connector/NET Using MySQL Installer

MySQL Installer provides an easy to use, wizard-based installation experience for all MySQL software on Windows. It can be used to install and upgrade your MySQL Connector/NET installation.

To use, download and install MySQL Installer.

After executing MySQL Installer, choose and install the Connector/NET product.

3.1.2 Installing Connector/NET Using the Standalone Installer

You can install MySQL Connector/NET through a Windows Installer (.msi) installation package, which can install Connector/NET on supported Windows operating systems. The MSI package is a file named mysql-connector-net-version.msi, where version indicates the Connector/NET version.

Note

Using the central MySQL Installer is recommended, instead of the standalone package that is documented in this section. The MySQL Installer is available for download at MySQL Installer.

To install Connector/NET:

  1. Double-click the MSI installer file, and click Next to start the installation.

  2. Choose the type of installation to perform (Typical, Custom, or Complete) and then click Next.

    • The typical installation is suitable in most cases. Click Typical and proceed to Step 5.

    • A Complete installation installs all the available files. To conduct a Complete installation, click the Complete button and proceed to step 5.

    • To customize your installation, including choosing the components to install and some installation options, click the Custom button and proceed to Step 3.

    The Connector/NET installer will register the connector within the Global Assembly Cache (GAC) - this will make the Connector/NET component available to all applications, not just those where you explicitly reference the Connector/NET component. The installer will also create the necessary links in the Start menu to the documentation and release notes.

  3. If you have chosen a custom installation, you can select the individual components to install, including the core interface component, supporting documentation options, examples, and the source code. Click Disk Usage to determine the disk-space requirements of your component choices.

    Select the items and their installation level and then click Next to continue the installation.

  4. You will be given a final opportunity to confirm the installation. Click Install to copy and install the files onto your computer. Use Back to return to the modify your component options.

  5. When prompted, click Finish to exit the MSI installer.

Unless you choose a different folder, Connector/NET is installed in C:\Program Files (x86)\MySQL\MySQL Connector Net version (the version installed). New installations do not overwrite existing versions of Connector/NET.

You may also use the /quiet or /q command-line option with the msiexec tool to install the Connector/NET package automatically (using the default options) with no notification to the user. Using this method the user cannot select options. Additionally, no prompts, messages or dialog boxes will be displayed.

C:\> msiexec /package connector-net.msi /quiet

To provide a progress bar to the user during automatic installation, use the /passive option.

3.1.3 Installing Connector/NET Using NuGet

MySQL Connector/NET functionality is available as packages from NuGet, an open-source package manager for the Microsoft development platform (including .NET Core). The NuGet Gallery is the central software package repository populated with the most recent NuGet packages for Connector/NET.

You can install or upgrade one or more individual Connector/NET packages with NuGet, making it a convenient way to introduce existing technology, such as Entity Framework, to your project. NuGet manages dependencies across the related packages and all of the prerequisites are listed in the NuGet Gallery. For a description of each Connector/NET package, see Connector/NET Packages (NuGet).

Important

For projects that require Connector/NET assemblies to be stored in the GAC, integration with Entity Framework Designer (Visual Studio), or access to MySQL for Visual Studio, use MySQL Installer or the standalone MSI to install Connector/NET, rather than installing the NuGet packages.

Consuming Connector/NET Packages with NuGet

The NuGet Gallery (https://www.nuget.org/) provides several client tools that can help you install or upgrade Connector/NET packages. If you are not familiar with the tool options or processes, see Package consumption workflow to get started. After locating a package description in NuGet, confirm the following information:

  • The identity and version number of the package are correct. Use the Version History list to select the current version.

  • All of the prerequisites are installed. See the Dependencies list for details.

  • The license terms are met. See the License Info link to view this information.

Connector/NET Packages (NuGet)

Connector/NET provides the following five NuGet packages:

MySql.Data

This package contains the core functionality of Connector/NET, including using MySQL as a document store (with Connector/NET 8.0 only). It implements the required ADO.NET interfaces and integrates with ADO.NET-aware tools. In addition, the packages provides access to multiple versions of MySQL server and encapsulates database-specific protocols.

MySql.Web

The MySql.Web package includes support for the ASP.NET 2.0 provider model (see Section 5.18, “ASP.NET Provider Model”). This model enables you to focus on the business logic of your application, rather than having to recreate boilerplate items such as membership and roles support. The package supports the membership, role, profile, and session-state providers.

Package dependency: MySql.Data.

MySql.Data.EntityFramework

This package provides object-relational mapper (ORM) capabilities, which enables you to work with MySQL databases using domain-specific objects, thereby eliminating the need for most of the data access code. Select this package for your Entity Framework 6 applications (see Section 9.1, “Entity Framework 6 Support”).

Package dependency: MySql.Data.

MySql.Data.EntityFrameworkCore

This package is similar to the MySql.Data.EntityFramework package; however, it provides multi-platform support for Entity Framework tasks. Select this package for your Entity Framework Core applications (see Section 9.2, “Entity Framework Core Support”).

MySql.Data.EntityFrameworkCore.Design

The MySql.Data.EntityFrameworkCore.Design package includes shared design-time components for Entity Framework Core tools, which enable you to scaffold and migrate MySQL databases.

3.2 Installing Connector/NET on Unix with Mono

There is no installer available for installing the MySQL Connector/NET component on your Unix installation. Before installing, ensure that you have a working Mono project installation. To test whether your system has Mono installed, enter:

shell> mono --version

The version of the Mono JIT compiler is displayed.

To compile C# source code, make sure a Mono C# compiler is installed.

Note

There are three Mono C# compilers available: mcs, which accesses the 1.0-profile libraries, gmcs, which accesses the 2.0-profile libraries, and dmcs, which accesses the 4.0-profile libraries.

To install Connector/NET on Unix/Mono:

  1. Download the mysql-connector-net-version-noinstall.zip and extract the contents to a directory of your choice, for example: ~/connector-net/.

  2. In the directory where you unzipped the connector to, change into the bin subdirectory. Ensure the file MySql.Data.dll is present. This filename is case-sensitive.

  3. You must register the Connector/NET component, MySql.Data, in the Global Assembly Cache (GAC). In the current directory enter the gacutil command:

    root-shell> gacutil /i MySql.Data.dll
    

    This will register MySql.Data into the GAC. You can check this by listing the contents of /usr/lib/mono/gac, where you will find MySql.Data if the registration has been successful.

You are now ready to compile your application. You must ensure that when you compile your application you include the Connector/NET component using the -r: command-line option. For example:

shell> gmcs -r:System.dll -r:System.Data.dll -r:MySql.Data.dll HelloWorld.cs

The referenced assemblies depend on the requirements of the application, but applications using Connector/NET must provide -r:MySql.Data at a minimum.

You can further check your installation by running the compiled program, for example:

shell> mono HelloWorld.exe

3.3 Installing Connector/NET from the Source Code

Source packages of MySQL Connector/NET are available for download from https://dev.mysql.com/downloads/connector/net/.

The file contains the following folders:

  • Documentation: Files to build the documentation into the compiled HTML (CHM) format.

  • EntityFramework: Source files and test cases.

  • EntityFrameworkCore: Source files and test cases.

  • MySQL.Data: Source files and test cases.

  • MySQL.Web: Source files for the web providers, including the membership/role/profile providers that are used in ASP.NET websites.

Building the Source Code on Microsoft Windows

The following procedure can be used to build the connector on Microsoft Windows.

  • Navigate to the root of the source code tree.

  • A Microsoft Visual Studio solution file named MySqlClient.sln is available to build the connector. Click this file to load the solution into Visual Studio.

    MySqlClient.sln must be compiled with VS 2008, VS 2010, or VS 2012. Also, depending on the version, the dependencies to build it include Visual Studio SDK, NUnit, Entity Framework, and ANTLR Integration for Visual Studio.

  • Select Build, Build Solution from the main menu to build the solution.

Building the Source Code on Unix

Support for building Connector/NET on Mono/Unix is not available.