| 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> > |
| 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> <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"> 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 & |
| 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> </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> |