Share via

Programming Enhanced Presence Schemas: Creating .NET Framework Assemblies from Schemas (Part 1 of 3)

  • Article

Summary:   Publishing and subscribing to enhanced presence involves creating, parsing, and manipulating enhanced presence category instances as XML elements. This article discusses how to transform the enhanced presence XML schema types into their corresponding Microsoft .NET Framework classes to use the common language runtime (CLR) objects to program by using the category instances.

This article is the first installment of a three-part series of articles. For information about part 2 and part 3, see Additional Resources.

Applies to:   Microsoft Lync 2010 | Microsoft Office Communicator 2007 R2

Published:   February 2011   Provided by:    Kurt De Ding, Microsoft | About the Author

Contents

  • Creating .NET Framework Assembly

  • Conclusion

  • Additional Resources

Creating .NET Framework Assembly

Enhanced presence simplifies real-time communications by providing information about the availability, capabilities, and willingness of the communication partners. To enable enhanced presence in your application, you must publish and subscribe to enhanced presence data. This involves creating XML strings as enhanced presence category instances for publication and for parsing the XML strings that are used in subscription.

You have to generate the XML strings if you use one of the following APIs:

  • Microsoft Unified Communications Managed API (UCMA) 2.0.

  • Microsoft Unified Communications Client API (UCC API).

  • Other unified communications APIs that do not encapsulate all of the enhanced presence data and do not expose them as programmable objects.

One way to generate the XML strings is to have them hard-coded in your application. However, this process can introduce errors. Furthermore, it makes your code dependent on the enhanced presence XML schemas that are currently used. Modifying existing schemas or introducing new schemas will likely require you to recode the XML strings. A better approach to programming with the enhanced presence category instances is to work with common language runtime (CLR) classes. They are generated from the enhanced presence schemas by using the XML serialization and are supported in the .NET Framework. This approach abstracts the XML operations into a reusable component and also separates the application logic from XML data manipulation.

To work with the presence data by using the System.Xml.Serialization namespace of the .NET Framework, you must convert the XML schema definition (XSD) types into CLR classes. To do this, use XSD.exe (a command-line tool) to generate the corresponding C# classes before you compile them into a .NET Framework assembly.

For publication, you create enhanced presence category instances in this manner:

  1. Instantiate the corresponding CLR classes with particular properties.

  2. Serialize the CLR objects into their corresponding XML strings.

For subscription, you create enhanced presence category instances in this manner:

  1. Deserialize the XML strings of the received enhanced presence category instances into their corresponding CLR objects.

  2. Determine a contact's presence by examining the properties of the CLR objects.

Using the XML serialization instead of creating the presence category XML strings has the following advantages:

  • The resulting enhanced presence category instance XML elements are well-formed and introduce fewer errors.

  • You can make your presence category instance generation code-independent of the XML schemas. This way, changes in the XML schemas will not break your code.

  • You can enable dynamic parsing of enhanced presence category instances by programmatically discovering and determining their property values by using the System.Reflection namespace of the .NET Framework.

In this series of three articles, you learn how to program the enhanced presence schemas for publication and subscription of enhanced presence category instances by using the System.Xml.Serialization namespace.

Part 1 describes how to generate a CLR assembly from a given enhanced presence XML schema definition (XSD) set.

Part 2 and 3 show how to complete these tasks:

  • Create publishable category instances for publication by using the CLR assembly of the given enhanced presence schemas.

  • Parse received category instances in subscription by using the programmable classes that are exposed by the .NET Framework assembly.

To build the .NET Framework assembly from the Microsoft Office Communications Server 2007 R2 enhanced presence schemas, follow these steps:

  1. Install the Unified Communications Enhanced Presence Schemas Reference for Office Communications Server 2007 R2.

  2. Generate the C# source files for the enhanced presence categories from the schemas.

  3. Compile and build the .NET Framework assembly from the generated C# files.

Important

The License Agreement that accompanies the Unified Communications Enhanced Presence Schemas Reference lets you use the downloaded schemas files in your code. However, you must not redistribute the schemas in any form unless you have obtained a redistributable license from Microsoft.

To install the Unified Communications enhanced presence schemas reference

  1. Go to Unified Communications Enhanced Presence Schemas for Microsoft Office Communications Server 2007 R2, and then click Download.

  2. In the File Download Security Warning dialog box, click Run.

  3. In the Internet Explorer Security Warning dialog box, click Run.

  4. Complete the steps that appear after you click Run, accept the License Agreement, and then finish the installation.

