Applies a function filter using a configuration file

Remarks

This project demonstrates how to use a function filter to restrict which add-in functions are made available to users. The project uses a configuration file to apply the policy, so that only add-in functions which are listed in the configuration file with a setting of true or 1 will be made available to users.

The configuration file should have the same root as the add-in itself, and an extension of .functionfilter: PublishRT.functionfilter. The contents of the file, as delivered, are as follows:

ReadyFn 1
ReadyFn2 1
NotReadyFn 0
NotReadyFn2 0

In the configuration file, PublishRT.functionfilter, the functions included fall into 3 groups.

1. ReadyFn & ReadyFn2 are listed as 1
2. NotReadyFn & NotReadyFn2 are listed as 0
3. OtherFn & OtherFn2 are not listed

Because a function filter is being applied, ReadyFn & ReadyFn2 will be published, but NotReadyFn & NotReadyFn2 will not. Because they are not specifically listed, and the configuration file is CXllFunctionFilterLoader::EXPLICIT, OtherFn & OtherFn2 will be published.

The only code added to the sample to achieve the filtering is the following:

#ifndef _DEBUG
CXllFunctionFilterEventHandlerFromFile theFunctionFilter(CXllFunctionFilterLoader::EXPLICIT);
#endif

This code declares a static global instance of CXllFunctionFilterEventHandlerFromFile, which automatically runs the filtering code just before add-in functions are registered with Excel. As a result, the configuration file is loaded and parsed, and any function that is marked as 0 or false will be suppressed.

Note that the code is surrounded by a #ifndef _DEBUG ... #endif block, so that the filter only applies to the Release build. This means that in the Debug build, the developer can continue to work with the functions that are filtered out.

Inspect the build properties of the configuration file, to see that the Custom Build Tool settings have been used to deliver the file from the source directory to the output directory whenever a build occurs.

For a discussion of function filtering, see the User Guide topic Publishing and suppressing add-in functions.

Requirements

To edit the functions in this add-in, you need to load the extension file FunctionFilter.xpe which is located in the extensions directory of your XLL+ installation. See Loading an extension file for instructions.

Classes and functions used

CXllFunctionFilter | CXllFunctionFilterEventHandlerFromFile

Sample project

Each sample project is located in a sub-directory of the Samples directory of the XLL+ installation. To use the sample project, open the solution file PublishRT.sln or the project file PublishRT.vcproj.

You can enable debugging under Excel by using the Setup Debugging command in the XLL+ ToolWindow.

When delivered, the help files are excluded from the build. You can enable the help build by selecting the files PublishRT.help.xml and PublishRT.chm in the Solution Explorer, and using the right-click menu to view Properties. Select the page "Configuration Properties/General" and set the "Excluded from build" property to "No". See Generating help in the User Guide for more information.

See Also

List of Sample Projects | Publish Opt-In Demo | Publish Opt-Out Demo | Publishing and suppressing add-in functions (User Guide)