Power BI APIs .NET SDK v3 has been released

Last week, Microsoft unveiled the February update for Power BI Desktop. This release, as is customary in monthly desktop refreshes for the analytics service, brought a host of new capabilities. These included a preview for the new hierarchical slicer, incremental refresh, and more.

Today, version 3 of Power BI APIs .NET SDK has been released as the Microsoft.PowerBI.Api NuGet Package. The changes introduced have primarily to do with making the SDK easier to use through new credentials classes and credential encryption techniques.

The major features that have been highlighted as part of this release include:

• 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 of the ways in which these changes have been implemented can be read in detail on the official blog post. Aside from the ones specifically mentioned above, other ones include altering of token generations, response handling if strings are being expected, and more.

The latest version is the only one that will be supporting newly introduced APIs. Since v3 isn't compatible with previous versions, updating to it may require code changes.

Further on that, as per Microsoft's Lifecycle Policy, the release of this new version means that .NET SDK v2 is being deprecated. The previous version will formally be removed two years later, in February 2022. However, it has been noted that "service security or health reliability" concerns may lead to this deadline being changed.