advanced ucma 3.0 developmentaz12722.vo.msecnd.net/.../labs/8l1-0/lab.docx · web viewin this lab,...

Hands-On LabAdvanced UCMA 3.0 Development

Lab version: 1.0

Last updated: 5/24/2023

................................................................................................................................................ CONTENTS

OVERVIEW................................................................................................................................................. 3System Requirements 3

EXERCISE 1: BACK-TO-BACK CALL FUNCTIONALITY ........................................................................4Task 1 – Open the Visual Studio Solution............................................................................................4

Task 2 – Create and Establish a Back-to-Back Call...............................................................................4

EXERCISE 2: MANUAL AUDIO ROUTES.................................................................................................6Task 1 – Open the Visual Studio Solution............................................................................................6

Task 2 – Register for an Incoming Call on the Application Endpoint....................................................7

EXERCISE 3: APPLICATION ENDPOINT DRAINING.............................................................................12Task 1 – Open the Visual Studio Solution..........................................................................................12

Task 2 – Draining an Application Endpoint........................................................................................12

SUMMARY................................................................................................................................................ 15

Overview

Lab Time: 45 Minutes

Lab Folder: C:\%UC14TrainingKit%\Labs\8\Source\Before

The After folder contains the completed lab exercises.

Lab Overview: The Unified Communications Managed API 3.0 SDK provides a managed API for developing server-side communications solutions for Microsoft Lync Server 2010 such as personal virtual assistants, automatic call distributors, and communications-enabled business processes.

This lab introduces new and advanced UCMA 3.0 development concepts such as back-to-back calling, audio routes, and application endpoint draining.

The lab solution you will build will use the UCMA 3.0 SDK to demonstrate the following.

Establishing a back-to-back call between two users.

Using audio routes to maintain fine-grained control over the experience of callers in a conference.

Using application endpoint draining to gracefully shutdown an application endpoint.

System Requirements

You must have the following items to complete this lab:

Microsoft Visual Studio 2010

Unified Communications Managed API 3.0 SDK

A provisioned UCMA 3.0 application

◦ Please refer to the Lab 6 - Introduction to UCMA 3.0 to learn how to create and provision a UCMA 3.0 application.

Exercise 1: Back-to-Back Call Functionality

Task 1 – Open the Visual Studio Solution

In this task, you will open the project and configure it to run with your parameter values.

1. Navigate to Start >> All Programs >> Microsoft Visual Studio 2010.

2. Click on the Microsoft Visual Studio 2010 icon to start Visual Studio 2010.

3. Select File >> Open Project.

4. Navigate to the folder C:\%UC14TrainingKit%\Labs\8\Source\Before.

5. Open the AdvancedUCMA solution.

6. In Solution Explorer, right-click the BackToBack project and select Set as StartUp Project.

7. In Solution Explorer, open the App.config file.

8. Change the value of ApplicationId to the application id of your provisioned UCMA 3.0 application, e.g. urn:application:LabApp10600.

9. Change the value of ApplicationName to the application name of your provisioned UCMA 3.0 application, e.g. LabApp10600.

10. Change the value of TrustedContactUri to SIP URI of the contact associated with your provisioned UCMA 3.0 application, e.g. sip:[email protected].

11. Change the value of SecondaryLabUserId with the SIP URI of your secondary lab user.

12. Select View >> Task List and select Comments from the menu.

Task 2 – Create and Establish a Back-to-Back Call

In this task, you will create and establish a back-to-back call between your primary and secondary lab user ids.

Back-to-Back allows a UCMA application to maintain control over a communication session by dividing it into two legs and acting as a proxy between the two participating endpoints. From the perspective of each endpoint, it is in a call with the UCMA application. However, audio is sent directly between the two endpoints, allowing the application to maintain control over the call and provide additional services.

1. In the Task List, navigate to TODO: 8.1.1.

2. Add the following code after the TODO: 8.1.1 comment. This creates an instance of BackToBackCallSettings for the incoming call to the application endpoint.

C#

