Repository files navigation

This repository contains the officialNeo4j driver for .NET.

This document covers the usage of the driver; for contribution guidance, seeContributing.

Neo4j publishes its .NET libraries to NuGet with the following targets:

• .NET Standard 2.0, for moreinfo:https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0
• .NET 6.0
• .NET 8.0 as of 5.17

To add the latestNuGet package:

> dotnet add package Neo4j.Driver

Starting with 5.0, the Neo4j drivers moved to a monthly release cadence. A new minor version is released on the lastThursday of each month to maintain versioning consistency with the core product (Neo4j DBMS), which also has moved to amonthly cadence.

As a policy, Neo4j will not release patch versions except on rare occasions. Bug fixes and updates will go into thelatest minor version; users should upgrade to a later version to patch bug fixes. Driver upgrades within a major versionwill never contain breaking API changes, excluding theNeo4j.Driver.Preview namespace reserved for the preview offeatures.

See also:https://neo4j.com/developer/kb/neo4j-supported-versions/

• Neo4j.Driver.Simple exposes synchronous APIs on the driver'sIDriver interface.
• Neo4j.Driver.Reactive exposes reactive APIs on the driver'sIDriver interface.

Astrong-named version of each driver packageis available on NuGetNeo4j.Driver.Signed. The strong-namedpackages contain the same version oftheir respective packages with strong-name compliance.Consider using the strong-named version only if your project isstrong-named or requires strong-named dependencies.

To add the strong-named version of the driver to your project using the NuGet Package Manager:

>Install-Package Neo4j.Driver.Signed

usingNeo4j.Driver;awaitusingvardriver=GraphDatabase.Driver("bolt://localhost:7687",AuthTokens.Basic("neo4j","password"));

There are a few points to highlight when adding the driver to your project:

• EachIDriver instance maintains a pool of connections inside; as a result, use a single driver instance perapplication.
• Sessions and transactions do not open new connections if a free one is in the driver's connection pool; this makesboth resources cheap to create and close.
• The driver is thread-safe and made to be used across an application. Sessions and transactions are not thread-safe;using a session or transaction concurrently will result in undefined behavior.

awaitdriver.VerifyConnectivityAsync();

To ensure the credentials and URLs specified when creating the driver, you can callVerifyConnectivityAsync on thedriver instance. If either configuration is wrong, the Task will result in an exception.

awaitdriver.ExecutableQuery("CREATE (:Node{id: 0})").WithConfig(newQueryConfig(database:"neo4j")).ExecuteAsync();

As of version 5.10, The .NET driver includes a fluent querying API on the driver's IDriver interface. The fluent API isthe most concise API for executing single query transactions. It avoids the boilerplate that comes with handling complexproblems, such as results that exceed memory or multi-query transactions.

.WithConfig(newQueryConfig(database:"neo4j"))

Always specify the database when you know which database the transaction should execute against. By setting the databaseparameter, the driver avoids a roundtrip and concurrency machinery associated with negotiating a home database.

varresponse=awaitdriver.ExecutableQuery("MATCH (n:Node) RETURN n.id as id").WithConfig(dbConfig).ExecuteAsync();

The response from the fluent APIs isanEagerResult<IReadOnlyList<IRecord>> unless we useother APIs; more on that later.EagerResult comprises of the following:

• All records materialized(Result).
• keys returned from the query(Keys).
• aquery summary(Summary).

var(result, _, _)=awaitdriver.ExecutableQuery(query).WithConfig(dbConfig).ExecuteAsync();foreach(varrecordinresult)Console.WriteLine($"node:{record["id"]}")

EagerResult allows you to discard unneeded values with decomposition for an expressive API.

var(result, _, _)=awaitdriver.ExecutableQuery(query).WithConfig(dbConfig).WithMap(record=>newEntityDTO{id=record["id"].As<long>()}).ExecuteAsync();

Values in a record are currently exposed as ofobject type.The underlying types of these values are determined by their Cypher types.

The mapping between driver types and Cypher types are listed in the table bellow:

To convert fromobject to the driver type, a helper methodValueExtensions#As<T> can be used:

IRecordrecord=awaitresult.SingleAsync();stringname=record["name"].As<string>();

The mapping among the Cypher temporal types, driver types, and convertible CLR temporal types - DateTime, TimeSpan andDateTimeOffset - (viaIConvertible interface) are as follows: