This repository contains the source code for embedding the Windows Terminal in your own WinUI3 applications. According to the Windows Terminal roadmap, WinUI3 support isn't planned until at least sometime in 2023. Fortunately, you no longer have to wait that long. This repository will be updated as new versions of Windows Terminal are released.
If you were looking for a WPF wrapper the Windows Terminal team already maintains one. Lastly, the Cascadia Code Font is not packaged with these libraries.
Related repositories include:
- Repo: Windows Terminal
- Windows Terminal Documentation (Repo: Contribute to the docs)
- Console API Documentation
- Cascadia Code Font
- Windows Implementation Libraries
Some of the functionality that Windows Terminal depends on appears to work fine with WinUI3 on Windows 11, but not on Windows 10. As of this writing all known issues are on Windows 10 but not Windows 11.
SwapChainPaneldoes not support compositing with transparency. This means if you set an image as the background forTermControlit will not show up.CoreTextServicesManagerdoes not work, this prevents the IME panel from being displayed.- SampleApp fails to start conhost.exe or it exits immediately after startup. If I remember correctly, conhost.exe should be spawned when CreatePseudoConsole is called. Conhost.exe failing causes the child console process to exit during startup. I suspect this might be due to packaged app/msix trust working differently on Win10 than Win11 but that's purely speculation at the moment.
The Windows Terminal repository is linked as a submodule. I did this because I only need a subset of the repository, though if it becomes too difficult to maintain I'll consider merging a fork. The Windows Terminal repository also contains its own submodules, so you need to make sure you recursively pull all submodules:
git clone --recurse-submodules https://github.com/Corillian/WindowsTerminal.git
Now the fun begins. For starters, everything must be compiled with the same version of WinRT. As of this writing, the Windows Terminal team is using a fairly old version of WinRT, however WinUI3 is much newer so I upgraded to the latest. Run UpdateOpenConsoleCppWinRT.ps1 to do the upgrade. To further complicate matters, they maintain their own NuGet server for all of their dependencies and of course, upgrading WinRT breaks a bunch of stuff. To resolve this matter I created another script, PatchOpenConsole.ps1, to massage the OpenConsole submodule back into a compilable state.
Since we aren't having enough fun yet there are additional considerations for the first time you build this repository. The OpenConsole submodule needs to have its NuGet dependencies restored and a specific subset of projects built because there are some non-WinRT libraries and auto-generated files that get pulled into the WinUI3 wrappers. I have created another script, Build.ps1, to take care of this. Originally, I played around with having some MSBuild targets that would sort all of this out but there were issues with the child MSBuild processes pulling in build state from the parent so... I wrote another script. If I was an MSBuild ninja there's probably a way to get it working but - a script works and you only need to do this once:
.\Build.ps1 -restore
This will restore OpenConsole, build the requisite subset of OpenConsole dependencies, and then build the WinUI3 wrappers in WindowsTerminal.sln. If OpenConsole fails to build due to errors about hitting the heap limit of the C++ compiler just run Build.ps1 (without -restore) until it stops complaining about heap limits and everything should work. After you do this initial build you can then open WindowsTerminal.sln and build via Visual Studio as you normally would. In fact, if Build.ps1 successfully builds OpenConsole but fails to build WindowsTerminal.sln you should try building WindowsTerminal.sln in Visual Studio because... welcome to WinRT.
If you stay exclusively in the land of C# things don't seem to be too bad. The moment you have to start dealing with C++/WinRT prepare for hate and discontent. The C++/WinRT build toolchain and its C# cousin, CsWinRT, currently seem to be buggy and flakey. Yes, flakey, as in non-deterministic - sometimes you will build and it'll work - sometimes it won't. What changed? Who knows, but restarting Visual Studio seems to help, except when it doesn't.
If the organization of this repository makes you think to yourself "was the person who created this on drugs?" the answer is yes - hard, hard drugs. To those of you who actually try to build this project I wish you all the best, and if you submit an issue complaining about how you can't get it to build I want to give you a heads up that I'm probably going to take a shot and ignore it.