Hands-On LabIntroduction to the Microsoft Lync 2010 Managed API

Lab version: 1.0

Last updated: 5/20/2023

CONTENTS

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

EXERCISE 1: EXPLORING THE CAPABILITIES OF AUTOMATION.......................................................4Task 1 – Beginning the Exercise...........................................................................................................4

Task 2 – Starting an Instant Messaging Conversation..........................................................................4

Task 3 – Starting an Audio Conversation.............................................................................................5

Task 4 – Sharing a Desktop..................................................................................................................6

Task 5 – Transferring a File..................................................................................................................7

Task 6 – Docking the Conversation Window........................................................................................8

EXERCISE 2: EXPLORING THE LYNC 2010 API OBJECT MODEL......................................................10Task 1 – Beginning the Exercise.........................................................................................................11

Task 2 – Signing in to the Instance of Lync 2010................................................................................11

Task 3 – Setting up Event Handlers for the Lync Events.....................................................................12

Task 4 – Setting up Event Handlers for Contacts and Groups............................................................13

Task 5 – Publishing your Presence, Availability, and a Personal Note...............................................14

SUMMARY................................................................................................................................................ 17

Overview

Lab Time: 45 Minutes

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

The After folder contains the completed lab exercises.

Lab Overview: The Microsoft Lync 2010 Managed API is a rich and full-featured client API that combines the automation capabilities of the Office Communicator Automation API with the flexibility and functionality of the UCC API. The Lync 2010 Managed API provides the Automation class to enable you to launch conversations, add contacts, and automate Lync within your applications.

The Lync 2010 Managed API also provides a rich object model that developers can use to build their own communications-enabled applications without the Lync 2010 UI.

In this lab solution, you will use the Lync 2010 Managed API to do the following:

Start an instant messaging conversation

Start an audio conversation

Start a desktop sharing conversation

Start a file transfer conversation

Dock and undock a conversation window

Prepare your application to sign in to Lync 2010

Set up event handlers for Lync events

Set up event handlers for Contact and Group events

Publish and retrieve presence items

System Requirements

You must have the following items to complete this lab:

Microsoft Visual Studio 2010

Microsoft Lync 2010

Microsoft Lync 2010 Controls SDK

Two accounts (referred to as the primary and secondary lab users in this document), provisioned for the Microsoft Lync Server 2010, that are able to successfully sign in to Lync 2010.

Exercise 1: Exploring the Capabilities of Automation

Task 1 – Beginning the Exercise

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

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\4\Source\Before.

5. Open the Lync2010API solution.

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

7. In Solution Explorer, open the App.config file of the AutomatingLync project.

8. Change the PrimaryLabUserId and SecondaryLabUserId values to your primary and secondary lab accounts.

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

10. Start a remote desktop session with the secondary lab user Id.

11. Return to the primary lab user’s session.

Task 2 – Starting an Instant Messaging Conversation

In this task, you will get the instance of Automation and start an instant messaging conversation with the secondary lab user.

1. Double click TODO: 4.1.1.

2. Add the following code after the TODO: 4.1.1 comment. This gets the Automation instance from the running instance of Lync.

C#

_automation = Microsoft.Lync.Model.LyncClient.GetAutomation();

3. Double click TODO: 4.1.2.

4. Add the following code after the TODO: 4.1.2 comment. Create a Dictionary of context data to add to the conversation, in this case specifying that the first instant message should be sent immediately to the recipient.

C#

var contextData = new Dictionary<AutomationModalitySettings, object>();

contextData.Add(AutomationModalitySettings.FirstInstantMessage, instantMessageText.Text);

contextData.Add(AutomationModalitySettings.SendFirstInstantMessageImmediately, true);

5. Double click TODO: 4.1.3.

6. Add the following code after the TODO: 4.1.3 comment. This starts an IM conversation by adding a participant, setting the context parameters, and specifying instant messaging mode.

C#

