If you create an application that is built from UCMA v1.0 SDK technology, the UCMA Redistribution MSI, UcmaRedist.msi, and UCMA merge file, UcmaRedist.msm, must be added to your application's MSI bootstrapper (or application chainer). An MSI bootstrapper is a setup program for your application that can bootstrap the desired set of prerequisite components for the application. This topic discusses the details of installing and uninstalling a UCMA Redistribution Package.
UCMA Redistribution Package
The UCMA Redistribution Package (UcmaRedist.msi and UcmaRedist.msm) can be obtained by installing the UCMA v1.0 SDK (UcmaSdk.msi), which comes in 32-bit and 64-bit editions. Each of the two editions of UcmaSdk.msi copies the appropriate version of UcmaRedist.msi and UcmaRedist.msm to the %ProgramFiles%\Office Communications Server 2007\UCMA v1.0 SDK\Redist directory or to a \Redist directory at a different location if the user specified an alternate location at setup.
An independent software vendor (ISV) must use the appropriate merge file for the platform targeted by the application: the 32-bit editions of UcmaRedist.msi and UcmaRedist.msm are used in an application running on a 32-bit platform, and the 64-bit editions of these files are used in an application running on a 64-bit platform.
The product codes for the two editions are shown in the following table.
| Edition | ProductCode |
|---|---|
|
32-bit |
{8A9A9126-1730-47AA-818A-C47A468BB26B} |
|
64-bit |
{9A6922B3-512A-4202-B23B-E3E15A31C01A} |
The bootstrapper for a 32-bit application should attempt to detect the ProductCode for the 32-bit edition. If this ProductCode is detected, the bootstrapper should not install the 32-bit redistribution package. If this ProductCode is not detected, the bootstrapper can install the 32-bit redistribution package. A similar rule applies for a bootstrapper for a 64-bit application.
The MSI for your application should also have a LaunchCondition that ensures that any necessary redistributable packages are installed, in case of failure by the application bootstrapper or if the MSI is manually installed. For more information, see .NET Framework 2.0 and Visual C++ 2005 SP 1 Redistributable Package later in this topic.
In addition to accepting the terms of of the end-user license agreement in the UCMA SDK MSI, an independent software vendor (ISV) must follow the process described in this topic.
Terms of Redistribution
In order to use the redistributable package in your product, its end-user licensing agreement (EULA) must contain the following standard Microsoft terms for redistribution:
Distributable Code. The software contains code that you are permitted to distribute in programs you develop if you comply with the terms below.
- Right to Use and Distribute. The code and text files listed
below are Distributable Code.
- Sample Code. You may modify, copy, and distribute the source
and object code from of code marked as sample.
- Icons. You may copy and distribute the icons in the Image
Library as described in the software documentation.
- Third Party Distribution. You may permit distributors of your
programs to copy and distribute the Distributable Code as part of
those programs.
- Sample Code. You may modify, copy, and distribute the source
and object code from of code marked as sample.
- Distribution Requirements. For any Distributuable Code you
distribute, you must
- add significant primary functionality to it in your
programs;
- require distributors and external end users to agree to terms
that protect it at least as much as this agreement;
- display your valid copyright notice on your programs; and
- indemnify, defend, and hold harmless Microsoft from any claims,
including attorneys' fees, related to the distribution or use of
your programs.
- add significant primary functionality to it in your
programs;
- Distribution Restrictions. You may not
- alter any copyright, trademark or patent notice in the
Distributable Code;
- use Microsoft's trademarks in your program's names or in a way
that suggests your programs come from or are endorsed by
Microsoft;
- distribute Distributable Code to run on a platform other than
the Windows platform;
- include Distributable Code in malicious, deceptive or unlawful
programs; or
- modify or distribute the source code of any Distributable Code
so that any part of it becomes subject of an Excluded License. An
Excluded License is one that requires, as a condition of use,
modification or distribution, that the code be disclosed or
distributed in source code form; or others have the right to modify
it.
- alter any copyright, trademark or patent notice in the
Distributable Code;
Product ID and Component ID Reference Counts
An application should incorporate UcmaRedist.msi and UcmaRedist.msm as part of its bootstrapper. When the application is installed, its internal reference count is incremented, and when it is uninstalled, its internal reference count is decremented.
.NET Framework Version 2.0 Redistributable Package and Visual C++ 2005 SP 1 Redistributable Package
When UcmaRedist.msi is run, it determines whether Microsoft .NET Framework Version 2.0 Redistributable Package and Microsoft Visual C++ 2005 SP1 Redistributable Package are already installed. If not, UcmaRedist.msi silently fails the installation.
It is the responsibility of the customer application to ensure that .NET Framework Version 2.0 Redistributable Package is installed prior to UcmaRedist.msi being launched.
There are 32-bit and 64-bit editions of both .NET Framework Version 2.0 Redistributable Package and Visual C++ 2005 SP 1 Redistributable Package. Install the editions that match the target platform for your application. The following links go to the download sites for the 32-bit editions.
- Microsoft .NET Framework Version 2.0 Redistributable Package
(x86)
- Microsoft Visual C++ 2005 SP1 Redistributable Package
(x86)
These links go to the download sites for the 64-bit editions.
Storing the Managed Code and Other DLLs
For redistribution, SIPEPS.dll and Microsoft.Rtc.Collaboration.dll are copied into the global assembly cache (GAC) so that the same assembly can be shared by multiple dependent customer applications. Unmanaged code DLLs, including S4Perf.dll, are copied to the directory specified in the MSI, but must not be placed into the GAC.
Registration of Performance Counters
When UcmaRedist.msi is run, it registers the managed SIP stack performance counters, if they are not already registered. For more information, see Managed SIP Stack Performance Counters.
UcmaRedist.msi also copies S4Perf.dll, S4Perf.h, and S4Perf.ini to the %ProgramFiles%\Office Communications Server 2007\Common\ directory. An application that uses Unified Communication Managed API and the performance counters should copy S4Perf.dll from this directory to the application's directory at the time the application is launched.
To register performance counters, UcmaRedist.msi executes the following command line:
 Copy Code |
