Getting Started

Getting started

Home / Start building

Goal: connect securely, run a small query, and release the connection correctly.

The ADO.NET driver documentation hub is the starting point for learning SqlClient. Use its driver overview for concepts and getting-started tutorial for the complete walkthrough. The checklist below helps you prepare.

Before you install

Choose a supported .NET runtime and driver release using Releases and support. Have a reachable SQL Server or Azure SQL database, an identity with the required permissions, and a certificate configuration trusted by your application host.

Installing the driver does not install SQL Server or grant database access.

Your first connection

1. Follow Install Microsoft.Data.SqlClient to add the NuGet package at the selected supported patch version.
2. For MDS 7.x driver-provided Entra authentication, also add the matching Microsoft.Data.SqlClient.Extensions.Azure package. SQL authentication and Windows integrated security do not require this extension.
3. Use the Microsoft.Data.SqlClient namespace. Keep general ADO.NET types such as DbConnection and SqlDbType in their existing namespaces.
4. Supply connection settings through application configuration or a secret store. Require encryption and validate the server certificate; do not solve a trust error by quietly disabling validation.
5. Follow the official getting-started tutorial. Begin with a small query using the identity and host configuration you will deploy.
6. Dispose connections, commands, and readers when their work is complete. Use parameters for values rather than constructing SQL with user input.

Success looks like: a connection opens, the query returns the expected result, and all disposable resources are released. Repeat from the actual deployment environment; a successful developer-machine connection does not prove production authentication, certificates, or native assets are ready.

If the first connection fails

Identify whether the error is name resolution/networking, certificate validation, authentication, or database authorization. Use Troubleshooting instead of changing several settings at once.

Next: Feature guides.

Sources: Getting started, connection strings, Entra authentication.