Newbie question: How to install wix?

[pixtur]

Hi,

I want to use WiX to build an installer for https://github.com/t3/tooll3.

From what I've read, WiX 4 seems like a perfect match. I've read some blog posts, the website, and the documentation, but I'm stuck at the first step: choosing which version of WiX to install and how to install it.

• It would be great if https://wixtoolset.org/docs/ had an "Installation" chapter.
• I checked https://github.com/wixtoolset/wix/releases/tag/v4.0.6 for an MSI installer, but it only lists WixAdditionalTools.exe, NuGet artifacts, and debug symbols.

I want to integrate it into a CI/CD pipeline, so the MSBuild/CLI tools seem like a better match.

Thanks for your help,
pixtur

[pixtur]

I've spent some more time looking of help or tutorials. Sadly the "other" wix hides most meaningful results and the few tutorials I found were either outdated (e.g. starting with a download on codeplex) or too advanced (skipping the installation step).

I will try wix5.0.2 because it at least has an installer.

[robmen]

The Getting Started page has what you are looking for.

Create a simple.wixproj

<Project Sdk="WixToolset.Sdk/5.0.1">
</Project>

And dotnet build it. That will install the tools for you.

Note: in the next couple of weeks we'll have a smaller Getting Started page to get that first build up and running faster.

[pixtur]

Thanks for that quick reply. I have to admit that I deeply underestimated the complexity of building an installer with WiX.

Although I have some experience with .NET and C#, I'm not a senior developer. As such, I have to confess that I'm giving up with WiX for now because the documentation and WiX version landscape are too complex for me to dive into. Since I'm also working on an open-source project, I know it's both painful and difficult to get feedback, but in its current state, WiX is just not really suited for intermediate users (i.e., me), because of its lack of clear and concise documentation that starts with an introduction.

Some feedback:

• I would start with three paragraphs on the homepage: Why to use it, how to set it up with Visual Studio, and a super minimal example of how the build project would look like.
• My application has hundreds of resource files, so adding single lines like:

        <ComponentGroup Id="AppFiles">
            <Component>
                <File Source="..\Tooll\StartT3.exe"/>
                <File Source="..\Tooll\SomeOtherFile.dll"/>
            </Component>
        </ComponentGroup>

is just impracticable. I wanted to find more documentation on that, but googling for "WiX fragment directory" only brings up documentation for WiX 3. At least there is a link...

...but sadly, this is only pointing to WiX 4 (giving another indication that WiX 5 might not be stable yet).

I read this guide and it helped me to get a rough understanding, but I got irritated that it required single file references, which wouldn't work for my use case. Clicking the link to the latest documentation is broken because that page no longer exists in the WiX 4 documentation.

Eventually, I got something to build, but again ran into the problem that even though I'm using WiX5, the required XML reference needs to be v4:

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">

I assume that at its current state, the WiX project is more focused on maintaining its current user base, which is of course perfectly valid. I hope all this doesn't sound too much like a rant. I know it's difficult, and you're building and sharing this software for free.

I just wish it were easier to understand how to do the "simple basic stuff."

[robmen]

Did you find this WiX Tutorial?

[pixtur]

Please let me know once you setup the Getting Started page.

[pixtur]

Did you find this WiX Tutorial?

I'm sorry. I saw the link, but in my simple mind this sounded like a 3rd party contributor trying to promote HeatWave. If WiX wouldn't be usable without 3rd party solutions, I just wouldn't use it.

I did another fresh start with using the .NET project approach:

I created:

1. A new project folder "Test" in my solution.
2. Test\Test.csproj with...

<Project Sdk="WixToolset.Sdk/5.0.1">
</Project>

Running dotnet build gives me...

dotnet build
Restore complete (0.4s)
  Test failed with 1 error(s) (0.0s)
    C:\Users\pixtur\.nuget\packages\wixtoolset.sdk\5.0.1\tools\wix.targets(909,5): error MSB3030: Could not copy the file "obj\Debug\Test.msi" because it was not found.

Build failed with 1 error(s) in 10.1s

