[WiX-users] Tutorial: How to install files into WinSxS

[ACKH <for...@ho...>]

Hi all,

After struggling for a couple of days I have decided to write a tutorial on
how to install files into the WinSxS folder. There are some pitfalls and I
hope I can spare frustration by providing this tutorial. Well, here it is:

Basically the WinSxS folder is for native assemblies what the Global
Assembly cache is for managed assemblies: An option to store multiple
versions of the same file.

Note that the WinSxS folder has been introduced with Windows XP and this
technology is therefore not available on Windows operating systems released
prior to Windows XP.


In order to install a native assembly into the WinSxS folder several steps
must be done:

1.	First of all the native assembly must have a version number. If no
version number is available it is (at least to my knowledge) not possible to
install the native assembly into the WinSxS folder.

2.	A manifest for the native assembly must be created (extension
“.manifest”). This manifest must contain the version number of the native
assembly and the public key token of the certificate that will later be used

3.	A verification catalog file for the native assembly must be created
(extension “.cat”).

4.	The verification catalog must be signed with a certificate. The public
key token of this certificate must be part of the previously mentioned
manifest. Note that the key used here must be at least 2048 bit long.

Instead of doing all these steps manually for each file that shall be
installed I have written a perl script. It is attached to this posting. In
order to run it you need a perl interpreter (free one available 
http://www.activestate.com/Products/activeperl/index.mhtml here ). Please
ensure two things before running the script: Make sure the perl package
“Win32-File-Ver” is installed (possible using the perl package manager that
comes with the perl interpreter linked above) and second make sure that the
required certificate is available in a folder named "certificate". This
folder must be in the same folder as the perl script. In order to create a
dummy certificate you can execute the attached batch file. You will then get
a certificate with a 2048 bit private key.

If this has been done execute the script with the dll that shall be
installed into the WinSxS folder as argument (e.g. "PrepareFileForWinSxS.pl
test.dll"). You will then get two additional files: the manifest and the
signed cat file.

Once the script has successfully been executed the file is ready to be
installed into the WinSxS folder. Using Windows Installer XML the following
code snippet can be used to achive this (Note: WiX2.0 schema):

<Component Id="test_dll" Guid="{B4ED2BF3-F2C7-4DB4-828D-72D047928937}">
  <File Id="test.dll" LongName="test.dll" Name="TEST1.dll"
AssemblyManifest="test.dll.manifest" Assembly="win32"
        Source="..\test\test.dll" KeyPath="yes" Vital="yes" />
  <File Id="test.dll.manifest" LongName="test.dll.manifest" Name="TEST2.DLL"
        Source="..\test\test.dll.manifest" Vital="yes" />
  <File Id="test.dll.cat" LongName="test.dll.cat" Name="TEST3.DLL"
        Source="..\test\test.dll.cat" Vital="yes" />
</Component>

Note the additional attribute "AssemblyManifest" that must point to the
manifest created by the perl script and that "Assembly" is set to "win32".

Building and installing such an msi will install the file into the WinSxS
folder.

In order to use the installed file all assemblies that shall load the this
file need to be equipped with a manifest that describes what version of the
of the file (because multiple versions can be installed in WinSxS) actually
shall be loaded. The manifest looks like this:

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<assembly xmlns='urn:schemas-microsoft-com:asm.v1' manifestVersion='1.0'>
  <dependency>
    <dependentAssembly>
      <assemblyIdentity type='win32'
                        name='test'
                        version='1.0.0.0'
                        processorArchitecture='x86'
                        publicKeyToken='<same token as in the manifest of
the file installed into WinSxS>' />
    </dependentAssembly>
  </dependency>
</assembly>

For managed C++ assemblies created with Visual Studio 2005 a manifest is
already available. That manifest describes what C/C++ runtime (also
installed in WinSxS) shall be used:

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<assembly xmlns='urn:schemas-microsoft-com:asm.v1' manifestVersion='1.0'>
  <dependency>
    <dependentAssembly>
      <assemblyIdentity type='win32'
                        name='Microsoft.VC80.CRT'
                        version='8.0.50608.0'
                        processorArchitecture='x86'
                        publicKeyToken='1fc8b3b9a1e18e3b' />
    </dependentAssembly>
  </dependency>
</assembly>

It is possible to add the entry to that manifest. To do that open the
project properties and expand the linker properties. To the “Additional
Manifest Dependencies” in the “Manifest File” options add the string
type='win32' name='test' version='1.0.0.0' processorArchitecture='x86'
publicKeyToken='<same token as in the manifest of the file installed into
WinSxS>'.

Once this is done compile the project. The resulting dll will get an
embedded manifest that describes both the version of the C/C++ runtime and
the version of the test.dll.

If anything is unclear just post it here.

Regards,

ACKH

http://n2.nabble.com/file/n841475/CreateCertificate.bat
CreateCertificate.bat 
http://n2.nabble.com/file/n841475/PrepareFileForWinSxS.pl
PrepareFileForWinSxS.pl 



-- 
View this message in context: http://n2.nabble.com/Tutorial%3A-How-to-install-files-into-WinSxS-tp841475p841475.html
Sent from the wix-users mailing list archive at Nabble.com.