Announcement!!!

[hkarthik7]

📢 Announcement!!! ❗❗

Version 6.0 introduces some breaking changes to the library. This is a complete re-write to make azd more robust, easy to extend and use. Currently azd uses single Client Api class per Azure DevOps Api (such as BuildApi, CoreApi, GitApi etc..), this is splitted into request builders to provide a declarative syntax and fluent Api style coding experience with single client instance to construct and execute the request.

v6.0 introduces additional configurations such as,

• Organization url is not hard coded, so the request can be constructed for Azure DevOps Services as well TFS server.
• Default retry mechanism.
• Pagination.
• Proxy configuration.

What is changing?

Api	Link	Details
Connection	Connection	Deprecated
AzDAsyncApi	AzDAsyncApi	Deprecated
BaseRestClient	BaseRestClient	Deprecated
RestClient	RestClient	Deprecated
RestClientProvider	RestClientProvider	Deprecated
JsonMapper	JsonMapper	Deprecated
AzDService	AzDService	New
OAuthAccessTokenBuilder	OAuthAccessTokenBuilder	New
AccessTokenCredential	AccessTokenCredential	New
ClientRequest	ClientRequest	New

Features

v6.0 brings new features and functionalities.

• Authentication: AccessTokenCredential interface provides the functionality of choosing the authentication provider. Currently azd supports Personal access token and OAuth on-behalf of authentication.
• Json -> POJO and viceversa: SerializerContext interface provides the serialization and deserialization functionalities.
• Paged response/continuation token: All the collects that derives from SerializableCollectionEntity exposes getNextPageLink() method which returns next page based link if continuation token is found in the header.

Note that, some Apis return link:rel=next; in the header and it is not managed by getNextPageLink() method. Instead use getResponse().getResponseHeaders() which returns the HttpResponseHeader object to retrieve the URL.

• ClientRequest: ClientRequest is responsible for sending and executing the request and deserializing the response.
• Client object: AzDServiceClient helps to create the client object and demands authentication provider.
• Declarative syntax: Unlike the Legacy Apis such as BuildApi, GitApi or CoreApi, the client object created using AzDServiceClient can be used to construct the requests and get the response back. See below for example.
• TFS or Azure DevOps server support: Support for TFS and Azure DevOps services.

Why changing now?

With the help of community contributors the functionalities of azd has grown huge, to make the code base maintaintable, easy to use, and align the usage more close to Azure DevOps Api. Also, v6.0 introduces declarative syntax to query the Api.

A glimpse of the usage:

// 1. Choose the authentication provider;
// AccessTokenCredential interface has few implementations.
// --> PersonalAccessTokenCredential - Use with your personal access token.
// --> OAuthAccessTokenCredential - Use for on-behalf of user and generate access token aka jwt.
// --> OAuthAccessTokenCredential provides automatic token refresh functionality.

// For Azure DevOps Services or TFS server the authentication provider object can be created as below
// https://dev.azure.com/{organization}
// https://server:port/tfs/{collection}
var oauthTokenCredential = new OAuthAccessTokenCredential(organizationUrl, projectName, appSecret, authCode, callbackUrl);
var personalAccessTokenCredential = new PersonalAccessTokenCredential(organizationUrl, project, personalAccessToken);


// 2. Create the client object with choosen authentication provider.
AzDServiceClient client = AzDService.builder()
    .authentication(personalAccessTokenCredential)
    .buildClient();
//or
AzDServiceClient client = AzDService.builder()
    .authentication(oauthTokenCredential)
    .buildClient();

// Single client instance and declarative syntax.
client.core().projects().list(); 

// Usage with query parameters.
client.core().projects().list(config -> {
    config.queryParameters.top = 100;
    config.queryParameters.stateFilter = ProjectState.ALL;
    config.queryParameters.getDefaultTeamImageUrl = true;
    config.queryParameters.skip = 10;
});

// All the Apis have overloaded methods that returns a CompletableFuture<> object.
client.core().projects().listAsync();

What happens to legacy Apis?

Legacy Apis are not going to change and will remain as is, indeed the internal implementations are going to change. The Legacy Apis will implement the new functionalities internally thus providing same output as before. Due to the deprecation of Apis that are used by Legacy Apis a minimal code change is required if you're using any of the Deprecated Apis. It is highly recommended that you move to new implementation.

PS: Latest code can be found here.