Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Device SDKs
/
/

Connect to an Atlas App Services Backend - .NET SDK

On this page

  • Access the App Client
  • Configuration
  • Connect to a Specific Server
  • Connect to a Different Server During Runtime

The App client is the interface to the App Services backend. It provides access to the authentication functionality, functions, and sync management.

Access the App Client

Pass the App ID for your App, which you can find in the Realm UI.

var myRealmAppId = "<your_app_id>";
var app = App.Create(myRealmAppId);

Configuration

For most use cases, you only need your application's App ID to connect to App Services. For granular control of your app connection, such as custom timeouts for connections and the log level, you can optionally pass an AppConfiguration object to the App.Create() method. The following example sets the LogLevel and the request timeout:

var appConfig = new AppConfiguration(myRealmAppId)
{
    DefaultRequestTimeout = TimeSpan.FromMilliseconds(1500)
};
app = App.Create(appConfig);

You can create multiple App client instances to connect to multiple Apps. All App client instances that share the same App ID use the same underlying connection.

Connect to a Specific Server

By default, Atlas Device SDK connects to Atlas using the global baseURL of https://services.cloud.mongodb.com. In some cases, you may want to connect to a different server:

  • Your App Services App uses local deployment, and you want to connect directly to a local baseURL in your region.

  • You want to connect to an Edge Server instance.

You can specify a baseURL in the AppConfiguration.

// Specify a base URL to connect to a server other than the default.
var appConfig = new AppConfiguration(YOUR_APP_ID);
appConfig.BaseUri = new Uri("http://localhost:80");
var app = App.Create(appConfig);

Connect to a Different Server During Runtime

New in version 12.1.0.

In some cases, you might want to change the baseURL while the app is running. For example, you might want to roam between Edge Servers, or move from an App Services connection to an Edge Server connection. To change the baseURL during runtime, call the app.UpdateBaseUriAsync() method:

// Specify a baseURL to connect to a server other than the default.
// In this case, an Edge Server instance running on the device
var appConfig = new AppConfiguration(YOUR_APP_ID);
appConfig.BaseUri = new Uri("http://localhost:80");
var app = App.Create(appConfig);
// ... log in a user and use the app ...
// Update the base URL back to the default.
#pragma warning disable Rlm001 // suppress the warning for the experimental method
await app.UpdateBaseUriAsync(new Uri("https://services.cloud.mongodb.com"));
#pragma warning restore Rlm001

This API is experimental. As seen above, you must use #pragma warning disable Rlm001 and #pragma warning restore Rlm001 to suppress the experimental errors, where Rlm001 is the experimental attributes's diagnosticId.

If you want to change the baseURL after you have logged in a user and have opened a synced database, the app must perform a client reset. Perform these steps in your code:

  1. Pause the Sync session.

  2. Update the baseURL by calling the app.updateBaseUrl(to: ) method.

  3. Authenticate and log the user in again with the new baseURL.

  4. Open a synced database pulling data from the new server.

Both the server and the client must be online for the user to authenticate and connect to the new server. If the server is not online or the client does not have a network connection, the user cannot authenticate and open the database.

Important

Changing an App Config After Initializing the App

Changed in version v11.7.0: BaseUri is not cached in the App configuration

When you initialize the App client, the configuration is cached internally. Attempting to close and then re-open an App with a changed configuration within the same process has no effect. The client continues to use the cached configuration.

In .NET SDK version 11.7.0 and later, the BaseUri is no longer cached in the App configuration. This means that you can change the BaseUri, and the App client will use the updated configuration. In earlier SDK versions, changes to the BaseUri in a cached App configuration have no effect.

← 
 →

On this page