aboutsummaryrefslogtreecommitdiff
path: root/src/samples/Dtf/Documents/Guide/Content/whatsnew.htm
diff options
context:
space:
mode:
Diffstat (limited to 'src/samples/Dtf/Documents/Guide/Content/whatsnew.htm')
-rw-r--r--src/samples/Dtf/Documents/Guide/Content/whatsnew.htm257
1 files changed, 257 insertions, 0 deletions
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>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-04 17:27:32 +0000