Proposal: Support object IDs

Object IDs

When debugging managed code, users are able to track a certain variable outside its scope by creating an Object ID for it. An adapter can take this request and create an ID associated with the variable. It supports both variables created from an expression evaluation and an existing variable in the debuggee.

For expression evaluation results, we also extended EvaluateResponse with a reference identifier which can be used afterwards when referencing to the variable produced from that result. This is used when creating an ID for the evaluation result, but it can also be used with other features going forward.

See the documentation for Track an out-of-scope object for more details.

interface EvaluateResponse {
    // ...

    /**
     * Reference integer for the evaluated expression result. This can be used when referencing the result on further requests.
     * The value should be less than or equal to 2147483647 (2^31 - 1).
     */
    evaluateResponseReference?: number;

    // ...
}

interface Capabilities {
    // ...

    /** The debug adapter supports creating and destroying object IDs on variables. */
    supportsObjectId?: boolean;
}

/** 
 * Create an object ID for the target variable.
 * After issuing a 'createObjectId' request, the client should requery the value of all displayed variables, as debug adapters 
 * would likely want to include the created id for the object in the variable's value.
 * Clients should only call this request if the capability 'supportsObjectId' is true.
 */
interface CreateObjectIdRequest extends Request {
    // command: 'createObjectId'
    arguments: CreateObjectIdArguments;
}

/** Arguments for 'createObjectId' request */
interface CreateObjectIdArguments{
  /**
   * Optional value, should be used when referencing to a local variable.
   * The reference of the variable container for the variable used for creating the object ID.
   */
  variablesReference?: number;

  /**
   * Optional value, should be used when referencing to a local variable.
   * The name of the variable in the container to create the object ID.
   * Valid variables have a VariablePresentationHint attribute of 'canHaveObjectId', which indicates that the object can 
   * have an object ID created for it.
   * Valid variables do not have a VariablePresentationHint attribute of 'hasObjectId', which indicates that the object already has
   * an object ID associated with it.
   */
  name?: string;

  /**
   * Optional value, should be used when referencing to an evaluation result.
   * The reference to the evaluation result identifier to create the object ID.
   * Valid variables have a VariablePresentationHint attribute of 'canHaveObjectId', which indicates that the object can 
   * have an object ID created for it.
   * Valid variables do not have a VariablePresentationHint attribute of 'hasObjectId', which indicates that the object already has
   * an object ID associated with it.
   */
  evaluateResponseReference?: number;
}

/** Response for 'createObjectId' request */
interface CreateObjectIdResponse extends Response {
}

/** 
 * Destroy the object id associated with the target variable.
 * After issuing a 'destroyObjectId' request, the client should requery the value of all displayed variables, as debug adapters 
 * would likely want to remove the created id for the object in the variable's value.
 * Clients should only call this request if the capability 'supportsObjectId' is true.
 */
interface DestroyObjectIdRequest extends Request {
    // command: 'destroyObjectId'
    arguments: DestroyObjectIdArguments;
}

/** Arguments for 'destroyObjectId' request */
interface DestroyObjectIdArguments {
  /**
   * Optional value, should be used when referencing to a local variable.
   * The reference of the variable container for the variable used for destroying its object ID.
   */
  variablesReference?: number;

  /**
   * Optional value, should be used when referencing to a local variable.
   * The name of the variable in the container to destroy its object ID.
   * Valid variables have a VariablePresentationHint attribute of 'hasObjectId', which indicates that the object has
   * an object ID associated with it.
   */
  name?: string;

  /**
   * Optional value, should be used when referencing to an evaluation result.
   * The reference to the evaluation result identifier to destroy its object ID.
   * Valid variables have a VariablePresentationHint attribute of 'hasObjectId', which indicates that the object has
   * an object ID associated with it.
   */
  evaluateResponseReference?: number;
}

/** Response for 'destroyObjectId' request */
interface DestroyObjectIdResponse extends Response {
}

CC: @andrewcrawley, @weinand

Start with the EvaluateResponse, Capabilities, CreateObjectIdRequest, and DestroyObjectIdRequest interfaces described in the issue, and inspect where these protocol definitions are maintained. Confirm how evaluation references, capability flags, variable presentation hints, and both request responses should be represented; done means the object-ID proposal is fully integrated into the protocol definitions and documented behavior.