[DefApp] Document how it works

[miniksa]

@miniksa and @cinnamon-msft to document how this works.

_Originally posted by @miniksa in https://github.com/microsoft/terminal/pull/7489

### Tasks
- [ ] Document how the app extension goo works
- [ ] document the com server interface
- [ ] probably add a way to do defterm unpackaged as well

[driver1998]

Implements the default application behavior and handoff mechanisms between console and terminal. The inbox portion is done already.

Could you hint us about what Windows version will support this feature?

[zadjii-msft]

Windows 11? 🤣

I'm kidding, it'll probably be something above build 21336, but that's about as sure as we can be right now. Build numbers can change a lot as a feature makes its way up the source tree. This feature needs a lot more testing still, and we still need to finish the Terminal side of things before it will do anything. I'm sure when it's ready for folks to try out, you'll know 😉

[just1a-person]

yes Windows 11

[LuanVSO]

he wasn't kidding after all

[MatejKafka]

Quick question, is there a way to set a custom terminal by just setting a path to a binary in HKCU/Console/%%Startup (or somewhere else), or does the terminal emulator have to implement a COM server?

Using just a path would be nice for portable apps (not installed system-wide), and simplify adding support even for installed apps (currently, at least Alacritty seems unlikely to implement support due to the added complexity of a COM server (https://github.com/alacritty/alacritty/issues/6036)).

[zadjii-msft]

as a note to self: https://github.com/contour-terminal/contour/issues/605

Off the top of my head, I don't think this'll be trivial to just point at a exe, instead of a COM server. There's a two-step handoff here, the OS conhost -> a Console server, and then that new console server hands off to a Terminal application.

So alacritty would need to handoff to an OpenConsole (via the commandline somehow), and then that openconsole would need to do the handoff to alacritty. I mean, maybe there's a way to pass those args on the commandline instead of via the COM interface:

• https://github.com/microsoft/terminal/blob/main/src/host/proxy/IConsoleHandoff.idl
• https://github.com/microsoft/terminal/blob/main/src/host/proxy/ITerminalHandoff.idl

er, looking closer at some of those, I feel like, that's maybe less possible

[DHowett]

Here's what I'm thinking, @zadjii-msft.

We always intended 2-stage handoff to be actually 2-part, not just 2-stage. We can provide an updated version of conhost (perhaps even inside terminal!) that other packages can register as their conhost. That will get them the new pty code, and we can complete second-stage handoff to them rather than to Terminal.

Idle notes on why we went with 2-stage handoff:

• We always wanted to provide conhost as a packaged app for other people to rely on
• By letting conhost speak conhost to conhost, it decouples the PTY handoff interface from the OS

[DHowett]

The original mockups for "default terminal" config actually had two parts: "What console handles these requests?" "What terminal does it send them to?" and that's actually still how it works internally.

[CrendKing]

It'd be nice if we can use the portable Windows Terminal installation as default terminal. I suppose all the necessary components are already there on the disk, but only the "COM registration" part is missing.

[ysc3839]

It looks like OpenConsoleProxy.dll is required to do marshaling. If I implement terminal handoff in my app, and register OpenConsoleProxy.dll in HKEY_CLASSES_ROOT, would it conflict with the one in Windows Terminal?

[feeas]

On a Windows 11 computer that does not have any version of Windows Terminal installed, is there a simple way to set the portable version of Windows Terminal as the Default Terminal?

[ysc3839]

@feeas Yes. By modifying registry manually.

[feeas]

@ysc3839 Can you further explain how to do it? I know that I may need to modify HKEY_CURRENT_USER\Console\%%Startup, but the value inside does not point to an exe path.

[ysc3839]

@feeas Use this reg file to register COM components:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\CLSID\{2EACA947-7F5F-4CFA-BA87-8F7FBEEFBE69}\LocalServer32]
@="C:\\terminal-1.21.2361.0\\OpenConsole.exe"

[HKEY_CLASSES_ROOT\CLSID\{E12CFF52-A866-4C77-9A90-F570A7AA2C6B}\LocalServer32]
@="C:\\terminal-1.21.2361.0\\WindowsTerminal.exe"

[HKEY_CLASSES_ROOT\CLSID\{3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F}\InprocServer32]
@="C:\\terminal-1.21.2361.0\\OpenConsoleProxy.dll"

[HKEY_CLASSES_ROOT\Interface\{59D55CCE-FC8A-48B4-ACE8-0A9286C6557F}\ProxyStubClsid32]
@="{3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F}"

[HKEY_CLASSES_ROOT\Interface\{746E6BC0-AB05-4E38-AB14-71E86763141F}\ProxyStubClsid32]
@="{3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F}"

[HKEY_CLASSES_ROOT\Interface\{AA6B364F-4A50-4176-9002-0AE755E7B5EF}\ProxyStubClsid32]
@="{3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F}"

[HKEY_CLASSES_ROOT\Interface\{E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4}\ProxyStubClsid32]
@="{3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F}"

Note that you need to modify the file location.

Use this to unregister:

Windows Registry Editor Version 5.00

[-HKEY_CLASSES_ROOT\CLSID\{2EACA947-7F5F-4CFA-BA87-8F7FBEEFBE69}]

[-HKEY_CLASSES_ROOT\CLSID\{E12CFF52-A866-4C77-9A90-F570A7AA2C6B}]

[-HKEY_CLASSES_ROOT\CLSID\{3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F}]

[-HKEY_CLASSES_ROOT\Interface\{59D55CCE-FC8A-48B4-ACE8-0A9286C6557F}]

[-HKEY_CLASSES_ROOT\Interface\{746E6BC0-AB05-4E38-AB14-71E86763141F}]

[-HKEY_CLASSES_ROOT\Interface\{AA6B364F-4A50-4176-9002-0AE755E7B5EF}]

[-HKEY_CLASSES_ROOT\Interface\{E686C757-9A35-4A1C-B3CE-0BCC8B5C69F4}]

Use this to set default terminal for current user:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Console\%%Startup]
"DelegationConsole"="{2EACA947-7F5F-4CFA-BA87-8F7FBEEFBE69}"
"DelegationTerminal"="{E12CFF52-A866-4C77-9A90-F570A7AA2C6B}"