|
|---|---|
%ProgramFiles%\Microsoft Office Communications Server 2007\Common>regsvr32 /n /i S4Perf.dll |
|
Installing the Logging Utilities
When UcmaRedist.msi is run, it copies OCSTracer.exe to the Common\Tracing\ directory under the Office Communications Server 2007 installation directory. Note that running UcmaSdk.msi copies OCSLogger.exe to the \Tracing directory of the UCMA v1.0 SDK installation directory.
For information about how to start and stop tracing, see Enabling Tracing.
Rollback
If the installation is cancelled or errors occur during the installation process, UcmaRedist.msi should be able to automatically roll back the operations it has already completed in order to restore the state prior to the installation launch.
Uninstalling a Customer
Application
When a customer application is uninstalled, the application uninstall procedure should be able to remove UcmaRedist.msi only if the product ID reference count is zero.
If the application being removed is the only application that consumes UCMA v1.0, it may uninstall UcmaRedist.msi. An application find all applications that consume UCMA v1.0 by checking the registry key at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Real-Time Communications\UCMA\ApplicationList. If the ApplicationList registry key has no children, the product can be removed.
Uninstalling UcmaRedist.msi and the
UcmaSdk.msi
An end user who chooses to uninstall UcmaSdk.msi can do so using Add or Remove Programs in Control Panel. UcmaRedist.msi can be uninstalled in the same way.
When this operation is launched and the product ID reference count or one of the component ID reference counts indicate that the SDK is being used by applications, a warning is given that indicates that this operation might break other applications.
A customer application can run the following command line when uninstalling itself:
| Copy Code |
|
|---|---|
msiexec /uninstall C:\<Location>\UcmaSdk.msi |
|
This command should fail if the product ID reference count or the component ID reference count indicates that the product or component is used by another application.
After this check, UcmaRedist.msi removes all of the assemblies from the global assembly cache (GAC), and UcmaSdk.msi removes all of the assemblies from the UCMA v1.0 SDK installation directory.
Both types of MSI unregister the performance counters by running the following command:
| Copy Code |
|
|---|---|
%ProgramFiles%\Office Communications Server 2007\Common>regsvr32 /u /n /i S4Perf.dll |
|
Each then removes S4Perf.dll, S4Perf.ini and S4Perf.h.
All of the directories created by the MSI are then removed.
Patching
Patching will always be done by deploying a UCMA MSP either by Windows Update or by an MSP installation.
The MSP should be able to patch SIPEPS.dll and Microsoft.Rtc.Collaboration.dll in the global assembly cache (GAC).
In addition, an MSP should also be able to patch S4perf.dll by:
- Unregistering the performance counters.
- Removing S4Perf.dll, replacing it with a new version.
- Registering the performance counters again.
When the patch is installed, running a redistribution MSI containing the assembly prior to the patch should not remove the patch.
Versioning
Any service pack or new release of UCMA SDK will update the version of its assemblies to avoid conflict between two versions.
It is required that a customer application that consumes UCMA SDK technology be built against the new service pack or release version of UCMA SDK. Two different versions of UCMA SDK should be able to coexist on the same machine.