Dotnet upgrade page

dotnet-manual/modules/ROOT/content-nav.adoc

@@ -3,4 +3,5 @@
 * xref:client-applications.adoc[]
 * xref:cypher-workflow.adoc[]
 * xref:session-api.adoc[]
+* xref:upgrade.adoc[]
 * xref:terminology.adoc[]

dotnet-manual/modules/ROOT/pages/upgrade.adoc

@@ -0,0 +1,157 @@
+:driver-changelog-url: https://github.com/neo4j/neo4j-dotnet-driver/wiki/5.X-Change-Log
+
+= Upgrade from older versions
+
+This page contains the list of new features and breaking changes of the driver from version 4.4 to 5.x. +
+For a full list of changes, see the link:{driver-changelog-url}[Driver -> Changelog].
+
+[NOTE]
+This page may be revised with new changes up until when the latest 5.x version is released.
+
+The latest driver version of the 5.x series (5.27) is compatible with Neo4j server both 4.4 and 5.x, so you can upgrade the driver before you upgrade the server.
+At the same time, the driver version 4.4 is forward compatible with Neo4j server 5.x, so you could also upgrade the server before the driver; however, given that it's easier to roll back an application upgrade than a server upgrade, it's recommended to start with the driver.
+
+[TIP]
+When upgrading the Neo4j server to a newer version, the Cypher queries in your application may also need updating. +
+See link:https://neo4j.com/docs/cypher-manual/current/deprecations-additions-removals-compatibility/[Cypher -> Deprecations, additions, and compatibility].
+
+
+[[new-features]]
+== New features
+
+[cols="1a,1a"]
+|===
+
+|
+.Support for .NET 8
+[%collapsible]
+====
+The driver supports the .NET Standard 2.0. For supported versions of the .NET Framework, see the link:https://dotnet.microsoft.com/en-us/platform/dotnet-standard[.NET Standard page].
+====
+|
+.Run transactions with less knowledge of driver's internals
+[%collapsible]
+====
+The new method `Driver.ExecutableQuery()` is a wrapper for `Session.ExecuteRead/Write()`, but it abstracts away the result processing part and returns a list of records to the caller directly.
+
+For more information, see link:https://github.com/neo4j/neo4j-dotnet-driver/wiki/5.X-Change-Log#examples[`ExecutableQuery`].
+====
+
+|
+.Record to object mapping
+[%collapsible]
+====
+Allows records to be mapped to objects simply and without endless boilerplate.
+
+For more information, see link:https://github.com/neo4j/neo4j-dotnet-driver/wiki/5.X-Change-Log#crystal_ball-preview-feature-record-to-object-mapping[Record to Object Mapping].
+====
+|
+.Re-authentication
+[%collapsible]
+====
+Allows for handling expiring authentication (backwards compatible) as well as session scoped authentication.
+
+For more information, see link:https://github.com/neo4j/neo4j-dotnet-driver/discussions/705[Re-authentication].
+====
+
+|
+.Mutual TLS (mTLS) as second authentication factor (2FA)
+[%collapsible]
+====
+Allows for configuring client side TLS certificates to authenticate against the server.
+
+// See link:https://github.com/neo4j/neo4j-javascript-driver/pull/1183[Mutual TLS].
+====
+|
+.`BookmarkManager` support
+[%collapsible]
+====
+Bookmark managers make it easier to achieve causal chaining of sessions.
+
+See link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IBookmarkManager.html[interface `IBookmarkManager`].
+====
+
+|
+.Notification filtering API
+[%collapsible]
+====
+Filtering allows to receive only a subset of notifications from the server, and to improve performance server-side.
+
+For more information, see link:https://github.com/neo4j/neo4j-dotnet-driver/wiki/5.X-Change-Log#notificationconfig[NotificationConfig].
+====
+|
+.GQL statuses and errors
+[%collapsible]
+====
+The property link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IResultSummary.GqlStatusObjects.html[`IResultSummary.GqlStatusObjects`] contains a sequence of link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IGqlStatusObject.html[`IGqlStatusObject`], holding information about the execution of the query.
+This API is planned to supersede the current notifications API.
+
+// Interface link:https://neo4j.com/docs/api/java-driver/current/org.neo4j.driver/org/neo4j/driver/exceptions/Neo4jException.html[`Neo4jException`] exposes GQL metadata as well.
+
+// For more information, see xref:result-summary.adoc#_notifications[Explore the query execution summary -> Notifications].
+====
+
+|
+.Telemetry
+[%collapsible]
+====
+The driver sends anonymous API usage statistics to the server.
+Use the driver configuration method `.WithTelemetryDisabled()` to opt out.
+
+See link:https://github.com/neo4j/neo4j-dotnet-driver/pull/735[API Telemetry].
+====
+|
+
+|===
+
+
+[[breaking-changes]]
+== Breaking changes and deprecations
+
+Deprecated features are likely to be removed in version 6.
+
+[cols="1,5a,1"]
+|===
+|Version |Message |Status
+
+|5.0
+|link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IServerInfo.html[`IServerInfo`] -- Method `.Version()` has been removed.
+Use `.Agent()`, `.ProtocolVersion()`, or call the link:https://neo4j.com/docs/operations-manual/current/reference/procedures/#procedure_dbms_components[`dbms.components`] Cypher procedure instead.
+|label:removed[]
+
+|5.0
+|link:[`ISession`], link:[`IRxSession`], link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IAsyncSession.html[`IAsyncSession`] -- Methods `.ReadTransaction()` and `.WriteTransaction()` are deprecated in favor of `.ExecuteRead()` and `.ExecuteWrite()`.
+The same holds for the async coounterparts `.ReadTransactionAsync()` and `.WriteTransactionAsync()`, replaced by `.ExecuteReadAsync()` and `.ExecuteWriteAsync()`.
+
+The new methods behave similarly, but the argument types are different and the new methods do not support the `.commit()`, `.rollback()`, `.close()`, and `.closed()` methods.
+|label:deprecated[]
+
+|5.0
+|link:[`ISession`], link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IAsyncSession.html[`IAsyncSession`] -- Method `.LastBookmark()` is deprecated in favor of `.LastBookmarks()`.
+|label:deprecated[]
+
+|5.0
+|Type `Bookmark` is deprecated in favor of link:[`Bookmarks`].
+|label:deprecated[]
+
+|5.0
+|link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.SessionConfigBuilder.html[`SessionConfigBuilder`] -- Method link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.SessionConfigBuilder.WithBookmarks.html#Neo4j_Driver_SessionConfigBuilder_WithBookmarks_Neo4j_Driver_Bookmarks___[`.WithBookmarks()`] takes `Bookmarks[]` as argument rather than `Bookmark[]`.
+|label:deprecated[]
+
+|5.0
+|`ZonedDateTime` -- Two constructors not including `DateTimeKind` are deprecated (link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.ZonedDateTime.-ctor.html#Neo4j_Driver_ZonedDateTime__ctor_System_Int32_System_Int32_System_Int32_System_Int32_System_Int32_System_Int32_Neo4j_Driver_Zone_[this] and link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.ZonedDateTime.-ctor.html#Neo4j_Driver_ZonedDateTime__ctor_System_Int32_System_Int32_System_Int32_System_Int32_System_Int32_System_Int32_System_Int32_Neo4j_Driver_Zone_[this]).
+|label:deprecated[]
+
+|5.0
+|link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IEntity.html[`IEntity`], link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.INode.html[`INode`], link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IRelationship.html[`IRelationship`] -- Method `.Id()` (`long`) is deprecated in favor of `.ElementId()` (`string`).
+|label:deprecated[]
+
+|5.0
+|link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.IRelationship.html[`IRelationship`] -- Methods `.StartNodeId()` and `.EndNodeId()` are deprecated in favor of `.StartNodeElementId()` and `.EndNodeElementId()`. Old identifiers were `long`, wereas new ElementIds are `string`.
+|label:deprecated[]
+
+|5.7
+|link:https://neo4j.com/docs/api/dotnet-driver/current/api/Neo4j.Driver.INotification.html[`INotification`] -- Property `Severity` is deprecated in favor of `SeverityLevel` or `RawSeverityLevel`.
+|label:deprecated[]
+
+|===