Important Change
Because of the problem mentioned in Microsoft's knowledge base article 905238 we will increase the assembly versions for every new major and minor version of OOo.Notes
For OOo 2.4.1 the version for policy.1.0.cli_basetypes.dll was changed from 9.0.0.0 to 9.1.0.0. This was done because a bug, possibly in .NET Framwork 1.1, caused the test program (cli_ure/qa/versioning) to fail, when the version was 10.0.0.0. or greater (11.0.0.0 etc.). It failed, however, only when StarOffice was updated. A stand-alone installation always worked.
The tests also failed with many updated respin versions of StarOffice. In all cases .NET failed to find the latest policy assembly. For example, when version 6 and 13 of policy.1.0.cli_ure.dll where installed, then the framwork chose the older version. Here is an overview of the tests. Tested where different respin version with an update 11:
StarOffice Test version result (respin) update u11 ---------------------------- final ok u1 ok u2 failed u3 failed u4 failed u5 failed u6 failed u7 failed u8 ok u9 ok u10 ok
It is possible that those respin versions which failed the test will also not work with older updates. For example, I tested a StarOffice u4 with the updates 8,9 and 10. The tests failed with all three offices.
When the runtests.exe was configured to use the .NET Framework 2.0 then it worked with all updated offices. To configure runtests to use another runtime one has to provide config file (runtests.exe.config), which contains for example:
<configuration> <startup> <supportedRuntime version="v2.0.50727" /> </startup> </configuration>
Note that the configuration file is only necessary if .NET Framework 1.1 AND .NET Framework 2.0 are installed. The easiest way to enforce the use of the latest framework is to simple uninstall .NET Framework 1.1.
As of StarOffice 9 (OOo 3.0) this problem will not exist anymore, since that office requires at least a .NET Framework 2.0.
Versioning for assemblies of CLI-UNO Binding
This documents gives some background about the versioning applied to the assemblies which are part of the CLI-UNO binding.
The assemblies have all a strong names. Hence the .NET runtime will strictly enforce versioning rules. That is, a client application can only run with the assemblies it was build with. The exception is, that users could change the application or machine config file and redirect the version of the respective assembly, or OOo installs policy assemblies.
For this document we assume that the reader has good knowledge of shared assemblies and policy assemblies.
Versioning Scheme
The version of an assembly consists of four parts:
major.minor.build.revision
The meaning of every part can be freely interpreted by developers. There is no need to use the parts exactly as their names indicate.
For our assemblies we will use this convention:
- major: expresses a major change
- minor: expresses a minor incompatible change
- build: expresses a compatible change.
- revision: expresses a compatible change.
For incompatible changes we will increase the major part of the assembly. The minor will remain unchanged, except for some urgent reasons.
The CLI-UNO assemblies should not become incompatible very often. In fact, we will try to keep them compatible as long as possible, so as not to break existing application.
Usually we will increase the “build” as a result of bug fixes or new compatible features.
The “revision” will remain unchanged, except for some urgent reasons.
Although a version could change everytime an assembly was modified, we will try to change the version only once between two official releases. For example, say OOo2.0 will be shipped based on 680m130. In m131 a bug will be fixed (compatibly). Then the version will be increased. Even if other bugs will be fixed (compatibly) in the following milestones, the version will remain unchanged. In the next official release, the version will be the one from m131. If, however, the assembly will be altered incompatibly, then the version must be increased again. But the following compatible or incompatible changes, will not affect the version of the forthcoming release. For example, in m132 an incompatibility will be introduced and the version will be increased again (major or minor). The next release will be based on m140. All other changes between 132 and 140 will not cause the version to change.
Developers, please notice that you should build your CLI client applications always with the final version, such as OOo2, OOo3, etc. If, for an example, the application was build with assemblies from OOo2.0.1, then users with OOo2 cannot use it.Compatible Changes and Policy Assemblies
Compatible changes are often caused by bug fixes. Because of the versioning rules of .NET (application runs only with the assembly it has been build with), client applications cannot benefit from the bug fixes without manual adaptations by the user. Because many users do not have the necessary knowledge, OpenOffice.org will provide publisher policy assemblies. By installing the policy assemblies we will ensure, that applications use the latest (compatible) assemblies of the CLI-UNO binding.
A policy assembly applies only for a particular assembly with a determined major and minor version. For example, policy.1.1.cli_types.dll only applies for version 1.1.x.x of cli_types.dll. This has some implications because the .NET framework does not support a chaining mechanism for policy assemblies. For example, let us assume there is a cli_types.dll with these versions:
1.1
1.2
1.3
Because the newer versions are
backwards compatible one could deploy these policy assemblies:
policy.1.1.cli_types.dll:
oldVersion: 1.1.0.0 newVersion: 1.2.0.0
policy.1.2.cli_types.dll:
oldVersion: 1.2.0.0 newVersion: 1.3.0.0
One could expect that an application that was build with version 1.1 of cli_types.dll uses version 1.3. But this is not the case. The application uses version 1.2. The version part in the name of the policy assembly corresponds to the macro.minor part of the assembly for which it provides the redirection. If one wanted applications, which were build with v1.1 to use v1.3, then one would have to provide a new policy assembly:
policy.1.1.cli_types.dll: oldVersion: 1.1.0.0 newVersion: 1.3.0.0
If we would allow that the minor part of the version could be used to indicate a compatible change, then one would have to provide a policy assembly for every minor. For example, let us again assume that the following versions of cli_types.dll are compatible (they are backwards compatible to the previous version):
1.1, 1.2, 1.3, 1.4
And we assume that there are applications, which have been build with one of these versions. In order to have them all use the latest version 1.4, one would have to ship three policy assemblies:
policy.1.1.cli_types.dll:
oldVersion: 1.1.0.0 newVersion: 1.4.0.0
policy.1.2.cli_types.dll:
oldVersion: 1.2.0.0 newVersion: 1.4.0.0
policy.1.3.cli_types.dll:
oldVersion: 1.3.0.0 newVersion: 1.4.0.0
And this would have to be done for all assemblies of CLI-UNO binding. Therefore, only the build and revision part of the version are used for compatible changes. Then it is sufficient to ship only one policy assembly for each assembly. Policy assemblies have also a version. If there are several policy assemblies installed, which all target the same assembly, then the .NET runtime uses the policy with the latest version.
Compatible Changes in cli_types.dll
Changes to unpublished types (declared in unoidl WITHOUT the keyword "published") are always regarded as compatible changes even if they have been changed incompatibly. This is possible because client programs must not use unpublished types. It is also necessary because changes to unpublished types may occur in every new version or product update. To declare the change to be incompatible would prevent client code to run with the respective version of the office.Versioning of Policy Assemblies
Policy assemblies must have a version the same as ordinary assemblies. By providing a version one can have different policy assemblies for one assembly. The .NET runtime will use the policy assembly with the latest version.
Policy assemblies are only used if there is a new version of an
assembly which is still backwards compatible. With our versioning
scheme this would apply to assemblies of the same name where the
major and minor part of the version are equal. For example, if there
are multiple versions of cli_types.dll: 1.1.0.0, 1.1.1.0, 1.1.2.0,
then there could be a policy.1.1.cli_types.dll
version 1.0.0.0, redirecting from 1.1.0.0 to 1.1.1.0
version 2.0.0.0, redirecting from 1.1.0.0-1.1.1.0 to 1.1.2.0
We will simply increase the major part unless there are urgent reasons to use the other parts of the version. Please notice that the name of the policy assembly already contains the major.minor version parts of the related assembly.
Last changed: $Date: 2008/05/07 13:22:48 $
