IVsDataProvider.GetUnsupportedReason Method (Guid, CommandID, Object)

Article
10/03/2012

Gets a localized string that explains why an operation is not supported for the specified DDEX data source.

Namespace: Microsoft.VisualStudio.Data.Core
Assembly: Microsoft.VisualStudio.Data.Core (in Microsoft.VisualStudio.Data.Core.dll)

Syntax

'Declaration
Function GetUnsupportedReason ( _
    source As Guid, _
    command As CommandID, _
    context As Object _
) As String

string GetUnsupportedReason(
    Guid source,
    CommandID command,
    Object context
)

String^ GetUnsupportedReason(
    Guid source, 
    CommandID^ command, 
    Object^ context
)

abstract GetUnsupportedReason : 
        source:Guid * 
        command:CommandID * 
        context:Object -> string

function GetUnsupportedReason(
    source : Guid, 
    command : CommandID, 
    context : Object
) : String

Parameters

source
Type: System.Guid

A DDEX data source identifier.

command
Type: System.ComponentModel.Design.CommandID

A command that identifies the operation.

context
Type: System.Object

An object that represents the context in which the operation exists.

Return Value

Type: System.String
A localized string that explains why the specified operation is not supported, if the operation is in fact not supported; otherwise, nulla null reference (Nothing in Visual Basic).

Exceptions

Exception	Condition
ArgumentNullException	The command parameter is nulla null reference (Nothing in Visual Basic).
[<ANY>]	The DDEX provider's GetUnsupportedReason implementation threw an exception.

Remarks

This method enables DDEX clients to provide users with a specific reason explaining why an operation they tried to perform is not supported in the current environment. The environment can differ, depending on which edition of Visual Studio is running and which runtime components are installed on the computer. The former is typically controlled by the edition of Visual Studio (for example, restricting some commands on the Express editions), whereas the latter is typically controlled by a provider’s IVsDataProviderDynamicSupport implementation, if there is one.

Many operations occur within some larger context. The simplest example of this is Open command for the connection, which occurs in the context of a particular connection. The context parameter of GetUnsupportedReason enables a recognizable object to be passed in and used as part of determining the reason for not supporting the operation.

This method starts by determining whether the edition of Visual Studio has a reason for not supporting the operation. If this query returns nulla null reference (Nothing in Visual Basic) (that is, Visual Studio has no reason for not supporting the operation) and the provider has supplied an IVsDataProviderDynamicSupport implementation, it queries the provider for a reason for not supporting the operation.

Examples

The following code demonstrates how to call the IsOperationSupported method to determine whether the provider supports deleting a particular data explorer node. If it does not, the code calls GetUnsupportedReason to determine an appropriate message to describe why the operation is not supported.

using System;
using System.Windows.Forms;
using System.ComponentModel.Design;
using Microsoft.VisualStudio.Data.Core;
using Microsoft.VisualStudio.Data.Services;

public class DDEX_IVsDataProviderExample7
{
    public static bool AllowDelete(IVsDataProvider provider,
        IVsDataExplorerNode node)
    {
        if (!provider.IsOperationSupported(StandardCommands.Delete, node))
        {
            MessageBox.Show(provider.GetUnsupportedReason(
                StandardCommands.Delete, node));
            return false;
        }
        return true;
    }
}

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Share via