--- title: Best Practices description: Speed up your application development, with some best practices for using Couchbase SDKs. pubDate: 2026-10-16T07:26:40.932Z meta: component: title: .NET SDK version: "3.10" antora: editUrl: https://github.com/couchbase/docs-sdk-dotnet/edit/release/3.10/modules/concept-docs/pages/best-practices.adoc xref: xref:dotnet-sdk:concept-docs:best-practices.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/dotnet-sdk/current/concept-docs/best-practices.html) # Best Practices > Speed up your application development, with some best practices for using Couchbase SDKs. From batching and reactive APIs, to unit tests and handling errors. There's plenty that can be done to remove bottlenecks in development and in performance, and this page can be your checklist of areas not to neglect as you develop your app. ## [](#security)Security But before worrying about bottlenecks, let's put security concerns first. Security is a process, and not just a set of checkboxes — but there are key areas you must check off as you move from development, through testing, to deploying in production. ### [](#roles-and-rbac)Roles and RBAC Self-managed Couchbase Server uses Role-Based Access Control (RBAC), for applications to restrict _resources_ on a Couchbase cluster to an identified _user_, which is reflected in our managed service (Capella) as a nuanced set of Roles. Data security depends in part on only giving access to the minimum amount of data and permissions required to do the job. * Couchbase Capella * Self-Managed Couchbase Server Control programmatic and application-level access to data for each cluster using [cluster access credentials](#clusters:manage-database-users.adoc). Capella offers [basic access credentials](../../../cloud/clusters/cluster-rbac.md#basic-access-credentials) with predefined read, write, or read/write permissions, and [advanced access credentials](../../../cloud/clusters/cluster-rbac.md#advanced-access-credentials) with fine-grained privileges and reusable access roles for more precise access control. You can choose specific [buckets, scopes, and collections](../../../cloud/clusters/data-service/about-buckets-scopes-collections.md) for your cluster access credentials to limit access to data. Only the [Project Owner](../../../cloud/projects/project-roles.md#project-owner-role) role can create cluster access credentials for their projects. See [Project Roles](../../../cloud/projects/project-roles.md)and [Organization Roles](../../../cloud/organizations/organization-user-roles.md) for more information. Each user who attempts resource-access is identified by means of the _credentials_ they pass to Couchbase Server, for purposes of _authentication_: these consist of a _username_ and (typically) a _password_. Once the user is authenticated, an _authorization_ process checks the _roles_ with which the user is associated. If one or more of these roles correspond to _privileges_ that permit the user-requested level of resource-access, access is duly granted; otherwise, it is denied. Users who have been assigned the **Admin** role for the cluster are able to create, edit, and remove users. The SDK provides APIs to support these activities. All aspects of the Couchbase RBAC system are covered in the section [Authorization](../../../server/current/learn/security/authorization-overview.md). Specifically, for information on: * Adding _Users_ and assigning _roles_, by means of the Couchbase Web Console, see [Manage Users and Roles](../../../server/current/manage/manage-security/manage-users-and-roles.md). * _Roles_ required for resource-access, and the privileges they entail, see [Roles](../../../server/current/learn/security/roles.md). * _Resources_ controlled by Couchbase RBAC, see [Resources Under Access Control](../../../server/current/learn/security/roles.md). > [!NOTE] > Introductory examples in the SDK documentation use the _Administrator_ user to ensure that developers can quickly get up and running; this _should not be used in production_. Elsewhere we use a general "user" which represents whichever permission levels are appropriate to your application. ## [](#performance)Performance Couchbase's Data Service uses a fast binary protocol, which will always outperform JSON streamed over HTTP from SQL++ queries. If you know the key (ID) of a document, then use the [Data Service](../howtos/kv-operations.md). If you need pessimistic locking, in particular if you need to lock documents for multi-document ACID transactions, then anything you can do at the schema level to reduce the number of documents locked simultaneously wil remove a bottleneck to updating the affected documents. ### [](#dealing-with-timeout-errors)Dealing with Timeout Errors * `waitUntilReady` should be the default setting for `Cluster.connect` and `Cluster.bucket` in most cases, so that resources are fully loaded before the client proceeds with CRUD calls to the cluster. * LAN-type connection of client and server is recommended in production, but WAN development is a reality pre-production. Ensure that you're familiar with the [best timeout options for WAN environments](../ref/client-settings.md#constrained-network-environments), or at least set a [WAN development Configuration Profile](../ref/client-settings.md#wan-development). ### [](#concurrency-and-async-apis)Concurrency and Async APIs We recommend using the reactive API over the `CompletableFuture` counterpart. See the [Async & Reactive APIs page](../howtos/concurrent-async-apis.md) for discussion and practical examples. ### [](#bulk-get-multi-get-and-network-latency)Bulk Get, Multi-Get, and Network Latency In traditional databases, a bulk get or multi-get is often an efficient way of overcoming network latencies as a bottleneck, or simply making more efficent use of your database's performance. Couchbase is a distributed database, efficiently fetching data from vbuckets spread across several nodes: bulk gets can be an anti-pattern, holding things up on the Server side, compared with the efficiency of fetching your data asynchronously. However, this depends upon your platform language's availability of asynchronous APIs — see the [bulk get and async API page](../howtos/concurrent-async-apis.md) for the specifics for the .NET SDK. #### [](#when-to-use-bulk-get)When to Use Bulk Get As stated above, bulk gets are rarely the best way to fetch data from different documents efficently. Nevertheless, if your business logic dictates that all of, say five, results need to be returned before processing for the application's next step, then a bulk get will give you all of the results together, as needed by your app. For this reason we do provide a [batching example](../howtos/concurrent-async-apis.md#batching) for the .NET SDK. ## [](#error-handling)Error Handling Best practices for error handling in Java depend somewhat upon your choice of API: blocking, asynchronous, or reactive, as covered in the [async and reactive API guide](../howtos/concurrent-async-apis.md). See also the [error handling guide](../howtos/error-handling.md), which covers specific errors, along with a broader look at error handling strategies. ## [](#threshold-orphan-logging)Threshold & Orphan Logging Observability is provided by the SDK in the following ways: ### [](#threshold-logging)Threshold Logging Threshold logging is the recording of slow operations — useful for diagnosing when and where problems occur in a distributed environment. It is enabled by default. You will see this information turning up in the logs something like this: ```json Threshold Log: {"service":"kv","count":2,"top":[{"operation_name":"Insert","total_us":161679},{"operation_name":"Upsert","total_us":161451}]} ``` And as tracing values such as `total_us`, the duration of the total time taken for the operation, expressed as microseconds. ### [](#orphaned-response-reporting)Orphaned Response Reporting Special reporting capabilities which explicitly collect information about responses which have been abandoned (i.e. timed out) at the time when the SDK tries to complete them. This is also enabled by default. ## [](#testing)Testing Integrate developing with the .NET SDK into your accustomed test framework. ## [](#additional-information)Additional Information SDKs are client to Couchbase Server — whether Capella Database-As-A-Service, or self-managed — and in some areas it would be wise to take a fully rounded approach. Read up on security and performance considerations relevant to your use case. ### [](#couchbase-security-best-practices)Couchbase Security Best Practices * [Security Best Practices in Capella](../../../cloud/security/security.md) * [Security for self-managed Couchbase Server](../../../server/current/learn/security/security-overview.md) ### [](#role-based-access-control)Role-Based Access Control For Capella, Roles, Cluster Access Credentials, and Authentication options are covered in the [Capella Security docs](../../../cloud/security/security.md). For self-managed Couchbase Server, all aspects of the Couchbase RBAC system are covered in the section [Authorization](../../../server/current/learn/security/authorization-overview.md). Specifically, for information on: * Adding _Users_ and assigning _roles_, by means of the Couchbase Web Console, see [Manage Users and Roles](../../../server/current/manage/manage-security/manage-users-and-roles.md). * _Roles_ required for resource-access, and the privileges they entail, see [Roles](../../../server/current/learn/security/roles.md). * _Resources_ controlled by Couchbase RBAC, see [Resources Under Access Control](../../../server/current/learn/security/roles.md).