Extending Unified Communications Services of UCMA Bots to PIC Clients: Building and Deploying Application (Part 5 of 5)

  • Article

Summary:   Learn how to extend Microsoft Lync Server 2010 supported unified communications services that are provided by a trusted Microsoft Unified Communications Managed API (UCMA) bot application to Public Internet Cloud (PIC) clients. Without the extension, the unified communications services are restricted to a limited number of Microsoft Lync 2010 clients in a single enterprise network domain. This number is derived from the CategorySubscriptions property of the presence policy that is set by a Lync Server 2010 administrator. Here, PIC clients can include Windows Live Messenger, Skype, and Yahoo! Messenger.

Programmatically, you learn how to enable a Lync Server 2010 application by using the Microsoft Lync Server 2010 SIP Application API and UCMA. Lync Server 2010 SIP Application API is used to intercept a presence subscription from a PIC client and UCMA is used to send the requesting PIC client the online status of an active bot.

Applies to:   Microsoft Unified Communications Managed API (UCMA) 3.0 Core SDK | Microsoft Lync Server 2010 SDK

Published:   May 2012 | Provided by:   Kurt De Ding and Ajay Soni, Microsoft | About the Author

Contents

  • Building and Deploying the Application on Lync Server

  • Building the Application as the Presence Subscription Interceptor for Bot

  • Deploying the Application as Trusted Lync Server Application

  • Running the Application

  • Debugging the Application

  • Conclusion

  • Additional Resources

Download code  Download code

This is the fifth in a series of five articles about how to extend the services of a Microsoft Unified Communications Managed API (UCMA) bot application to Public Internet Cloud (PIC) clients by enabling an unlimited number of PIC clients that can subscribe to the presence of the UCMA bot.

Building and Deploying the Application on Lync Server

In part 1 to 4, you learned how the application works logically. In part 5, you learn how to build and run the application. If you are new to building and deploying a Microsoft Lync Server 2010 application that includes a UCMA managed component, you might find the process challenging. The undertaking can be fancy, involves different technologies and requires correct configuration on the server. To help you start the process smoothly, part 5 includes end-to-end steps in building, deploying, and running the application.

Building the Application as the Presence Subscription Interceptor for Bot

Before you start, make sure that Microsoft Visual Studio 2010 development system, Microsoft Lync Server 2010 SDK, and UCMA 3.0 SDK are installed on your development computer. For more information about installation, see Additional Resources.

To build the application as the presence subscription interceptor for bot

  1. Start Visual Studio and then choose File, New, Project.

  2. In the New Project dialog box select the Visual C# Console Application template, use PresenceSubInterceptorForBot for the project name, and then specify a location for the project files, for example, c:\MyApps. In the area above the template selection pane, open the shortcut menu and ensure that .NET Framework 3.5 is selected, and then choose the OK button.

  3. In Solution Explorer, double-click Properties and ensure that the targeted platform is set to x64. The ServerAgent.Dll and the threading library use 64-bit binaries.

  4. In Solution Explorer, right-click References and then select Add References. In the Add Reference dialog box, select the Browse tab, navigate to the directories where the Lync Server 2010 SDK and UCMA 3.0 SDK are installed, choose the serveragent.dll (Microsoft Lync Server 2010 SIP Application API), microsoft.rtc.collabration.dll (UCMA) and SIPEPS.DLL (UCMA) assembly files, and then choose OK.

  5. Add a text file to the PresenceSubInterceptorForBot.am project. Write the application manifest in the file. You can either copy the application manifest from the code listings presented in this article or from the accompanying application project.

  6. Add C# class files to the project. You may want to add multiple class files to make coding easier to manage. You can rename the default Program.cs file that uses a more descriptive name, such as PresenceSubInterceptorForBot.cs, and then add AppEndpointManger.cs and AppUtils.cs files following the practice of the accompanying application project. In the C# class files, you may want to add the following, and possibly other, #include statements for any namespaces that are referenced by the application.

    using Microsoft.Rtc.Sip;             // To use Lync Server API
