This post serves as a tutorial for creating a MSI installer for your WPF Applications in Visual Studio. For this we use WiX (recommended by Microsoft).
If you don't already have Wix installed, go ahead and download it from here. You'll be redirected to the relevant GitHub releases page where you can download the .exe file to install WiX.
For example, on this page you can download WiX version 3.11 by downloading and running the 'wix311.exe' file.
When the .exe is running you should see some tiles. Select the 'Install' option. Once installed it will look something like this:
For Visual Studio 2019 you can download the extension from the marketplace here.
If you are using a different version of Visual Studio then you can find links to download the extensions from the WiX downloads page.
In the New Project Wizard select project type 'Setup Project for WiX v3'.
Enter a name for the project like 'MyApp.Installer' and create it.
In the Solution Explorer, right click on the WiX project references and select 'Add Reference'.
In the window that appears, select the 'Projects' tab. This is where we add files which come from other projects in our solution.
To add the 'exe' output by the WPF project, select the project from the list which produces the WPF application and press 'Add'.
You can also add libraries output by other projects in the same way.
You can now close the references window. We still need to add those '.dll' files. To do this perform a release build of the WPF Application, so they are created in the output 'bin/Release' directory.
In the Solution Explorer right-click on the WiX project and select 'Add' -> 'Existing Item ...'
Now select all the '.dll' files which your release build produced.
Now all the required files are part of the WiX project, but we still need to tell WiX to actually bundle them in the installer.
Scroll down to the 'TODO's. This is where we need to add references to our files.
You can add other <Component> tags like this to add other files which are the output of other projects within the solution (that have been referenced in step 4).
We still need to add any other '.dll' files. To do this we add more <Component> tags in the following format:
Now if you build the Installer project (through right-clicking in Solution Explorer), there will be a '.msi' installer generated in the 'bin/Release' directory of the Installer project.
The generated MSI should work, and now is a good time to check.
But notice it also outputs a '.cab' file and the installer won't work without it. In the remaining steps we'll remove this '.cab' file and make some other improvements.
Again this is easy to do with WiX. First add a reference to the WiX project (like in step 2), under the 'Browse' tab, navigate to the WiX install location and select the 'WixNetFxExtension.dll' file.
(for me this was at path: C:\Program Files (x86)\WiX Toolset v3.11\bin\WixNetFxExtension.dll')
Then in your 'Product.wxs' file declare we are using the namespace at the top of the file by adding it to the <Wix> tag.
So the <Wix> tag should look like this:
Next you need to actually use this property, and prevent the install from going ahead if it is false. This can be done using a <Condition> tag with an error message as follows:
Users expect start menu shortcuts to appear with new software, so we better add one.
In the 'Product.wxs' file within the <Product> tag and within a <Feature> tag add the following line:
In the <Directory> tag with Id "TARGETDIR" we'll need to add a start menu folder directory. In the code below we've just added the three lines starting with the "ProgramMenuFolder". You can copy this code changing it to use the correct project name:
I hope you got what you were looking for with this post. Please leave comments and questions below.
This post serves as a tutorial for creating a MSI installer for your WPF Applications in Visual Studio. For this we use WiX (recommended by Microsoft).Prerequisites
I assume you already have a Visual Studio solution containing a WPF Project. And I assume you have some experience with Visual Studio and XML. You do not need any prior knowledge of WiX.Step 1: Install Wix
We are going to need WiX to generate our MSI.If you don't already have Wix installed, go ahead and download it from here. You'll be redirected to the relevant GitHub releases page where you can download the .exe file to install WiX.
For example, on this page you can download WiX version 3.11 by downloading and running the 'wix311.exe' file.
When the .exe is running you should see some tiles. Select the 'Install' option. Once installed it will look something like this:
Step 2: Install Wix Visual Studio Extension
With Wix you can use the Command Line to generate your MSI, but instead we'll be creating a project in Visual Studio. To do this we first need the WiX Visual Studio Extension installed.For Visual Studio 2019 you can download the extension from the marketplace here.
If you are using a different version of Visual Studio then you can find links to download the extensions from the WiX downloads page.
Step 3: Add a Wix Installer Project to your Solution
Now open your solution in Visual Studio and right click on the solution in the Solution Explorer. Select 'Add' -> 'New Project'In the New Project Wizard select project type 'Setup Project for WiX v3'.
Enter a name for the project like 'MyApp.Installer' and create it.
Step 4: Add files to the Wix Project
If you perform a release build of your WPF Application, and look at the output exe it may have various '.dll' files it requires. These might come from NuGet dependencies, library projects in the same solution or '.dll' files you've manually added. We need our MSI Installer to output all of these files to the installation directory, so first the WiX project needs to know what these files are.In the Solution Explorer, right click on the WiX project references and select 'Add Reference'.
To add the 'exe' output by the WPF project, select the project from the list which produces the WPF application and press 'Add'.
You can also add libraries output by other projects in the same way.
You can now close the references window. We still need to add those '.dll' files. To do this perform a release build of the WPF Application, so they are created in the output 'bin/Release' directory.
In the Solution Explorer right-click on the WiX project and select 'Add' -> 'Existing Item ...'
Now select all the '.dll' files which your release build produced.
Now all the required files are part of the WiX project, but we still need to tell WiX to actually bundle them in the installer.
Step 5: Bundle files with MSI
In the WiX project open the 'Product.wxs' file. This is where all the logic for the Installer is contained. The file contents are in XML format.Scroll down to the 'TODO's. This is where we need to add references to our files.
<Fragment>
<ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
<!-- TODO: Remove the comments around this Component element and the ComponentRef below in order to add resources to this installer. -->
<!-- <Component Id="ProductComponent"> -->
<!-- TODO: Insert files, registry keys, and other resources here. -->
<!-- </Component> -->
</ComponentGroup>
</Fragment>
<Component Id="ProductComponent">
<File Source="$(var.WpfProjectName.TargetPath)" />
</Component>
You can add other <Component> tags like this to add other files which are the output of other projects within the solution (that have been referenced in step 4).
We still need to add any other '.dll' files. To do this we add more <Component> tags in the following format:
<Component Id="MyDll.dll" Guid="ADD-GUID-HERE">
<File Id="MyDll.dll" Source="MyDll.dll" KeyPath="yes" Checksum="yes"/>
</Component>
Now if you build the Installer project (through right-clicking in Solution Explorer), there will be a '.msi' installer generated in the 'bin/Release' directory of the Installer project.
The generated MSI should work, and now is a good time to check.
But notice it also outputs a '.cab' file and the installer won't work without it. In the remaining steps we'll remove this '.cab' file and make some other improvements.
Step 6: Embed Cab file in Installer
To remove the '.cab' file we want to embed it within the '.msi' file. This is really easy to do by adding 'EmbedCab="yes"' to the <MediaTemplate> tag inside the 'Product.wxs' file.<MediaTemplate EmbedCab="yes"/>
Step 7: Make installer check for .NET version
If you run your MSI installer on any Windows Machine, the installation will complete successfully. This happens even if that machine doesn't have the required version of .NET Framework / .NET Core installed. It would be much better if our installer failed if the required framework was missing.Again this is easy to do with WiX. First add a reference to the WiX project (like in step 2), under the 'Browse' tab, navigate to the WiX install location and select the 'WixNetFxExtension.dll' file.
(for me this was at path: C:\Program Files (x86)\WiX Toolset v3.11\bin\WixNetFxExtension.dll')
Then in your 'Product.wxs' file declare we are using the namespace at the top of the file by adding it to the <Wix> tag.
So the <Wix> tag should look like this:
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"
xmlns:netfx="http://schemas.microsoft.com/wix/NetFxExtension">
<PropertyRef Id="WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED"/>
Next you need to actually use this property, and prevent the install from going ahead if it is false. This can be done using a <Condition> tag with an error message as follows:
<Condition Message=".NET Framework 4.6.2 or later not found. Install the .NET Framework and try again.">
<![CDATA[INSTALLED OR WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED]]>
</Condition>
Step 8: Add Start Menu Shortcut
When you run the MSI installer, no shortcuts to your application are added. It simply installs the application to Program Files, and expects you to find it yourself!Users expect start menu shortcuts to appear with new software, so we better add one.
In the 'Product.wxs' file within the <Product> tag and within a <Feature> tag add the following line:
<ComponentRef Id="ApplicationShortcut"/>
In the <Directory> tag with Id "TARGETDIR" we'll need to add a start menu folder directory. In the code below we've just added the three lines starting with the "ProgramMenuFolder". You can copy this code changing it to use the correct project name:
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramMenuFolder">
<Directory Id="ApplicationProgramsFolder" Name="WpfProjectName"/>
</Directory>
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="WpfProjectName" />
</Directory>
</Directory>
</Fragment>
<Fragment>
<DirectoryRef Id="ApplicationProgramsFolder">
<Component Id="ApplicationShortcut" Guid="ab43392d-d93c-4e0f-b2b0-652112a557f3">
<Shortcut Id="ApplicationStartMenuShortcut"
Name="ProductName"
Description="ProductDescription"
Target="[#WpfProjectName.exe]"
WorkingDirectory="APPLICATIONROOTDIRECTORY"/>
<RemoveFolder Id="CleanUpShortCut" Directory="ApplicationProgramsFolder" On="uninstall"/>
<RegistryValue Root="HKCU" Key="Software\CompanyName\ProductName" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
</Component>
</DirectoryRef>
</Fragment>
We're Done!
Note that these MSIs are not signed. It is quite easy to add a digital signature to your MSI and isdefinitley worthwhile if you are distributing it publically. Maybe I'll post about this in the future. If you choose not to add a signature, at least make sure your users are given other reasons to trust it!I hope you got what you were looking for with this post. Please leave comments and questions below.
Comments
Post a Comment