sip:[email protected]

var incomingCallSettings = new BackToBackCallSettings(e.Call);

3. Navigate to TODO: 8.1.2.

4. Add the following code after the TODO: 8.1.2 comment. This create a new outgoing call on the application endpoint.

C#

var outgoingCallConversation = new Conversation(_applicationEndpoint);var outgoingCall = new AudioVideoCall(outgoingCallConversation);


6. Add the following code after the TODO: 8.1.3 comment. This creates an instance of BackToBackCallSettings for the outgoing call to the secondary lab user.

C#

var outgoingCallSettings = new BackToBackCallSettings(outgoingCall, _secondaryLabUserId);


8. Add the following code after the TODO: 8.1.4 comment. This creates a new BackToBackCall and pass in the incoming and outgoing BackToBackCallSettings.

C#

backToBackCall = new BackToBackCall(incomingCallSettings, outgoingCallSettings);


10. Add the following code after the TODO: 8.1.5 comment. This establishes the back-to-back call between the primary and secondary lab users.

C#

Console.WriteLine("Established back-to-back call.");backToBackCall.EndEstablish(result);

11. Go to Debug >> Start Without Debugging or use the shortcut key [CTRL]+[F5] to start the application. The platform will start up, establish the application endpoint, register for an incoming call, and notify the user that it is ready and waiting for an incoming call.

12. Switch to Microsoft Lync and locate the contact for your provisioned lab contact, e.g. [email protected].

13. Place an audio call to the contact. The application begins establishing the back-to-back call to the secondary lab user.

14. Switch to the secondary lab user’s session. The call appears to be coming from the UCMA application.

mailto:[email protected]

15. Accept the call. The back-to-back call is established between the primary and secondary lab users. Notice that the identity of the primary lab user is masked from the secondary lab user.

16. Switch to the primary lab user’s session. The identity of the secondary lab user is also masked from the primary lab user.

17. Switch to the console application.

18. Press Enter to shut down the console application.

Exercise 2: Manual Audio Routes






4. Navigate to the folder C:\%UC14TrainingKit%\Labs\8\Before.


6. In Solution Explorer, right-click the AudioRoutes project and select Set as StartUp Project.







Task 2 – Register for an Incoming Call on the Application Endpoint

The UCMA 3.0 SDK provides developers with fine-grained control over the audio routes in an Audio/Video call. This enables functionality such as Supervisor Whisper which allows a supervisor to talk to a customer service agent who is on a call with a customer, without the customer hearing the supervisor.

In this task, you will create a hold music player and attach it to the flow of the audio/video call, invite the primary and secondary lab users to a conference, remove the conference participants from the default audio route to place them on hold, and finally add the conference participants back to the default audio route to take them off hold.


2. Add the following code after the TODO: 8.2.1 comment. This defines a source for the hold music and creates an instance of the Player object to act as the hold music player. It also sets the source of the hold music player and sets the player mode to Automatic so that the hold music will loop continuously.

C#

_holdMusicSource.EndPrepareSource(prepareSourceResult);Console.WriteLine("Prepared hold music source.");

// Create a new Player object using the WMA file source._holdMusicPlayer = new Player();_holdMusicPlayer.SetSource(_holdMusicSource);

// Set the mode to automatic so that the music will loop._holdMusicPlayer.SetMode(PlayerMode.Automatic);Console.WriteLine("Prepared hold music player.");


4. Add the following code after the TODO: 8.2.2 comment. This creates a new conversation on the application endpoint and joins the ad hoc conference. Every conversation has a ConferenceSession to enable the application to join a conference and perform other operations related to an activated conference. The application joins the conference as a


trusted participant, meaning that other participants will not see it in the call. An instance of ConferenceJoinOptions with JoinMode set to JoinMode.TrustedParticipant specifies that the participant is joining the conference as a trusted participant.

C#

conversation.ConferenceSession.EndJoin(result);Console.WriteLine("Joined the conference.");_initialAVCall = new AudioVideoCall(conversation);


