aboutsummaryrefslogtreecommitdiff
path: root/src/samples/Dtf/Documents/Guide/Content
diff options
context:
space:
mode:
authorRob Mensching <rob@firegiant.com>2021-05-11 07:36:37 -0700
committerRob Mensching <rob@firegiant.com>2021-05-11 07:36:37 -0700
commit3f583916719eeef598d10a5d4e14ef14f008243b (patch)
tree3d528e0ddb5c0550954217c97059d2f19cd6152a /src/samples/Dtf/Documents/Guide/Content
parent2e5ab696b8b4666d551b2a0532b95fb7fe6dbe03 (diff)
downloadwix-3f583916719eeef598d10a5d4e14ef14f008243b.tar.gz
wix-3f583916719eeef598d10a5d4e14ef14f008243b.tar.bz2
wix-3f583916719eeef598d10a5d4e14ef14f008243b.zip
Merge Dtf
Diffstat (limited to 'src/samples/Dtf/Documents/Guide/Content')
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/about.htm59
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/buildingcas.htm94
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/cabpack.htm63
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/cabs.htm101
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/cabwrapper.htm63
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/caconfig.htm83
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/caproxy.htm74
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/databases.htm120
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/debuggingcas.htm66
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/dependencies.htm88
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/filepatchwrapper.htm34
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/history.htm437
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/installutil.htm94
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/inventory.htm78
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/managedcas.htm53
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/msihelper.htm59
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/msiwrapper.htm80
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/packages.htm86
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/powerdiff.htm71
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/samplecas.htm84
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/samples.htm59
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/support.htm52
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/using.htm50
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/whatsnew.htm257
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/wifile.htm73
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/writingcas.htm114
26 files changed, 2492 insertions, 0 deletions
diff --git a/src/samples/Dtf/Documents/Guide/Content/about.htm b/src/samples/Dtf/Documents/Guide/Content/about.htm
new file mode 100644
index 00000000..393b5a81
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/about.htm
@@ -0,0 +1,59 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Deployment Tools Foundation Overview</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Deployment Tools Foundation</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet"><span class="nolink">Overview</span></span>
15 <span id="languageFilter">v4.0</span>
16 </div>
17 </div>
18 <div id="main">
19 <div id="header">
20 </div>
21 <div class="summary">
22 <p>Deployment Tools Foundation is a rich set of .NET class libraries and
23 related resources that together bring the Windows deployment platform
24 technologies into the .NET world. It is designed to greatly simplify
25 deployment-related development tasks while still exposing the complete
26 functionality of the underlying technology.</p>
27
28 <p>The primary focus of DTF is to provide a foundation for development of
29 various kinds of tools to support deployment throughout the product
30 lifecycle, including setup authoring, building, analysis, debugging, and
31 testing tools. In addition to tools, DTF can also be useful for install-time
32 activities such as setup bootstrappers, external UI, and custom actions,
33 and for application run-time activities that need to access the deployment
34 platform.</p>
35
36 <p>For a description of the the latest changes, see <a
37 href="whatsnew.htm">What's New</a>.</p>
38
39 </div>
40
41 <div id="footer">
42 <p />
43 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
44 wix-users@lists.sourceforge.net</a>
45
46 <script type="text/javascript">
47 var HT_mailLink = document.getElementById("HT_MailLink");
48 var HT_mailLinkText = HT_mailLink.innerHTML;
49 HT_mailLink.href += ": " + document.title;
50 HT_mailLink.innerHTML = HT_mailLinkText;
51 </script>
52
53 <p />
54
55 </div>
56 </div>
57
58</body>
59</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/buildingcas.htm b/src/samples/Dtf/Documents/Guide/Content/buildingcas.htm
new file mode 100644
index 00000000..e88ad552
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/buildingcas.htm
@@ -0,0 +1,94 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Building Managed Custom Actions</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Building Managed Custom Actions</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="managedcas.htm">Managed CAs</a> &gt;
17 <span class="nolink">Building</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25
26 <p>The build process for managed CA DLLs is a little complicated becuase of the
27 proxy-wrapper and dll-export requirements. Here's an overview:</p>
28 <ol>
29 <li>
30 <p>Compile your CA assembly, which references WixToolset.Dtf.WindowsInstaller.dll and
31 marks exported custom actions with a CustomActionAttribute.</p>
32 <li>
33 <p>Package the CA assembly, CustomAction.config, WixToolset.Dtf.WindowsInstaller.dll,
34 and any other dependencies using <b>MakeSfxCA.exe</b>. The filenames of CustomAction.config
35 and WixToolset.Dtf.WindowsInstaller.dll must not be changed, since
36 the custom action proxy specifically looks for those files.</p>
37 </ol>
38 <p><br>
39 </p>
40 <p><b>Compiling</b></p>
41 <pre><font face="Consolas, Courier New">
42 csc.exe
43 /target:library
44 /r:$(DTFbin)\WixToolset.Dtf.WindowsInstaller.dll
45 /out:SampleCAs.dll
46 *.cs
47 </font></pre>
48 <p><b>Wrapping</b><pre><font face="Consolas, Courier New">
49 MakeSfxCA.exe
50 $(OutDir)\SampleCAsPackage.dll
51 $(DTFbin)\SfxCA.dll
52 SampleCAs.dll
53 CustomAction.config
54 $(DTFbin)\WixToolset.Dtf.WindowsInstaller.dll
55 </font></pre>
56 </p>
57 <p>Now the resulting package, SampleCAsPackage.dll, is ready to be inserted
58 into the Binary table of the MSI.</p>
59 <p><br/>
60 </p>
61 <p>For a working example of building a managed custom action package
62 you can look at included sample ManagedCAs project.</p>
63 <p><br/>
64 </p>
65
66 <p><br/></p>
67 <p><b>See also:</b></p>
68 <ul>
69 <li><a href="writingcas.htm">Writing Managed Custom Actions</a></li>
70 <li><a href="caconfig.htm">Specifying the Runtime Version</a></li>
71 </ul>
72 <p><br/></p>
73
74 </div>
75
76 <div id="footer">
77 <p />
78 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
79 wix-users@lists.sourceforge.net</a>
80
81 <script type="text/javascript">
82 var HT_mailLink = document.getElementById("HT_MailLink");
83 var HT_mailLinkText = HT_mailLink.innerHTML;
84 HT_mailLink.href += ": " + document.title;
85 HT_mailLink.innerHTML = HT_mailLinkText;
86 </script>
87
88 <p />
89
90 </div>
91 </div>
92
93</body>
94</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/cabpack.htm b/src/samples/Dtf/Documents/Guide/Content/cabpack.htm
new file mode 100644
index 00000000..2d9f725e
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/cabpack.htm
@@ -0,0 +1,63 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Archive Pack/Unpack Tool</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Archive Pack/Unpack Tool</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="samples.htm">Samples</a> &gt;
17 <span class="nolink">XPack</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25 <p><pre><font face="Consolas, Courier New">Usage: CabPack.exe &lt;directory&gt; &lt;package.cab&gt;
26Usage: XPack /P &lt;archive.cab&gt; &lt;directory&gt;
27Usage: XPack /P &lt;archive.zip&gt; &lt;directory&gt;
28
29Packs all files in a directory tree into an archive,
30using either the cab or zip format. Any existing archive
31with the same name will be overwritten.
32
33
34Usage: XPack /U &lt;archive.cab&gt; &lt;directory&gt;
35Usage: XPack /U &lt;archive.zip&gt; &lt;directory&gt;
36
37Unpacks all files from a cab or zip archive to the
38specified directory. Any existing files with the same
39names will be overwritten.</font></pre>
40 </p>
41 <p><br/></p>
42
43 </div>
44
45 <div id="footer">
46 <p />
47 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
48 wix-users@lists.sourceforge.net</a>
49
50 <script type="text/javascript">
51 var HT_mailLink = document.getElementById("HT_MailLink");
52 var HT_mailLinkText = HT_mailLink.innerHTML;
53 HT_mailLink.href += ": " + document.title;
54 HT_mailLink.innerHTML = HT_mailLinkText;
55 </script>
56
57 <p />
58
59 </div>
60 </div>
61
62</body>
63</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/cabs.htm b/src/samples/Dtf/Documents/Guide/Content/cabs.htm
new file mode 100644
index 00000000..e88d1e15
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/cabs.htm
@@ -0,0 +1,101 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Working with Cabinet Files</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Working with Cabinet Files</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <span class="nolink">Cabinet Files</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24
25 <h3>Creating a cabinet</h3>
26 <pre><font face="Consolas, Courier New"> CabInfo cabInfo = <font color="blue">new</font> CabInfo(<font color="purple">"package.cab"</font>);
27 cabInfo.Pack(<font color="purple">"D:\\FilesToCompress"</font>);</font></pre><br />
28 <p>1.&nbsp; Create a <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_Compression_Cab_CabInfo__ctor_1.htm">new CabInfo</a> instance referring to the (future) location of the .cab file.</p>
29 <p>2.&nbsp; Compress files:</p><ul>
30 <li>Easily compress an entire directory with the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_Compression_ArchiveInfo_Pack.htm">Pack</a> method.</li>
31 <li>Compress a specific list of exernal and internal filenames with the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_Compression_ArchiveInfo_PackFiles.htm">PackFiles</a> method.</li>
32 <li>Compress a dictionary mapping of internal to external filenames with the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_Compression_ArchiveInfo_PackFileSet.htm">PackFileSet</a> method.</li>
33 </ul>
34
35 <p><br/></p>
36 <h3>Listing a cabinet</h3>
37 <pre><font face="Consolas, Courier New"> CabInfo cabInfo = <font color="blue">new</font> CabInfo(<font color="purple">"package.cab"</font>);
38 <font color="blue">foreach</font> (CabFileInfo fileInfo <font color="blue">in</font> cabInfo.GetFiles())
39 Console.WriteLine(fileInfo.Name + <font color="purple">"\t"</font> + fileInfo.Length);</font></pre><br />
40 <p>1.&nbsp; Create a <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_Compression_Cab_CabInfo__ctor_1.htm">new CabInfo</a> instance referring to the location of the .cab file.</p>
41 <p>2.&nbsp; Enumerate files returned by the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_Compression_Cab_CabInfo_GetFiles.htm">GetFiles</a> method.</p><ul>
42 <li>Each <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_Compression_Cab_CabFileInfo.htm">CabFileInfo</a> instance contains metadata about one file.</li>
43 </ul>
44
45 <p><br/></p>
46 <h3>Extracting a cabinet</h3>
47 <pre><font face="Consolas, Courier New"> CabInfo cabInfo = <font color="blue">new</font> CabInfo(<font color="purple">"package.cab"</font>);
48 cabInfo.Unpack(<font color="purple">"D:\\ExtractedFiles"</font>);</font></pre><br />
49 <p>1.&nbsp; Create a <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_Compression_Cab_CabInfo__ctor_1.htm">new CabInfo</a> instance referring to the location of the .cab file.</p>
50 <p>2.&nbsp; Extract files:</p><ul>
51 <li>Easily extract all files to a directory with the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_Compression_ArchiveInfo_Unpack.htm">Unpack</a> method.</li>
52 <li>Easily extract a single file with the <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_Compression_ArchiveInfo_UnpackFile.htm">UnpackFile</a> method.</li>
53 <li>Extract a specific list of filenames with the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_Compression_ArchiveInfo_UnpackFiles.htm">UnpackFiles</a> method.</li>
54 <li>Extract a dictionary mapping of internal to external filenames with the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_Compression_ArchiveInfo_UnpackFileSet.htm">UnpackFileSet</a> method.</li>
55 </ul>
56
57 <p><br/></p>
58 <h3>Getting progress</h3>
59 Most cabinet operation methods have an overload that allows you to specify a event handler
60 for receiving <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_Compression_ArchiveProgressEventArgs.htm">archive
61 progress events</a>. The <a href="cabpack.htm">XPack sample</a>
62 demonstrates use of the callback to report detailed progress to the console.
63
64 <p><br/></p>
65 <h3>Stream-based compression</h3>
66 The CabEngine class contains static methods for performing compression/decompression operations directly
67 on any kind of Stream. However these methods are more difficult to use, since the caller must implement a
68 <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_Compression_ArchiveFileStreamContext.htm">stream context</a>
69 that provides the file metadata which would otherwise have been provided by the filesystem. The CabInfo class
70 uses the CabEngine class with FileStreams to provide the more traditional file-based interface.
71
72 <p><br/></p>
73 <p><b>See also:</b></p>
74 <ul>
75 <li><a href="DTFAPI.chm::/html/T_Microsoft_Deployment_Compression_Cab_CabInfo.htm">CabInfo class</a></li>
76 <li><a href="DTFAPI.chm::/html/T_Microsoft_Deployment_Compression_Cab_CabEngine.htm">CabEngine class</a></li>
77 <li><a href="cabpack.htm">XPack Sample Tool</a></li>
78 </ul>
79 <p><br/></p>
80
81 </div>
82
83 <div id="footer">
84 <p />
85 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
86 wix-users@lists.sourceforge.net</a>
87
88 <script type="text/javascript">
89 var HT_mailLink = document.getElementById("HT_MailLink");
90 var HT_mailLinkText = HT_mailLink.innerHTML;
91 HT_mailLink.href += ": " + document.title;
92 HT_mailLink.innerHTML = HT_mailLinkText;
93 </script>
94
95 <p />
96
97 </div>
98 </div>
99
100</body>
101</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/cabwrapper.htm b/src/samples/Dtf/Documents/Guide/Content/cabwrapper.htm
new file mode 100644
index 00000000..fd88437c
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/cabwrapper.htm
@@ -0,0 +1,63 @@
1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
2<html>
3 <head>
4 <title>Managed Wrapper Library for Cabinet APIs</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
6 <link rel="stylesheet" type="text/css" href="MSDN.css">
7 </head>
8 <body id="bodyID" class="dtBODY">
9 <div id="nsbanner">
10 <div id="bannerrow1">
11 <table class="bannerparthead" cellspacing="0" id="Table1">
12 <tr id="hdr">
13 <td class="runninghead">Managed Libraries for Windows Installer</td>
14 <td class="product"></td>
15 </tr>
16 </table>
17 </div>
18 <div id="TitleRow">
19 <h1 class="dtH1">Managed Wrapper Library for Cabinet APIs</h1>
20 </div>
21 </div>
22 <div id="nstext">
23 <p>This is a managed library that provides the ability to
24 create and extract cabinet files. It uses cabinet.dll (present on all versions of Windows)
25 to do the actual compression/decompression. It provides access to nearly all
26 cabinet capabilities, including spanning of multiple cab files. It even has support for
27 preserving directory structures and UTF8 paths.</p>
28 <p>There are two ways to use the library. <a href="ms-its:MMLRef.chm::/Microsoft.Cab.CabinetInfo.html">CabinetInfo</a>
29 and <a href="ms-its:MMLRef.chm::/Microsoft.Cab.CabinetFileInfo.html">CabinetFileInfo</a>
30 (similar to DirectoryInfo and FileInfo respectively)
31 provide high-level object-oriented methods for doing common file-based cabinet creation and
32 extraction tasks. On the other hand, the <a href="ms-its:MMLRef.chm::/Microsoft.Cab.Cabinet.html">Cabinet</a>
33 class provides low-level access to all
34 functionality, and operates completely in terms of .NET Streams. The previous two classes use
35 the Cabinet class to do all the actual work.</p>
36 <p>There are also two ways to build the library.
37 Compiling it normally will produce the fully functional
38 library in the <a href="ms-its:MMLRef.chm::/Microsoft.Cab.html">Microsoft.Cab</a>
39 namespace, while compiling it with the <tt>/D:CABMINIMAL
40 /D:CABEXTRACTONLY</tt> flags will create a compact assembly with only the core extraction
41 functionality, in the <a href="ms-its:MMLRef.chm::/Microsoft.Cab.MiniExtract.html">Microsoft.Cab.MiniExtract</a>
42 namespace.</p>
43 <p>The cabinet library interops with native cabinet APIs which use the 'cdecl'
44 calling-convention. When building against .NET Framework versions before 2.0,
45 this library requires a special post-build step to process the UnmanagedFunctionPointerAttribute.
46 If you use this code in another assembly, don't forget to run <a href="augmentil.htm">AugmentIL</a>
47 on it to fix the delegate calling-conventions, otherwise you will encounter a
48 NullReferenceException when attempting to call the cabinet APIs. When building against
49 .NET Framework version 2.0 or later, the UnmanagedFunctionPointerAttribute.cs source file
50 should be omitted.</p>
51
52 <p><br/></p>
53 <p><b>See also:</b></p>
54 <ul>
55 <li><a href="cabs.htm">Working with Cabinet Files</a></li>
56 <li><a href="ms-its:MMLRef.chm::/Microsoft.Cab.CabinetInfoMethods.html">CabinetInfo Methods</a></li>
57 <li><a href="ms-its:MMLRef.chm::/Microsoft.Cab.CabinetMethods.html">Cabinet Methods</a></li>
58 <li><a href="cabpack.htm">CabPack Sample Tool</a></li>
59 </ul>
60 <p><br/></p>
61 </div>
62 </body>
63</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/caconfig.htm b/src/samples/Dtf/Documents/Guide/Content/caconfig.htm
new file mode 100644
index 00000000..a6c97d2b
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/caconfig.htm
@@ -0,0 +1,83 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Specifying the Runtime Version</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Specifying the Runtime Version</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="managedcas.htm">Managed CAs</a> &gt;
17 <a href="writingcas.htm">Writing CAs</a> &gt;
18 <span class="nolink">CustomAction.config</span>
19 </span>
20 </div>
21 </div>
22 <div id="main">
23 <div id="header">
24 </div>
25 <div class="summary">
26
27 <p>Every managed custom action package should contain a CustomAction.config file, even though it is not required by the toolset.
28 Here is a sample:</p><pre><font face="Consolas, Courier New">
29&lt;?xml version="1.0" encoding="utf-8" ?&gt;
30&lt;configuration&gt;
31 &lt;startup&gt;
32 &lt;supportedRuntime version=&quot;v2.0.50727&quot;/&gt;
33 &lt;/startup&gt;
34&lt;/configuration&gt;</font></pre><br />
35 <p>The configuration file follows the standard schema for .NET Framework
36 configuration files <a target=_blank href="http://msdn2.microsoft.com/en-us/library/9w519wzk(VS.80).aspx">documented on MSDN</a>.</p>
37 <p><br/></p>
38 <p><b>Supported Runtime Version</b></p>
39 <p>In the startup section, use <a target=_blank href="http://msdn2.microsoft.com/en-us/library/w4atty68(VS.80).aspx">supportedRuntime</a>
40 tags to explicitly specify the version(s) of the .NET Framework that the custom action should run on.
41 If no versions are specified, the chosen version of the .NET Framework will be
42 the "best" match to what WixToolset.Dtf.WindowsInstaller.dll was built against.</p>
43 <p><font color="red"><b>Warning: leaving the version unspecified is dangerous</b></font>
44 as it introduces a risk of compatibility problems with future versions of the .NET Framework.
45 It is highly recommended that you specify only the version(s)
46 of the .NET Framework that you have tested against.</p>
47 <p><br/></p>
48
49 <p><b>Other Configuration</b></p>
50 <p>Various other kinds of configuration settings may also be added to this file, as it is a standard
51 <a target=_blank href="http://msdn2.microsoft.com/en-us/library/kza1yk3a(VS.80).aspx">.NET Framework application config file</a>
52 for the custom action.</p>
53 <p><br/></p>
54
55 <p><b>See also:</b></p>
56 <ul>
57 <li><a href="writingcas.htm">Writing Managed Custom Actions</a></li>
58 <li><a href="buildingcas.htm">Building Managed Custom Actions</a></li>
59 <li><a href="caproxy.htm">Proxy for Managed Custom Actions</a></li>
60 </ul>
61 <p><br/></p>
62
63 </div>
64
65 <div id="footer">
66 <p />
67 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
68 wix-users@lists.sourceforge.net</a>
69
70 <script type="text/javascript">
71 var HT_mailLink = document.getElementById("HT_MailLink");
72 var HT_mailLinkText = HT_mailLink.innerHTML;
73 HT_mailLink.href += ": " + document.title;
74 HT_mailLink.innerHTML = HT_mailLinkText;
75 </script>
76
77 <p />
78
79 </div>
80 </div>
81
82</body>
83</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/caproxy.htm b/src/samples/Dtf/Documents/Guide/Content/caproxy.htm
new file mode 100644
index 00000000..2ee962d5
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/caproxy.htm
@@ -0,0 +1,74 @@
1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
2<html>
3 <head>
4 <title>Proxy Class for Managed Custom Actions</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
6 <link rel="stylesheet" type="text/css" href="MSDN.css">
7 </head>
8 <body id="bodyID" class="dtBODY">
9 <div id="nsbanner">
10 <div id="bannerrow1">
11 <table class="bannerparthead" cellspacing="0" id="Table1">
12 <tr id="hdr">
13 <td class="runninghead">Managed Libraries for Windows Installer</td>
14 <td class="product"></td>
15 </tr>
16 </table>
17 </div>
18 <div id="TitleRow">
19 <h1 class="dtH1">Proxy for Managed Custom Actions</h1>
20 </div>
21 </div>
22 <div id="nstext">
23 <p>The custom action proxy allows an MSI developer to write
24 custom actions in managed code, while maintaing all the advantages of type 1
25 DLL custom actions including full access to installer state, properties,
26 and the session database.</p>
27 <p>There are generally four problems that needed to be
28 solved in order to create a type 1 custom action in managed code:</p>
29 <ol>
30 <li><p><strong>Exporting the CA function as a native entry point callable by
31 MSI:</strong> The Windows Installer engine expects to call a LoadLibrary and
32 GetProcAddress on the custom action DLL, so an unmanaged DLL needs to implement
33 the function that is initially called by MSI and ultimately returns the result.
34 This function acts as a proxy to relay the custom action call into the
35 managed custom action assembly, and relay the result back to the caller. </p>
36 <li><strong>Providing supporting assemblies without
37 requiring them to be installed as files:</strong> If a DLL custom
38 action runs before the product's files are installed, then it is difficult
39 to provide any supporting files, because of the way the CA DLL is singly
40 extracted and executed from a temp file. (This can be a problem for
41 unmanaged CAs as well.) With managed custom actions we have already hit
42 that problem since both the CA assembly and the MSI wrapper assembly
43 need to be loaded. To solve this, the proxy DLL carries an appended
44 cab package. When invoked, it will extract all contents of the
45 cab package to a temporary working directory. This way the cab package can
46 carry any arbitrary dependencies the custom action may require.</li>
47 <li><p><strong>Hosting and configuring the Common Language Runtime:</strong>
48 In order to invoke a method in a managed assembly from a previously
49 unmanaged process, the CLR needs to be "hosted". This involves choosing
50 the correct version of the .NET Framework to use out of the available
51 version(s) on the system, binding that version to the current process, and
52 configuring it to load assemblies from the temporary working directory.</p>
53 <li><p><strong>Converting the integer session handle into a
54 Session object:</strong> The <a href="">Session</a> class in the managed
55 wrapper library has a constructor which takes an integer session handle as
56 its parameter. So the proxy simply instantiates this object before
57 calling the real CA function.</p>
58 </ol>
59 <p>The unmanaged CAPack module, when used in combination with the managed proxy in
60 the
61 Microsoft.WindowsInstaller assembly, accomplishes the tasks above to enable
62 fully-functional managed DLL custom actions.</p>
63 <p><br/></p>
64 <p><b>See also:</b></p>
65 <ul>
66 <li><a href="writingcas.htm">Writing Managed Custom Actions</a></li>
67 <li><a href="caconfig.htm">Writing the CustomAction.config file</a></li>
68 <li><a href="samplecas.htm">Sample C# Custom Actions</a></li>
69 <li><a href="buildingcas.htm">Building Managed Custom Actions</a></li>
70 </ul>
71 <p><br/></p>
72 </div>
73 </body>
74</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/databases.htm b/src/samples/Dtf/Documents/Guide/Content/databases.htm
new file mode 100644
index 00000000..4fe1fba9
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/databases.htm
@@ -0,0 +1,120 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Working with MSI Databases</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Working with MSI Databases</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <span class="nolink">MSI Databases</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24
25 <h3>Querying a database</h3>
26 <pre><font face="Consolas, Courier New"> <font color=blue>using</font> (Database db = <font color=blue>new</font> Database(<font color="purple">"product.msi"</font>, DatabaseOpenMode.ReadOnly))
27 {
28 <font color=blue>string</font> value = (<font color=blue>string</font>) db.ExecuteScalar(
29 <font color="purple">"SELECT `Value` FROM `Property` WHERE `Property` = '{0}'"</font>, propName);
30 }</font></pre><br />
31 <p>1.&nbsp; Create a <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_Database__ctor.htm">new Database</a>
32 instance referring to the location of the .msi or .msm file.</p>
33 <p>2.&nbsp; Execute the query:</p><ul>
34 <li>The <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_Database_ExecuteScalar.htm">ExecuteScalar</a>
35 method is a shortcut for opening a view, executing the view, and fetching a single value.</li>
36 <li>The <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_Database_ExecuteQuery.htm">ExecuteQuery</a>
37 method is a shortcut for opening a view, executing the view, and fetching all values.</li>
38 <li>Or do it all manually with <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_WindowsInstaller_Database_OpenView.htm">Database.OpenView</a>,
39 <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_View_Execute.htm">View.Execute</a>, and
40 <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_WindowsInstaller_View_Fetch.htm">View.Fetch</a>.</li>
41 </ul>
42
43 <p><br/></p>
44 <h3>Updating a binary</h3>
45 <pre><font face="Consolas, Courier New"> Database db = <font color=blue>null</font>;
46 View view = <font color=blue>null</font>;
47 Record rec = <font color=blue>null</font>;
48 <font color=blue>try</font>
49 {
50 db = <font color=blue>new</font> Database(<font color="purple">"product.msi"</font>, DatabaseOpenMode.Direct);
51 view = db.OpenView(<font color="purple">"UPDATE `Binary` SET `Data` = ? WHERE `Name` = '{0}'"</font>, binName))
52 rec = <font color=blue>new</font> Record(1);
53 rec.SetStream(1, binFile);
54 view.Execute(rec);
55 db.Commit();
56 }
57 <font color=blue>finally</font>
58 {
59 <font color=blue>if</font> (rec != <font color=blue>null</font>) rec.Close();
60 <font color=blue>if</font> (view != <font color=blue>null</font>) view.Close();
61 <font color=blue>if</font> (db != <font color=blue>null</font>) db.Close();
62 }</font></pre><br />
63 <p>1.&nbsp; Create a <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_Database__ctor.htm">new Database</a>
64 instance referring to the location of the .msi or .msm file.</p>
65 <p>2.&nbsp; Open a view by calling one of the <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_WindowsInstaller_Database_OpenView.htm">Database.OpenView</a> overloads.</p><ul>
66 <li>Parameters can be substituted in the SQL string using the String.Format syntax.</li>
67 </ul>
68 <p>3.&nbsp; Create a record with one field containing the new binary value.</p>
69 <p>4.&nbsp; Execute the view by calling one of the <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_View_Execute.htm">View.Execute</a> overloads.</p><ul>
70 <li>A record can be supplied for substitution of field tokens (?) in the query.</li>
71 </ul>
72 <p>5.&nbsp; <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_WindowsInstaller_Database_Commit.htm">Commit</a> the Database.</p>
73 <p>6.&nbsp; <a href="DTFAPI.chm::/html/M_Microsoft_Deployment_WindowsInstaller_InstallerHandle_Close.htm">Close</a> the handles.</p>
74
75 <p><br/></p>
76 <h3>About handles</h3>
77 <p>Handle objects (Database, View, Record, SummaryInfo, Session) will remain open until
78 they are explicitly closed or until the objects are collected by the GC. So for the tightest
79 code, handle objects should be explicitly closed when they are no longer needed,
80 since closing them can release significant resources, and too many unnecessary
81 open handles can degrade performance. This is especially important within a loop
82 construct: for example when iterating over all the Records in a table, it is much cleaner
83 and faster to close each Record after it is used.</p>
84 <p>The handle classes in the managed library all extend the
85 <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_InstallerHandle.htm">InstallerHandle</a>
86 class, which implements the IDisposable interface. This makes them easily managed with C#'s
87 using statement. Alternatively, they can be closed in a finally block.</p>
88 <p>As a general rule, <i>methods</i> in the library return new handle objects that should be managed
89 and closed by the calling code, while <i>properties</i> only return a reference to a prexisting handle
90 object.</p>
91
92 <p><br/></p>
93 <p><b>See also:</b></p>
94 <ul>
95 <li><a href="powerdiff.htm">MSI Diff Sample Tool</a></li>
96 <li><a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Database.htm">Database Class</a></li>
97 </ul>
98 <p><br/></p>
99
100 </div>
101
102 <div id="footer">
103 <p />
104 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
105 wix-users@lists.sourceforge.net</a>
106
107 <script type="text/javascript">
108 var HT_mailLink = document.getElementById("HT_MailLink");
109 var HT_mailLinkText = HT_mailLink.innerHTML;
110 HT_mailLink.href += ": " + document.title;
111 HT_mailLink.innerHTML = HT_mailLinkText;
112 </script>
113
114 <p />
115
116 </div>
117 </div>
118
119</body>
120</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/debuggingcas.htm b/src/samples/Dtf/Documents/Guide/Content/debuggingcas.htm
new file mode 100644
index 00000000..ca1be161
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/debuggingcas.htm
@@ -0,0 +1,66 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Debugging Managed Custom Actions</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Debugging Managed Custom Actions</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="managedcas.htm">Managed CAs</a> &gt;
17 <span class="nolink">Debugging</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25 <p>There are two ways to attach a debugger to a managed custom action.</p>
26 <p><b>Attach to message-box:</b> Add some temporary code to your custom action to display a
27 message box. Then when the message box pops up at install time, you can attch your
28 debugger to that process (usually identifiable by the title of the message box).
29 Once attached, you can ensure that symbols are loaded if necessary (they will be automatically
30 loaded if PDB files were embedded in the CA assembly at build time), then set breakpoints
31 anywhere in the custom action code.</p>
32 <p><b>MMsiBreak environment variable:</b> When debugging <i>managed</i> custom actions,
33 you should use the MMsiBreak environment variable instead of MsiBreak. Set the MMsiBreak
34 variable to the custom action entrypoint name. (Remember this might be different from
35 the method name if it was overridden by the CustomActionAttribute.) When the CA proxy
36 finds a matching name, the CLR JIT-debugging dialog
37 will appear with text similar to "An exception 'Launch for user' has occurred
38 in <i>YourCustomActionName</i>." The debug break occurs after the custom
39 action assembly has been loaded, but just before custom action method is invoked.
40 Once attached, you can ensure that symbols are loaded if necessary,
41 then set breakpoints anywhere in the custom action code. Note: the MMsiBreak
42 environment variable can also accept a comma-separated list of action names, any of
43 which will cause a break when hit.</p>
44 <p><br/></p>
45
46 </div>
47
48 <div id="footer">
49 <p />
50 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
51 wix-users@lists.sourceforge.net</a>
52
53 <script type="text/javascript">
54 var HT_mailLink = document.getElementById("HT_MailLink");
55 var HT_mailLinkText = HT_mailLink.innerHTML;
56 HT_mailLink.href += ": " + document.title;
57 HT_mailLink.innerHTML = HT_mailLinkText;
58 </script>
59
60 <p />
61
62 </div>
63 </div>
64
65</body>
66</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/dependencies.htm b/src/samples/Dtf/Documents/Guide/Content/dependencies.htm
new file mode 100644
index 00000000..cfec5880
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/dependencies.htm
@@ -0,0 +1,88 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Dependencies</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Dependencies</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="about.htm">Overview</a> &gt;
16 <span class="nolink">Dependencies</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24
25 <p>This page lists all the components that the DTF project depends on, at build time and at run-time.</p>
26
27 <h3>Build-time Dependencies</h3>
28 <ul>
29 <li><p><b>Visual Studio / .NET Framework</b> - Most of DTF can be built with Visual Studio 2005 &
30 .NET Framework 2.0. However, the LINQ project requires VS 2008 & .NET Framework 3.5.</p></li>
31
32 <li><p><b>Sandcastle</b> - .NET documentation build engine from Microsoft, used to process all the XML doc-comments
33 in DTF libraries into DTFAPI.chm.
34 <a href="http://www.codeplex.com/Sandcastle/" target="_blank">(official site)</a></p></li>
35
36 <li><p><b>Sandcastle Builder</b> - Sandcastle by itself is complex and difficult to use; this free tool
37 from Codeplex provides an easy-to-use project system around it to automate the documentation build process.
38 <a href="http://www.codeplex.com/SHFB/" target="_blank">(project link)</a></p></li>
39
40 <li><p><b>HTML Help Workshop</b> - Tools for building HTML Help 1.x (CHM files). Used to build DTF.chm.
41 <a href="http://msdn2.microsoft.com/en-us/library/ms669985.aspx" target="_blank">(download link)</a></p></li>
42 </ul>
43
44 <h3>Run-time Dependencies</h3>
45 <ul>
46 <li><p><b>.NET Framework</b> - Most of DTF requires .NET Framework 2.0. (.NET 1.1 is no longer supported.)
47 The only exception is the LINQ assembly which requires .NET Framework 3.5.</p></li>
48
49 <li><p><b>Windows Installer</b> - Windows Installer introduced new APIs and capabilities with each successive
50 version. Obviously, the corresponding functionality in the managed APIs is only available when the required
51 version of the Windows Instaler (msi.dll) is installed on the system. Use the Installer.Version property
52 to easily check the currently installed MSI version. Attempting to use an API not supported by the current
53 version will result in an EntryPointNotFoundException. To check what version is required for a particular API,
54 see the documentation link to the corresponding unmanaged API in MSI.chm.</p>
55 <p>In some instances when a newer version of MSI provides an "Ex" alternative to a function, only the "Ex"
56 function is used by the managed library. This may hide some functionality that would have otherwise been
57 available on a system with an older version of MSI.</p></li>
58
59 <li><p><b>cabinet.dll</b> - The DTF cabinet compression library uses cabinet.dll to implement the
60 low-level cabinet compression and decompression. This DLL is part of all versions of Windows,
61 located in the system directory.</p></li>
62
63 <li><p><b>System.IO.Compression.DeflateStream</b> - The DTF zip compression library uses this class
64 to implement the low-level zip compression and decompression. This class is part of .NET Framework
65 2.0 and later.</p></li>
66 </ul>
67
68 </div>
69
70 <div id="footer">
71 <p />
72 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
73 wix-users@lists.sourceforge.net</a>
74
75 <script type="text/javascript">
76 var HT_mailLink = document.getElementById("HT_MailLink");
77 var HT_mailLinkText = HT_mailLink.innerHTML;
78 HT_mailLink.href += ": " + document.title;
79 HT_mailLink.innerHTML = HT_mailLinkText;
80 </script>
81
82 <p />
83
84 </div>
85 </div>
86
87</body>
88</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/filepatchwrapper.htm b/src/samples/Dtf/Documents/Guide/Content/filepatchwrapper.htm
new file mode 100644
index 00000000..6bab69b5
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/filepatchwrapper.htm
@@ -0,0 +1,34 @@
1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
2<html>
3 <head>
4 <title>Managed Wrapper for Binary File Patch APIs</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
6 <link rel="stylesheet" type="text/css" href="MSDN.css">
7 </head>
8 <body id="bodyID" class="dtBODY">
9 <div id="nsbanner">
10 <div id="bannerrow1">
11 <table class="bannerparthead" cellspacing="0" id="Table1">
12 <tr id="hdr">
13 <td class="runninghead">Managed Libraries for Windows Installer</td>
14 <td class="product"></td>
15 </tr>
16 </table>
17 </div>
18 <div id="TitleRow">
19 <h1 class="dtH1">Managed Wrapper for Binary File Patch APIs</h1>
20 </div>
21 </div>
22 <div id="nstext">
23 <p>The binary file patch creation and application APIs (supplied by MsPatchC.dll and
24 MsPatchA.dll) are wrapped in the Microsoft.WindowsInstaller.FilePatch.dll assembly.</p>
25
26 <p><br/></p>
27 <p><b>See also:</b></p>
28 <ul>
29 <li><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.FilePatch.html">FilePatch Class</a></li>
30 </ul>
31 <p><br/></p>
32 </div>
33 </body>
34</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/history.htm b/src/samples/Dtf/Documents/Guide/Content/history.htm
new file mode 100644
index 00000000..704ce875
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/history.htm
@@ -0,0 +1,437 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Change History</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Change History</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="about.htm">Overview</a> &gt;
16 <span class="nolink">Change History</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24
25<h3><b>2007-07-03</b></h3>
26<i>See <a href="whatsnew.htm">What's New?</a></i><br />&nbsp;<br />&nbsp;<br />
27<hr size="2"/>
28<h3><b>2005-03-30</b></h3>
29
30<ul>
31<li>New custom action proxy<ul>
32 <li><b>Managed custom actions use an XML config file to specify the CLR version.</b></li>
33 <li>New CAPack module is an unmanaged self-extracting CA DLL that can wrap both
34 managed and unmanaged custom actions. (The old managed CAProxy module is obsolete.)</li>
35 <li>Custom action build process is different but still complicated --
36 see documentation for details.</li>
37 <li>CustomActionAttribute no longer accepts the optional NativeDependencies
38 parameter since it does not apply to the new proxy (all packaged files
39 are always extracted and available when the CA executes). </li>
40</ul></li>
41
42<li>64bit support<ul>
43 <li>Various code fixes to pointer/handle types and structure alignments.</li>
44 <li>Cabinet and MSI libraries tested on AMD64 CLR.</li>
45 <li>Unmanaged and managed parts of custom action proxy tested on AMD64.</li>
46</ul></li>
47
48<li>MSI 3.1 APIs added:<ul>
49 <li>Installer.SetExternalUI(ExternalUIRecordHandler)</li>
50 <li>Installer.NotifySidChange</li>
51</ul></li>
52
53<li>Code builds easier with .NET Famework 2.0<ul>
54 <li>AugmentIL post-build step is no longer necessary when compiling the cabinet code
55 against .NET Framework 2.0, which has builtin support for cdecl delegates.</li>
56 <li>All C# code compiles against .NET Framework 2.0 without obsolete warnings,
57 when setting the NETFX2 preprocessor define.</li>
58 <li>Same code is still compatible with .NET Framework 1.0 + AugmentIL.</li>
59</ul></li>
60
61<li>Miscellaneous bugfixes/changes:<ul>
62 <li>InstallPackage.ExtractFiles could fail in some cominations of
63 compressed/uncompressed files - fixed.</li>
64 <li>Installer.DeterminePatchSequence was broken due to an incorrect interop struct - fixed.</li>
65 <li>CabinetInfo and CabinetFileInfo classes made serializable.</li>
66 <li>Added Session.FormatString method to simplify formatting a string with
67 property substitutions.</li>
68</ul></li>
69<li>Documentation updates:<ul>
70 <li>Updated all documentation for new CA proxy.</li>
71 <li>Added new topic discussing InstallUtil.</li>
72</ul></li>
73</ul>
74
75<hr size="2"/>
76<h3><b>2004-04-13</b></h3>
77
78<ul>
79<li>Documentation<ul>
80 <li>Consolidated all documentation into a single CHM file.</li>
81 <li>Added new topics about working with MSI databases & cabinet files,
82 to help new users get oriented more easily.</li>
83</ul></li>
84
85<li>WindowsInstaller<ul>
86 <li>Removed [Beta] tags from MSI 3.0 APIs, but otherwise there
87 have been no changes since 3.0 Beta 1.<ul>
88 <li>Be warned these are still the least-tested parts of
89 the library, so early users may encounter bugs.</li>
90 </ul></li>
91</ul></li>
92
93<li>InstallPackage<ul>
94 <li>Fixed InstallPackage.ExtractFiles() bug when directory doesn't exist.</li>
95 <li>Added ability to handle uncompressed files in a package marked as compressed.</li>
96</ul></li>
97
98<li>Cabinet<ul>
99 <li>Fixed improper handling of file attributes.<ul>
100 <li>This bug caused some packages to not be extractable by other tools.</li>
101 </ul></li>
102 <li>Added support for UTF filenames.<ul>
103 <li>Non-ASCII filenames will automatically be stored as UTF-8.
104 (But note most other tools don't know how to extract them.)</li>
105 </ul></li>
106</ul></li>
107</ul>
108
109<hr size="2"/>
110<h3><b>2003-10-13</b></h3>
111
112<ul>
113<li>Cab<ul>
114 <li>Fixed a bug introduced in v2.4.0 that caused files to be left in the %TEMP%
115 directory after creating a cab.</li>
116 <li>Unsealed the CabinetInfo, CabinetFileInfo, CabinetStatus classes and made a few methods
117 protected and virtual.</li>
118</ul></li>
119
120<li>AugmentIL<ul>
121 <li>Fixed a bug that sometimes caused a crash when specifying a relative output path
122 on the command-line.</li>
123 <li>Fixed a bug that sometimes caused the Win32 version to be missing from the output file.</li>
124</ul></li>
125
126<li>Samples\Diff: added new sample tool<ul>
127 <li>Recursively diffs directories, MSIs, MSPs, CABs, other files.</li>
128</ul></li>
129</ul>
130
131<hr size="2"/>
132<h3><b>2003-09-23</b></h3>
133
134<ul>
135<li>Cab<ul>
136 <li>Fixed a bug that caused compressing very large files/file sets to use way too
137 much memory. Performance on large inputs is now within a few % of native cab tools
138 (sometimes even a little faster!) for the same compression level.</li>
139</ul></li>
140
141<li>WindowsInstaller<ul>
142 <li>All the new MSI 3.0 beta APIs are wrapped, resulting in the following additions:<ul>
143 <li>New classes - Product, Patch (for accessing sourcelist and other config)</li>
144 <li>New methods on Install class - GetProducts, GetPatches, RemovePatches,
145 ApplyMultiplePatches, DetermineApplicablePatches, ExtractPatchXmlData</li>
146 <li>New enumerations - InstallContext, PatchStates, SourceType</li>
147 <li>Additional InstallProperty values</li>
148 </ul></li>
149 <li>Note, MSI 3.0 support should be considered preliminary for now,
150 as APIs (both native and managed) are subject to change.</li>
151 <li>For MSI 2.0 compatibility, developers should not use any classes or
152 methods that are marked as [MSI 3.0 beta] in the documentation.</li>
153 <li>And unrelated to 3.0, a few additional enums have been added:
154 DialogAttributes, ControlAttributes, CustomActionTypes,
155 IniFileAction, RegistryRoot, RemoveFileInstallMode,
156 ServiceControlEvents, ServiceInstallFlags, TextStyles,
157 UpgradeAttributes, LocatorType</li>
158 <li>Also made a few minor non-breaking changes to keep the library FxCop-clean.</li>
159</ul></li>
160
161<li>AugmentIL<ul>
162 <li>Added support for strongname signing and delay-signing. AugmentIL tries to
163 locate the keyfile using the AssemblyKeyFileAttribute, or you may specify the
164 path with the new /key option.</li>
165 <li>All &quot;released&quot; assemblies will now be strongname-signed
166 (with an unofficial key).</li>
167</ul></li>
168
169<li>CAProxy<ul>
170 <li>Added support for NativeDependencies property on CustomActionAttribute. This enables
171 custom actions to P/Invoke into native DLLs that are carried with them.</li>
172</ul></li>
173
174<li>Samples\SampleCAs<ul>
175 <li>In SampleCA2, changed MessageBox.Show(&quot;&quot;) to session.Message(User,&quot;&quot;),
176 because generally it is a bad practice for CAs to show independent UI.</li>
177 <li>Added test of CustomActionAttribute.NativeDependencies functionality.</li>
178</ul></li>
179
180<li>Samples\CabPack: added new sample<ul>
181 <li>Demonstrates &amp; tests the cab library by creating self-extracting packages</li>
182</ul></li>
183
184<li>Samples\Inventory: added new sample<ul>
185 <li>Shows a hierarchical, relational, searchable view of all of the product,
186 feature, component, file, and patch data managed by MSI, for all products
187 installed on the system.</li>
188</ul></li>
189</ul>
190
191<hr size="2"/>
192<h3><b>2003-09-12</b></h3>
193
194<ul>
195<li>Cab:<ul>
196 <li>Added CabinetInfo.CompressDirectory method, capable of compressing an
197 entire directory tree structure.</li>
198 <li>Updated documentation of various methods concerning support of directory
199 structure inside cabs.</li>
200 <li>CabinetInfo case-sensitivity was inconsistent -
201 now it is case-insensitive by default, though case is still preserved</li>
202 <li>Separated assembly attributes into assembly.cs</li>
203</ul></li>
204<li>Msi:<ul>
205 <li>InstallerException and subclasses automatically get extended error data
206 from MSI's last-error-record when available. The data is stored
207 in the exception and made available through the GetErrorRecord()
208 method, and the exception's Message includes the formatted error
209 message and data. This makes most exceptions extremely informative!</li>
210 <li>Added View.GetValidationErrors() method, and supporting ValidationErrorInfo
211 struct and ValidationError enum. This wrapper for the MsiViewGetError
212 API had been accidentally left out.</li>
213 <li>Session.Message() now supports message-box flags to specify buttons &amp; icon</li>
214 <li>Added doc remarks to various methods about closing handles.</li>
215 <li>Separated assembly attributes into assembly.cs</li>
216</ul></li>
217<li>AugmentIL:<ul>
218 <li>Recent builds of ildasm v2.0.* have a slightly different output format,
219 which could break AugmentIL in some cases - fixed</li>
220</ul></li>
221<li>SampleCAs:<ul>
222 <li>Removed 'using' clause from SampleCA1 -- there's no need to close the session's active database handle</li>
223</ul></li>
224<li>Documentation:<ul>
225 <li>Added note to ReadMe about compiling the cab source into another assembly</li>
226</ul></li>
227</ul>
228
229<hr size="2"/>
230<h3><b>2003-08-07</b></h3>
231
232<ul>
233<li>Cab:<ul>
234 <li>CabinetInfo.IsValid() usually returned false even for valid cabs - fixed</li>
235 <li>Extracting cab files with null timestamps generated exception - fixed</li>
236</ul></li>
237<li>Msi:<ul>
238 <li>Added InstallCanceledException, subclass of InstallerException;
239 Methods which may be canceled by the user can throw this exception</li>
240 <li>Added MessageResult enumeration;
241 Used by Session.Message() and ExternalUIHandler delegate</li>
242 <li>Installer.EnableLog() now supports extended attributes correctly:
243 Append mode and flush-every-line</li>
244 <li>Added Session.DoActionSequence() -
245 This wrapper for the MsiSequence API had been accidentally left out</li>
246</ul></li>
247<li>CAProxy:<ul>
248 <li>Catches InstallCanceledException, returns ERROR_INSTALL_USEREXIT
249 so CA developer doesn't necessarily have to handle the exception</li>
250</ul></li>
251<li>Msi\Package:<ul>
252 <li>Added TransformInfo class: metadata about an individual patch transform</li>
253 <li>Added PatchPackage.GetTransform*() methods which return TransformInfo</li>
254</ul></li>
255<li>Documentation:<ul>
256 <li>Added section to ReadMe.htm about building managed custom actions</li>
257</ul></li>
258</ul>
259
260<hr size="2"/>
261<h3><b>2003-06-02</b></h3>
262
263<ul>
264<li>Msi:<ul>
265 <li>Validation didn't work on merge modules - fixed</li>
266</ul></li>
267<li>CAProxy:<ul>
268 <li>Was broken in 2.1 - fixed</li>
269</ul></li>
270</ul>
271
272<hr size="2"/>
273<h3><b>2003-05-14</b></h3>
274
275<ul>
276<li>Msi:<ul>
277 <li>External UI handler didn't survive a garbage collection - fixed</li>
278 <li>Validation engine was completely broken - now it should work
279 at least for MSIs which are already mostly valid</li>
280 <li>Added DynamicLoad property to CustomActionAttribute<br />
281 Usage: set DynamicLoad=false when using XmlSerialization; default is true</li>
282</ul></li>
283<li>Msi\Package:<ul>
284 <li>File extraction and update methods didn't work on merge modules - fixed</li>
285 <li>Made file update code slightly more robust</li>
286 <li>Removed hard-reference to the FilePatch assembly - now it is only
287 loaded if working with binary file patches</li>
288</ul></li>
289<li>AugmentIL:<ul>
290 <li>AugmentIL would crash if some input files had read-only attr - fixed</li>
291 <li>Made /verbose switch slightly more verbose</li>
292</ul></li>
293<li>CAProxy:<ul>
294 <li>Added support for the DynamicLoad property of CustomActionAttribute</li>
295 <li>Added MMsiBreak debugging functionality - see doc</li>
296</ul></li>
297<li>Samples\WiFile:<ul>
298 <li>Added /l (list files) switch</li>
299</ul></li>
300<li>Samples\SampleCAs:<ul>
301 <li>In the makefile the comments about debug builds had an error;
302 Now the sample builds debug packages (correctly) by default.</li>
303</ul></li>
304<li>Documentation:<ul>
305 <li>Wrote AugmentIL.htm describing the AugmentIL tool and its options.</li>
306 <li>Wrote WiFile.htm describing the WiFile sample tool.</li>
307 <li>Added section to ReadMe.htm about debugging managed custom actions.</li>
308</ul></li>
309</ul>
310
311<hr size="2"/>
312<h3><b>2003-03-31</b></h3>
313
314<ul>
315<li>Msi: Implemented the remaining APIs, also minor improvements and bugfixes<ul>
316 <li>All published APIs are wrapped, with the exception of four:
317 MsiGetFileSignatureInformation (because I don't know of a .NET analog
318 for the returned certificate structure), and 3 APIs for previewing UI</li>
319 <li>Database.OpenView and Database.Execute* now take String.Format style params</li>
320 <li>Database.ApplyTransform can optionally use the error-suppression flags
321 stored in the transform summary info</li>
322 <li>Added a few supporting enumerations and structures for the remaining APIs</li>
323 <li>InstallerException gets a descriptive message for any MSI or system error</li>
324 <li>Fixed a bug in InstallerException which would usually report &quot;error 0&quot;</li>
325 <li>Added optimization for setting a Record field to a MemoryStream</li>
326 <li>Record.GetStream is capable of extracting substorages</li>
327 <li>Moved InstallPath class to Microsoft.WindowsInstaller.Package assembly</li>
328</ul></li>
329<li>Msi\FilePatch: added new project<ul>
330 <li>Binary file patch API wrapper</li>
331</ul></li>
332<li>Msi\Package: added new project<ul>
333 <li>Helper classes for working with MSI and MSP packages</li>
334</ul></li>
335<li>Cab: some minor bugfixes<ul>
336 <li>Cabinet.Extract(stream, name) threw a NullReferenceException if the file
337 didn't exist in the cab -- now it returns null</li>
338 <li>CabinetInfo.CompressFileSet() was broken -- fixed</li>
339 <li>If a Cabinet callback throws an exception, it is propogated as the
340 inner-exception of the CabinetException</li>
341</ul></li>
342<li>Samples\WiFile: added new sample<ul>
343 <li>Demonstrates some features of InstallPackage class in Msi\Package project</li>
344</ul></li>
345</ul>
346
347<hr size="2"/>
348<h3><b>2003-03-20</b></h3>
349
350Documentation!<ul>
351 <li>Msi and Cab sources include complete C# XML documentation.</li>
352 <li>Msi and Cab makefiles generate XML documentation files.</li>
353 <li>Reference CHM compiled from XML documentation with NDoc.</li>
354</ul>
355
356<p>I am aware that exceptions are still not documented in most areas.
357 Other than that, feel free to send me a note if it's still not clear
358 how to use parts of the API after reading the documentation.</p>
359
360<p>Version is still 1.1 because there are no code changes in this release.</p>
361
362<hr size="2"/>
363<h3><b>2003-03-13</b></h3>
364
365<ul>
366<li>Msi: lots of small improvements for usability and consistency<ul>
367 <li>Reworked ExternalUIHandler support</li>
368 <li>Added Installer properties/methods:<ul>
369 <li>Components</li>
370 <li>ComponentClients()</li>
371 <li>ComponentState()</li>
372 <li>ComponentPath()</li>
373 <li>EnableLog()</li>
374 </ul></li>
375 <li>Added Session.EvaluateCondition() method</li>
376 <li>Improved exception-handling in many methods in Installer, Database,
377 &amp; Session classes</li>
378 <li>Added extensive XML doc-comments to Installer, Database, View,
379 &amp; Session classes</li>
380 <li>A few breaking changes:<ul>
381 <li>View.ModifyMode enumeration moved outside View and
382 renamed ViewModifyMode</li>
383 <li>InstallLogMode enumeration renamed to InstallLogModes
384 (naming convention for bitfields)</li>
385 <li>Record constructor takes arbitrary number of parameters</li>
386 </ul></li>
387</ul></li>
388<li>AugmentIL: almost completely rewritten<ul>
389 <li>Ildasm/ilasm steps are built-in<ul>
390 <li>The round-trip can be done in one step</li>
391 <li>IL source input/output is still supported</li>
392 </ul></li>
393 <li>Never throws an unhandled exception</li>
394 <li>Organized command-line options, consistent with other .NET tools</li>
395 <li>Uses a plugin architecture to allow additional augmentations</li>
396</ul></li>
397<li>CAProxy: Added AIL_CAProxy.cs - AugmentIL plugin generates CA proxy methods</li>
398
399<li>SampleCAs: Updated makefile for new AugmentIL usage</li>
400</ul>
401
402<hr size="2"/>
403<h3><b>2003-01-16</b></h3>
404
405<ul>
406<li>ReadMe.htm: Added section on writing managed CAs</li>
407<li>SampleCAs: Added missing reference to System.Windows.Forms.dll to the makefile</li>
408<li>AugmentIL: Added specific warning messages for when CA method has wrong signature</li>
409<li>Put sources in Toolbox-hosted Source Depot.</li>
410</ul>
411
412<hr size="2"/>
413<h3><b>2003-01-14</b></h3>
414Initial posting to http://toolbox
415
416<p>&nbsp;</p>
417 </div>
418
419 <div id="footer">
420 <p />
421 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
422 wix-users@lists.sourceforge.net</a>
423
424 <script type="text/javascript">
425 var HT_mailLink = document.getElementById("HT_MailLink");
426 var HT_mailLinkText = HT_mailLink.innerHTML;
427 HT_mailLink.href += ": " + document.title;
428 HT_mailLink.innerHTML = HT_mailLinkText;
429 </script>
430
431 <p />
432
433 </div>
434 </div>
435
436</body>
437</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/installutil.htm b/src/samples/Dtf/Documents/Guide/Content/installutil.htm
new file mode 100644
index 00000000..e235a7b6
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/installutil.htm
@@ -0,0 +1,94 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>About InstallUtil</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">About InstallUtil</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="managedcas.htm">Managed CAs</a> &gt;
17 <span class="nolink">InstallUtil</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25 <p>
26 InstallUtil is often considered as another option for executing MSI custom actions
27 written in managed code. But in most cases it is not the best solution, for a number
28 of reasons.</p>
29 <p>
30 InstallUtil (in either InstallUtil.exe or InstallUtilLib.dll form) is a .NET Framework
31 tool for executing the System.Configuration.Installer classes that are implemented
32 in an assembly. That way the assembly can contain any special code required to install
33 itself and uninstall itself. Essentially it is the .NET replacement for COM self-registration
34 aka DllRegisterServer.</p>
35 <p>
36 Self-reg or System.Configuration.Installer is convenient for development use in
37 order to test code without creating an actual setup package, or for an IDE which
38 wants to generate self-installing code. But experienced setup developers and the
39 <a href="MSI.chm::/setup/selfreg_table.htm">Windows Installer documentation</a>
40 all agree that self-reg is a bad practice for a
41 production-quality setup. The current theory of state-of-the-art setup is that it
42 should be as data-driven as possible. That is, the setup package describes as fully
43 as possible the desired state of the system, and then the installer engine calculates
44 the necessary actions to install, uninstall, patch, etc.</p>
45 <p>
46 S.C.I encourages developers to write code for things such as registering services
47 or registering COM classes or other things which are more appropriately done using
48 built-in MSI functionality (the ServiceInstall and Registry tables). The Visual
49 Studio .NET wizards also tend to generate this kind of install code. Again, that
50 is nice for development but not good for real installations. You end up with similar
51 but slightly different code in many places for doing the same thing. And that code
52 is a black-box to the installer engine.</p>
53 <p>
54 An ideal MSI custom action is a logical extension of the setup engine, meaning it
55 is data-driven and written in a very generic way to read from existing or custom
56 tables in the MSI database, following a very similar pattern to the built-in actions.
57 This makes the CA re-usable, and makes the installation more transparent. S.C.I
58 custom actions invoked by InstallUtil cannot be data-driven because they don't have
59 full access to the install session or database. They also cannot write to the install
60 session's regular MSI log, but instead use a separate log which is bad for supportability.</p>
61 <p>
62 InstallUtil also requires that the assembly be installed before the CA is able to
63 execute. This is a problem for CAs that need to execute during the UI phase, or
64 gather information before installation. For that purpose MSI allows custom action
65 binaries to be embedded as non-installed files, but InstallUtil cannot make use
66 of those.</p>
67 <p>
68 Custom actions developed with DTF have none of the limitations of InstallUtil,
69 giving a setup developer full capabilities to write well-designed custom actions,
70 only now in managed code.
71 </p>
72
73 <p>&nbsp;</p>
74 </div>
75
76 <div id="footer">
77 <p />
78 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
79 wix-users@lists.sourceforge.net</a>
80
81 <script type="text/javascript">
82 var HT_mailLink = document.getElementById("HT_MailLink");
83 var HT_mailLinkText = HT_mailLink.innerHTML;
84 HT_mailLink.href += ": " + document.title;
85 HT_mailLink.innerHTML = HT_mailLinkText;
86 </script>
87
88 <p />
89
90 </div>
91 </div>
92
93</body>
94</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/inventory.htm b/src/samples/Dtf/Documents/Guide/Content/inventory.htm
new file mode 100644
index 00000000..40a6ef74
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/inventory.htm
@@ -0,0 +1,78 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Windows Installer System Inventory Viewer</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Windows Installer System Inventory Viewer</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="samples.htm">Samples</a> &gt;
17 <span class="nolink">Inventory</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25 <p>This application shows a hierarchical, relational, searchable
26 view of all of the product, feature, component, file, and patch
27 data managed by MSI, for all products installed on the system.</p>
28 <p><br/></p>
29
30 <h4>Navigation</h4>
31 <ol>
32 <li><p>The tree on the left is self-explanatory.</p></li>
33 <li><p>Click on a row-header (grey box on the left side of the
34 grid) to jump to a table with more details about the item referred
35 to by that row. For example, clicking on a row-header of a
36 table that lists components will take you to a table that lists
37 the files in that component. Not every table has this ability,
38 but the cursor will turn to a hand shape to indicate when this is
39 possible.</p></li>
40 <li><p>Also you can navigate back and forward through your history
41 using the buttons in the application or mouse buttons 4 and 5.</p></li>
42 </ol>
43 <p><br/></p>
44
45 <h4>Searching</h4>
46 <p>The search feature is not hard to find. By default, searches
47 are limited to the current table. However, if you choose to find
48 &quot;In Subtree&quot; by checking the box, the search will include
49 the current table as well as all tables under the current location in
50 the tree. While this can take a long time if there is a lot of
51 data under the current node, you can stop the search at any time with
52 the stop button. The search pauses when a match is found, but
53 clicking &quot;Find&quot; again will continue the same search from that
54 point (unless you uncheck the &quot;Continue&quot; checkbox or change
55 the search string).</p>
56
57 <p><br/></p>
58 </div>
59
60 <div id="footer">
61 <p />
62 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
63 wix-users@lists.sourceforge.net</a>
64
65 <script type="text/javascript">
66 var HT_mailLink = document.getElementById("HT_MailLink");
67 var HT_mailLinkText = HT_mailLink.innerHTML;
68 HT_mailLink.href += ": " + document.title;
69 HT_mailLink.innerHTML = HT_mailLinkText;
70 </script>
71
72 <p />
73
74 </div>
75 </div>
76
77</body>
78</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/managedcas.htm b/src/samples/Dtf/Documents/Guide/Content/managedcas.htm
new file mode 100644
index 00000000..9cce0432
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/managedcas.htm
@@ -0,0 +1,53 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Managed Custom Actions</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Managed Custom Actions</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <span class="nolink">Managed CAs</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24
25 <ul>
26 <li><a href="writingcas.htm">Writing Managed Custom Actions</a></li>
27 <li><a href="caconfig.htm">Specifying the Runtime Version</a></li>
28 <li><a href="buildingcas.htm">Building Managed Custom Actions</a></li>
29 <li><a href="debuggingcas.htm">Debugging Managed Custom Actions</a></li>
30 <li><a href="installutil.htm">About InstallUtil</a></li>
31 </ul>
32
33 </div>
34
35 <div id="footer">
36 <p />
37 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
38 wix-users@lists.sourceforge.net</a>
39
40 <script type="text/javascript">
41 var HT_mailLink = document.getElementById("HT_MailLink");
42 var HT_mailLinkText = HT_mailLink.innerHTML;
43 HT_mailLink.href += ": " + document.title;
44 HT_mailLink.innerHTML = HT_mailLinkText;
45 </script>
46
47 <p />
48
49 </div>
50 </div>
51
52</body>
53</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/msihelper.htm b/src/samples/Dtf/Documents/Guide/Content/msihelper.htm
new file mode 100644
index 00000000..c1493117
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/msihelper.htm
@@ -0,0 +1,59 @@
1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
2<html>
3 <head>
4 <title>Included Components</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
6 <link rel="stylesheet" type="text/css" href="MSDN.css">
7 </head>
8 <body id="bodyID" class="dtBODY">
9 <div id="nsbanner">
10 <div id="bannerrow1">
11 <table class="bannerparthead" cellspacing="0" id="Table1">
12 <tr id="hdr">
13 <td class="runninghead">Managed Libraries for Windows Installer</td>
14 <td class="product"></td>
15 </tr>
16 </table>
17 </div>
18 <div id="TitleRow">
19 <h1 class="dtH1">Helper Classes for Windows Installer Packages</h1>
20 </div>
21 </div>
22 <div id="nstext">
23 <p>Included are some useful helper classes for working with
24 MSI and MSP packages:</p>
25 <ul>
26 <li><p><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.InstallPackage.html"
27 ><strong>InstallPackage</strong></a> - extends the Database class to provide powerful
28 package-based operations such as:</p>
29 <ul>
30 <li>direct extraction of files to uncompressed source
31 path
32 <li>updating files from uncompressed source path back
33 into the compressed source for the package (including updating file
34 metadata)
35 <li>applying a patch directly to the package
36 <li>consolidating a package with uncompressed source files or multiple msm-cabs
37 into a package with a single compressed cabinet</li>
38 </ul>
39 <P></P>
40 <li><p><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.InstallPathMap.html"
41 ><strong>InstallPathMap</strong>, <a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.InstallPath.html"
42 ><strong>InstallPath</strong></a> - represent the directory structure
43 of an installation package, including file, component, and directory source and target
44 install paths. Accessible by file, component, or directory keys; searchable by
45 filename.</p>
46 <li><p><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.PatchPackage.html"
47 ><strong>PatchPackage</strong></a> - allows convenient access to patch properties,
48 and analysis and extraction of transforms</p></li>
49 </ul>
50 <p><br/></p>
51 <p>These classes are in the Microsoft.WindowsInstaller.Package.dll assembly.</p>
52 <p><br/></p>
53 <p><b>See also:</b></p>
54 <p>The <a href="wifile.htm">WiFile</a> sample tool demonstrates some usage of the
55 InstallPackage class.</p>
56 <p><br/></p>
57 </div>
58 </body>
59</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/msiwrapper.htm b/src/samples/Dtf/Documents/Guide/Content/msiwrapper.htm
new file mode 100644
index 00000000..70190ac4
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/msiwrapper.htm
@@ -0,0 +1,80 @@
1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
2<html>
3 <head>
4 <title>Included Components</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252">
6 <link rel="stylesheet" type="text/css" href="MSDN.css">
7 </head>
8 <body id="bodyID" class="dtBODY">
9 <div id="nsbanner">
10 <div id="bannerrow1">
11 <table class="bannerparthead" cellspacing="0" id="Table1">
12 <tr id="hdr">
13 <td class="runninghead">Managed Libraries for Windows Installer</td>
14 <td class="product"></td>
15 </tr>
16 </table>
17 </div>
18 <div id="TitleRow">
19 <h1 class="dtH1">Managed wrapper library for Windows Installer APIs</h1>
20 </div>
21 </div>
22 <div id="nstext">
23 <p>Microsoft.WindowsInstaller.dll is a complete .NET wrapper for the
24 Windows Installer APIs. It provides a convenient object model that is
25 comfortable to .NET developers and still familiar to anyone who has used
26 the MSI scripting object model.</p>
27 <h3>Notes</h3>
28 <ul>
29 <li><p>All published MSI APIs are wrapped, with the exception of four:
30 MsiGetFileSignatureInformation (because I don't know of a .NET analog for the
31 returned certificate structure), and three APIs for previewing UI dialogs.
32 Other than that, you should be able to do everything that you can
33 do via the C APIs or the COM automation interface.</p>
34 <li><p>Some parts of this code have never had a formal test
35 pass, so use at your own risk. But much of the code is exercised daily, used
36 by the Developer Division Sustaining Engineering team's BRIQS system to build
37 and test patches. And it has been in use by many other teams for over two
38 years now with only a few minor fixes, so it can be considered very stable.</p>
39 <li><p>Despite its official-sounding namespace, this assembly is not officially
40 sanctioned by the Windows Installer team. But currently there are not any
41 plans for an official set of managed even in Longhorn, so I don't see a
42 conflict for now.</p></li>
43 </ul>
44 <h3>Why rewrite it?</h3>
45 <p>It is possible to access MSI's COM Automation interfaces via C# and VB.NET.
46 So why create yet another wrapper? Here are some of my reasons:</p>
47 <ul>
48 <li><p>One of the primary things I wanted to be able to do
49 was write custom actions in C#. The automation interface was not usable in
50 that case, because there is no way to convert the integer session handle
51 (received as a parameter to the type 1 custom action function) into a Session
52 automation object.</p>
53 <li><p>The automation interface does not provide a way to
54 specify an external UI handler. Besides external UI, this is also needed
55 to do validation.</p>
56 <li><p>The automation interface does not provide a way to
57 explicitly close handles (other than Views). I ran into this problem when I
58 wanted to programmatically delete a database that I'd just finished using, but
59 couldn't because it was still open!</p>
60 <li><p>Finally, COM Automation is somewhat slower than invoking
61 the APIs directly.</p></li>
62 </ul>
63
64 <p><br/></p>
65 <p><b>See also:</b></p>
66 <ul>
67 <li><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.html">Microsoft.WindowsInstaller Namespace</a></li>
68 <ul>
69 <li><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.Installer.html">Installer Class</a></li>
70 <li><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.Database.html">Database Class</a></li>
71 <li><a href="ms-its:MMLRef.chm::/Microsoft.WindowsInstaller.Session.html">Session Class</a></li>
72 </ul>
73 <li><a href="msihelper.htm">Helper Classes for Windows Installer Packages</a></li>
74 <li><a href="writingcas.htm">Writing Managed Custom Actions</a></li>
75 <li><a href="databases.htm">Working with MSI Databases</a></li>
76 </ul>
77 <p><br/></p>
78 </div>
79 </body>
80</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/packages.htm b/src/samples/Dtf/Documents/Guide/Content/packages.htm
new file mode 100644
index 00000000..aa521685
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/packages.htm
@@ -0,0 +1,86 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Working with Install Packages</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Working with Install Packages</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <span class="nolink">Install Packages</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24
25 <h3>Updating files in a product layout</h3>
26 <p>The InstallPackage class makes it easy to work with files and cabinets
27 in the context of a compressed or uncompressed product layout.</p>
28 <p>This hypothetical example takes an IDictionary 'files' which maps file keys to file paths. Each
29 file is to be updated in the package layout; cabinets are even recompressed if necessary to include the new files.</p>
30 <pre><font face="Consolas, Courier New"> <font color=blue>using</font> (InstallPackage pkg = <font color=blue>new</font> InstallPackage(<font color=purple>"d:\builds\product.msi"</font>,
31 DatabaseOpenMode.Transact))
32 {
33 pkg.WorkingDirectory = Path.Combine(Path.GetTempFolder(), <font color=purple>"pkgtmp"</font>);
34 <font color=blue>foreach</font> (string fileKey in files.Keys)
35 {
36 <font color=blue>string</font> sourceFilePath = files[fileKey];
37 <font color=blue>string</font> destFilePath = pkg.Files[fileKey].SourcePath;
38 destFilePath = Path.Combine(pkg.WorkingDirectory, destFilePath);
39 File.Copy(sourceFilePath, destFilePath, <font color=blue>true</font>);
40 }
41 pkg.UpdateFiles(<font color=blue>new</font> ArrayList(files.Keys));
42 pkg.Commit();
43 Directory.Delete(pkg.WorkingDirectory, <font color=blue>true</font>);
44 }</font></pre><br />
45 <p>1.&nbsp; Create a <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_Package_InstallPackage__ctor.htm">new InstallPackage</a>
46 instance referring to the location of the .msi. This is actually just a specialized subclass of a Database.</p>
47 <p>2.&nbsp; Set the <a href="DTFAPI.chm::/html/P_Microsoft_Deployment_WindowsInstaller_Package_InstallPackage_WorkingDirectory.htm">WorkingDirectory</a>.
48 This is the root directory where the package expects to find the new source files.</p>
49 <p>3.&nbsp; Copy each file to its proper location in the working directory. The
50 <a href="DTFAPI.chm::/html/P_Microsoft_Deployment_WindowsInstaller_Package_InstallPackage_Files.htm">InstallPackage.Files</a>
51 property is used to look up the relative source path of each file.</p>
52 <p>4.&nbsp; Call <a href="DTFAPI.chm::/html/Overload_Microsoft_Deployment_WindowsInstaller_Package_InstallPackage_UpdateFiles.htm">InstallPackage.UpdateFiles</a>
53 with the list of file keys. This will re-compress and package the files if necessary, and also update the
54 following data: File.FileSize, File.Version, File.Language, MsiFileHash.HashPart*.</p>
55 <p>5.&nbsp; Commit the database changes and cleanup the working directory.</p>
56 </ul>
57
58 <p><br/></p>
59 <p><b>See also:</b></p>
60 <ul>
61 <li><a href="wifile.htm">WiFile Sample Tool</a> - a more complete tool that expands on the above example.</li>
62 <li><a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Package_InstallPackage.htm">InstallPackage Class</a></li>
63 </ul>
64 <p><br/></p>
65
66 </div>
67
68 <div id="footer">
69 <p />
70 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
71 wix-users@lists.sourceforge.net</a>
72
73 <script type="text/javascript">
74 var HT_mailLink = document.getElementById("HT_MailLink");
75 var HT_mailLinkText = HT_mailLink.innerHTML;
76 HT_mailLink.href += ": " + document.title;
77 HT_mailLink.innerHTML = HT_mailLinkText;
78 </script>
79
80 <p />
81
82 </div>
83 </div>
84
85</body>
86</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/powerdiff.htm b/src/samples/Dtf/Documents/Guide/Content/powerdiff.htm
new file mode 100644
index 00000000..f420b47e
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/powerdiff.htm
@@ -0,0 +1,71 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>MSI, MSP, CAB Diff Tool</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">MSI, MSP, CAB Diff Tool</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="samples.htm">Samples</a> &gt;
17 <span class="nolink">DDiff</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25 <h2>MSI, MSP, CAB Diff Tool</h2>
26
27 <p><pre><font face="Consolas, Courier New">Usage: DDiff target1 target2 [options]
28Example: DDiff d:\dir1 d:\dir2
29Example: DDiff setup1.msi setup2.msi
30Example: DDiff patch1.msp patch2.msp -patchtarget target.msi
31Example: DDiff package1.cab package2.cab
32
33Options:
34 /o [filename] Output results to text file (UTF8)
35 /p [package.msi] Diff patches relative to target MSI</font></pre>
36 </p>
37 <p><br/></p>
38
39 <p>The following types of inputs can be diffed:
40 <ul>
41 <li><b>Directories</b>: files and subdirectories are compared.</li>
42 <li><b>Cab files</b>: internal file list and files are compared.</li>
43 <li><b>MSI/MSM database files</b>: summary info, tables, and embedded binary and cab streams are compared.</li>
44 <li><b>MSP files</b>: summary info and embedded file cab are compared. When a patch target MSI is provided, the MSP's tables are also compared.</li>
45 <li><b>Versioned files</b>: Win32 file version is compared.</li>
46 <li><b>Text files</b>: if diff.exe is in the path, it is used to get a line-by-line diff.</li>
47 <li><b>Other files</b>: file size and bytes are compared.</li>
48 </ul>
49 All processing is done recursively. So a versioned file within a cab within an MSI within a directory will have meaningful diff results.</p>
50
51 <p><br/></p>
52 </div>
53 <div id="footer">
54 <p />
55 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
56 wix-users@lists.sourceforge.net</a>
57
58 <script type="text/javascript">
59 var HT_mailLink = document.getElementById("HT_MailLink");
60 var HT_mailLinkText = HT_mailLink.innerHTML;
61 HT_mailLink.href += ": " + document.title;
62 HT_mailLink.innerHTML = HT_mailLinkText;
63 </script>
64
65 <p />
66
67 </div>
68 </div>
69
70</body>
71</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/samplecas.htm b/src/samples/Dtf/Documents/Guide/Content/samplecas.htm
new file mode 100644
index 00000000..4dfed6f0
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/samplecas.htm
@@ -0,0 +1,84 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Sample C# Custom Action</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Sample C# Custom Action</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="managedcas.htm">Managed CAs</a> &gt;
17 <a href="writingcas.htm">Writing CAs</a> &gt;
18 <span class="nolink">C# Sample</span>
19 </span>
20 </div>
21 </div>
22 <div id="main">
23 <div id="header">
24 </div>
25 <div class="summary">
26
27 <p>MSI custom actions are MUCH easier to write in C# than
28 in C++!</p><pre><font face="Consolas, Courier New"> [CustomAction]
29 <font color=blue>public</font> <font color=blue>static</font> ActionResult SampleCustomAction1(Session session)
30 {
31 session.Log(<font color="purple">"Hello from SampleCA1"</font>);
32
33 <font color=blue>string</font> testProp = session[<font color="purple">"SampleCATest"</font>];
34 <font color=blue>string</font> testProp2;
35 testProp2 = (<font color="blue">string</font>) session.Database.ExecuteScalar(
36 <font color="purple">"SELECT `Value` FROM `Property` WHERE `Property` = 'SampleCATest'"</font>);
37
38 <font color=blue>if</font>(testProp == testProp2)
39 {
40 session.Log(<font color="purple">"Simple property test passed."</font>);
41 <font color=blue>return</font> ActionResult.Success;
42 }
43 <font color=blue>else</font>
44 <font color=blue>return</font> ActionResult.Failure;
45 }
46 </font></pre>
47 <p>A sample CA project with two CAs is included in the
48 Samples\ManagedCA directory.&nbsp; Running the CustomActionTest project will package the CA and insert
49 it into a test MSI. The MSI will invoke the custom actions, but it will not install anything
50 since the second sample CA returns ActionResult.UserExit.
51 </p>
52
53 <p><br/></p>
54 <p><b>See also:</b></p>
55 <ul>
56 <li><a href="writingcas.htm">Writing Managed Custom Actions</a></li>
57 <li><a href="caconfig.htm">Specifying the Runtime Version</a></li>
58 <li><a href="databases.htm">Working with MSI Databases</a></li>
59 <li><a href="buildingcas.htm">Building Managed Custom Actions</a></li>
60 <li><a href="debuggingcas.htm">Debugging Managed Custom Actions</a></li>
61 </ul>
62 <p><br/></p>
63
64 </div>
65
66 <div id="footer">
67 <p />
68 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
69 wix-users@lists.sourceforge.net</a>
70
71 <script type="text/javascript">
72 var HT_mailLink = document.getElementById("HT_MailLink");
73 var HT_mailLinkText = HT_mailLink.innerHTML;
74 HT_mailLink.href += ": " + document.title;
75 HT_mailLink.innerHTML = HT_mailLinkText;
76 </script>
77
78 <p />
79
80 </div>
81 </div>
82
83</body>
84</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/samples.htm b/src/samples/Dtf/Documents/Guide/Content/samples.htm
new file mode 100644
index 00000000..3bcd379a
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/samples.htm
@@ -0,0 +1,59 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Sample Applications</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Sample Applications</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <span class="nolink">Samples</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24 <p>Besides the simple managed custom action sample, there are three functional
25 and useful sample tools included in this distribution:</p>
26 <p><a href="Inventory.htm"><b>MSI Inventory</b></a><br/>
27 Shows a hierarchical, relational, searchable view of all of the product,
28 feature, component, file, and patch data managed by MSI, for all products
29 installed on the system.</p>
30 <p><a href="WiFile.htm"><b>WiFile</b></a><br/>
31 Extracts and updates cabbed files in an MSI setup.</p>
32 <p><a href="CabPack.htm"><b>CabPack</b></a><br/>
33 Creates simple self-extracting cab packages. OK, so this one isn't
34 especially useful as a tool, but the code should be helpful.</p>
35 <p><a href="PowerDiff.htm"><b>DDiff</b></a><br/>
36 Recursively diffs MSI, MSP, CAB, and other files and directories.
37 Much more thorough than widiffdb.vbs.</p>
38 <p><br/></p>
39 </div>
40
41 <div id="footer">
42 <p />
43 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
44 wix-users@lists.sourceforge.net</a>
45
46 <script type="text/javascript">
47 var HT_mailLink = document.getElementById("HT_MailLink");
48 var HT_mailLinkText = HT_mailLink.innerHTML;
49 HT_mailLink.href += ": " + document.title;
50 HT_mailLink.innerHTML = HT_mailLinkText;
51 </script>
52
53 <p />
54
55 </div>
56 </div>
57
58</body>
59</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/support.htm b/src/samples/Dtf/Documents/Guide/Content/support.htm
new file mode 100644
index 00000000..89acbadf
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/support.htm
@@ -0,0 +1,52 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Support/Bugs</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Support/Bugs</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="about.htm">Overview</a> &gt;
16 <span class="nolink">Support/Bugs</span>
17 </span>
18 </div>
19 </div>
20 <div id="main">
21 <div id="header">
22 </div>
23 <div class="summary">
24 <p>Please send general support questions or comments to the
25 <a href="mailto:wix-users@sourceforge.net">wix-users</a> discussion list.</p>
26
27 <p>Bugs, suggestions, or feature requests can be submitted at the
28 <a href="http://wix.sourceforge.net/">WiX project</a>
29 on Sourceforge.net.</p>
30
31 <p><br/></p>
32 </div>
33
34 <div id="footer">
35 <p />
36 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
37 wix-users@lists.sourceforge.net</a>
38
39 <script type="text/javascript">
40 var HT_mailLink = document.getElementById("HT_MailLink");
41 var HT_mailLinkText = HT_mailLink.innerHTML;
42 HT_mailLink.href += ": " + document.title;
43 HT_mailLink.innerHTML = HT_mailLinkText;
44 </script>
45
46 <p />
47
48 </div>
49 </div>
50
51</body>
52</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/using.htm b/src/samples/Dtf/Documents/Guide/Content/using.htm
new file mode 100644
index 00000000..6fe960e8
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/using.htm
@@ -0,0 +1,50 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Deployment Tools Foundation Development Guide</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Deployment Tools Foundation Development Guide</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <span class="nolink">Development Guide</span>
16 </span>
17 </div>
18 </div>
19 <div id="main">
20 <div id="header">
21 </div>
22 <div class="summary">
23 <ul>
24 <li><a href="managedcas.htm">Managed Custom Actions</a></li>
25 <li><a href="databases.htm">Working with MSI Databases</a></li>
26 <li><a href="cabs.htm">Working with Cabinet Files</a></li>
27 <li><a href="packages.htm">Working with Install Packages</a></li>
28 <li><a href="samples.htm">Sample Applications</a></li>
29 </ul>
30 </div>
31
32 <div id="footer">
33 <p />
34 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
35 wix-users@lists.sourceforge.net</a>
36
37 <script type="text/javascript">
38 var HT_mailLink = document.getElementById("HT_MailLink");
39 var HT_mailLinkText = HT_mailLink.innerHTML;
40 HT_mailLink.href += ": " + document.title;
41 HT_mailLink.innerHTML = HT_mailLinkText;
42 </script>
43
44 <p />
45
46 </div>
47 </div>
48
49</body>
50</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/whatsnew.htm b/src/samples/Dtf/Documents/Guide/Content/whatsnew.htm
new file mode 100644
index 00000000..3efe67bd
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/whatsnew.htm
@@ -0,0 +1,257 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>What's New?</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">What's New?</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="about.htm">Overview</a> &gt;
16 <span class="nolink">What's New?</span>
17 </span>
18 <span id="languageFilter">2007-07-03</span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25
26 <h3>Highlights</h3>
27 <ul>
28 <li><p>New project name name "Deployment Tools Foundation", and
29 new namespaces <font face="Consolas, Courier New">WixToolset.Dtf.*</font></p></li>
30 <li><p>Added ZIP compression library</p></li>
31 <li><p>Added library for reading/writing Win32 resources including file versions</p></li>
32 <li><p>Managed custom action improvements:</p><ul>
33 <li><p>Simplified authoring and building -- new MakeSfxCA tool
34 automatically maps DLL entrypoints to CA methods.</p></li>
35 <li><p>Managed custom action DLLs now run in a separate process for
36 better reliability with respect to CLR versions, but still have
37 full access to the MSI session.</p></li>
38 </ul></li>
39 <li><p>Found and fixed many bugs with extensive unit test suite</p></li>
40 <li><p>LINQ to MSI ! (preview)</p></li>
41 </ul>
42
43 <p>Unfortunately, all these changes do mean that migrating tools and applications from
44 the previous release can be a moderate amount of work.</p>
45
46 <h3>Breaking Changes</h3>
47 <p>For the first time since v1.0, this release contains some major breaking
48 changes, due to a significant redesign and cleanup effort that has been a
49 long time coming. The overall purpose of the changes is to bring the class
50 libraries much closer to ship-quality.</p>
51 <ul>
52 <li><p>All libraries use a new namespace hierarchy
53 under <font face="Consolas, Courier New">WixToolset.Dtf</font>.
54 The new namespace aligns with the new project name, gives all the various
55 libraries an identity that makes them obviously related to the DTF project,
56 and mostly avoids "taking over" a namespace that might be rightfully owned
57 by the platform technology owner.</p></li>
58
59 <li><p>Assemblies are also renamed to follow namespaces.</p></li>
60
61 <li><p>A new unified compression framework forms the basis for the new ZIP
62 library and a redesigned CAB library. Additional archive formats can
63 be plugged into the framework. The stream-based compression APIs have
64 been redesigned to be more object-oriented and easier to use. The file-based
65 APIs are mostly unchanged from the old cabinet library, although some names
66 have changed in order to fit into the new unified framework.</p></li>
67
68 <li><p>Large parts of the WindowsInstaller library have been redesigned
69 to be more object-oriented and to better follow .NET Framework design
70 guidelines. And various APIs throughout the library have naming or other
71 changes for better consistency and to follow conventions and best
72 pratices as enforced by FxCop.</p></li>
73
74 <li><p>The WindowsInstaller APIs no longer make any attempt to mimic the
75 MSI COM automation interfaces. The naming and object patterns in the
76 automation interfaces often conflicted with with best practices for
77 .NET Framework class libraries. Since most people start using DTF
78 without having ever experienced MSI scripting, there is little
79 reason to match the scripting object model. Making the APIs more
80 consistent with .NET conventions will make them much easier to use
81 for people already experienced with the .NET Framework.</p></li>
82
83 <li><p>APIs in all class libraries use generics where appropriate, especially
84 the generic collection interfaces. This means .NET Framework 2.0 or later
85 is required.</p></li>
86
87 <li><p>The FilePatch library is missing from this release. An updated
88 and redesigned file-delta library is in development.</p></li>
89 </ul>
90
91 <h3>Other Changes</h3>
92 <ul>
93 <li><p>New MakeSfxCA tool for building managed custom action packages: In addition to
94 packaging the CA DLL and dependencies, it automatically detects managed CA methods
95 and generates corresponding unmanaged DLL entrypoints in the CA host DLL (SfxCA.dll),
96 where they are called by MSI. Previously it was necessary to either provide this
97 mapping in a CustomAction.config file, or live with the generic "ManagedCustomActionN"
98 names when authoring the CustomAction table in the MSI. For more info, see the
99 help topic on building managed custom actions.</p></li>
100
101 <li><p>Out-of-proc managed custom action DLLs:
102 When a managed custom action runs, it normally requests a specific major
103 version of the CLR via CustomAction.config. However in the previous implementation,
104 the request could be ignored if there was already a different version of the CLR
105 loaded into the MSI process, either from a previous custom action or by some other
106 means. (The CLR doesn't allow side-by-side versions within the same process.)
107 While there have been no reports of this issue causing setup failures in practice,
108 it may be only a matter of time, as new CLR versions keep coming out.</p>
109
110 <p>The redesigned native host for managed custom actions, SfxCA.dll, re-launches
111 itself in a separate process before loading the CLR and invoking the managed CA.
112 This ensures that the desired CLR version is always loaded, assuming it is available
113 on the system. It also sets up a named-pipe remoting channel between the two processes.
114 All session-related MSI API calls are routed through that channel, so that the
115 custom action has full access to the installer session just as if it were
116 running in-process.</p></li>
117
118 <li><p>The new zip compression library supports nearly all features of the zip
119 file format. This includes the ZIP64 extensions for archives greater than 4GB,
120 as well as disk-spanning capabilities. Zip encryption is not supported. The zip
121 library has been tested against a variety of third-party zip tools; please
122 report any issues with incompatible packages.</p>
123
124 <p>Currently only the basic DEFLATE compression algorithm is supported
125 (via System.IO.Compression.DeflateStream), and the compression level is not adjustable
126 when packing an archive. The zip file format has a mechanism for plugging in arbitrary
127 compression algorithms, and that capability is exposed: you can provide a Stream object
128 capable of compressing and decompressing bytes as an alternative to DeflateStream.</p></li>
129
130 <li><p>Added support for the few APIs new in MSI 4.0:</p>
131 <ul>
132 <li><font face="Consolas, Courier New">Installer.GetPatchFileList()</font></li>
133 <li><font face="Consolas, Courier New">InstallLogModes.RMFilesInUse</font></li>
134 <li><font face="Consolas, Courier New">ComponentAttributes.DisableRegistryReflection</font></li>
135 <li><font face="Consolas, Courier New">ControlAttributes.ElevationShield</font></li>
136 </ul>&nbsp;<br /></li>
137
138 <li><p>The documentation is now built with the
139 <a href="http://msdn2.microsoft.com/en-us/vstudio/bb608422.aspx" target="_blank">Sandcastle</a> doc build engine,
140 with help from the <a href="http://www.codeplex.com/SHFB" target="_blank">Sandcastle
141 Help File Builder</a>. (The old CHM was built with NDoc.)</p></li>
142
143 <li><p>The documentation includes detailed class diagrams for the
144 WindowsInstaller and Compression namespaces.</p></li>
145
146 <li><p>WindowsInstaller API doc topics now link straight to the corresponding
147 unmanaged MSI API topics in MSDN. If you know an unmanaged MSI API you want to
148 use but don't know the managed equivalent, you can search for it and find what
149 managed APIs link to it.</p></li>
150
151 <li><p>Unit tests cover about 90% of the Compression, Compression.Zip, and
152 Compression.Cab assemblies -- basically everything except some rare
153 error-handling cases.</p></li>
154
155 <li><p>Unit tests along with samples cover over 50% of the WindowsInstaller and
156 WindowsInstaller.Package assemblies (including custom action functionality). More
157 test cases are still being added.</p></li>
158 </ul>
159
160 <h3>Bugfixes</h3>
161 <p>In addition to the extensive cleanup due to redesigns and unit tests, the following
162 reported bugs have been fixed:</p>
163 <ul>
164 <li><p>Managed custom actions could in rare instances fail to load with error 183
165 (directory already exists)</p></li>
166 <li><p>Timestamps of files in a cabinet could be incorrectly offset based on the timezone.
167 (This was due to a behavior change in the DateTime class between .NET 1.1 and 2.0.)</p></li>
168 <li><p>Unicode file paths for cabbed files could be handled incorrectly in some cases</p></li>
169 <li><p>Installer.DetermineApplicablePatches just didn't work</p></li>
170 <li><p>InstallPackage.ApplyPatch couldn't handle applying multiple patches to the same layout</p></li>
171 </ul>
172
173 <h3>LINQ to MSI</h3>
174 <p><i>You'll never want to write MSI SQL again!</i></p>
175 <p>Language INtegrated Query is a new feature in .NET Framework 3.5 and C# 3.0. Through
176 a combination of intuitive language syntax and powerful query operations, LINQ provides
177 a whole new level of productivity for working with data in your code. While the .NET
178 Framework 3.5 provides LINQ capability for SQL databases and XML data, now you
179 can write LINQ queries to fetch and even update data in MSI databases!</p>
180
181 <p>Look at the following example:<br />
182
183<pre><font face="Consolas, Courier New"> <font color="blue">var</font> actions = <font color="blue">from</font> a <font color="blue">in</font> db.InstallExecuteSequences
184 <font color="blue">join</font> ca <font color="blue">in</font> db.CustomActions <font color="blue">on</font> a.Action <font color="blue">equals</font> ca.Action
185 <font color="blue">where</font> ca.Type == CustomActionTypes.Dll
186 <font color="blue">orderby</font> a.Sequence
187 <font color="blue">select new</font> {
188 Name = a.Action,
189 Target = ca.Target,
190 Sequence = a.Sequence };
191
192 <font color="blue">foreach</font> (<font color="blue">var</font> a <font color="blue">in</font> actions)
193 {
194 Console.WriteLine(a);
195 }
196 </font></pre>
197
198 The query above gets automatically translated to MSI SQL:</p>
199
200 <p><font face="Consolas, Courier New">&nbsp;&nbsp;&nbsp;&nbsp;SELECT `InstallExecuteSequence`.`Action`,
201 `CustomAction`.`Target`, `InstallExecuteSequence`.`Sequence` FROM `InstallExecuteSequence`, `CustomAction`
202 WHERE `InstallExecuteSequence`.Action` = `CustomAction`.`Action` ORDER BY `InstallExecuteSequence`.`Sequence`</font></p>
203
204 <p>But the query is not executed until the <font face="Consolas, Courier New">foreach</font>
205 enumeration. Then records are fetched from the results incrementally as the enumeration progresses.
206 The objects fetched are actually of an anonymous type created there in the query with exactly
207 the desired fields. So the result of this code will be to print the Action, Target, and Sequence
208 of all Type 1 custom actions.</p>
209
210 <p>The query functionality is currently limited by the capabilities of the MSI SQL engine. For
211 example, a query can't use <font face="Consolas, Courier New">where (ca.Type &amp;
212 CustomActionTypes.Dll) != 0</font> because the bitwise-and operator is not supported by
213 MSI SQL. The preview version of LINQ to MSI will throw an exception for cases like that, but
214 the eventual goal is to have it automatically move the data and operation outside of MSI when
215 necessary, so that any arbitrary expressions are supported in the query.</p>
216
217 <p>Note there are no MSI handles (or <font face="Consolas, Courier New">IDisposable</font>s)
218 to worry about! Handles are all managed internally and closed deterministically. Also,
219 with the entity object model for common tables, the compiler will tell you if you get a
220 column name wrong or misspelled. The entity objects even support easy inserting, updating,
221 and deleting (not shown here).</p>
222
223 <p>For more examples, see the LinqTest project in the source. More documentation
224 is being written.</p>
225
226 <p>Obviously, LINQ to MSI requires .NET Framework 3.5. Everything else
227 in DTF requires only .NET Framework 2.0.</p>
228
229 <p><font color="red">Note: The LINQ functionality in this DTF release is of preview quality only
230 and should not be used in production. While there are unit tests covering a wide
231 variety of queries, using advanced queries outside what is covered by the tests
232 is likely to result in unexpected exceptions, and retrieved data might possibly be
233 incorrect or incomplete. An updated LINQ to MSI library is in development.</font></p>
234
235 <p>&nbsp;</p>
236
237 </div>
238
239 <div id="footer">
240 <p />
241 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
242 wix-users@lists.sourceforge.net</a>
243
244 <script type="text/javascript">
245 var HT_mailLink = document.getElementById("HT_MailLink");
246 var HT_mailLinkText = HT_mailLink.innerHTML;
247 HT_mailLink.href += ": " + document.title;
248 HT_mailLink.innerHTML = HT_mailLinkText;
249 </script>
250
251 <p />
252
253 </div>
254 </div>
255
256</body>
257</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/wifile.htm b/src/samples/Dtf/Documents/Guide/Content/wifile.htm
new file mode 100644
index 00000000..20998b73
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/wifile.htm
@@ -0,0 +1,73 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Windows Installer Package File Manipulation Tool</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Windows Installer Package File Manipulation Tool</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="samples.htm">Samples</a> &gt;
17 <span class="nolink">WiFile</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25 <p><pre><font face="Consolas, Courier New">Usage: WiFile.exe package.msi /l [filename,filename2,...]
26Usage: WiFile.exe package.msi /x [filename,filename2,...]
27Usage: WiFile.exe package.msi /u [filename,filename2,...]
28
29Lists (/l), extracts (/x) or updates (/u) files in an MSI or MSM.
30Files are extracted using their source path relative to the package.
31Specified filenames do not include paths.
32Filenames may be a pattern such as *.exe or file?.dll</font></pre>
33 </p>
34 <p><br/></p>
35
36 <h4>Example</h4>
37 <p>The most powerful use of WiFile.exe is to do a round-trip update of files in a
38 compressed MSI/MSM package. It works like this:<ol>
39 <li>Extract specific file(s) or all files from the package:
40 <tt>WiFile.exe package.msi /x *</tt></li>
41 <li>The files are now expanded into their directory structure. You can edit/update
42 the files however you like.</li>
43 <li>Update the package with the changed files: <tt>WiFile.exe package.msi /u *</tt>&nbsp;
44 This also updates the file metadata in the MSI including the file version, size, and hash.</li>
45 </ol></p>
46 <p><br/></p>
47
48 <h4>Notes</h4>
49 <ul>
50 <li><p>Also works with packages that have multiple and/or external cab(s).</p></li>
51 </ul>
52
53 <p><br/></p>
54 </div>
55 <div id="footer">
56 <p />
57 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
58 wix-users@lists.sourceforge.net</a>
59
60 <script type="text/javascript">
61 var HT_mailLink = document.getElementById("HT_MailLink");
62 var HT_mailLinkText = HT_mailLink.innerHTML;
63 HT_mailLink.href += ": " + document.title;
64 HT_mailLink.innerHTML = HT_mailLinkText;
65 </script>
66
67 <p />
68
69 </div>
70 </div>
71
72</body>
73</html>
diff --git a/src/samples/Dtf/Documents/Guide/Content/writingcas.htm b/src/samples/Dtf/Documents/Guide/Content/writingcas.htm
new file mode 100644
index 00000000..6beccf5f
--- /dev/null
+++ b/src/samples/Dtf/Documents/Guide/Content/writingcas.htm
@@ -0,0 +1,114 @@
1<html xmlns="http://www.w3.org/1999/xhtml">
2<head>
3 <title>Writing Managed Custom Actions</title>
4 <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
5 <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
6</head>
7
8<body>
9
10 <div id="control">
11 <span class="productTitle">Deployment Tools Foundation</span><br />
12 <span class="topicTitle">Writing Managed Custom Actions</span><br />
13 <div id="toolbar">
14 <span id="chickenFeet">
15 <a href="using.htm">Development Guide</a> &gt;
16 <a href="managedcas.htm">Managed CAs</a> &gt;
17 <span class="nolink">Writing CAs</span>
18 </span>
19 </div>
20 </div>
21 <div id="main">
22 <div id="header">
23 </div>
24 <div class="summary">
25 <p><b>Caveats</b></p>
26 <p>Before choosing to write a custom action in managed code instead of
27 traditional native C++ code, you should carefully consider the following:</p>
28 <ul>
29 <li><p>Obviously, it introduces a dependency on the .NET Framework. Your
30 MSI package should probably have a LaunchCondition to check for the presence
31 of the correct version of the .NET Framework before anything else happens.</p></li>
32 <li><p>If the custom action runs at uninstall time, then even the uninstall of
33 your product may fail if the .NET Framework is not present. This means a
34 user could run into a problem if they uninstall the .NET Framework before
35 your product.</p></li>
36 <li><p>A managed custom action should be configured to run against a specific
37 version of the .NET Framework, and that version should match the version your
38 actual product runs against. Allowing the version to "float" to the latest
39 installed .NET Framework is likely to lead to compatibility problems with
40 future versions. The .NET Framework provides side-by-side functionality for
41 good reason -- use it.</p></li>
42
43 </ul>
44 <p><br/></p>
45 <p><b>How To</b></p>
46 <ul>
47 <li><p>A custom action function needs to be declared as
48 <tt>public static</tt> (aka <tt>Public Shared</tt> in VB.NET). It takes one parameter which is
49 a <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Session.htm">Session</a> object, and returns a
50 <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_ActionResult.htm">ActionResult</a> enumeration.</p>
51 <pre><font face="Consolas, Courier New"> [CustomAction]
52 <font color=blue>public</font> <font color=blue>static</font> ActionResult MyCustomAction(Session session)</font></pre><br />
53 <li><p>The function must have a
54 <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_CustomActionAttribute.htm"
55 >CustomActionAttribute</a>, which enables it to be
56 linked to a proxy function. The attribute can take an optional
57 &quot;name&quot; parameter, which is the name of the entrypoint
58 that is exported from the custom action DLL.</p>
59 <li><p>Fill in MSI CustomAction table entries just like you
60 would for a normal type 1 native-DLL CA. Managed CAs can also work just
61 as well in deferred, rollback, and commit modes.</p>
62 <li><p>If the custom action function throws any kind of
63 Exception that isn't handled internally, then it will be caught by the proxy
64 function. The Exception message and stack trace will be printed to the
65 MSI log if logging is enabled, and the CA will return a failure code.</p>
66 <li><p>To be technically correct, any MSI handles obtained should be
67 closed before a custom action function exits -- otherwise a warning
68 gets printed to the log. The handle classes in the managed library
69 (<a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Database.htm">Database</a>,
70 <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_View.htm">View</a>,
71 <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Record.htm">Record</a>,
72 <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_SummaryInfo.htm">SummaryInfo</a>)
73 all implement the IDisposable interface,
74 which makes them easily managed with C#'s <tt>using</tt>
75 statement. Alternatively, they can be closed in a finally block.
76 As a general rule, <i>methods</i> return new handle objects that should be
77 managed and closed by the user code, while <i>properties</i> only return a reference
78 to a prexisting handle object.</p></li>
79 <li><p>Don't forget to use a <a href="caconfig.htm">CustomAction.config</a> file to
80 specify what version of the .NET Framework the custom action should run against.</p></li>
81 </ul>
82
83 <p><br/></p>
84 <p><b>See also:</b></p>
85 <ul>
86 <li><a href="samplecas.htm">Sample C# Custom Actions</a></li>
87 <li><a href="caconfig.htm">Specifying the Runtime Version</a></li>
88 <li><a href="databases.htm">Working with MSI Databases</a></li>
89 <li><a href="buildingcas.htm">Building Managed Custom Actions</a></li>
90 <li><a href="debuggingcas.htm">Debugging Managed Custom Actions</a></li>
91 </ul>
92 <p><br/></p>
93
94 </div>
95
96 <div id="footer">
97 <p />
98 Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
99 wix-users@lists.sourceforge.net</a>
100
101 <script type="text/javascript">
102 var HT_mailLink = document.getElementById("HT_MailLink");
103 var HT_mailLinkText = HT_mailLink.innerHTML;
104 HT_mailLink.href += ": " + document.title;
105 HT_mailLink.innerHTML = HT_mailLinkText;
106 </script>
107
108 <p />
109
110 </div>
111 </div>
112
113</body>
114</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-04 11:37:05 +0000