I assume I have to add references and dependencies to other projects. The only documentation I could find was https://wixtoolset.org/docs/tools/msbuild/, which is really intimidating. As feedback, my thoughts are:

• The first chapter is great.
• The two tips and info I ignored because I have no clue what they are trying to tell me.
• Then I read the chapter... "Properties"... "AdditionalCub", "BindFiles", "CabinetCreationThreadCount"... what?
• It refers to a .wixproj—is this my .csproj file extension? (I now learned that cs is special for C# and I should have used wixproj).
• Then I tried to understand what "Properties" are referring to... Maybe the <Project> tag? But then there would be an entry "Sdk." So maybe properties are other tags like "". But then again, "Project" is not listed... So basically, I ignored that table and moved on...
• Eventually, I find "Project Reference," which sounds exactly like the thing I'm looking for. But I just wish there would be a 3-line XML example. I'm also confused why "ProjectReference" didn't come up in the Properties and Items tables.
• Finally, the "Centralizing MSBuild properties" section has some examples, but it’s on a topic that is already too advanced.

Is there a minimal .wixproj example file somewhere that links to a simple .NET 9 console application?

I coming more from a UX side and did a lot of usability tests. My hope is that my ramblings might help you to identify some potentials on how to structure the documentation for first time users.

[pixtur]

The current setup of the project I'm maintaining already exceeds the level of complexity a normal contributor can understand. So I'm trying very hard to reduce the number of additional dependencies like libraries, drivers, etc. NuGet packages are acceptable, but ideally, even those I try to replace if I only need a single algorithm or helper method.

So for WiX, my thoughts would have been the following:

It's a solution that turns a .NET build artifact into an installer (e.g., MSI) that will install dependencies like the .NET SDK and, in our case, the Windows Graphic Tools.
I set it up once (ideally without installing an executable), and it becomes a new build step or build configuration, similar to publishing a package.
After listing the dependencies, install steps, and the same manifest-like stuff like AppId, I can build this configuration and get a single MSI package in an output folder.

If I have to install 2 packages (e.g., WiX and let's say Python 2.7 for a super annoying example), setting up a build environment just got one step more complex. If some additional software is required for the core purpose of a solution like WiX, then obviously that software isn't doing its job (completely).

Please note, that I'm not implying that you can't do that with WiX. I was just to stupid to figure it out and HeatWave sounded like yet another layer to an already very complex topic.

I don't want to criticize. I didn't pay anything for WiX, so I can't have any expectations. I just wanted to share my thoughts, and maybe sometimes getting another perspective helps to understand things.

I'm always amazed at how peculiar ways users use our software when they're sharing their screens. Sometimes we can guide them (e.g., with tutorials right in front of them), and sometimes we can also learn from them and nudge our way closer to their mental model.

But anyway, I've moved on to Inno Setup, which works exactly as I would have expected. It's closer to my low-level expertise but solved my problem in about 30 minutes.

[robmen]

Best of luck to you.

For other's future reference, WiX works exactly as desired by the OP above. You create a .wixproj just like you create a .csproj and that references your .wxs code the way .csproj references .cs code. Those projects can be integrated into a .sln and built using a single command to dotnet build or msbuild.

HeatWave is a Visual Studio extension that provides all the functionality needed to open, build, edit and otherwise work with .wixproj in Visual Studio. It turns out Visual Studio ships with .csproj support.

HeatWave makes you more productive and it's templates make it easier to set up your first project correctly, but isn't required as everything is text files, just like .csproj and .cs files.

Things I've learned from this thread, in no particular order:

1. A .wixproj with no .wxs files does not fail until it tries to place the MSI project that was not built. I'll look at what .csproj does in this case and improve the error message.

2. The relationship between FireGiant and WiX is not clear enough. FireGiant employs the maintainers of the WiX Toolset. Without FireGiant, we probably walked away from WiX years ago. :) As I mentioned, in the last WiX Online Meeting, we're unifying FireGiant and WiX documentation and sites in the next few weeks. I expect that change will significantly reduce this confusion.

3. Documentation is one of the biggest problems facing WiX. I'm deeply disappointed that all work falls on the maintainers of OSS projects. I'm still coming to terms with this "fact". But, the above mentioned merge makes it "my" problem (instead of "our" problem) and it will get tackled.

4. At the same time, I am concerned that even with documentation, people won't read it. My last couple of experiences where people complained when there was in fact documentation were not promising. Most apologized but also turned around and said something like: "Well, the documentation didn't say it in a concise enough way for me to read it."

Anyway, changes are coming. The initial integration effort will be completed in the next couple of weeks. We'll see where we go from there.

[pixtur]

Hi Robmen,

I know how incredibly frustrating that must sound. I spend a lot of my spare time on a FOSS project, and I would love for contributors to be more active. A lot of people are eager to help, but one thing I’ve learned is that the core documentation (e.g., the first 3 pages or so that people read) should be driven by the core developers and then rephrased by people who can write. Nowadays, LLMs can really help with the second part.

It's sad, but nobody will help you on that front because it's just not feasible. They will either lack the expert knowledge or (even worse) they will make things up.

My personal method for this would be:

1. Find somebody who matches your target audience but has no prior experience.
2. Answer all questions. Explain the essentials. Walk them through the steps of building a very simple installer while recording the mic and the screen. Make it open and relaxed. Take an hour or two.
3. Fix all critical bugs and showstoppers (if you think you’ll not find any during this exercise, you're kidding yourself or you’re not being user-centric).
4. Write a 2-page summary with screenshots. (It might be that NotebookLM might help with the transcript and summary).

Done. The whole thing (depending on #3) takes less than a day. It will do wonders for your project.

Just my 2 cents, of course.

---

ps: This book really helped me with this stuff: https://sensible.com/rocket-surgery-made-easy/

[bevanweiss]

@pixtur

My personal method for this would be:

Find somebody who matches your target audience but has no prior experience.
Answer all questions. Explain the essentials. Walk them through the steps of building a very simple installer while recording the mic and the screen. Make it open and relaxed. Take an hour or two.
Fix all critical bugs and showstoppers (if you think you’ll not find any during this exercise, you're kidding yourself or you’re not being user-centric).
Write a 2-page summary with screenshots. (It might be that NotebookLM might help with the transcript and summary).

Have you seen the Deployment Dojo series?
https://youtube.com/playlist?list=PLDlzbQXIs18slmqmdlS10_de_Cps-QRg6&si=m3xBSLus5-FQuZCe

WiX installation is very simple

dotnet tool install --global wix

Even better is that once you've got a real wixproj, you can do something like

dotnet tool restore

from the .wixproj folder to get the WiX tool installed locally for that project, so that there's no complexity for the development team.

To have a nicer Visual Studio development experience the HeatWave extension is good.
But it's not required. Editing the XML files (.wxs / .wxl, as well as the .wixproj) is easy enough.

If you're looking to make a Windows Installer compliant installation, then InnoSetup is the wrong thing (https://jrsoftware.org/isfaq.php#msi). It produces an arbitrary executable that does its own magic.
Microsoft themselves use WiX, so if you're developing installers for Windows, WiX is the more aligned tool to use.
Unfortunately it does have some burden with getting to know aspects of the Windows Installer subsystem. Although some of the sharp edges of this are being more robustly abstracted away in recent WiX versions (WiX 4+).

If you start needing to have dependencies like .NET installation, or configuration of IIS services, or similar, then WiX has capabilities for these. Trying to do similar in a robust fashion with InnoSetup / NSIS becomes trickier.

[pixtur]

Thanks for these tips. I have seen the YouTube channel and skimmed through some of the videos. But it's probably targeting more experienced users. I was then looking for somehow "how to start from scratch" (or just how to install it). I just didn't find the right one.

I'm aware that WiX would have been the more sustainable choice. But I'm doing this in my spare time (on a week-end). And after 4 hours of fighting with it, I just gave up. As I said, once there is more stable documentation, I might well give it a second try.