# DDB .NET Client

The DDB Microservices .NET Client allows access to all DDB operations in languages such as C#. Each microservice is accessed using a different nuget package.

Note for external users - many of the links in the following section refer to internal applications. Please speak to your project team for support.

# Prerequisites

.NET
- These clients target .NET Standard 2.0. See this (opens new window) page for a list of compatible .NET versions.
- If starting a new, standalone project it is recommended to use .NET 6, which can be downloaded from Arup Apps (opens new window)
Azure Artifacts credential provider
- Follow instructions here (opens new window)
- The recommended method is to use the automatic PowerShell script (opens new window)

# Installation

# `nuget.config`

A nuget.config file is required to install the nuget packages. Create the file next to your .csproj or .sln file with the following contents:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="ddb" value="https://pkgs.dev.azure.com/ovearup/_packaging/ddb/nuget/v3/index.json" />
  </packageSources>
</configuration>

# Packages

Each microservice is provided by a different nuget package. Packages can be installed with the command:

dotnet add package <package name> --interactive

The available packages are:

Arup.DDB.CommentsService (API Docs (opens new window))
Arup.DDB.EnvironmentContextService (API Docs (opens new window))
Arup.DDB.ParameterMetadataService (API Docs (opens new window))
Arup.DDB.ParameterService (API Docs (opens new window))
Arup.DDB.QAService (API Docs (opens new window))
Arup.DDB.ReferenceDataService (API Docs (opens new window))
Arup.DDB.UserService (API Docs (opens new window))

# Configuration

You will need an Azure AD App Registration (opens new window) for the client that is accessing the API. You will need to configure scopes and a redirect URI for your application.

# Scopes

The scopes are configured on the API permissions page. These can be added through Add a permission, then selecting APIS my organization uses, and finally selecting DigitalDesignBriefAPI. The permission required is user_impersonation. Once you have added these, they will need to be approved with Grant admin consent for Arup which will need to be logged in a service ticket.

# Redirect URI

You will also need to configure a Redirect URI for your application. This is done on the Authentication page. For desktop applications, select Add a platform, then Mobile and desktop applications, and finally select https://login.microsoftonline.com/common/oauth2/nativeclient. For other applications, follow the instructions on the Authentication page.

# Usage

The DDBClient object configures the authentication and environment for each microservice. Each installed microservice can then be requested using the extension methods on the client. An implementation of the token acquisition is provided for desktop applications. Other applications, such as servers, will need to implement their own token acquisition by implementing the ITokenAcquisition interface. This can then be passed to the DDBClient or DDBClientFactory in the constructor.

string clientId = "<client id>";
var ddbClient = new DDBClient(Environment.Sandbox, clientId);

var commentsService = ddbClient.GetCommentsService();

foreach (var comment in (await commentsService.GetCommentsAsync()).Comments)
{
    Console.WriteLine(comment.Content);
}

# Client Factory

A DDBClientFactory class is also provided, which allows the creation of DDBClient objects for a given environment, while authentication is handled by the factory. This can be useful in scenarios where dependency injection is used.

# Pagination

Helper functions are supplied for working with paginated endpoints. These are found in the Helpers static class.

The pagination helper functions simplify repeatedly calling an endpoint to return a paginated list of results. An example signature is:

IAsyncEnumerable<O> Unpaginate<T, O>(RequestFunction<T> requestFunction, Func<T, IEnumerable<O>> getInner, Func<T, string> getAfter)

requestFunction is a function that passes the after parameter to the DDB function, initially being passed null.

getInner gets the inner collection from the result response.

getAfter gets the after cursor from the result response.

For example:

var results = Helpers.Unpaginate(
  after => parameterService.GetAllParametersAsync(after: after, project_id: projectId),
  t => t.Parameters,
  t => t?.Paging?.Cursors?.After
);

# Helpers.Unpaginate

This is available from .NET Core 3.1 and it is recommended you use this when available, as it will lazily make each request as it is iterated, rather than having to retrieve all the results into memory. It returns an IAsyncEnumerable, and with the System.Linq.Async (opens new window) package installed can be operated on with familiar LINQ methods.

# Helpers.UnpaginateAll

This returns a single list of objects by repeatedly calling the provided request method until all results have been collected. This should generally only be used if Helpers.Unpaginate is not available. An overload is provided which takes an additional transformation function, allowing results to be transformed as they come in before being added to the list.

# Helpers.GetPaginatedFirstOrDefault

This returns a single result from a paginated endpoint. It takes a predicate function and returns the first response that matches the predicate.

← DDB Python Client