Excel-DNA / Excel-DNA/Excel-DNA.github.io
Docs: Custom Task Panes section omits the .NET 6+ COM default-interface requirement
- Dominant language
- JavaScript
- Stars
- 0
- Forks
- 4
- PR merge metrics
- No merged PRs in 30d
Description
### Summary
`src/pages/reference-various.md` → **Custom Task Panes** documents the CTP API but not the COM attribution a `UserControl` needs on .NET 6+. Without it, `CustomTaskPaneFactory.CreateCustomTaskPane` fails with a bare `E_FAIL` (`0x80004005`) and no diagnostic text.
This is already known — you answered it in [issue #558](https://github.com/Excel-DNA/ExcelDna/issues/558) and in the group thread [*CustomTaskPaneFactory.CreateCustomTaskPane throws 'Unable to create specified ActiveX control'*](https://groups.google.com/g/exceldna/c/onRDZLJwoBY):
> You now need an explicit 'default interface' for your type - this will cause the class to implement IDispatch (if it is ComVisible).
The reference page doesn't carry that, so it's still reachable by reading the docs alone.
### What I measured
Standalone add-in, no other dependency, `ExcelDna.AddIn` 1.9.0, SDK 10.0.400, Excel 16.0.20326.20112 x64 Click-to-Run Current Channel, Windows 11 25H2 26200.9168, not elevated, Defender only, Trust Center at defaults.
Control under test:
```csharp
[ComVisible(true)]
public sealed class FixedLabelControl : UserControl
{
public FixedLabelControl() => Controls.Add(new Label { Text = "Repro Pane", AutoSize = true });
}
```
| Target | Runtime | Result |
|---|---|---|
| `net10.0-windows` | 10.0.11 | `COMException`, HRESULT `-2147467259` (`0x80004005`) |
| `net7.0-windows` | 7.0.7 | `COMException`, HRESULT `-2147467259` (`0x80004005`) |
Byte-identical source both times; only the TFM differed. Adding the documented attribution and changing nothing else:
```csharp
[ComVisible(true)]
[Guid("...")]
public interface IFixedLabelControl { }
[ComVisible(true)]
[Guid("...")]
[ComDefaultInterface(typeof(IFixedLabelControl))]
public sealed class FixedLabelControl : UserControl, IFixedLabelControl { ... }
```
`net10.0-windows` then completed the full lifecycle — create, show, hide, delete, dispose — with no HRESULT.
Because the requirement splits .NET Framework from .NET Core rather than one .NET version from another, a net7-vs-net10 comparison can't discriminate it: both fail identically. That cost me a fair amount of bisecting before I found #558, which is really the motivation for this request.
### Suggested addition
After the `CreateCustomTaskPane` example in the **Custom Task Panes** section:
> **.NET 6 and later:** the control needs an explicit COM default interface. .NET Framework generated a class interface automatically, so a `[ComVisible(true)] UserControl` had a usable `IDispatch`; .NET Core and later do not, and `CreateCustomTaskPane` then fails with `E_FAIL` / "Unable to create specified ActiveX control".
>
> ```csharp
> public interface IMyUserControl { }
>
> [ComVisible(true)]
> [Guid("....")]
> [ComDefaultInterface(typeof(IMyUserControl))]
> public class MyUserControl : UserControl, IMyUserControl { }
> ```
Happy to open a PR against `src/pages/reference-various.md` if that's easier.
### Separately, if it's ever cheap to do
`ExcelCustomTaskPane.CreateCustomTaskPane` already logs a helpful message for the `UnauthorizedAccessException` registry case. A comparable hint when `ICTPFactory.CreateCTP` throws `E_FAIL` — pointing at the default-interface requirement — would make this self-diagnosing. Entirely optional; the docs change is the ask.
Contributor guide
No contributing guide indexed for this repository
Research direction
Open src/pages/reference-various.md and read the Custom Task Panes section, especially the CreateCustomTaskPane example; compare it with the guidance in issue #558. Add the .NET 6+ explicit COM default-interface requirement and example after that section, while keeping the optional diagnostic change separate. Done means the reference page explains the E_FAIL cause and shows the required attribution clearly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100