Quantcast

Tutorial: How to install files into WinSxS

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Tutorial: How to install files into WinSxS

ACKH
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 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

CreateCertificate.bat
PrepareFileForWinSxS.pl


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Tutorial: How to install files into WinSxS

BeantownGuy80
Hi, thanks for sharing your steps. I am having some issues with the .dll placement upon installation and I have some questions too. You didn't mention any context in which to add the top level Component tag. Does it need to go in the Wix, Product, Package, top-level Directory (with Id="TARGETDIR") tag? Does it belong somewhere else or not matter? Also, I followed the instructions as best I could, but the .dll itself does not get installed into the C:\Windows\WinSxS folder. In fact it doesn't get copied anywhere on the system. However, the catalogs and manifests DO end up in the right folder with the right naming scheme (C:\Windows\WinSxS\Manifests). Is there another step I need to complete so that the actual .dll will be placed in C:\Windows\WinSxS? I could manually copy the files to the SxS folder but 1) this is hacky, and 2) I can't necessarily predict the correct decorated filenames that SxS comes up with (something to do with the base filename, version, some hash, some OS specific stuff, etc...).

Thanks,
James

ACKH wrote
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 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

CreateCertificate.bat
PrepareFileForWinSxS.pl

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Tutorial: How to install files into WinSxS

ACKH
Hi,

The Component that installs the native assembly into the WinSxS folder can be placed anywhere below the TARGETDIR directory, it doesn't really matter.
Without seeing you code it is hard to find out what is wrong.

I think it might be helpful if I send you an example I have created. Studying that example might help you in finding out whats wrong. I can't send you a mail with attachement, or at least I don't know how via nabble. If you send me an email to my address via nabble I can reply to it and add the attachement.

Regards,

ACKH
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Tutorial: How to install files into WinSxS

Durwin Wright
I would be interested in such an attachment.

Durwin Wright | Sr. Architect | [hidden email] | Ingres | 500
Arguello Street | Suite 200 | Redwood City | CA | 94063 | USA  +1
650-587-5523 | fax: +1 650-587-5550 | "Wag the Dog"

-----Original Message-----
From: ACKH [mailto:[hidden email]]
Sent: Wednesday, June 17, 2009 9:34 AM
To: [hidden email]
Subject: Re: [WiX-users] Tutorial: How to install files into WinSxS


Hi,

The Component that installs the native assembly into the WinSxS folder
can
be placed anywhere below the TARGETDIR directory, it doesn't really
matter.
Without seeing you code it is hard to find out what is wrong.

I think it might be helpful if I send you an example I have created.
Studying that example might help you in finding out whats wrong. I can't
send you a mail with attachement, or at least I don't know how via
nabble.
If you send me an email to my address via nabble I can reply to it and
add
the attachement.

Regards,

ACKH

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


------------------------------------------------------------------------
------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
WiX-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/wix-users

------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
WiX-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/wix-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

ACKH
Alright, here it is. There is a ReadMe.txt in the root of the zip file that describes the details.^
 
Let me know if you encounter problems.
 
Regards
 
ACKH

 

Date: Wed, 17 Jun 2009 10:31:25 -0700
From: [hidden email]
To: [hidden email]
Subject: Re: [WiX-users] Tutorial: How to install files into WinSxS

I would be interested in such an attachment.

Durwin Wright | Sr. Architect | Durwin.Wright@... | Ingres | 500
Arguello Street | Suite 200 | Redwood City | CA | 94063 | USA  +1
650-587-5523 | fax: +1 650-587-5550 | "Wag the Dog"

-----Original Message-----
From: ACKH [mailto:forforumhelp@...]
Sent: Wednesday, June 17, 2009 9:34 AM
To: wix-users@...
Subject: Re: [WiX-users] Tutorial: How to install files into WinSxS


Hi,

The Component that installs the native assembly into the WinSxS folder
can
be placed anywhere below the TARGETDIR directory, it doesn't really
matter.
Without seeing you code it is hard to find out what is wrong.

I think it might be helpful if I send you an example I have created.
Studying that example might help you in finding out whats wrong. I can't
send you a mail with attachement, or at least I don't know how via
nabble.
If you send me an email to my address via nabble I can reply to it and
add
the attachement.

Regards,

ACKH

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


------------------------------------------------------------------------
------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
WiX-users mailing list
WiX-users@...
https://lists.sourceforge.net/lists/listinfo/wix-users

------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
WiX-users mailing list
WiX-users@...
https://lists.sourceforge.net/lists/listinfo/wix-users



This email is a reply to your post @ http://n2.nabble.com/Tutorial%3A-How-to-install-files-into-WinSxS-tp841475p3094248.html
You can reply by email or by visting the link above.



Windows Live™: Keep your life in sync. Check it out!

WinSxS-Test.zip (3M) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