using Microsoft.Rtc.Collaboration;   // To use UCMA
using Microsoft.Rtc.Signaling;       // To use UCMA
using System.Text;                   // for text manipulation
using System.Management.Automation;             // To use PowerShell
using System.Management.Automation.Runspaces;   // To use PowerShell

  7. Add a PresenceSubInterceptorForBot.exe.config file that contains the configurable application settings for provisioning the application as a UCMA trusted server application.

  8. In Visual Studio, choose Build, Build Solution to build the project.

At this point, you cannot yet start or debug the application because it must be properly deployed on the server before it can be executed without exceptions. The next section discusses how to deploy the application.

Deploying the Application as Trusted Lync Server Application

To deploy the Lync Server 2010 application, you install it on a server. If the application also uses UCMA, the application is deployed as a trusted server application.

To deploy the application as a trusted Lync Server application

  1. To enable the server application as a trusted UCMA application, run the following PowerShell commands from a Lync Server Management Shell window on a Lync Server 2010 Front End computer, in the following, order:

    New-CsTrustedApplicationPool -identity lync-fe.contoso.com -site 1 -registrar lync-fe.contoso.com

New-CsTrustedApplication -identity lync-fe.contoso.com/PresenceSubInterceptorForBot -port 5061

Enable-cstopology

New-CsTrustedApplicationEndpoint -sipaddress sip:picinterceptor@contoso.com -applicationId "urn:application:PresenceSubInterceptorForBot" -trustedapplicationpoolfqdn lync-fe.contoso.com

    Here, the New-CsTrustedApplicationPool cmdlet creates an application pool in which the trusted application runs. The New-CsTrustedApplication cmdlet configures the application as a trusted application. The “PresenceSubInterceptorForBot” substring in the –Identity parameter is the name of the application (PresenceSubInterceptorForBot.exe) that is upgraded to a trusted application. The New-CsTrustedApplicationEndpoint cmdlet registers the application as a trusted application endpoint with a SIP URI of “sip:picinterceptor@contoso.com”. This URI must be supplied when the ApplicationEndpoint object is created. The application will have to supply the value of the -applicationId parameter when it instantiates a ProvisionedApplicationPlatformSettings object for the construction of the ApplicationEndpoint object.

  2. To install the application on Lync Server 2010, run the following PowerShell cmdlet from the Lync Server Management Shell window on a Lync Server 2010 Front End computer.

    New-CsServerApplication -Uri https://www.microsoft.com/LCS/sdk/samples/PresenceSubInterceptorForBot -Critical $false             -Priority 2 -Identity Service:Registrar:lync-fe.contoso.com/PresenceSubInterceptorForBot -enabled $true

    Here, the New-CsServerApplication cmdlet registers a managed application as a Lync Server 2010 application that runs on the Lync Server 2010 computer (lync-fe.contoso.com). The -Uri parameter value specified in the cmdlet uniquely identifies the application and must be the same as the appUri attribute declared in the application manifest. The “PresenceSubInceptorForBot” substring in the -Identity parameter value can be any string value. This –identity parameter value is used to identify this application when Get-CsServerApplication or Remove-CsServerApplication is used later to inspect or delete the application, respectively.

    When the server application is connecting to the server, the application manifest is compiled and loaded into the server, and the embedded MSPL script is started. For a script-only Lync Server 2010 application, the -ScriptName parameter (not shown in part 5) must be included to specify the location of the application manifest file. Registering a script-only Lync Server 2010 application also loads the application manifest and runs the embedded MSPL script.

Running the Application

To run the application, you must be an administrator who is also a member of the RTC Server Applications local group. The accompanying application manifest (.am) file must be located in the same folder as the application’s executable (.exe) file. You should also copy the required application configuration (.config) file into the same folder.

To run the application

  1. Log on to the Lync Server 2010 computer that uses an administrator account. Ensure that the user account is a member of the RTC Server Applications local group. If not, add the user account to the group, log off, and then log on to the computer.

  2. Create a folder and copy the PresenceSubInterceptorForBot.am, PresenceSubInterceptorForBot.exe, PresenceSubInterceptorForBot.exe.config, Microsoft.Rtc.Collaboration.dll, SIPEPS.Dll, and ServerAgent.Dll files to the application folder.

  3. Start the application (PresenceSubInterceptorForBot.exe).