6. Add the following code after the TODO: 8.2.3 comment. With the ad hoc conference established, invite the primary and secondary lab users to the conference. Send a conference invitation to the primary lab user. Only send a conference invitation to the secondary lab user when the primary lab user has accepted the invitation.

C#

confInvitePrimaryLabUser.EndDeliver(deliverResult);Console.WriteLine("Primary lab user accepted.");


8. Add the following code after the TODO: 8.2.4 comment. Once both the primary and secondary lab users have joined the conference, the console application prompts us to press Enter to put them both on hold. This code attaches the hold music player to the flow of the audio/video call and starts it. Get a reference to the AudioVideoMcuSession of the call and iterate through each conference participant.

C#

_holdMusicPlayer.AttachFlow(_initialAVCall.Flow);_holdMusicPlayer.Start();


10. Add the following code after the TODO: 8.2.5 comment. This removes each participant from the default MCU routing. Removing a participant from the default MCU routing indicates that there are no longer any audio routes that begin or terminate at that participant’s endpoint. Nobody can hear the participant and the participant can’t hear anything. It is up to the application to now manually add the audio routes to and from that participant’s endpoint as needed.

C#

avMcu.EndRemoveFromDefaultRouting(removeResult);Console.WriteLine("Removed participant {0} from default MCU routing.", participantEndpoint.Participant.Uri);


12. Add the following code after the TODO: 8.2.6 comment. This creates a new OutgoingAudioRoute to the participant’s endpoint. Set the route’s Operation property to

RouteUpdateOperation.Add to indicate that a new route is being added to the AudioVideoMcuRouting for the call.

C#

OutgoingAudioRoute outgoingRoute = null;outgoingRoute = new OutgoingAudioRoute(participantEndpoint);outgoingRoute.Operation = RouteUpdateOperation.Add;outgoingRoutes.Add(outgoingRoute);Console.WriteLine("Adding an outgoing audio route for participant {0}.", participantEndpoint.Participant.Uri);


14. Add the following code after the TODO: 8.2.7 comment. This calls BeginUpdateAudioVideoRoutes to begin the route update operation. BeginUpdateAudioVideoRoutes accepts a list of outgoing and incoming audio routes. Multiple outgoing and incoming routes can be added or removed at the same time. It is recommended that route update operations be processed in bulk, e.g. update outgoing and incoming audio routes to multiple endpoints in the same call to BeginUpdateAudioVideoRoutes.

C#

_initialAVCall.AudioVideoMcuRouting.BeginUpdateAudioRoutes( outgoingRoutes: outgoingRoutes, incomingRoutes: null, userCallback: result => { try { var avMcuRouting = result.AsyncState as AudioVideoMcuRouting; avMcuRouting.EndUpdateAudioRoutes(result); } catch (RealTimeException rtExAudioRoutes) { throw rtExAudioRoutes; } }, state: _initialAVCall.AudioVideoMcuRouting);


16. Add the following code after the TODO: 8.2.8 comment. Instead of stopping the hold music player, we can just remove all the audio routes from the application to the conference participant endpoints. Get a reference to the AudioVideoMcuSession of the call and iterate through each conference participant. Create a route update operation to remove the audio routes.

C#

foreach (var participantEndpoint in avMcu.GetRemoteParticipantEndpoints()){ OutgoingAudioRoute outgoingRoute = null; outgoingRoute = new OutgoingAudioRoute(participantEndpoint); outgoingRoute.Operation = RouteUpdateOperation.Remove; outgoingRoutes.Add(outgoingRoute);}

17. Add the following code after the TODO: 8.2.9 comment. This adds each participant back to the default routing of the AudioVideoMcuSession. The participants can now resume the conference.

C#

avMcu.EndAddToDefaultRouting(addResult);Console.WriteLine("Added participant {0} to default MCU routing.", participantEndpoint.Participant.Uri);

18. Go to Debug >> Start Without Debugging or use the shortcut key [CTRL]+[F5] to start the application. The application starts the collaboration platform and establishes the application endpoint. The application then sets up and prepares the hold music player and invites the primary lab user to the conference.