_automation.BeginStartConversation( conversationModes: AutomationModalities.InstantMessage, participantUris: participants, contextData: contextData, callback: StartConversationCallback, state: _automation);

7. Defining an optional callback method allows you to get a handle to the window.

8. Go to Debug >> Start Without Debugging or use the shortcut key [Ctrl]+[F5] to start the application.

9. Enter “Hello” into the instant message textbox and click the Send IM button.

10. Switch to the secondary lab user’s session and receive the message.

11. Close the application.

Task 3 – Starting an Audio Conversation

In this task, you will start an audio conversation with the secondary lab user.

1. Navigate to TODO: 4.1.4.

2. Add the following code after the TODO: 4.1.4 comment. This starts an audio conversation by specifying audio mode.

C#

_automation.BeginStartConversation( AutomationModalities.Audio, participants, null, StartConversationCallback, _automation);

3. Press [Ctrl]+[F5] to start the application.

4. Click the Start Audio button.

5. Switch to the secondary lab user’s session and accept the call.

6. Close the application.

Task 4 – Sharing a Desktop

In this task, you will share your desktop with the secondary lab user.

1. Navigate to TODO: 4.1.5.

2. Add the following code after the TODO: 4.1.5 comment. This shares a desktop by setting the context parameters and specifying the app sharing mode.

C#

var contextData = new Dictionary<AutomationModalitySettings, object>();

contextData.Add(AutomationModalitySettings.SharedDesktop, true);

_automation.BeginStartConversation( AutomationModalities.ApplicationSharing, participants, contextData,

StartConversationCallback, _automation);

3. Press [Ctrl]+[F5] to start the application.

4. Click the Share Desktop button.

5. Switch to the secondary lab user’s session and join the desktop sharing conversation.

6. Close the application.

Task 5 – Transferring a File

In this task, you will transfer a file to the secondary lab user.

1. Navigate to TODO: 4.1.6.

2. Add the following code after the TODO: 4.1.6 comment. This transfers a file by setting the context parameters to include the file transfer modality and the file path.

C#

var contextData = new Dictionary<AutomationModalitySettings, object>();

contextData.Add(AutomationModalitySettings.FilePathToTransfer, fileTransferPath.Text);contextData.Add(AutomationModalitySettings.FileIsShared, true);

_automation.BeginStartConversation( AutomationModalities.FileTransfer, participants, contextData, StartConversationCallback, _automation);

3. Press [Ctrl]+[F5] to start the application.

4. Click the Browse button to select a file to transfer.

5. Select FileTransferSample.txt and click the Open button.

6. Click the Transfer File button.

7. Switch to the secondary lab user’s session and download the file.

8. Close the application.

Task 6 – Docking the Conversation Window

In this task, you will dock and undock the conversation window.

1. Navigate to TODO: 4.1.7.

2. Add the following code after the TODO: 4.1.7 comment. This gets the handle to the conversation window.

C#

_conversationWindow = ((Automation)ar.AsyncState).EndStartConversation(ar);

Dispatcher.Invoke(new Action(() =>{ if (_canDock) {

dockConversationWindow.IsEnabled = true; _conversationWindow.Move(_conversationWindow.Left, _conversationWindow.Top); } else { dockConversationWindow.IsEnabled = false; }}));

3. Navigate to TODO: 4.1.8.

4. Add the following code after the TODO: 4.1.8 comment adds event handlers for the conversation window events.

C#

_conversationWindow.NeedsSizeChange += new EventHandler<ConversationWindowNeedsSizeChangeEventArgs>(ConversationWindow_NeedsSizeChange);

_conversationWindow.NeedsAttention += new EventHandler<ConversationWindowNeedsAttentionEventArgs>(ConversationWindow_NeedsAttention);

5. Navigate to TODO: 4.1.9.

6. Add the following code after the TODO: 4.1.9 comment. This docks the window by calling its Dock method and passing the handle to the WindowsFormsHost control that will contain the docked window.