By default, the following enhanced presence XSD files are installed in the %ProgramFiles(x86)%\Microsoft Office Communications Server 2007\Enhanced Presence Schemas\Schemas directory:

  • calendardata.xsd

  • calendardatatypes.xsd

  • commontypes.xsd

  • contactcard.xsd

  • contactcardtypes.xsd

  • device.xsd

  • devicetypes.xsd

  • note.xsd

  • options-Alerts.xsd

  • options-OtherOptions.xsd

  • options-RccOptions.xsd

  • options-RccOptionsTypes.xsd

  • options-UserInformation.xsd

  • options-UserInformationTypes.xsd

  • service.xsd

  • servicetypes.xsd

  • state.xsd

  • statetypes.xsd

  • userProperties.xsd

For information about these XSD files, see Unified Communications Enhanced Presence Schema Reference (2007 R2).

To generate the C# source files for the enhanced presence categories from the schemas

  1. Create a folder on your local hard disk drive as the working directory. For example: %homedrive%\categorySchemas

  2. Copy the enhanced presence schemas files from the installation directory to your new directory.

  3. Click Start, in the Run dialog box type cmd. The Command Prompt window appears.

  4. Change to the working directory that you created in step 1 by typing the following command at the command prompt: cd %homedrive%\categorySchemas

  5. Copy the following commands to your favorite editor (for example, Notepad):

    • Xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.CalendarData calendardata.xsd calendardatatypes.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.ContactCard contactcard.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.Device device.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.Note note.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.AlertsOptions options-Alerts.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.OtherOptions options-OtherOptions.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.RccOptions options-RccOptions.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.UserOptions options-UserInformation.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.Service service.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.State state.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.UserProperties userProperties.xsd commontypes.xsd

    • xsd.exe /c /n:Microsoft.Rtc.Sdk.Categories.Routing routing.xsd

  6. XSD.exe is included in the.NET Framework SDK and the Microsoft Windows SDK download. XSD.exe is saved to one of the following directories:

    • %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bin

    • %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bin\x64

  7. Save XSD2CS.cmd in your current working directory.

  8. Invoke the commands by typing the following at the command prompt: XSD2CS.cmd

Successfully running the previous commands creates the following C# source files:

  • calendardata_calendardatatypes_commontypes.cs

  • contactcard_commontypes.csReplaceThisText

  • device_commontypes.cs

  • note_commontypes.cs

  • options-Alerts_commontypes.cs

  • options-OtherOptions_commontypes.cs

  • options-RccOptions_commontypes.cs

  • options-UserInformation_commontypes.cs

  • service_commontypes.cs

  • state_commontypes.cs

  • userProperties_commontypes.cs

To compile and build the .NET Framework assembly from the generated C# files

At the command prompt, copy the following command. It compiles and builds a .NET Framework assembly from the C# source files for the enhanced presence types that you previously generated:

  • csc.exe /out:Microsoft.Rtc.Sdk.Categories.dll /t:library /r:system.dll contactcard_commontypes.cs calendardata_calendardatatypes_commontypes.cs device_commontypes.cs note_commontypes.cs options-Alerts_commontypes.cs options-OtherOptions_commontypes.cs options-RccOptions_commontypes.cs options-UserInformation_commontypes.cs service_commontypes.cs state_commontypes.cs userProperties_commontypes.cs routing.cs

The C# compiler, csc.exe, is available in Microsoft Visual Studio 2008 and can be found in the %homedrive%\Windows\Microsoft.NET\Framework\v3.5 directory.

Successfully running the previous command creates a .NET Framework assembly named Microsoft.Rtc.Sdk.Categories.dll. You can add a reference to this assembly in your application project that publishes and subscribes to enhanced presence, which is discussed in part 2 and 3:

Conclusion

In part 1, XSD.exe is used to create a .NET Framework assembly from the enhanced presence schemas. The resulting CLR types in the assembly correspond to the XML types that are defined in the schema files. By using this .NET Framework assembly, you can manipulate the enhanced presence XML from object-oriented and type-safe CLR classes. For presence publication, this helps ensure that you produce well-formed XML strings for the enhanced presence category instance values.

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.