Our C# SDKs provide convenient access to the LUSID REST API and other applications in the ecosystem in .NET 6 environments.
Note: Supporting applications in the FINBOURNE platform (such as Drive, Scheduler and Luminesce) have their own C# SDKs.
Note the following:
We strongly recommend pinning a SDK to an exact version to control when you take updates and make your builds repeatable.
The
master
/main
branch of a SDK may not always have the latest REST API version; there may, for example, also bev2
orv3
branches. We aim to keepmaster
/main
updated with the latest API version, but there may be some lead time while we deprecate older endpoints. Once we deprecate older API versions, the latest API version is moved to themaster
/main
branch.
Installing the latest C# SDKs
You can install v2 of the LUSID C# SDK using the following .NET command:
$ dotnet add package Lusid.Sdk
Alternatively, you can download the source from Github.
To authenticate for the first time, you must generate a client ID and secret and store them with the credentials of a valid LUSID user as either environment variables or in a secrets file. The LUSID C# SDK uses these credentials to obtain a short-lived API access token from FINBOURNE's identity provider (Okta) on demand. More information.
Documentation for SDK methods is available as a searchable package on Readthedocs.
Upgrading to v2 from an earlier version
You can upgrade from v1 to v2 of the LUSID C# SDK by using the following .NET command:
$ dotnet add package Lusid.Sdk
We recommend upgrading to this version as soon as possible to ensure you have access to the latest features.
Note that you must upgrade all SDKs used in a particular process to v2 at the same time. A process that uses both the Scheduler and Drive SDKs, for example, must either use v1 of both SDKs or v2 of both SDKs; mixing major versions will lead to dependency conflicts.
Users need to update their code to reflect the following v2 changes...
Prerequisites for v2
.NET at version 6.0 or above.
Preview SDKs
This release discontinues publishing the LUSID Preview SDK, instead adding the Experimental and Beta lifecycle APIs to a single SDK. The LUSID C# SDK now contains all the newest features; only Lusid.Sdk
need be installed. Note that making requests to Experimental and Beta APIs requires additional licences; for more details please contact support.
Long-running API requests
Long-running API requests are enabled, giving users the option to extend or remove request timeout limits (previously timed out at 350 seconds). To extend the timeout on API calls, construct a configuration object and pass it into the ApiFactory
, for example:
var configuration = new Configuration
{
BasePath = "https://<your-domain>.lusid.com/api",
AccessToken = System.Environment.GetEnvironmentVariable("ACCESS_TOKEN"),
Timeout = (int)TimeSpan.FromMinutes(10).TotalMilliseconds,
};
var client = new ApiFactory(configuration);
Name changes
The following namespaces, classes and interfaces are renamed:
using Lusid.Sdk.Utilities
becomesusing Lusid.Sdk.Extensions
.LusidApiFactory
becomesApiFactoryFactory
.ILusidApiFactory
becomesIApiFactory
.
Version
becomes a reserved word in OpenApi Generator:
Sdk.Version
becomesSdk.ModelVersion
.Any model that implemented an
Sdk.Version
(nowSdk.ModelVersion
) changes fromVersion
to_Version
.
Upgrading to v2.2 onwards of the C# SDKs
You can upgrade to v2.2 onwards of the LUSID C# SDK by running the following .NET command, but note the upgrade includes breaking changes due to the removal of the RestSharp dependency:
$ dotnet add package Lusid.Sdk
Important
If you are not ready to update to v2.2 onwards, you can run the following .NET command to pin the SDK to the previous minor version (where
x
andy
correspond to the minor and patch versions of the SDK you’re currently using):$ dotnet add package Lusid.Sdk --version "[2.x.y,2.2)"
Removal of RestSharp dependency
Version 2.2 onwards of the C# SDKs includes the removal of the RestSharp dependency. Methods which previously used RestSharp types have been changed to use an equivalent type in the SDK and renamed. They may also contain fewer properties or have properties with different names.
When upgrading to v2.2 onwards, you must check for breaking changes by compiling the code. You must update any code that directly references types from the RestSharp package.
You may need to update your code:
If using
CreateHttpMessageHandler
orcreateRestClientFunc
optional arguments in anApiClient
constructor.When defining or referencing static retry configuration on
RetryConfiguration
orPollyApiRetryHandler
.In any references to the following properties which have been removed - these will fail to compile:
Cookies
property ofIApiResponse
andApiResponse
CookieContainer
property ofRestClientOptions
You can expand the following to see examples of how your code may need to change with v2.2 onwards:
CreateHttpMessageHandler
example
CreateHttpMessageHandler
exampleThe following code references the CookieContainer
property of RestClientOptions
from the RestSharp package. v2.2 replaces this with ClientOptions
, for which the CookieContainer
property does not exist:
// v2.1x and below of LUSID C# SDK:
var apiClient = new ApiClient(url, CreateHttpMessageHandler: options =>
{
var handler = new HttpClientHandler();
handler.Proxy = options.Proxy;
handler.CookieContainer = options.CookieContainer;
return handler;
});
// Becomes the following in v2.2 and above of the LUSID C# SDK:
var apiClient = new ApiClient(url, CreateHttpMessageHandler: options =>
{
var handler = new HttpClientHandler();
handler.Proxy = options.Proxy;
return handler;
});
createRestClientFunc
example
createRestClientFunc
exampleThe following references the types IRestClientWrapper
, RestRequest
and RestResponse
.
RestRequest
andRestResponse
are types which come from the RestSharp package and have been replaced withRequest
andResponse
in the v2.2 onwards.IRestClientWrapper
has been renamed toIClient
and its methods have changed.RestResponse<T> WrappedExecute<T>(RestRequest request);
is nowResponse<T> Execute<T>(Request request);
.
Note this optional parameter can be used when testing, as shown below, to stub out the server.
// v2.1x and below of LUSID C# SDK:
using System.Net;
using Lusid.Sdk.Api;
using Lusid.Sdk.Client;
using Lusid.Sdk.Model;
using Moq;
using RestSharp;
namespace TestSdks;
public class BreakingChangesExamples
{
[Test]
public void CreateRestClientFuncExample()
{
var mockClient = new Mock<IRestClientWrapper>(MockBehavior.Strict);
var url = "http://localhost:1234";
var portfoliosToReturn = new ResourceListOfPortfolio(new List<Portfolio>
{
new Portfolio(
id: new ResourceId("my-scope", "my-code"),
displayName: "my-portfolio"
)
});
var apiClient = new ApiClient(url, createRestClientFunc: (options, configuration) =>
{
mockClient.Setup(x => x.WrappedExecute<ResourceListOfPortfolio>(
It.Is<RestRequest>(request => request.Resource == "/api/portfolios")))
.Returns(new RestResponse<ResourceListOfPortfolio>(new RestRequest())
{
Data = portfoliosToReturn,
StatusCode = HttpStatusCode.OK,
ResponseStatus = ResponseStatus.Completed
});
return mockClient.Object;
});
var apiInstance = new PortfoliosApi(apiClient, apiClient, new Configuration());
var portfolios = apiInstance.ListPortfolios();
Assert.That(portfolios.Values, Is.EquivalentTo(portfoliosToReturn.Values));
}
}
// Becomes the following in v2.2 and above of the LUSID C# SDK:
using System.Net;
using Lusid.Sdk.Api;
using Lusid.Sdk.Client;
using Lusid.Sdk.Model;
using Moq;
namespace TestSdks;
public class BreakingChangesExamples
{
[Test]
public void CreateRestClientFuncExample()
{
// IRestClientWrapper has become IClient
var mockClient = new Mock<IClient>(MockBehavior.Strict);
var url = "http://localhost:1234";
var portfoliosToReturn = new ResourceListOfPortfolio(new List<Portfolio>
{
new Portfolio(
id: new ResourceId("my-scope", "my-code"),
displayName: "my-portfolio"
)
});
var apiClient = new ApiClient(url, createRestClientFunc: (options, configuration) =>
{
// WrappedExecute has become Execute
mockClient.Setup(x => x.Execute<ResourceListOfPortfolio>(
// RestRequest has become Request
It.Is<Request>(request => request.Resource == "/api/portfolios")))
// RestResponse has become Response
.Returns(new Response<ResourceListOfPortfolio>(new Request())
{
Data = portfoliosToReturn,
StatusCode = HttpStatusCode.OK,
ResponseStatus = ResponseStatus.Completed
});
return mockClient.Object;
});
var apiInstance = new PortfoliosApi(apiClient, apiClient, new Configuration());
var portfolios = apiInstance.ListPortfolios();
Assert.That(portfolios.Values, Is.EquivalentTo(portfoliosToReturn.Values));
}
}
RetryConfiguration
example
RetryConfiguration
exampleThe following code defines the retry policy on the static class RetryConfiguration
. It references RestResponse
which comes from the RestSharp package. In v2.2 onwards, HandleResult
takes the type ResponseBase
instead of RestResponse
.
// v2.1x and below of LUSID C# SDK:
RetryConfiguration.RetryPolicy = Policy
.HandleResult<RestResponse>(response => response is
{
StatusCode: HttpStatusCode.BadGateway,
ResponseStatus: ResponseStatus.TimedOut
})
.Retry();
// Becomes the following in v2.2 and above of the LUSID C# SDK:
RetryConfiguration.RetryPolicy = Policy
.HandleResult<ResponseBase>(response => response is
{
StatusCode: HttpStatusCode.BadGateway,
ResponseStatus: ResponseStatus.TimedOut
})
.Retry();
PollyApiRetryHandler
example
PollyApiRetryHandler
exampleThe following code calls a method from the static class PollyApiRetryHandler
which takes a parameter of type RestResponse
. In v2.2 onwards, RestResponse
is replaced with Response<T>
.
// v2.1x and below of LUSID C# SDK:
var willRetry = PollyApiRetryHandler.GetPollyRetryCondition(new RestResponse
{
StatusCode = HttpStatusCode.TooManyRequests
});
// Becomes the following in v2.2 and above of the LUSID C# SDK:
var willRetry = PollyApiRetryHandler.GetPollyRetryCondition(new Response<object>
{
StatusCode = HttpStatusCode.TooManyRequests
});
Note
With v2.2 onwards, it’s no longer necessary to import the RestSharp package. This version of the SDK also removes cookie handling.
New package Finbourne.Sdk.Core
In v2.2, SDKs also reference the new package Finbourne.Sdk.Core. It is not necessary to reference this package directly but you should verify that your build processes do not block it, for example if you allow-list specified package downloads.
Note
The behaviour of the SDK is largely unchanged; although the RestSharp package dependency is removed, the RestSharp client is still in use.
Finbourne.Sdk.Core
encapsulates a version of RestSharp forked from the v112.0.0 release.
Installing v1 of the LUSID C# SDK
Please note v1 of Lusid.Sdk
and Lusid.Sdk.Preview
is now discontinued, but if you do need to install it then two packages are published:
If you do need to install v1 of the LUSID C# SDK for any reason, note two packages are published:
Lusid.Sdk
contains only APIs with a lifecycle status of Production or Early Access. You can install the LUSID C# SDK using the following .NET command:$ dotnet add package Lusid.Sdk --version "[1.*,2.0)"
Lusid.Sdk.Preview
contains additional APIs with a lifecycle status of Experimental or Beta. You can install the LUSID C# Preview SDK using the following .NET command:$ dotnet add package Lusid.Sdk.Preview --version "[1.*,2.0)"