Implement and register a port supplier

  • Article

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

The role of a port supplier is to track and supply ports, which in turn manage processes. When a port needs to be created, the port supplier is instantiated using CoCreate with the port supplier's GUID (the session debug manager [SDM] will use the port supplier that the user selected or the port supplier specified by the project system). The SDM then calls CanAddPort to see if any ports can be added. If a port can be added, a new port is requested by calling AddPort and passing it an IDebugPortRequest2 that describes the port. AddPort returns a new port represented by an IDebugPort2 interface.

Discussion

A port is created by a port supplier, which is associated with a machine or debug server. A server enumerates its port suppliers through theEnumPortSuppliers method, and a port supplier enumerates its ports through the EnumPorts method.

In addition to the typical COM registration, a port supplier must register itself with Visual Studio by placing its CLSID and name in specific registry locations. A Debugging SDK helper function called SetMetric handles this chore: it is called once for each item to be registered, thus:

SetMetric(metrictypePortSupplier,
          <GUID of your port supplier>,
          metricCLSID,
          <CLSID of your port supplier>,
          false,
          NULL)
SetMetric(metrictypePortSupplier,
          <GUID of your port supplier>,
          metricName,
          <name of your port supplier>,
          false,
          NULL);

A port supplier unregisters itself by calling RemoveMetric (another Debugging SDK helper function) once for each item that was registered, thus:

RemoveMetric(metrictypePortSupplier,
             <GUID of your port supplier>,
             metricCLSID,
             NULL);
RemoveMetric(metrictypePortSupplier,
             <GUID of your port supplier>,
             metricName,
             NULL);

Note

The SDK helpers for debuggingSetMetric and RemoveMetric are static functions defined in dbgmetric.h and compiled into ad2de.lib. The metrictypePortSupplier, metricCLSID, and metricName helpers are also defined in dbgmetric.h.

A port supplier can supply its name and GUID through the methods GetPortSupplierName and GetPortSupplierId, respectively.

See also