This changelog covers what’s changed in Microsoft Graph Communications SDK and its associated samples.
POST ~/call/{id}/keepAlive API to v1.0 samples.
~/app/ endpoint to the ~/communications/ endpoint.| Change type | Version | Description |
|---|---|---|
| Addition | beta | Added new action updateRecordingStatus to call entity. |
| Addition | beta | Added new complex type incomingContext. |
| Addition | beta | Added new property incomingContext to call entity. |
| Addition | beta | Added new property endpointType to participantInfo complex type. |
| Addition | beta | Added new property endpointType to invitationParticipantInfo complex type. |
| Addition | beta | Added new property recordingStatus to recordingInfo complex type. |
| Deletion | beta | Removed property status from recordingInfo complex type. |
| Deletion | beta | Removed inheritance of participantInfo from invitationParticipantInfo complex type. |
The Communications SDKs are now decoupled from the Microsoft.Graph SDK. New nugets have been released to as version 1.1.0-prerelease.* to signal breaking changes due to objects being moved to Microsoft.Graph.
This library no longer contains any Calls contracts… it now references Microsoft.Graph 1.14.0 and Microsoft.Graph.Core 1.15.0-preview.2 and only contains shared contracts not present in Microsoft.Graph. It also contains serialization/deserialization helpers and extensions methods to help with the Calling APIs (IdentitySet.GetGuest/IdentitySet.SetGuest/etc…). The frameworks have been bumped up to net461 and netstandard2.0 so the core SDK can leverage Microsoft.Graph.Communications.Common. Customers using this SDK now have to move to the one containing their specific contracts (below).
Calls wire SDK (contains all the calls and online meetings contracts). Note that some object names have changed as not to conflict with Microsoft.Graph names.
DefaultContainerClient => CallsGraphServiceClient
Notification => CommsNotification
Notifications => CommsNotifications
Now references Microsoft.Graph.Communications.Core.Calls and Microsoft.Graph.Communications.Client.
Naming conventions of these SDKs were changed as they are namespaced and do not need the Call prefix:
ICallParticipantCollection => IParticipantCollection
ICallParticipant => IParticipant
Microsoft.Graph.Core 1.15.0-preview.2 SDK to resolve inconsistencies between ServiceException types.Microsoft.Graph 1.14.0 SDK.Microsoft.Skype.Bots.Media 1.12.1.6-alpha SDK.promptsQueued callback to be notified when a prompt has been queued, and the next one can be added. This is only valid for scenarios where bot developers queue a single prompt at a time. If 1P developers pass in multiple prompts, order is guaranteed.Dispose() being called.ICache interface that notifies the bot developer whenever internal state has changed. It is also used to recover state when calling ICommunicationsClient.RehydrateAsync. An implementation of re-hydration from PMA is built in by default, but it does not support AudioRoutingGroup entities.| API | Update |
|---|---|
| ICall.PlayPromptAsync and ICall.RecordAsync | Fixed OData deserialization on the SDK side to create the expected type when the graph endpoint returns a base type. This patch will fix the 2 API calls here until graph metadata is adjusted to return the correct types. |
When the stateful SDK receives a notification it validates it, queues it up for dispatching to events, and returns 202 Accepted immediately as not to hold up the response. The stateful SDK then has a number of background queues for processing inbound notifications, one global queue and one queue per top level resource (I.E. call). In the past the global queue handled additions and deletions, but with this release the deletions have been moved to the resource queue. This change will ensure that all notifications are sequential, and removes potential bottlenecks on the main queue.
| API | Update |
|---|---|
| ICall.RecordAsync | Updated to return recordResourceLocation and recordResourceAccessToken. The access token is required to be sent as a bearer token to download the recording. |
| VideoSocket.SetSendBandwidthLimit | Sets the bandwidth limit on the send stream of the VideoSocket. |
| VideoSocket.SetReceiveBandwidthLimit | Sets the bandwidth limit on the receive stream of the VideoSocket. |
SDK package names have been updated to avoid confusion with Microsoft Graph SDK. When upgrading to the latest version (1.0.0-prerelease.494) in the original package names, you will encounter build warning CS0618. The warning message shows the actions you need to take to upgrade to the new packages.
| Original nuget package | New nuget package |
|---|---|
| Microsoft.Graph.Calls | Microsoft.Graph.Communications.Calls |
| Microsoft.Graph.Calls.Media | Microsoft.Graph.Communications.Calls.Media |
| Microsoft.Graph.Core.Stateful | Microsoft.Graph.Communications.Common |
| Microsoft.Graph.CoreSDK | Microsoft.Graph.Communications.Core |
| Microsoft.Graph.StatefulClient | Microsoft.Graph.Communications.Client |
Namespaces have been updated to match the assembly and package names. In addition, the top level interfaces have been renamed to match the new naming scheme.
| Original namespace | New namespace |
|---|---|
| Microsoft.Graph.Calls | Microsoft.Graph.Communications.Calls |
| Microsoft.Graph.Calls.Media | Microsoft.Graph.Communications.Calls.Media |
| Microsoft.Graph.Core | Microsoft.Graph.Communications.Common |
| Microsoft.Graph.CoreSDK | Microsoft.Graph.Communications.Core |
| Microsoft.Graph.StatefulClient | Microsoft.Graph.Communications.Client |
| IStatefulClient | ICommunicationsClient |
| StatefulClientBuilder | CommunicationsClientBuilder |
This release cleans up interfaces where some members have been renamed or removed. Older names are retained for backward compatibility, it is expected to be removed over the next releases.
| Deprecated items | Replacement |
|---|---|
| AudioRoutingGroup.Owner | no longer used |
| Call.Error | Call.ResultInfo |
| Call.Transfer(TransferTarget,…) | Call.Transfer(TransferTarget) |
| CommsOperation.ErrorInfo | CommsOperation.ResultInfo |
| MeetingParticipantInfo.SipProxyAddress | no longer used |
| OnlineMeeting.CanceledTime | OnlineMeeting.CanceledDateTime |
| OnlineMeeting.CreationTime | OnlineMeeting.CreationDateTime |
| OnlineMeeting.EndTime | OnlineMeeting.EndDateTime |
| OnlineMeeting.ExpirationTime | OnlineMeeting.ExpirationDateTime |
| OnlineMeeting.MeetingInfo | OnlineMeeting.Participants.Organizer |
| OnlineMeeting.StartTime | OnlineMeeting.StartDateTime |
| Participant.SubscribeVideoAsync | Call.GetLocalMediaSession().VideoSocket.Subscribe |
Removed properties from some graph owned contracts:
Identity.TenantId property. This still flows through on the wire, but needs to be fetched from Identity.AdditionalData.Identity.IdentityProvider as it was not required. IdentityProvider is now expected to be inferred using tenantId
{
"@odata.type": "#microsoft.graph.identitySet",
"user": {
"@odata.type": "#microsoft.graph.identity",
"id": "<guid>",
"displayName": "User Name",
"tenantId": "<guid>",
}
}
Identity is no longer represented using IdentitySet.User with IdentityProvider.None.
{
"@odata.type": "#microsoft.graph.identitySet",
"guest": {
"@odata.type": "#microsoft.graph.identity",
"id": "<guid>",
"displayName": "Guest Name",
"tenantId": "<guid>",
}
}
CommsOperation, which inherits from Operation. In the future most calling APIs will return CommsOperation.RecordingInfo contracts, which provide recording information on a given call participant.Identity.GetTenantId() and Identity.SetTenantId(string)IdentitySet.GetApplicationInstance() and IdentitySet.SetApplicationInstance(Identity)IdentitySet.GetGuest() and IdentitySet.SetGuest(Identity)IdentitySet.GetEncrypted() and IdentitySet.SetEncrypted(Identity)IResourceBase used by both IResource and IResourceCollection.IResource interface which were meant to be internal.No changes
Added proper handling of the operation response.
null, Idle or Running the action is treated as asynchronous and SDK will wait for subsequent Running Failed or Completed operation notifications.Failed SDK will throw a ServiceException with the error details.Completed the action is treated as synchronous and SDK will return from the calling method.400 Bad Request after some operations, and fixes issues with Mute/Unmute.Subscribe and Unsubscribe on the video sockets, instead of using the IParticipant.SubscribeAsync./// <summary>
/// Interface to a VideoSocket.
/// </summary>
public interface IVideoSocket : IDisposable
/// <summary>
/// Video Subscription API for the conference scenario, once the MediaReceiveStatus is raised with active status,
/// it is possible to call this api to subscribe to a specific video using the media source id.
/// </summary>
/// <param name="preferredVideoResolution">The requested video resolution,
/// The received video buffers should have the requested resolution if the bandwidth constraints and sender capabilities are satisfied</param>
void Subscribe(VideoResolution preferredVideoResolution, uint MediaSourceId);
/// <summary>
/// Subscribe API for the 1:1 case. No need to specify the media source id
/// </summary>
void Subscribe(VideoResolution preferredVideoResolution);
void Unsubscribe();
Note: The VideoSocket.Subscribe method will throw an InvalidOperationException if it is called too early, before the media session is established/active. The bot can monitor the (also new) VideoSocket.VideoReceiveStatusChanged event to see when the VideoSocket reports MediaReceiveStatus.Active, to know when it can start making video subscription requests.
Updated to latest SDK version. This includes minor bug fixes and contract changes.
OrganizerMeetingInfo.OrganizerId and OrganizerMeetingInfo.TenantId parameters have been replaced with IdentitySet Organizer.IdenitySet Target and string ReplacesCallId parameters have been replaced with InvitationParticipantInfo TransferTarget.Added logic to handle failed call deletion, or any time a stale call needs to be removed from SDK memory.
// Manually remove the call from SDK state.
// This will trigger the ICallCollection.OnUpdated event with the removed resource.
this.Client.Calls().TryForceRemove(callLegId, out ICall call);
No changes
IGraphLogger as part of ICommunicationsClient.AllowConversationWithoutHost = true; for joined meetings. This will ensure that any participants joining the meeting after the bot will not get kicked out of the meeting once bot leaves.correlationId for new calls and media sessions.ICommunicationsClient.TerminateAsync(bool onlyMedia, TimeSpan timeout); SDK supports couple flavors of cleanup:
TerminateAsync(false, timeout) will terminate all existing calls, terminate the media platform, shut down background threads, and dispose internal objects. Setting timeout will still terminate the media platform, shut down background threads, and dispose internal objects, but it will limit the time spent waiting for calls to be terminated.ICommunicationsClient.TermianteAsync(true, timeout) will only terminate the media platform. In this instance the timeout parameter is ignored.ICommunicationsClient.TerminateAsync(timeout) is used for media hosted on MSFT cloud, and not relevant in this drop.If bots wish to shut down cleanly, we recommend the following:
try
{
// Terminate all existing calls and wait for confirmation.
// Terminate media platform, terminate background threads, dispose objects.
await this.Client
.TerminateAsync(false, new TimeSpan(hours: 0, minutes: 1, seconds: 0))
.ConfigureAwait(false);
}
catch (Exception)
{
// Terminate with error.
}
// Perform graceful termination logic.