1 files changed, 114 insertions, 0 deletions
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 @@
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <title>Writing Managed Custom Actions</title>
+  <link rel="stylesheet" type="text/css" href="../styles/presentation.css" />
+  <link rel="stylesheet" type="text/css" href="ms-help://Hx/HxRuntime/HxLink.css" />
+</head>
+<body>
+  <div id="control">
+    <span class="productTitle">Deployment Tools Foundation</span><br />
+    <span class="topicTitle">Writing Managed Custom Actions</span><br />
+    <div id="toolbar">
+      <span id="chickenFeet">
+        <a href="using.htm">Development Guide</a> &gt;
+        <a href="managedcas.htm">Managed CAs</a> &gt;
+        <span class="nolink">Writing CAs</span>
+      </span>
+    </div>
+    </div>
+    <div id="main">
+      <div id="header">
+      </div>
+      <div class="summary">
+                <p><b>Caveats</b></p>
+                <p>Before choosing to write a custom action in managed code instead of
+                traditional native C++ code, you should carefully consider the following:</p>
+                <ul>
+                    <li><p>Obviously, it introduces a dependency on the .NET Framework. Your
+                    MSI package should probably have a LaunchCondition to check for the presence
+                    of the correct version of the .NET Framework before anything else happens.</p></li>
+                    <li><p>If the custom action runs at uninstall time, then even the uninstall of
+                    your product may fail if the .NET Framework is not present. This means a
+                    user could run into a problem if they uninstall the .NET Framework before
+                    your product.</p></li>
+                    <li><p>A managed custom action should be configured to run against a specific
+                    version of the .NET Framework, and that version should match the version your
+                    actual product runs against. Allowing the version to "float" to the latest
+                    installed .NET Framework is likely to lead to compatibility problems with
+                    future versions. The .NET Framework provides side-by-side functionality for
+                    good reason -- use it.</p></li>
+                </ul>
+                <p><br/></p>
+                <p><b>How To</b></p>
+        <ul>
+        <li><p>A custom action function needs to be declared as 
+        <tt>public static</tt> (aka <tt>Public Shared</tt> in VB.NET). It takes one parameter which is 
+        a <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Session.htm">Session</a> object, and returns a 
+        <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_ActionResult.htm">ActionResult</a> enumeration.</p>
+        <pre><font face="Consolas, Courier New">    [CustomAction]
+    <font color=blue>public</font> <font color=blue>static</font> ActionResult MyCustomAction(Session session)</font></pre><br />
+        <li><p>The function must have a 
+        <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_CustomActionAttribute.htm"
+        >CustomActionAttribute</a>, which enables it to be 
+        linked to a proxy function. The attribute can take an optional 
+        &quot;name&quot; parameter, which is the name of the entrypoint
+        that is exported from the custom action DLL.</p>
+        <li><p>Fill in MSI CustomAction table entries just like you 
+        would for a normal type 1 native-DLL CA. Managed CAs can also work just 
+        as well in deferred, rollback, and commit modes.</p>
+        <li><p>If the custom action function throws any kind of 
+        Exception that isn't handled internally, then it will be caught by the proxy 
+        function. The Exception message and stack trace will be printed to the 
+        MSI log if logging is enabled, and the CA will return a failure code.</p>
+        <li><p>To be technically correct, any MSI handles obtained should be 
+        closed before a custom action function exits -- otherwise a warning 
+        gets printed to the log. The handle classes in the managed library 
+        (<a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Database.htm">Database</a>,
+        <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_View.htm">View</a>,
+        <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_Record.htm">Record</a>,
+        <a href="DTFAPI.chm::/html/T_Microsoft_Deployment_WindowsInstaller_SummaryInfo.htm">SummaryInfo</a>)
+        all implement the IDisposable interface, 
+        which makes them easily managed with C#'s <tt>using</tt> 
+        statement. Alternatively, they can be closed in a finally block. 
+        As a general rule, <i>methods</i> return new handle objects that should be 
+        managed and closed by the user code, while <i>properties</i> only return a reference
+        to a prexisting handle object.</p></li>
+        <li><p>Don't forget to use a <a href="caconfig.htm">CustomAction.config</a> file to
+        specify what version of the .NET Framework the custom action should run against.</p></li>
+        </ul>
+            
+        <p><br/></p>
+        <p><b>See also:</b></p>
+        <ul>
+            <li><a href="samplecas.htm">Sample C# Custom Actions</a></li>
+            <li><a href="caconfig.htm">Specifying the Runtime Version</a></li>
+            <li><a href="databases.htm">Working with MSI Databases</a></li>
+            <li><a href="buildingcas.htm">Building Managed Custom Actions</a></li>
+            <li><a href="debuggingcas.htm">Debugging Managed Custom Actions</a></li>
+        </ul>
+        <p><br/></p>
+        
+      </div>
+        
+      <div id="footer">
+        <p />
+        Send comments on this topic to <a id="HT_MailLink" href="mailto:wix-users%40lists.sourceforge.net?Subject=Deployment Tools Foundation Documentation">
+        wix-users@lists.sourceforge.net</a>
+        <script type="text/javascript">
+          var HT_mailLink = document.getElementById("HT_MailLink");
+          var HT_mailLinkText = HT_mailLink.innerHTML;
+          HT_mailLink.href += ": " + document.title;
+          HT_mailLink.innerHTML = HT_mailLinkText;
+        </script>
+        <p />
+        
+      </div>
+   </div>
+    
+</body>
+</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> >
	16	<a href="managedcas.htm">Managed CAs</a> >
	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	"name" 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>