C#

_conversationWindow.Dock(windowsFormsHost.Handle);

7. Navigate to TODO: 4.1.10.

8. Add the following code after the TODO: 4.1.10 comment. This undocks the window by calling its Undock method.

C#

_conversationWindow.Undock();

9. Press [Ctrl]+[F5] to start the application.

10. Enter “Hello” into the instant message textbox and click the Send IM button.

11. Click the Dock button.

12. Verify that the IM conversation window’s chrome is removed and the conversation window is placed in the application window

13. Drag the application window across the screen to see the IM window stay docked in the application.

14. Click the Undock button.

15. Verify that the IM window’s chrome returns and that the window is no longer bound to the application’s position.

16. Close the application.

Exercise 2: Exploring the Lync 2010 API Object Model

Task 1 – Beginning the Exercise

In this task, you will open the project.

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\4\Source\Before.

5. Open the Lync2010API solution.

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

7. Open the Window1.xaml.cs file of the LyncEventsLogger project.

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

9. Start a remote desktop session with the secondary lab user Id.

10. Return to the primary lab user’s session.

Task 2 – Signing in to the Instance of Lync 2010

In this task, you will get a reference to the running instance of Lync 2010, sign in if necessary, and perform setup logic.

1. Navigate to TODO: 4.3.1.

2. Add the following code after the TODO: 4.3.1 comment. This gets the running instance of Lync 2010.

C#

_lyncClient = Microsoft.Lync.Model.LyncClient.GetClient();

3. Navigate to TODO: 4.3.2.

4. Add the following code after the TODO: 4.3.2 comment. This signs in to Lync 2010 if it is not currently signed in and specifies a callback method.

C#

_lyncClient.BeginSignIn(null, null, null, SignInCallback, "Local user signing in" as object);

5. Navigate to TODO: 4.3.3.

6. Add the following code after the TODO: 4.3.3 comment. This checks that sign in was successful and proceeds with initialization logic.

C#

LogEvent("SignInCallback", "Signing in to Lync");InitializeClient();

7. Navigate to TODO: 4.3.4.

8. Add the following code after the TODO: 4.3.4 comment. This gets references to Lync objects used to manage conversations, contacts and groups, and the signed-in user.

C#

_conversationManager = _lyncClient.ConversationManager;_contactManager = _lyncClient.ContactManager;_self = _lyncClient.Self;

9. Sign out of Lync 2010.

10. Go to Debug >> Start Without Debugging or press [Ctrl]+[F5] to start the application.

11. Check that Lync 2010 signs in and the event logger tracks the sign in process.

12. Close the application.

Task 3 – Setting up Event Handlers for the Lync Events

In this task, you will set up event handlers for the local user’s Lync account.

1. Navigate to TODO: 4.3.5.

2. Add the following code after the TODO: 4.3.5 comment. This sets up event handlers for events relating to the local account’s groups and conversations and presence using the Self.Contact reference.

C#

_conversationManager.ConversationAdded += new EventHandler<ConversationManagerEventArgs>(Conversations_ConversationAdded);_conversationManager.ConversationRemoved += new EventHandler<ConversationManagerEventArgs>(Conversations_ConversationRemoved);

_self.Contact.ContactInformationChanged += new EventHandler<ContactInformationChangedEventArgs>(Self_ContactInformationChanged);

_contactManager.GroupAdded += new EventHandler<GroupCollectionChangedEventArgs>(ContactManager_GroupAdded);_contactManager.GroupRemoved += new EventHandler<GroupCollectionChangedEventArgs>(ContactManager_GroupRemoved);

3. Press [Ctrl]+[F5] to start the application.

4. Open Lync 2010, locate the secondary lab user’s contact card, and double-click to start an IM conversation.

5. Observe the Conversation and Participant added events in the Event Log.

6. Close the application.

Task 4 – Setting up Event Handlers for Contacts and Groups

In this task, you will set up event handlers and subscriptions for groups and contacts.

