Announcing Power BI APIs .NET SDK v3

[Amit_Shuster]

We're excited to announce the release of Power BI APIs .NET SDK v3.

The new version is easier to use, have additional capabilities including the new credentials classes and easier way to encrypt credentials.

According to Microsoft Lifecycle Policy, as new versions are released, the previous version will eventually be retired. The Power BI APIs .NET SDK v2 is now deprecated, and will be retired in 24 months (February 2022). We might make exceptions to this policy for service security or health reliability issues.

We strongly recommend that you migrate to the latest version as soon as possible, new APIs will only be added to the Power BI APIs .NET SDK v3.
v3 release is not compatible with previous versions, code changes are required when updating to v3.

The Power BI APIs .NET SDK is released as Microsoft.PowerBI.Api NuGet package.

What you should know about v3

Here are the key changes with this version update:

• Namespaces renaming:
  • Microsoft.PowerBI.Api.V2  was changed to Microsoft.PowerBI.Api
  • Microsoft.PowerBI.Api.Extensions.V2  was changed to Microsoft.PowerBI.Api.Extensions
  • Microsoft.PowerBI.Api.V1 namespace was removed.
• SetAllConnections and SetAllConnectionsInGroup operations are deprecated and marked as obsolete.
  You should use UpdateDatasources or UpdateParameters APIs instead.

• PowerBI artifacts IDs typing was changed* from string to Guid, we recommend to work with Guid when possible.
      *   Dataset ID is an exception and it's typing will remain string.
• 'ODataResponse[List[Object]]' types was changed to 'Objects', thus returning an objects collection on responses.
  For example, a response of ODataResponse[List[Report]] type will now return Reports collection as the return type.
• New credentials classes allow easier build of credentialDetails. The new classes include: `BasicCredentials`, `WindowsCredentials`, `OAuth2Credentials`, and more.
  Read Configure credentials article to learn more.
• New encryption helper classes for easier encryption when creating CredentialDetails.
  For example, using AsymmetricKeyEncryptor class with a gateway public key:
  GatewayPublicKey publicKey = new GatewayPublicKey { Exponent = "...", Modulus = "..." }; CredentialsBase credentials = new BasicCredentials("<USER>", "<PASSWORD>"); var credentialsEncryptor = new AsymmetricKeyEncryptor(publicKey); var credentialDetails = new CredentialDetails(credentials, PrivacyLevel.None, EncryptedConnection.Encrypted, credentialsEncryptor);
  Read Configure credentials article to learn more.

• Consistency on field names.
  For example, reportKey, datasetKey, dashboardKey and tileKey was changed to reportId, datasetId, dashboardId and tileId.
• Consistency on operations names.
  For example, use GetDataset instead of GetDatasetById.
  The effected opertation names are imports, datasets, gateways and datasources.
• Use enum class instead of string for enumerated types.
  For example, In the generateTokenRequest, we recommend to use `TokenAccessLevel.View`, and not explicitly use "view" as value.
• Required fields was marked - some fields was changed to required fields are not nullable anymore.

Examples

Change in Get Reports call if WorkspaceId is a string:

var reports = await client.Reports.GetReportsInGroupAsync(WorkspaceId);

var reports = await client.Reports.GetReportsInGroupAsync(new Guid(WorkspaceId));

 

Change in response handling if a string is expected:

report = reports.Value.FirstOrDefault(r => r.Id.Equals(ReportId, StringComparison.InvariantCultureIgnoreCase));

report = reports.Value.FirstOrDefault(r => r.Id.ToString().Equals(ReportId, StringComparison.InvariantCultureIgnoreCase));

 

Change in Generate token:

var tokenResponse = await client.Reports.GenerateTokenInGroupAsync(WorkspaceId, report.Id, generateTokenRequestParameters);

var tokenResponse = await client.Reports.GenerateTokenInGroupAsync(new Guid(WorkspaceId), report.Id, generateTokenRequestParameters);

 

Change in Generate token response handling if a string is expected:

m_embedConfig.Id = report.Id;

m_embedConfig.Id = report.Id.ToString();

 

Required fields are not nullable, i.e. Expiration is not nullable and the Value property should be removed:

var minutesToExpiration = EmbedToken.Expiration.Value - DateTime.UtcNow;

var minutesToExpiration = EmbedToken.Expiration - DateTime.UtcNow;

 

Consistency on operations names, i.e. use GetDataset instead of GetDatasetById:

var datasets = await client.Datasets.GetDatasetByIdInGroupAsync(WorkspaceId, report.DatasetId);

var datasets = await client.Datasets.GetDatasetInGroupAsync(new Guid(WorkspaceId), report.DatasetId);

 

That’s all for this post. We hope you found it useful.

We recommend that you start adopting Power BI APIs .NET SDK version 3 as soon as you can.

Please share your feedback with us, if you want to read more:

• Power BI .NET SDK on GitHub
• Power BI developer documentation