IVsCfgProviderEventsHelper Interface

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

Implemented by the environment, called by projects to use as a helper implementing IVsCfgProvider2.

public interface class IVsCfgProviderEventsHelper

public interface class IVsCfgProviderEventsHelper

__interface IVsCfgProviderEventsHelper

[System.Runtime.InteropServices.Guid("0D6D480C-894F-48E4-98D2-E0A7127750E4")]
[System.Runtime.InteropServices.InterfaceType(System.Runtime.InteropServices.ComInterfaceType.InterfaceIsIUnknown)]
public interface IVsCfgProviderEventsHelper

[<System.Runtime.InteropServices.Guid("0D6D480C-894F-48E4-98D2-E0A7127750E4")>]
[<System.Runtime.InteropServices.InterfaceType(System.Runtime.InteropServices.ComInterfaceType.InterfaceIsIUnknown)>]
type IVsCfgProviderEventsHelper = interface

Public Interface IVsCfgProviderEventsHelper

Attributes

GuidAttribute InterfaceTypeAttribute

Remarks

IVsCfgProvider allows you to support platforms and edit configurations for your project. If your project implements IVsCfgProvider2, you must also implement its AdviseCfgProviderEvents and UnadviseCfgProviderEvents methods to sink with clients listening for configuration events fired by IVsCfgProviderEvents.

It is your project's responsibility to maintain an array of clients listening for your project's configuration events. In addition, you also need a mechanism for notifying each of the listeners of the firing of configuration events, so you must have a process whereby you loop through the array and call each one to fire the requested events.

IVsCfgProviderEventsHelper is a helper object that provides that functionality for you by managing the array of listeners for the project, then delegating from IVsCfgProvider2 to the helper to fire events at the correct times to everyone on the list. You know as Configuration Provider when you add, delete, or rename a configuration and you call the helper to notify other objects within your project and the environment of the events. That is why you need to fire these events at the right time. By using this helper object, you only have to pass the fact that a new client is listening for configuration events to the helper, or that a client can be removed from the array. Then, when an event fires, all you have to do is pass a notification of the event to the helper object, which will take on the responsibility of notifying all of the listeners.

By using the helper object, you can turn a call to AdviseCfgProviderEvents into a two line call to AdviseCfgProviderEvents — instantiate the help object if it does not already exist, and use the helper instance to build the array of listener objects to be notified of a configuration event.

IVsCfgProviderEventsHelper is instantiated by calling the CreateInstance method of ILocalRegistry and passing it CLSID_VsCfgProviderEventsHelper. Once an instance of IVsCfgProviderEventsHelper is started, AdviseCfgProviderEvents and UnadviseCfgProviderEvents will add and remove listeners for the events to the array.

Similarly, the implementation of UnadviseCfgProviderEvents passes through to the helper method UnadviseCfgProviderEvents to take the listener out of the array.

Then, when configuration events should be fired, implementing the notification sink events becomes a matter of a one line call from IVsCfgProviderEvents to the appropriate notify method on IVsCfgProviderEventsHelper who will notify all of the listeners in the array. In this way, you can pass one notification that a configuration name was added, for example, from AddCfgsOfCfgName, through OnCfgNameAdded, to NotifyOnCfgNameAdded who will then be responsible for notifying all of the listeners of the event.

You can, of course, implement this IVsCfgProvider2 functionality yourself directly and manage this array of sinks, but the helper makes it simpler by using one line calls to implement Advise, Unadvise, and Notify events.

Notes to Implementers

Implemented by the environment to provide notification of configuration-related events firing.

Notes to Callers

Called by projects that use this object as a helper for implementation of IVsCfgProvider2, it maintains an array of clients listening for events, and fires notifications of configuration events to those clients.

Methods

AdviseCfgProviderEvents(IVsCfgProviderEvents, UInt32)	Called to add listeners for configuration events to the array.
NotifyOnCfgNameAdded(String)	Fired to sink configuration name added events for all listeners in the array.
NotifyOnCfgNameDeleted(String)	Fired to sink configuration name deleted events for all listeners in the array.
NotifyOnCfgNameRenamed(String, String)	Fired to sink configuration name renamed events for all listeners in the array.
NotifyOnPlatformNameAdded(String)	Fired to sink platform name added events for all listeners in the array.
NotifyOnPlatformNameDeleted(String)	Fired to sink platform name deleted events for all listeners in the array.
UnadviseCfgProviderEvents(UInt32)	Called to remove listeners from the array of listeners for configuration events.