[feeas]

@ysc3839 Have you tested this reg file? I tested it on two PCs, but both failed. I can see Windows Command Processor and OpenConsole running in Task Manager, but no WindowsTerminal.exe is started. I can launch WindowsTerminal.exe directly, and I’ve confirmed that my path is correct.

edited: I resolved the issue by downgrading from version v1.22.2702.0 to v1.21.2701.0. Is this a problem with the new version of Windows Terminal? It's really strange. No more issues now. Thank you very much for your registry. It was really helpful and also solved the issue with administrator scripts being unable to invoke Windows Terminal.

[CrendKing]

Thank you @ysc3839 ! Those registry works for me. More interestingly, when I open a .cmd or .ps1 file, even though Windows Terminal shows up, from the task manager I can see there is still a cmd.exe there. So it seems like there is some proxying happened.

Also, Settings -> System -> For developers -> Terminal doesn't have Windows Terminal as a selectable.

[DHowett]

I can see there is still a cmd.exe there

cmd.exe is the Command Prompt. You should only see it when you launch a .cmd file or Windows Command Prompt.

I suspect you are mixing up cmd (the shell) and conhost (the console).

Conhost is usually in charge of the window and the keyboard input. In the "default terminal" case, conhost is still running (there are some annoying reasons for this today) but it hands off to another instance of itself called OpenConsole. OpenConsole talks to Terminal.

[CrendKing]

I'm sorry I probably misremembered the case before. There is nothing weird about the registry method. Everything works as expected.

Is there any chance we can make it more official than a comment in an issue? I'm sure we can include this in the Scoop manifest and make the portable installation more smooth.

[ysc3839]

@feeas Version 1.22 uses a new COM interface, I didn't add its interface id to the reg file.

@CrendKing The default terminal selection list requires packaged app (AppX or MSIX).

[CrendKing]

Do you mean we need a new reg for future versions?

[DHowett]

You just need another interface entry,

{6F23DA90-15C5-4203-9DB0-64E73F1B1B00}

[CrendKing]

Thanks for the info. But this doesn't seem to be very future-proof. How to expect a normal user to find out all these obscure interface IDs, let alone to put them in registry? And one day there might be another new interface.

I feel this should be treated the same level as how portable mode is treated. The latter at least has a dedicated document page section to explain how it works. If a user is able to create a ".portable" file, surely they can run a "register_windows_terminal_as_default.ps1" if it is provided and maintained by the WT team, right?

[ysc3839]

@CrendKing This is for third-party terminal developers to implement a "register as default terminal" function. It's not for end users.

[CrendKing]

I'm sorry if I sounded as it is for end user. I was talking about third-party package maintainers. If I maintain the Scoop Windows Terminal manifest, I'd love to have official information on how to register the installed terminal as default, which is, as you can see, lacking in that manifest. It only contains creating the .portable file.

[feeas]

@DHowett Could you tell me if adding this will make it work in version 1.22? I tried but it didn't work.

Windows Registry Editor Version 5.00
[HKEY_CLASSES_ROOT\Interface\{6F23DA90-15C5-4203-9DB0-64E73F1B1B00}\ProxyStubClsid32]
@="{3171DE52-6EFA-4AEF-8A9F-D02BD67E7A4F}"

[ysc3839]

@feeas Currently 1.22 is Preview, its CLSID is different from normal version.