19. Accept the conference invitation. The primary lab user joins the conference. The application then invites the secondary lab user to the conference. Note: After accepting the incoming call, press the microphone icon in the conversation window to mute the call and prevent audio feedback.

20. Switch to the secondary lab user’s session.

21. Accept the conference invitation. The secondary lab user joins the conference. Note that the conference appears to only have two participants. The application is not visible in the People list since it joined the conference as a trusted participant. Note: After accepting the incoming call, press the microphone icon in the conversation window to mute the call and prevent audio feedback.

22. Switch to the primary lab user’s session.

23. Press Enter to put the conference participants on hold. The hold music player starts. Both participants can now hear the hold music. The participants cannot hear each other.

24. Press Enter to take the conference participants off hold. The hold music player stops. The participants can resume the conference.

25. Press Enter to terminate the application endpoint and shutdown the collaboration platform.

Exercise 3: Application Endpoint Draining






4. Navigate to the folder C:\%UC14TrainingKit%\Labs\8\Before.


6. In Solution Explorer, right-click the Draining project and select Set as StartUp Project.







Task 2 – Draining an Application Endpoint

In previous versions of UCMA, once an application endpoint is terminated, all current calls in place with the endpoint are also immediately terminated. Gracefully shutting down a UCMA application thus involved writing code to wait for all active calls to terminate, while at the same time forwarding any incoming calls to another application endpoint or gracefully declining them.

The UCMA 3.0 SDK introduces the concept of draining, allowing an application endpoint to shutdown gracefully after all active calls have terminated. The endpoint does not accept any new calls, but waits until all calls are terminated before shutting down without affecting any calls currently in progress.


2. Add the following code after the TODO: 8.3.1 comment. This drains the application endpoint before terminating it.

C#


DrainEndpoint();


4. Add the following code after the TODO: 8.3.2 comment. Before draining the application endpoint, configure its draining sessions by calling ApplyDrainingSettings. Passing in DeclineNewIncomingConversations indicates that the application endpoint will decline incoming calls while draining. Begin draining the application endpoint by calling BeginDraining.

C#

_applicationEndpoint.BeginDrain(userCallback: DrainingCompleted, state: null);


6. Add the following code after the TODO: 8.3.3 comment. The application endpoint is ready to be terminated once it has completed draining.

C#

_applicationEndpoint.EndDrain(result);Console.WriteLine("Draining completed.");


8. Add the following code after the TODO: 8.3.4 comment. This terminates the application endpoint.

C#

Console.WriteLine("\nTerminating the endpoint.");_applicationEndpoint.BeginTerminate(userCallback: TerminateEndpointCompleted, state: null);

9. Go to Debug >> Start Without Debugging or use the shortcut key [CTRL]+[F5] to start the application. The application starts the collaboration platform and establishes the application endpoint.


11. Place an audio call to the contact. The application endpoint accepts and establishes the incoming call.

12. Switch to the console application.

13. Press Enter to begin draining the application endpoint. The state of the application endpoint changes from Established to Draining. Note that the current call is unaffected.

14. Switch to the secondary lab user’s session.


16. Place an audio call to the contact. The application endpoint declines the call. The AudioVideoCall_Received event never fires on the application endpoint since it has begun draining.

17. Switch back to the primary user’s session.

18. Hang up the call. All active calls with the application endpoint have now terminated.

19. The application endpoint completes draining.

20. Press Enter. The application endpoint is terminated and the collaboration platform is shut down.

Summary

In this lab, you learned how to create and establish a back-to-back call between two participants while masking their identity from each other. You also saw how UCMA 3.0 allows you to manually create audio routes between participants in a conference to give you fine-grained control over the participants’ experience. Finally, you saw how to use draining to gracefully shutdown an application endpoint.

advanced ucma 3.0 developmentaz12722.vo.msecnd.net/.../labs/8l1-0/lab.docx · web viewin this lab,...

Documents