To run the application in the background, you must run it as a service. For more information about how to create and run an application as a Windows service, see Introduction to Windows Service Applications.

Debugging the Application

To debug the server application, tracing can be enabled for both the MSPL scripts and the managed component. For the MSPL script, ApiLogger can be used to trace the logs. For the managed application, the usual debugging techniques can be employed. If UCMA is used, the SIP traffic can be logged by OCSLogger. How to use ApiLogger and OCSLogger to trace the logs generated by a MSPL script and a UCMA server application are discussed later in part 5.

To debug a MSPL script, , logs can be enabled by calling the Log(“Debugr”, “title”, “value”) function against the built-in debugger named Debugr in the script. Logged titles and values are displayed by the ApiLogger utility, a Lync Server 2010 SIP Application API application debugging tool that is included in the Lync Server 2010 SDK.

To check the MSPL script for errors

  1. To check an MSPL script for possible grammatical errors, use the CompileSPL tool at the compile time by running the following command at a command prompt.

    CompileSPL PresenceSubInterceptorForBot.am

  2. To enable logs in a MSPL script, insert the statement of Log(“Debugr”, “title”, “value”) in appropriate locations in the script. The title parameter is a placeholder for a message description, and the value parameter is a placeholder for the message. “Debugr” must be used as is.

  3. To display the logs that are created by a MSPL script, start ApiLogger.exe. You will then be prompted to stop and restart the Lync Server 2010 computer. You can stop and restart the server by using the following commands.

    net stop rtcrrv
net start rtcsrv

  4. Start the server application. The logs appear in the command window where ApiLogger is running, while the server application is in session.

To debug the UCMA managed server application

  1. Start OCSlogger.exe and choose the kind of debugging process.

  2. In OCSLogger, click Start Logging.

  3. Run the server application.

  4. In OCSLogger, click Stop Logging.

  5. Click Analyze log Files. This starts the Snooper to displace execution traces and the SIP traffic.

To debug the server application by using the Microsoft.Rtc.Sip namespace, add serveragent.dll as an additional component in the OCSLogger configuration, and then repeat the previous steps.

Conclusion

In this article, you learned how to extend unified communications services that are provided by a trusted UCMA bot application, which otherwise can be accessed only by a limited number of Lync 2010 clients in a single enterprise network domain, by creating a managed Lync Server 2010 SIP Application API application that is also a trusted UCMA server application. You learned how the Lync Server 2010 SIP Application API application is used to intercept SIP SUBSCRIBE requests that are targeted for a bot’s presence and sourced from a PIC client. The process involved creating a SIP application manifest that contains an embedded MSPL script, which among other tasks, served to dispatch the intercepted message to a managed code event handler by using the Microsoft.Rtc.Sip and Microsoft.Rtc.Collaboration namespaces. For the presence SUBSCRIBE request that is targeted for an enabled bot, the available presence status of the bot is returned, in a page-mode SIP message of the NOTIFY type, to the requesting client directly. All other messages are rerouted back to the server for regular processing. The list of the currently enabled bots is obtained by programmatically by periodically invoking appropriate Lync Server Management Shell cmdlets that are processed in a separately maintained thread.

You also learn how to build and register the Lync Server 2010 application, enable it as a trusted UCMA server application, and instantiate a UCMA application endpoint by using the application settings that are provisioned from the Lync Server 2010 computer.

The development process that is used in this article applies to many application scenarios that involve interactions between UCMA bots and PIC clients in federated networks. An example would be the integration of Skype and Lync 2010 services.

Additional Resources

For more information, see the following resources:

About the Author

Kurt De Ding is a Senior Programming Writer in the Microsoft Office Content Publishing (UA) group. Ajay Soni is a Senior Program Manager with Engineering, Community & Online (ECO) of Microsoft Services.