IVsExternalFilesManager2.TransferDocument Method

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

Transfers a document to the Miscellaneous Files project.

public:
 int TransferDocument(System::String ^ pszMkDocumentOld, System::String ^ pszMkDocumentNew, Microsoft::VisualStudio::Shell::Interop::IVsWindowFrame ^ punkWindowFrame);

public:
 int TransferDocument(Platform::String ^ pszMkDocumentOld, Platform::String ^ pszMkDocumentNew, Microsoft::VisualStudio::Shell::Interop::IVsWindowFrame ^ punkWindowFrame);

int TransferDocument(std::wstring const & pszMkDocumentOld, std::wstring const & pszMkDocumentNew, Microsoft::VisualStudio::Shell::Interop::IVsWindowFrame const & punkWindowFrame);

public int TransferDocument (string pszMkDocumentOld, string pszMkDocumentNew, Microsoft.VisualStudio.Shell.Interop.IVsWindowFrame punkWindowFrame);

abstract member TransferDocument : string * string * Microsoft.VisualStudio.Shell.Interop.IVsWindowFrame -> int

Public Function TransferDocument (pszMkDocumentOld As String, pszMkDocumentNew As String, punkWindowFrame As IVsWindowFrame) As Integer

Parameters

pszMkDocumentOld

String

[in] Specifies the original path to the file to be transferred.

pszMkDocumentNew

String

[in] Specifies the new path to the file.

punkWindowFrame

IVsWindowFrame

[in] Specifies the pointer to the open window for the file.

Returns

Int32

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

Implements

TransferDocument(String, String, IVsWindowFrame)

Remarks

COM Signature

From vsshell.idl:

HRESULT IVsExternalFilesManager2::TransferDocument(  
   [in] LPCOLESTR pszMkDocumentOld,  
   [in] LPCOLESTR pszMkDocumentNew,  
   [in] IVsWindowFrame *punkWindowFrame  
);  

This is the implementation of the Open External File command on the system File menu. If no project can service this file and the Miscellaneous Files (External Files) project is not already present, the environment creates the Miscellaneous Files project and tries again.

In the environment, the Miscellaneous Files project is implemented using the external files manager (IVsExternalFilesManager). This interface allows you to manipulate the Miscellaneous Files project.

If you have a World Wide Web project, then the definition of your project system is tightly bound to the fact that your Web pages reside in a specific directory mimicking the hierarchy of the Web site. If your project has a file open from the Web and the user chooses to do a Save As on that file to save it to a floppy disk, then that file can no longer be considered a file that belongs to the Web site because it does not live in the directory of the Web site. The environment's model of Save As is that the open editor tracks the file in its new location. That is, the editor continues editing the new file in its new location and the old file remains unchanged in the original location and is no longer open. Because the new file is no longer a member of the Web site project, the project system hands the open editor to the Miscellaneous Files project.

To complete this transfer, the hierarchy/itemID owner of the project (in this example, the Web project) calls Query Service for SID_SVsExternalFilesManager to receive a pointer to IVsExternalFilesManager. The project then calls TransferDocument passing in the old document moniker (pszMkDocumentString) for the document when it was in the Web project. This moniker could be a URL, http:// or UNC path and is the key to the original file in the running document table (RDT). It also passes the new pszMkDocumentString and the new open window frame pointer. The Miscellaneous Files project then transfers the file to its project, allocates a new item ID for it, and then updates the RDT by calling RenameDocument Method. Window frames and different entities that listen for RDT events then know to update their references to the document.