Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Expand Minimize

PowerShell Scripting Lync 2010 SDK Using Lync Model API

Summary:   In this article you learn how to automate Microsoft Lync 2010 by using Microsoft Windows PowerShell scripting and Microsoft Lync Model API.

Microsoft Lync 2010 API includes the Microsoft Lync Model API and the Microsoft Lync Extensibility API. This article discusses Lync Model API PowerShell scripting. For information about Lync Extensibility API PowerShell scripting, see PowerShell Scripting Lync 2010 SDK Using Lync Extensibility API. This article describes how to complete the following tasks:

  • Obtain the entry point to the Lync Model API and then sign in to Microsoft Lync Server 2010 if the user is not already signed in.

  • Inspect and update local user’s phone numbers.

  • Register for change notification of the local contact information.

  • Examine the organization information for the local user, and discuss how to pass parameters by reference in a PowerShell script.

  • Publish presence of the local user.

For information about how to download Microsoft Lync 2010 SDK and importing an assembly into a PowerShell session, see PowerShell Scripting Lync 2010 SDK Using Lync Extensibility API.

To use the Lync Model API, you must first obtain the LyncClient object by calling the static GetClient method on the Microsoft.Lync.Model.LyncClient type. The following code example shows how to complete this task in PowerShell.


# Obtain the entry point to the Lync.Model API
$client = [Microsoft.Lync.Model.LyncClient]::GetClient()

NoteNote

Before this call, you must import the Microsoft.Lync.Model.Dll assembly.

Once you obtain the LyncClient object, you should verify that the Lync instance is signed in before you call other Lync Model API features. The following code example shows how to complete the task.


# Sign Lync in to Lync Server 2010, if Lync is not already signed in to the server.
if ($client.State -ne [Microsoft.Lync.Model.ClientState]::SignedIn)
{
    $client.EndSignIn(
        $client.BeginSignIn("user@contoso.com", "domain\user", "passwd", $null, $null))
}

Asynchronous calls are invoked in a synchronous manner throughout this article.

NoteNote

The previous code example should work when Lync is not in UISuppression mode. If the UISuppression mode is enabled on Lync, different coding patterns should be followed. For more information, see Understanding UI Suppression in Lync SDK and Walkthrough: Sign In to Lync with UI Suppressed.

The code examples that appear next show how to program Lync Model API in PowerShell scripts.

The following code example shows how to inspect the available phone lines of the local user.


$self = $client.Self;

write-host ("Phone types:")
foreach ($pt in [Enum]::GetValues([Microsoft.Lync.Model.ContactEndpointType]))
{
    $ph = $null
    $ph = $self.GetPhone($pt) 
    " $pt : " + $ph.Endpoint.DisplayName + ", " + $ph.Endpoint.Uri | write-host
    trap [Exception]
    {
        # ignore unassigned phones 
        continue
    }
}

The following code example shows how to set the OtherPhone line of the local user.

#Set OtherPhone
$pt = [Microsoft.Lync.Model.ContactEndpointType]::OtherPhone
if ($self.CanSetPhone($pt))
{
    $ar = $self.BeginSetPhone($pt, "+1 (206)-555-0199", $true, $null, $null)
    $self.EndSetPhone($ar)
    "$pt added." 
}    

The following code example shows how to remove the OtherPhone line of the local user.


#Remove the OtherPhone
if ($self.CanSetPhone($pt))
{
    $ar = $self.BeginRemovePhone($pt, $null, $null)
    $self.EndRemovePhone($ar)
    "$pt removed."    
}

The eventing process is widely used in Lync SDK and in other unified communications APIs that are supported in a Lync Server 2010 deployment. The following code example shows how to register and handle the ContactInformationChanged events in a PowerShell script. You can apply the technique to handle other events that are supported by this API and other unified communications APIs.


#Get a remote contact
$contact = $client.ContactManager.GetContactByUri("johnd@contoso.com");

#Register ContactInformationChanged events raised by the $contact object
Register-ObjectEvent -InputObject $contact `
  -EventName "ContactInformationChanged" `
  -SourceIdentifier "RemoteContactInformationChangedEvent" `
  -action { ContactInfoChangedEventHandler $sender $event }

#Event handler for ContactInformationChanged events
function ContactInfoChangedEventHandler ($sender, $event)
{ 
    $c = $sender -as [Microsoft.Lync.Model.Contact];
    $t = [DateTime]::Now;
    write-host "ContactInfomationChanged on $t for: " $c.Uri; 
    
    foreach($infoType in $event.SourceEventArgs.ChangedContactInformation) 
    {  
         write-host(" $infoType  = " + $c.GetContactInformation($infoType) );
    }
}


NoteNote

The grave accent (`) character is used in a PowerShell script to mark the continuation of the command to the next line.

