budul.PrismTaskPanes.DryIoc.PowerPoint 6.0.0

PrismTaskPanes

Prism based WPF task panes for Microsoft Excel and PowerPoint COM add-ins built with NetOffice and .NET.

PrismTaskPanes takes care of the plumbing between Office custom task panes and Prism: it creates the task panes, hosts your WPF views in them, wires up a DryIoc container with Prism modules and navigation, and keeps a separate scope per document.

Features

• Declarative task panes via attributes on the add-in class
• Prism modules, regions and navigation inside Office task panes
• One DryIoc scope per workbook or presentation
• Visibility, size and dock position of each task pane are remembered per document
• COM host for .NET (no .NET Framework, no regasm)

Packages

Requirements

• Windows with Microsoft Excel or PowerPoint (Microsoft 365 or Office 2016 and newer)
• .NET 10 Desktop Runtime in the bitness of Office (x64 or x86)
• An add-in project targeting net10.0-windows with EnableComHosting set to true

Getting started

1. Create the add-in project

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0-windows</TargetFramework>
    <EnableComHosting>true</EnableComHosting>
  </PropertyGroup>

  <ItemGroup>
    <EmbeddedResource Include="RibbonUI.xml" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="budul.PrismTaskPanes.DryIoc.Excel" Version="x.y.z" />
  </ItemGroup>

</Project>

The package copies PrismTaskPanes.Host.comhost.dll and PrismTaskPanes.Host.runtimeconfig.json to the output folder. Both files must be deployed together with the add-in.

2. Declare the task panes and register the host

[COMAddin("My Excel Add-In", "Description of my add-in.", LoadBehavior.LoadAtStartup),
    ProgId("MyCompany.MyExcelAddIn"),
    Guid("00000000-0000-0000-0000-000000000000"),
    RegistryLocation(RegistrySaveLocation.LocalMachine),
    Codebase,
    ComVisible(true)]
[CustomUI("RibbonUI.xml", true)]
[PrismTaskPane("Main", "My task pane", typeof(MainView), "MainRegion")]
public class AddIn : COMAddin, ITaskPanesReceiver
{
    private TaskPanesProvider provider;

    [ComRegisterFunction]
    public static void Register(Type type)
    {
        RegisterFunction(type);
        type.RegisterTaskPaneHost();
    }

    [ComUnregisterFunction]
    public static void Unregister(Type type)
    {
        UnregisterFunction(type);
        type.UnregisterTaskPaneHost();
    }

    public override void CTPFactoryAvailable(object CTPFactoryInst)
    {
        base.CTPFactoryAvailable(CTPFactoryInst);

        provider = new TaskPanesProvider(
            receiver: this,
            officeApplication: Application,
            ctpFactoryInst: CTPFactoryInst,
            showErrorIfAlreadyLoaded: true);

        provider.OnConfigureModuleCatalogEvent += (s, e) => e.Content.AddModule<MainModule>();
        provider.OnRegisterTypesEvent += (s, e) => e.Content.RegisterInstance<IMyService>(new MyService());
    }

    // Called by PrismTaskPanes whenever the state of a task pane changes
    public void InvalidateRibbonUI()
    {
        RibbonUI?.Invalidate();
    }

    // Ribbon callbacks
    public void ToggleMainPane(IRibbonControl control, bool pressed)
    {
        provider.SetTaskPaneVisibility(id: "Main", isVisible: pressed);
    }

    public bool IsMainPaneVisible(IRibbonControl control)
    {
        return provider.TaskPaneIsVisible(id: "Main");
    }
}

For PowerPoint, reference budul.PrismTaskPanes.DryIoc.PowerPoint and use PrismTaskPanes.DryIoc.PowerPoint.TaskPanesProvider with a NetOffice.PowerPointApi.Application. Everything else is identical.

3. Add a toggle button to the ribbon

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="CustomUI_OnLoad">
  <ribbon>
    <tabs>
      <tab id="MyTab" label="My Add-In">
        <group id="MyGroup" label="My Add-In">
          <toggleButton id="ToggleMainPane" label="Task pane" size="large" imageMso="CreateFormBlankForm"
                        getPressed="IsMainPaneVisible" onAction="ToggleMainPane" />
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

4. Create the module, view and view model

Reference budul.PrismTaskPanes.View in the project containing the views.

public class MainModule : IModule
{
    public void RegisterTypes(IContainerRegistry containerRegistry)
    {
        containerRegistry.RegisterForNavigation<MainView>();
    }

    public void OnInitialized(IContainerProvider containerProvider)
    {
        containerProvider.Resolve<IRegionManager>()
            .RegisterViewWithRegion(regionName: "MainRegion", viewType: typeof(MainView));
    }
}

View models deriving from ScopedContentBase are initialized when the task pane navigates to them:

public class MainViewModel : ScopedContentBase
{
    public MainViewModel(IMyService service)
    {
        // Constructor injection works with the scope of the current document
    }

    protected override void Initialize(NavigationContext navigationContext)
    {
        // Called on every navigation to this view
    }
}

If InitializeComponent() fails because the XAML resources cannot be resolved inside the Office process, load the BAML explicitly:

public MainView()
{
    try
    {
        InitializeComponent();
    }
    catch (Exception)
    {
        this.LoadViewFromUri("/MyViews;component/views/mainview.xaml");
    }
}

5. Register the add-in

Register the COM host of the add-in with administrator rights:

regsvr32 MyExcelAddIn.comhost.dll

This calls the ComRegisterFunction, which registers the add-in in Office and the PrismTaskPanes host on the machine. To remove the add-in, call regsvr32 /u on the same file.

Configuration

PrismTaskPane attribute

The attribute can be applied several times to declare several task panes.

Provider events

The current scope is available via provider.Scope. The Office application object, the receiver and the provider itself are registered in the container automatically.

Limitations

• One PrismTaskPanes add-in per Office session. Only one add-in based on PrismTaskPanes can be active in an Excel or PowerPoint process at a time. With showErrorIfAlreadyLoaded: true the user is informed if another one is loaded already.
• One .NET runtime per Office process. All .NET add-ins loaded into the same Office process must run on the same major .NET version. An add-in built for an older .NET version cannot be loaded once a newer runtime is active, and vice versa.
• Machine-wide registration. The PrismTaskPanes host is registered once per machine. Registration requires administrator rights.

Examples

The Examples folder contains two Excel and two PowerPoint add-ins together with a shared Prism module. Build the solution in Debug configuration with administrator rights to register them automatically.

License

MIT