NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Assemblies and Versioning

All versioning in the NGWS runtime is done at the assembly level. The specific version of an assembly and the versions of dependent assemblies are recorded in the assembly's manifest. Version policy, which version should be used, is specified by configuration files. These two files, the assembly manifest and an optional configuration file, provide the means for expressing version and version policy and the NGWS runtime then enforces this policy at runtime.

Note: Versioning is done only on assemblies with shared names. Private assemblies are never checked for version information.

Each assembly has its version expressed by two separate "numbers." The first "number" is called a compatibility version. This version number is part of the assembly’s identity and is a key part in the type resolution process at runtime. It is called a compatibility number because this number is used by the runtime when enforcing version policy to determine a particular version’s compatibility with previous versions.

The second version "number" is called an informational version. The informational version is a string and is used to represent additional version information that is included for documentation purposes only. This textual version information corresponds to the product’s marketing literature, packaging, or product name and is not used by the runtime. For example, an informational version could be “NGWS runtime Beta1" or “Acme Control SP 2”.

An Assembly's Compatibility Version Number

Each assembly has a specific compatibility version number as part of its identity. As such, two assemblies that differ by compatibility version are considered by the runtime to be completely different assemblies. This compatibility version number is physically represented as a four part number with the following format:

<major version>.<minor version>.<build number>.<revision>

For example, version 1.5.1254.0.

Each portion of this number has a specific meaning to the runtime as it determines which version of an assembly to load. It is important that you understand the significance of each number. The runtime views the four numbers as three logical parts:

For example, an assembly with compatibility version number 5.4.0.0 is considered incompatibly with an assembly whose compatibility number is 4.1.11.00. An assembly with a version number of 3.5.1342.0 may be compatible with an assembly with version number 3.5.1340.0. Finally, an assembly with a revision number of 5.4.0.23 is considered a QFE for an assembly with a version number of 5.4.0.0.

The compatibility version number is stored in the assembly’s manifest along with other identity information including the assembly name, originator, and version number, as well as information on relationships and locations of other assemblies connected with the application. Because the version number is integral to the assembly, two assemblies with different version numbers are treated as different assemblies by the runtime.

When an assembly is built, the development tool records dependency information for each assembly that is referenced. This information is kept in the assembly manifest as AssemblyRefs. The runtime uses these version numbers, in conjunction with configuration information set by an administrator, to load the proper version of a referenced assembly.

The runtime distinguishes between private and shared assemblies for the purposes of versioning. No version checking is done when resolving references to private assemblies. Since a private assembly is deployed along with the application and is placed in the same directory or subdirectory as the application, the application author has control over the contents and distribution of the assembly.

For information on how to specify version binding policies, see Specifying Version Policies in Configuration Files. For information on how the runtime uses version information to find a particular assembly, see How the runtime Works with Assemblies.

An Assembly's Informational Version

As discussed above, the informational version is a string used to attach additional version information to an assembly for documentation purposes only; this information is not used at runtime. In this release the information is displayed by admin tools and the property pages visible in the shell.

The informational version is represented using the custom attribute System.Reflection.AssemblyInformationalVersionAttribute. The definition of that attribute is: