Couchbase .NET SDK Release Notes and Archives

    Release notes, installation instructions, and download archive for the Couchbase .NET Client.

    The Couchbase .NET SDK targets and is tested with .NET Standard 2.0 and 2.1, which in turn supports .NET Framework 4.6.2+ and .NET Core (e.g. netcoreapp) 2.1. A full list of supported platforms can be found in the .NET Standard documentation. The SDK also may use some dependencies that have not yet made it into .NET Standard; these can enabled by targeting .netcoreapp2.1 or .netcoreapp3.0. Eventually as they are added to the standard, these platform targets will be removed.

    These pages cover the 3.0 versions of the Couchbase .NET SDK. For release notes, download links, and installation methods for 2.7 and earlier releases of the Couchbase .NET Client, please see the 2.x .NET Release Notes & Download Archive.


    Quick Installation Using NuGet

    For every release, we currently package the binaries and store the latest version in NuGet. If you are not familiar with NuGet, it’s the official and most widely supported package manager for Microsoft Visual Studio and .NET in general.

    NuGet from Visual Studio

    Using Visual Studio 2013 or later, follow these steps to get started with the Couchbase .NET SDK:

    1. From the IDE, right-click the project you want to add the dependency to.

    2. In the context menu, click Manage NuGet Packages. The NuGet package manager modal dialog opens.

    3. From the Tree View menu on the left, select Online >

    4. In the search box at the top right-hand side of the dialog, type CouchbaseNetClient and then press enter on your keyboard.

    5. In the search results, select the CouchbaseNetClient package and then click Install.

    NuGet from the Package Manager Console

    From the Package Manager Console within your project:

    1. From the Visual Studio menu bar, click Tools.

    2. Select NuGet Package Manager > Package Manager Console.

    3. In the console, enter the package installation command:

      • To install the latest version:

     Install-Package CouchbaseNetClient
    • To install a specific version, include the version parameter. For example:

     Install-Package CouchbaseNetClient -Version 2.7.0

    Downloading and referencing the binaries

    If you do not want to use NuGet to include the Couchbase .NET SDK in your project, you can download and reference the binaries directly. If you chose this route, you’ll also be responsible for including and resolving dependencies used internally by the SDK.

    To download and reference the binaries directly:

    1. Download the version of the SDK you want to install.

    2. In Visual Studio, right-click the project you want to include the SDK in and then click Add.

    3. Click Reference to open the Reference Manager.

    4. On the left side, click Browse and select the binaries you downloaded.

    5. Click OK.

    After you have referenced the Couchbase .NET SDK binaries, you need to locate and reference the dependencies it uses in a similar fashion. At the time of this writing, the dependencies are:

    Other versions might not be compatible with the current SDK version.

    Building from source

    If none of the other installation options suffice or if you want to debug the source or perhaps contribute, building directly from the source is the best option for you. All source is located on GitHub.

    Note:The software provided via NuGet and S3 are the official releases that have been through a rigorous testing process. Code on GitHub that is not tagged as an official release is still in development.

    To build the .NET SDK from source:

    1. (Optional) Fork the GitHub repository:

    2. Using a Git console, enter the command to clone the repository:

    git clone
    1. Enter the command to retrieve the latest code from GitHub:

    git pull origin master
    1. Navigate to the directory that the source was cloned to and open the solution.

    2. Build the solution.

    After you have successfully built the source, it’s then just a matter of referencing the binaries (.DLL files) from your consuming project. Note that you can checkout a specific tag for each release as well.

    Version 3.0.5 (1 September 2020)

    Fixed Issues

    • NCBC-2504: Intermittent ViewQuery failures after rebound Rb2OutEpt-HYBRID

    • NCBC-2559: Test_BootStrap_Error_Propagates_To_View_Operations fails w/BucketNotFoundException

    • NCBC-2561: CreateAndDropIndex and Test_QueryManager conflict

    • NCBC-2625: Ensure new NodeAdapter is assigned to ClusterNode on change

    • NCBC-2634: Expiry returned with entire document when ContentAs invoked

    • NCBC-2405: SDK3 DOC on User Auth options

    • NCBC-2541: WaitUntilReady() doc code sample

    • NCBC-2603: Missing snippets & sections in Managing Connections doc

    • NCBC-2623: Implement Threshold Logging features of RTO

    • NCBC-2636: Test max limitations of collections and scopes

    • NCBC-2637: Split Couchbase.IntegrationTests into seperate projects for Management and main API

    • NCBC-2427: Verify that out-of-order K/V request/responses are supported

    • NCBC-2584: Add N1QL Support for Collections

    • NCBC-2630: Enhance User Management for Collections/RBAC

    Version 3.0.4 (5 August 2020)

    Known Issues

    • NCBC-2187: CollectionManager — 400: Not allowed on this version of cluster.

    Fixed Issues

    • NCBC-2605: Expiration less than 1000ms creates a doc with an infinite lifespan

    • NCBC-2608: Connection fails if first node in connection string array is unavailable.

    • NCBC-2620: Expiry not being set by MutateIn

    • NCBC-2621: Ensure the CName field is set per operation

    • NCBC-2601: SUBDOC_XATTR_INVALID_FLAG_COMBO when mixing MutationMacro and XAttr

    New Features and Behavioral Changes.

    • NCBC-2441: Implement tracing using OpenTelemetry for FTS

    • NCBC-2442: Implement tracing using OpenTelemetry for KV

    • NCBC-2443: Implement tracing using OpenTelemetry for Analytics

    • NCBC-2444: Implement tracing using OpenTelemetry for Views

    • NCBC-2579: Implement tracing of spans for all services towards Response Time Observability for SDK 3.0

    • NCBC-2583: Add support for looking up certificates via Cert Store

    • NCBC-2602: Add Support for MutateIn.SetDocument

    • NCBC-2609: Add PublicKey to AssemblyInfo for DI when building release packages

    • NCBC-2617: When signing make friend assemblies use public key

    Version 3.0.3 (14 July 2020)

    Known Issues

    • NCBC-2187: CollectionManager — 400: Not allowed on this version of cluster.

    Fixed Issues

    • NCBC-2588: LookupIn should re-order subdoc requests so that XATTRs come first.

    • NCBC-2450: KV failure after removing entry point node for pre-MH server

    • NCBC-2501: latency detected in FoEptRb-SubDoc after rebound never recovers

    • NCBC-2502: latency detected in FoEptEject-SUBDOC after rebound never recovers

    • NCBC-2503: Latency detected for FoRbAnalytics-CBAS after rebound never recovers

    • NCBC-2545: Hello World example in the docs repo doesn't build.

    • NCBC-2553: Remove authzid from Sasl Negotiation

    • NCBC-2563: StreamingQueryResult fails to populate errors on InternalServerError

    • NCBC-2587: LookupInSpecBuilder allows only a single XATTR per request.

    • NCBC-2592: Fix custom circuit breaker not being injected

    • NCBC-1836: CAS samples

    New Features and Behavioral Changes.

    • NCBC-2542: OpenTelemetry tracing extension

    • NCBC-2593: Update install and start docs to reflect .NET Standard/Core support

    • NCBC-2594: Update version number on release notes

    • NCBC-2595: Indent code on error handling page so that it is readable.

    • NCBC-2227: Author Managing Connections documentation

    • NCBC-2170: Implement tracing using OpenTelemetry for Query

    • NCBC-2519: Review docs for update items, identify/file issues

    • NCBC-2598: Misc SDK improvements for Transactions

    • NCBC-2591: Allow registration of custom services

    Version 3.0.2 (20 June 2020)

    Known Issues

    • NCBC-2187: CollectionManager — 400: Not allowed on this version of cluster.

    Fixed Issues

    • NCBC-2436: User connstr example in migration guide

    • NCBC-2459: Remove QueryOptions from StartUsing.cs in docs

    • NCBC-2487: NRE when bootstrapping - BucketConfigExtensions.ReplacePlaceholderWithBootstrapHost

    • NCBC-2506: Connection attempt failed / timeout exception with Cloud and .NET SDK 3.0.1

    • NCBC-2508: Alternate Addresses are not handled correctly in sdk3

    • NCBC-2512: Additional debug logging and improvements

    • NCBC-2525: Connection pool does not scale up to minimum connections after a temporary network failure.

    • NCBC-2526: requests wait forever while cluster is unreachable

    • NCBC-2537: Orphaned nodes when bootstrapping with a Memcached and a Couchbase bucket

    • NCBC-2538: Analytics failures after failover/rebalance of the ept node

    • NCBC-2540: Enumerating query results from SELECT RAW queries throws an exception

    • NCBC-2546: Retry all exceptions with the IRetriable marker interface

    • NCBC-2548: Ensure all operations attempt retrys when NMVB status is returned by server

    • NCBC-2549: Subdoc failures after restarting CB server

    • NCBC-2552: Intermittent cluster connection failures with CB Server <6.5

    • NCBC-2555: Memcached and SSL results in "The handshake failed due to an unexpected packet format."

    • NCBC-2556: Capture thrown exception and log the error when bootstrapping

    • NCBC-2558: Couchbase.Extensions.DependencyInjection Failing On .NET Core 3.1

    New Features and Behavioral Changes.

    • NCBC-2202: Integration tests need to configure tests to run based on server version

    • NCBC-2237: PLAIN must not be enabled by default on non-tls connections

    • NCBC-2404: ConnectAsync throws ArgumentNullException when cluster cannot be reached

    • NCBC-2530: Provide navigation properties to get from ICouchbaseCollection back to ICluster

    • NCBC-2533: Provide access to ITypeSerializer on ICluster for Linq2Couchbase

    • NCBC-2544: Add additional DEBUG logging info and ContextIds

    • NCBC-2463: Document documentation .NET

    • NCBC-2469: Make nightly Jenkins builds work

    • NCBC-2495: Update NuGet API Key in deployment pipeline on Jenkins

    • NCBC-2509: CreateAndConnectAsync ONLY creates CouchbaseBuckets (not MemCache or Ephemeral)

    • NCBC-2517: DependencyInjection project refactoring

    • NCBC-2523: Port ClusterVersion from sdk2 to sdk3

    • NCBC-2527: Update DnsClient to 1.3.2

    • NCBC-2529: CB Cloud: non-KV nodes fail when used for bootstraping

    • NCBC-2534: .NET Collections Functional Testing

    • NCBC-2539: Port UnixMillisecondsConverter from sdk2 to sdk3

    • NCBC-2482: Couchbase.IntegrationTests.Services.Search.SearchIndexManagerTests.TestSearchManager

    • NCBC-2483: Couchbase.IntegrationTests.UserManagerTests.Test_UserManager

    • NCBC-2484: Couchbase.IntegrationTests.BucketManagerTests.Test_BucketManager

    • NCBC-2485: Couchbase.IntegrationTests.Diagnostics.PingReportTests.Can_Get_PingReport_With_ReportId

    • NCBC-2486: Couchbase.IntegrationTests.CollectionManagerTests.Test_CollectionManager

    • NCBC-2489: Couchbase.IntegrationTests.ClusterTests.Test_Open_More_Than_One_Bucket

    • NCBC-2490: Couchbase.ServiceNotAvailableException : Service views not available.

    • NCBC-2518: HttpStreamingConfigListener should continue running after all streams break.

    • NCBC-2524: Couchbase.IntegrationTests.ClusterTests.Test_WaitUntilReadyAsync

    • NCBC-2531: Implement OpenTelemetry Stub in CouchbaseNetClient

    • NCBC-2532: Remove existing OpenTracing dependency

    Version 3.0.1 (13 May 2020)

    Known Issues

    • NCBC-2187: CollectionManager — 400: Not allowed on this version of cluster.

    Fixed Issues

    • NCBC-2033: 3.0 API Query snippets in concept doc

    • NCBC-2204: Improve exception when bootstrapping fails

    • NCBC-2301: 3.0 Logging / Collecting Info page

    • NCBC-2303: Client Settings page for SDK 3.0

    • NCBC-2388: Ensure that prepared statements that are previously created are not retried

    • NCBC-2435: Connstr not taking username properly

    • NCBC-2439: improve formatting on exception context

    • NCBC-2451: QueryPreparedStatementFailure in situational tests with MH

    • NCBC-2454: EndPoint may be null during SendAsync

    • NCBC-2456: Transient NodeNotAvailableException rebalance under kv load

    • NCBC-2458: QueryAsync(String statement) does not exist

    • NCBC-2460: .NET Core App 3.x targets require consumers add reference to Microsoft.Bcl.AsyncInterfaces

    • NCBC-2462: ConnectAsync is failing "Cannot resolve DNS for localhost"

    • NCBC-2466: Ensure TaskCancelationExceptions are rethrown

    • NCBC-2467: CLONE - Ensure TaskCancelationExceptions are rethrown

    • NCBC-2468: System.ArgumentException: ReadResult does not contain valid MutationToken

    • NCBC-2473: Incorrect Verbiage for NuGet Package

    • NCBC-2475: GetNodes() sometimes returns no results, incorrectly.

    • NCBC-2479: Point config.json for combination tests back at localhost

    • NCBC-2480: SocketException: Cannot bind to address in SslConnectionTests

    • NCBC-2481: KV operations don’t respect IgnoreCertificateNameMismatch

    • NCBC-2488: Couchbase.IntegrationTests.BootstrapFailedTests.Test_BootStrap_Error_Propagates_To_View_Operations [FAIL]

    • NCBC-2493: Improve error logging and handling for Query

    • NCBC-2497: SetKeepAlive fails on Windows

    New Features and Behavioral Changes.

    • NCBC-2304: Managing Connections - SDK3

    • NCBC-2464: Build/deploy the .NET Dependency Injection extension for SDK 3.0

    • NCBC-2478: Cluster.ConnectAsync throws PlatformNotSupportedException

    • NCBC-2492: Log warning when TCPKeepAlive cannot be enabled

    • NCBC-2494: Fix TCPKeepAlive to work on non Windows Platform

    Version 3.0.0 (31 March 2020)

    This is the first GA release of the third generation .NET SDK.

    This release features significant changes to the API, simplifies the programming model, adds support for newer Durability Requirements and enables simple extension for features coming in future Couchbase Server releases. See the Migration Guide for help with migrating from .NET SDK 2.x.

    Known Issues

    • NCBC-2187: CollectionManager — 400: Not allowed on this version of cluster.

    Fixed Issues

    • NCBC-2149: ConfigConext throws NullReferenceException when processing new cluster maps

    • NCBC-2153: Fix failing integration tests for SDK3

    • NCBC-2166: Authentication Errors after adding nodes to cluster

    • NCBC-2168: QueryException does not provide textual details coming from the server

    • NCBC-2199: Missing string interpolation sign in CouchbaseBucket

    • NCBC-2213: N1QL situational test failure - Rb1SwapQuery

    • NCBC-2214: N1QL situational test failure - SvcRestartQuery

    • NCBC-2217: Deserialization issues with GetAsync<T>

    • NCBC-2219: Cluster instantiation using ClusterOptions ignores WithServers servers

    • NCBC-2222: AuthenticationFailure thrown when accessing bucket while combination testing

    • NCBC-2230: QueryException missing XxxxContext

    • NCBC-2241: Defer bootstrapping errors on buckets to first operation

    • NCBC-2266: UserManager#AvailableRolesAsync must be called getRoles

    • NCBC-2268: CollectionManager does not align with RFC

    • NCBC-2273: Incorrect ScopeMissingException

    • NCBC-2274: Can’t connect to two buckets from one cluster object

    • NCBC-2277: SearchOptions does not map query parameters

    • NCBC-2282: fix test and implementation of positional params

    • NCBC-2286: Make all options have no "With" prefix

    • NCBC-2288: MutateIn ContentAs() functionality missing

    • NCBC-2290: Add Timeout to all options classes in BucketManager

    • NCBC-2306: Match RFC requirement for Rows property for query services

    • NCBC-2307: Cannot query using any type other than dynamic

    • NCBC-2308: N1QL query situational failure

    • NCBC-2309: Hybrid/view query errors with situational testing

    • NCBC-2316: Ensure view request get default timeout if not supplied

    • NCBC-2324: Random KeyNotFoundException in LogManagerTests.Test_LogLevel_Debug

    • NCBC-2350: SearchOptions.Raw is unused, and throws an NRE

    • NCBC-2351: View timeout is not applied to view query string

    • NCBC-2352: Cleanup Service Exceptions Hiding Context

    • NCBC-2353: Cleanup .NET SDK 3 Build Warnings

    • NCBC-2354: Most Integration Tests Failing

    • NCBC-2365: Ensure Exists checks if deleted is true then exists returns false

    • NCBC-2366: AnalyticsManager does not exist

    • NCBC-2367: Methods in ClusterNode have unused "connections" parameter

    • NCBC-2369: Ping diagnostics are not accurately reporting ping times

    • NCBC-2372: NRE thrown while initializing cluster

    • NCBC-2384: SSL connections cannot find node for K/V operations

    • NCBC-2389: ClusterNode must be associated with a bucket once a bucket has been opened

    • NCBC-2397: OPS pulses between zero and the expected performance

    • NCBC-2402: Add ConfigureAwait(false) to all asynchronous code

    • NCBC-2407: Couchbase.ServiceNotAvailableException: Service n1ql not available

    • NCBC-2416: ViewQuery failure/hanging

    • NCBC-2421: Remove default to NotBounded in FTS

    • NCBC-2422: Error replacing dead connections on N1QL Failover rebalance

    • NCBC-2426: Service Restart failure - replacing dead connections failure

    • NCBC-2429: Should be MaxHttpConnections instead of MaxHttpConnection

    • NCBC-2446: Ensure bootstrapping continues after BucketNotConnected on pre-6.5 servers

    • NCBC-2448: unpublish concurrent document mutations

    • NCBC-2183: Exists must use "getMeta" (0xa0) instead of Observe

    • NCBC-2410: LookupInResult has NotImplementedException for some methods

    • NCBC-2412: Cluster.AnaytlicsIndexes throws NotImplementedException

    • NCBC-2414: Connection terminated when packet exceeds NetworkStream buffer size

    • NCBC-2415: error CS0649: Field 'SubDocSingularBase<T>.CurrentSpec' is null

    • NCBC-2430: HttpMaxConnections renaming breaks DI unit tests

    • NCBC-2431: Failed DNS resolution throws NullReferenceException

    • NCBC-2433: Fix failing tests involving MaxHttpConnection

    • NCBC-2305: RequestId, ClientContextId, and Signature Lost After N1QL Query Enumeration

    • NCBC-2358: Timeout is not written to the packet when using Durability

    New Features and Behavioral Changes.

    • NCBC-2315: Improve logging for each service request

    • NCBC-2325: Add SCRAM-SHA Sasl Authentication

    • NCBC-1863: Add Flushing or Deleting a Collection logic

    • NCBC-1870: Support Log Redaction

    • NCBC-1915: Add new consistency API to SDK 3.0

    • NCBC-2151: Migrating from SDK 2 to 3.0

    • NCBC-2169: Migrating from SDK 2 to 3.0

    • NCBC-2209: Add Converters/Transcoders per RFC

    • NCBC-2220: Ensure ClusterOptions properties are integrated into SDK

    • NCBC-2234: Mark all ErrorContexts as Uncomitted

    • NCBC-2302: Getting Started Tidy Up

    • NCBC-2413: Add XxxErrorContext information to K/V

    • NCBC-2417: Remove all Singular Sub-Document classes

    • NCBC-1799: Analytics client needs to support streaming results

    • NCBC-1989: Add connection pooling

    • NCBC-2244: WaitUntilReady not available at the cluster and bucket levels

    • NCBC-2245: Cluster-level ping missing

    • NCBC-2260: Tighten OperationSpec for lookupIn and mutateIn

    • NCBC-2293: Remove deprecated ErrorAttribute enum

    • NCBC-2297: Decrease API surface surrounding K/V operations/connections

    • NCBC-2299: Implement non-streaming fallback for N1QL queries

    • NCBC-2300: Support custom stream deserializers for view queries

    • NCBC-2310: Make IQueryResult implementations internal

    • NCBC-2312: Make IServiceResult.RetryReason read only

    • NCBC-2313: Align StreamAlreadyReadException with other Couchbase exceptions

    • NCBC-2314: Implement non-streaming fallback for view queries

    • NCBC-2318: Refactor view queries to be strongly typed

    • NCBC-2319: Implement non-streaming fallback for analytics queries

    • NCBC-2320: Cleanup K/V classes in root namespace

    • NCBC-2322: Enable symbol packages and SourceLink for debugging

    • NCBC-2323: Enable C# 8 nullable ref types for buckets/scopes/collections

    • NCBC-2327: Create Lightweight DI system for Couchbase SDK

    • NCBC-2328: Update Cluster and Bucket to use DI for Logging

    • NCBC-2329: Update RetryOrchestrator to use DI for logging

    • NCBC-2330: Make transaction/serializer/mapper configurable via DI

    • NCBC-2331: Use DI for Scope and Collection logging

    • NCBC-2332: Remove default constructor added to BucketBase (CS8618 warning)

    • NCBC-2334: All integration tests fail, cannot bootstrap

    • NCBC-2336: Use DI for CouchbaseHttpClient

    • NCBC-2337: Remove ClusterContext requirement from service clients

    • NCBC-2338: Use DI for service clients and their loggers

    • NCBC-2340: Use DI for logging in configuration handlers

    • NCBC-2341: Use DI for OrphanedResponseLogger logging

    • NCBC-2343: Use DI for logging in data structures

    • NCBC-2344: Use DI for logging in managers

    • NCBC-2345: Use DI for logging in DNS resolver

    • NCBC-2346: Use DI for logging in GetResult

    • NCBC-2347: Use DI for logging in QueryUriTesters

    • NCBC-2348: Use DI for VBucket and ErrorMap logging

    • NCBC-2349: Enable Nullable Ref Types in ClusterOptions

    • NCBC-2355: Support deserialization of ClusterOptions from configuration

    • NCBC-2356: Move content services directory to root in Couchbase.UnitTests

    • NCBC-2357: Enable nullable ref types for XxxOptions classes

    • NCBC-2359: Use DNS resolver for IP address resolution

    • NCBC-2360: Use DNS resolver in Ketama key mapper and ClusterContext

    • NCBC-2362: Make ConfigChanged handling async

    • NCBC-2363: Use DNS resolver for VBucketServerMap.IPEndPoints

    • NCBC-2364: Enable null reference types for K/V specs/results

    • NCBC-2368: Remove Servers From ClusterOptions

    • NCBC-2370: Support custom port numbers in ConnectionString

    • NCBC-2371: Make BucketConfig and other config serialization classes internal

    • NCBC-2373: Implement abstraction layer for connection pool implementations

    • NCBC-2374: Replace TKey with string parameter in persistent collections

    • NCBC-2376: Cleanup BootstrapUri on ClusterNode

    • NCBC-2377: Implement auto scaling on connection pools

    • NCBC-2378: Add log redaction to DataFlowConnectionPool

    • NCBC-2379: Respect couchbases scheme for DNS SRV lookup

    • NCBC-2380: ClusterOptions MgmtPort and EnableTls cleanup

    • NCBC-2381: Cleanup IConnection interface

    • NCBC-2382: Support multiplexing on SslConnection

    • NCBC-2383: NodeAdapter is null on non-bootstrap nodes

    • NCBC-2387: Reduce heap allocations related to K/V operation response handling

    • NCBC-2391: Include XML documentation in NuGet package

    • NCBC-2392: Reduce heap allocations around MultiplexingConnection async state

    • NCBC-2393: Align QueryScanConsistency with the RFC

    • NCBC-2398: Change ICollection interface to ICouchbaseCollection interface

    • NCBC-2399: Add bootstrap service

    • NCBC-2408: Add BucketContext or equivalent for cohesion and less coupling

    • NCBC-2409: Route nodes into service specific CouchbaseNodeCollections

    • NCBC-2425: Reduce heap allocations calling BucketAsync


    Numerous Alpha and Beta releases were made in the run-up to the 3.0 release, and although unsupported, the release notes and download links are retained for archive purposes here.

    Older Releases

    Although no longer supported, documentation for older releases continues to be available in our docs archive.