BeantownGuy80
Actually I had exactly the same WiX code as you, except for the assembly names and filenames of course. I was using an automated build process. The compiler was generating a very empty manifest file for my SxS assemblies. This required using mt.exe with the -identity parameter to add the assembly identity. I was also using the makecdfs argument to make a .cdf file which I later turned into a catalog with makecat.exe. Then I would sign with signtool.exe, etc...

Anyway, long story short, the .manifests and .cats were getting installed into the WinSxS\Manifests folder, but the .dlls were not showing up in WinSxS under their munged directory name. Well, that's because th original generated .manifest file did not include the file element... that's right, all it needed was a simple <file name="MySxSDll.dll">. Wow! Well once I realized this, and I could not find a way to make any of the MS build tools generate this (cl.exe, link.exe, mt.exe, etc...),  I just used a simple 'sed' statement. I think it's important to do this before the mt.exe call since any changes to the manifest will invalidate signing.


ACKH wrote
Alright, here it is. There is a ReadMe.txt in the root of the zip file that describes the details.^

 

Let me know if you encounter problems.

 

Regards

 

ACKH


 


Date: Wed, 17 Jun 2009 10:31:25 -0700
From: ml-user+61091-998187462@n2.nabble.com
To: forforumhelp@hotmail.com
Subject: Re: [WiX-users] Tutorial: How to install files into WinSxS

I would be interested in such an attachment.

Durwin Wright | Sr. Architect | Durwin.Wright@... | Ingres | 500
Arguello Street | Suite 200 | Redwood City | CA | 94063 | USA  +1
650-587-5523 | fax: +1 650-587-5550 | "Wag the Dog"

-----Original Message-----
From: ACKH [mailto:forforumhelp@...]
Sent: Wednesday, June 17, 2009 9:34 AM
To: wix-users@...
Subject: Re: [WiX-users] Tutorial: How to install files into WinSxS


Hi,

The Component that installs the native assembly into the WinSxS folder
can
be placed anywhere below the TARGETDIR directory, it doesn't really
matter.
Without seeing you code it is hard to find out what is wrong.

I think it might be helpful if I send you an example I have created.
Studying that example might help you in finding out whats wrong. I can't
send you a mail with attachement, or at least I don't know how via
nabble.
If you send me an email to my address via nabble I can reply to it and
add
the attachement.

Regards,

ACKH

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


------------------------------------------------------------------------
------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
WiX-users mailing list
WiX-users@...
https://lists.sourceforge.net/lists/listinfo/wix-users

------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
WiX-users mailing list
WiX-users@...
https://lists.sourceforge.net/lists/listinfo/wix-users





This email is a reply to your post @ http://n2.nabble.com/Tutorial%3A-How-to-install-files-into-WinSxS-tp841475p3094248.html
You can reply by email or by visting the link above.


_________________________________________________________________
Windows Live™: Keep your life in sync. Check it out!
http://windowslive.com/explore?ocid=TXT_TAGLM_WL_t1_allup_explore_012009
 
MRB
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Tutorial: How to install files into WinSxS

MRB
This post has NOT been accepted by the mailing list yet.
In reply to this post by ACKH
Could I also get the zip file example that you put together.  Thanks!


ACKH wrote
Hi,

The Component that installs the native assembly into the WinSxS folder can be placed anywhere below the TARGETDIR directory, it doesn't really matter.
Without seeing you code it is hard to find out what is wrong.

I think it might be helpful if I send you an example I have created. Studying that example might help you in finding out whats wrong. I can't send you a mail with attachement, or at least I don't know how via nabble. If you send me an email to my address via nabble I can reply to it and add the attachement.

Regards,

ACKH
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

ACKH
Yes, here is the example. I currently don't have an accessible location but as soon as I get one I will put it there.
 

 

Date: Fri, 28 Aug 2009 14:56:07 -0500
From: [hidden email]
To: [hidden email]
Subject: Re: [WiX-users] Tutorial: How to install files into WinSxS

Could I also get the zip file example that you put together.  Thanks!


ACKH wrote:
Hi,

The Component that installs the native assembly into the WinSxS folder can be placed anywhere below the TARGETDIR directory, it doesn't really matter.
Without seeing you code it is hard to find out what is wrong.

I think it might be helpful if I send you an example I have created. Studying that example might help you in finding out whats wrong. I can't send you a mail with attachement, or at least I don't know how via nabble. If you send me an email to my address via nabble I can reply to it and add the attachement.

Regards,

ACKH



View message @ http://n2.nabble.com/Tutorial-How-to-install-files-into-WinSxS-tp841475p3537095.html
To unsubscribe from Re: Tutorial: How to install files into WinSxS, click here.



Share your memories online with anyone you want anyone you want.

WinSxS-Test.zip (3M) Download Attachment
Loading...