1. Navigate to TODO: 4.3.6.

2. Add the following code after the TODO: 4.3.6 comment. This adds events handlers for individual groups.

C#

group.ContactAdded += new EventHandler<GroupMemberChangedEventArgs>(Group_ContactAdded);group.ContactRemoved += new EventHandler<GroupMemberChangedEventArgs>(Group_ContactRemoved);

3. Navigate to TODO: 4.3.7.

4. Add the following code after the TODO: 4.3.7 comment. This creates a subscription for Availability and Activity changes to presence items of your contacts.

C#

var subscription = _contactManager.CreateSubscription();

var contactInformationTypes = new List<ContactInformationType>() { ContactInformationType.Availability, ContactInformationType.Activity };

subscription.Subscribe(ContactSubscriptionRefreshRate.Low, contactInformationTypes);_contactSubscriptions.Add(group.Name, subscription);

5. Navigate to TODO: 4.3.8.

6. Add the following code after the TODO: 4.3.8 comment. This adds an event handler for each contact’s presence changed event.

C#

contact.ContactInformationChanged += new EventHandler<ContactInformationChangedEventArgs>( Contact_ContactInformationChanged);

7. Press [Ctrl]+[F5] to start the application.

8. Switch to the secondary lab user’s remote desktop session and change their status in Lync to Be Right Back.

9. Return to the primary session and view the updated presence event for that contact in the Event Log.

10. Close the application.

Task 5 – Publishing your Presence, Availability, and a Personal Note

In this task, you will publish and retrieve your presence items.

1. Navigate to TODO: 4.3.9.

2. Add the following code after the TODO: 4.3.9 comment. This calls the Self. BeginPublishContactInformation method to publish a personal note for the local Lync account.

C#

var contactInformation = new List<KeyValuePair<PublishableContactInformationType, object>>();contactInformation.Add(new KeyValuePair<PublishableContactInformationType, object>( PublishableContactInformationType.PersonalNote, personalNote.Text.Trim()));

_self.BeginPublishContactInformation( contactInformation, result => _self.EndPublishContactInformation(result), "Publishing personal note");

3. Navigate to TODO: 4.3.10.

4. Add the following code after the TODO: 4.3.10 comment. This gets the Activity of the local Lync account (e.g. Available, Busy).

C#

myAvailability.Text = _self.Contact.GetContactInformation(ContactInformationType.Activity).ToString();

5. Navigate to TODO: 4.3.11.

6. Add the following code after the TODO: 4.3.11 comment. This calls Self. BeginPublishContactInformation to change the availability of the local Lync account.

C#

var contactInformation = new List<KeyValuePair<PublishableContactInformationType, object>>();contactInformation.Add(new KeyValuePair<PublishableContactInformationType, object>( PublishableContactInformationType.Availability, Convert.ToInt32((status.SelectedValue as ComboBoxItem).Tag)));_self.BeginPublishContactInformation( contactInformation, result => _self.EndPublishContactInformation(result), "Updating my status");

7. Press [Ctrl]+[F5] to start the application.

8. Type “In a Conference” in the personal note text box and click the Publish button.

9. Check for the event in the Event Log.

10. Open Microsoft Lync 2010 and check that the new personal note is visible at the top of the window.

11. In the Lync window, change the Availability to Busy.

12. Check that the My Status area is updated and the event is logged.

13. In the Update My Status menu of the application, change the status to Available and click the Update button.

14. Check that the event is logged and the availability is updated in the Lync 2010 window.

15. Close the application.

Summary

In this lab, you used the Microsoft Lync 2010 Managed API to build simple applications that leverage Automation and the Lync 2010 object model. You saw how easy it is to start conversations in different modalities (IM, Audio, Desktop Sharing, File Transfer) using Automation. You also learned how to configure your application to sign in to the running instance of Lync 2010, how to set up event handlers to listen for useful Lync events, and how to publish and retrieve your presence information.