Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update DTF documentation for v4 WRT building managed CAs #221

Merged
merged 5 commits into from
Oct 31, 2023
Merged

Update DTF documentation for v4 WRT building managed CAs #221

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b38e21e
Update DTF documentation for v4 WRT building managed CAs
BMurri Aug 17, 2023
83589ab
Remove reference to NET Core
BMurri Aug 17, 2023
beb4fb5
Write in complete sentences
BMurri Aug 17, 2023
0adb8cd
Separate MSBuild projects from other project layouts
BMurri Aug 17, 2023
55086eb
Merge branch 'master' into dtf-v4-doc-fixes
BMurri Oct 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions src/Docusaurus/docs/tools/dtf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,8 @@ Before choosing to write a custom action in managed code instead of traditional
- 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.
- 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.

Note: Both `.NET Framework` versions and newer franeworks such as `.NET 6` can now be targeted.
robmen marked this conversation as resolved.
Show resolved Hide resolved


### Proxy for Managed Custom Actions

Expand Down Expand Up @@ -209,13 +211,12 @@ The configuration file follows [the standard schema for .NET Framework configura

#### Supported Runtime Version

In the startup section, use [supportedRuntime](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/startup/supportedruntime-element) tags to explicitly specify the version(s) of the .NET Framework that the custom action should run on. If no versions are specified, the chosen version of the .NET Framework will be the "best" match to what Microsoft.Deployment.WindowsInstaller.dll was built against.
In the startup section, use [supportedRuntime](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/startup/supportedruntime-element) tags to explicitly specify the version(s) of the .NET Framework that the custom action should run on. If no versions are specified, the chosen version of the .NET Framework will be the "best" match to what WixToolset.Dtf.WindowsInstaller.dll was built against.

:::caution
Warning: Leaving the version unspecified is dangerous as it introduces a risk of compatibility problems with future versions of the .NET Framework. It is highly recommended that you specify only the version(s) of the .NET Framework that you have tested against.
:::


#### Other Configuration

Various other kinds of configuration settings may also be added to this file, as it is a standard .NET Framework application config file for the custom action.
Expand Down Expand Up @@ -253,15 +254,16 @@ A sample CA project with two CAs is included in the Samples\ManagedCA directory.

The build process for managed CA DLLs is a little complicated becuase of the proxy-wrapper and dll-export requirements. Here's an overview:

1. Compile your CA assembly, which references Microsoft.Deployment.WindowsInstaller.dll and marks exported custom actions with a CustomActionAttribute.
2. Package the CA assembly, CustomAction.config, Microsoft.Deployment.WindowsInstaller.dll, and any other dependencies using MakeSfxCA.exe. The filenames of CustomAction.config and Microsoft.Deployment.WindowsInstaller.dll must not be changed, since the custom action proxy specifically looks for those files.
1. Add a package reference to the `WixToolset.Dtf.CustomAction` nuget package to your msbuild project or otherwise make both the `WixToolset.Dtf.CustomAction` and `WixToolset.Dtf.WindowsInstaller` nuget packages
2. Compile your CA assembly, which references WixToolset.Dtf.WindowsInstaller.dll and marks exported custom actions with a CustomActionAttribute.
3. Package the CA assembly, CustomAction.config, WixToolset.Dtf.WindowsInstaller.dll, and any other dependencies using MakeSfxCA.exe. The filenames of CustomAction.config and WixToolset.Dtf.WindowsInstaller.dll must not be changed, since the custom action proxy specifically looks for those files.

#### Compiling

```
csc.exe
/target:library
/r:$(DTFbin)\Microsoft.Deployment.WindowsInstaller.dll
/r:$(DTFbin)\WixToolset.Dtf.WindowsInstaller.dll
/out:SampleCAs.dll
*.cs
```
Expand All @@ -274,7 +276,7 @@ MakeSfxCA.exe
$(DTFbin)\SfxCA.dll
SampleCAs.dll
CustomAction.config
$(DTFbin)\Microsoft.Deployment.WindowsInstaller.dll
$(DTFbin)\WixToolset.Dtf.WindowsInstaller.dll
```

Now the resulting package, SampleCAsPackage.dll, is ready to be inserted into the Binary table of the MSI.
Expand Down