IVsUIHierarchy.GetCanonicalName(UInt32, String) Method

Reference

Definition

Namespace:: Microsoft.VisualStudio.Shell.Interop

Assembly:: Microsoft.VisualStudio.Shell.Interop.dll

Assembly:: Microsoft.VisualStudio.Interop.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Used for workspace persistence, for example, for remembering window positions.

public:
 int GetCanonicalName(System::UInt32 itemid, [Runtime::InteropServices::Out] System::String ^ % pbstrName);

int GetCanonicalName(unsigned int itemid, [Runtime::InteropServices::Out] std::wstring const & & pbstrName);

public int GetCanonicalName (uint itemid, out string pbstrName);

abstract member GetCanonicalName : uint32 * string -> int

Public Function GetCanonicalName (itemid As UInteger, ByRef pbstrName As String) As Integer

Parameters

itemid: UInt32

[in] Identifier of the hierarchy item. For a list of itemid values, see VSITEMID.

pbstrName: String

[out] Pointer to the canonical name of the hierarchy item.

Returns

Int32

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Implements

GetCanonicalName(UInt32, String)

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsUIHierarchy::GetCanonicalName(  
   [in] VSITEMID itemid,  
   [out] BSTR *pbstrName  
);

A hierarchy is an object that contains many items, but does not necessarily contain an object for each of those items. Thus, to get information about any of the hierarchy items, you need to query the hierarchy object for that information. The item identifier (itemid) is used to identify the requested item in that query. Using the GetCanonicalName method, you pass in the itemid and the canonical name is returned. The canonical name is a unique name used to distinguish a particular item in the hierarchy from every other item in the hierarchy.

Canonical names do not change between sessions of the environment, but item identifiers do. Use this method to manage workspace persistence, such as remembering window positions.

Note

The environment typically calls this method, but it can be called by anyone with a hierarchy object and a particular item identifier.

Use ParseCanonicalName to determine an item identifier (item ID), given the canonical name for an item.

Applies to