In the Register-ObjectEvent cmdlet, the InputObject parameter refers to the object ($contact) that raises the events of the specified event name (ContactInformationChanged). The SourceIdentifier parameter value is an application-specified string, which must be unique in a PowerShell session. The action parameter value refers to a script block that is invoked when the event is raised. In the previous code example, the action script block is expressed as a function (ContactInfoChangedEventHandler) with two input parameters. The parameters are used to pass some of the event’s automatic variables ($sender and $event) into the function.

The event registration must be canceled before your script ends or when you are no longer interested in the events. The following code example shows how to cancel the event registration that is discussed earlier.


#Cancel the ContactInformationChanged event registration
Unregister-Event "RemoteContactInformationChangedEvent"

The previous code example can be used to handle the ContactInformationChanged events that are raised by the local user’s Contact object, if the InputObject parameter value is changed to $self.Contact and the SourceIdentifier parameter value changed to a different unique string value, for example, LocalContactInformationChangedEvent.

The following code example shows how to retrieve the organization information from the local user’s Contact object. It can also be applied to a remote contact.


# Retrieve the local user's organization information
# Specify types of the organization information by setting the OrganizationStructureTypes bit flags
$orgStruct = [Microsoft.Lync.Model.OrganizationStructureTypes]::Managers 
$orgStruct = $orgStruct -bor [Microsoft.Lync.Model.OrganizationStructureTypes]::Peers
$orgStruct = $orgStruct -bor [Microsoft.Lync.Model.OrganizationStructureTypes]::Directs

# Initialize the $managers, $peers and $directs objects. 
# Initialization is required to pass the objects by 
# reference into the EndGetOrganizationInformation method.
$managers = $null
$peers = $null
$directs = $null

$ar = $self.Contact.BeginGetOrganizationInformation($orgStruct, $null, $null)
$self.Contact.EndGetOrganizationInformation([ref] $managers, [ref] $peers, [ref] $directs, $ar)

write-host "managers: "
if ($managers)
{
  foreach($c in $managers)
  {
    $m = $c -as [Microsoft.Lync.Model.Contact]
    $m.Uri | write-host
  }
}

write-host "peers:"
if ($peers)
{
   foreach($c in $peers)
   {
     $p = $c -as [Microsoft.Lync.Model.Contact]
     $p.Uri | write-host
   }
}

write-host "directs:"
if ($directs)
{
  foreach($c in $directs)
  {
    $d = $c -as [Microsoft.Lync.Model.Contact]
    $d.Uri | write-host
  }
}

In the previous code example, $orgStruct corresponds to bit-wise flags that is used to filter the kind of organization information that is retrieved. Here, the code is designed to find the managers, peers and direct reports that are associated with the local user. This is specified by combining the three options using bitwise OR operators (-bor).

The Lync Model API documentation shows that the C# syntax of the EndGetOrganizationInformation method has three out parameters that return the retrieved managers, peers, and directs reports. In PowerShell, this kind of out parameter is qualified with [ref] keywords that must be initialized with $null values before they are passed to the method call.

The following code example shows how to publish presence information for a local user.


#Publish personal note and presence availability of the local user
$date = [DateTime]::Now
$availability = 6500
$contactInfo = new-object 'System.Collections.Generic.Dictionary[Microsoft.Lync.Model.PublishableContactInformationType, object]'
$contactInfo.Add([Microsoft.Lync.Model.PublishableContactInformationType]::PersonalNote, 
                "Set availability to $availability using the Lync Model API in PowerShell on $date")
$contactInfo.Add([Microsoft.Lync.Model.PublishableContactInformationType]::Availability, 
                $availability)

$ar = $self.BeginPublishContactInformation($contactInfo, $null, $null)
$self.EndPublishContactInformation($ar)

In the previous code example, the presence publication includes only the personal note and presence state availability number. The availability number ($availability) is set to an integer value of 6500, which indicates that the local user is busy. The personal note is only a string. If you have registered for the ContactInformationChanged events on the local user’s Contact object, the publication forces this kind event to run and the new data should be caught by the registered event handler.

You can also set the presence availability value by using the ContactAvailability enumeration. The following code example shows how to use ContactAvailability to set the value.

$availability = [Microsoft.Lync.Controls.ContactAvailability]::Busy

As shown in the following example, at the beginning of the code file, ensure that you add a reference to the Microsoft.Lync.Controlls.dll assembly.

import-module "C:\Program Files (x86)\Microsoft Lync\SDK\Assemblies\Desktop\Microsoft.Lync.Controls.Dll"

In this article, various PowerShell scripts are used to call into Lync Model API. This article discussed how to use PowerShell scripting and the Lync Model API to complete the following tasks:

  • Sign in to Lync Server 2010.

  • Inspect and update local user information.

  • Register event handlers to receive event alerts.

  • Obtain organization information that is associated with a user and pass parameters by reference in a PowerShell script.

  • Publish a local user’s presence information.

Kurt De Ding is a Senior Programming Writer, Microsoft Office Content Publishing (UA) group.

Show:
© 2015 Microsoft