One of the workflows provided by the VDF is downloading a file. When downloading a file from Vault, there are usually several other steps involved besides just pulling down the bits from the Vault server.
These include things like determining the working folder location for the file, displaying a progress dialog, repairing broken file reference due to moves or renames, etc. Even if client apps don't need any of this business logic, the VDF layer provides additional benefits such as performance improvements with parallel downloading of files and hiding the complexity of dealing with the Filestore service.
Like several of the areas of functionality provided by the VDF, there are both GUI and non-GUI versions of acquire files API methods. The non-GUI acquire file method is accessed off the FileManager service which lives off the VDF Connection class. This service provides a few different methods for working with Vault files. The specific method to use for downloading one or more Vault files comes in two flavors, FileManager.AcquireFiles() and FileManager.AcqurieFilesAsync(). As the name implies, the first is a synchronous download call while the second is an asynchronous call that will return immediately with a System.Threading.Tasks.Task that you can use to schedule a continuation on. The GUI versions of the acquire files methods are similarly named AcquireFiles() and AcquireFilesAsync() but instead are accessed off the VDF.Vault.Forms.Library class. As with the non-GUI method, the async GUI version will return control to the calling method almost immediately and returns a Task of the actual acquire work. The GUI methods will, by default, display a progress dialog to the user during the download. The progress dialog will be modeless if the async version was used and will be a modal dialog, otherwise.
All of these different acquire methods accept some form of a settings object to control various aspects of the acquire workflow. The non-GUI methods accept the VDF.Vault.Settings.AcquireFilesSettings class as a parameter. This class is used as the base class for all different flavors of the download settings. The GUI versions of the acquire files methods accept two different versions settings classes that have the AcquireFilesSettings class as a base class. These are the VDF.Vault.Forms.Settings.ProgressAcquireFilesSettings class and the VDF.Vault.Forms.Settings.InteractiveAcquireFilesSettings class. Either of these settings classes can be passed into the GUI acquire file methods. If client applications use the ProgressAcquireFilesSettings, then the user will only see a progress dialog during a file download. If an instance of InteractiveAcquireFilesSettings is instead passed into the GUI acquire files methods, the VDF will display a "get/checkout" dialog to the user before attempting to download files. Using this dialog, the user can modify some of the download settings before the download begins, such as specifying whether to checkout certain files or change the download location.
Client applications will largely use all the different acquire files settings classes in the same way. The general process of setting up the acquire files settings typically has just two steps. First, simply create a new instance of the settings class. The setting's constructors takes a VDF connection, and this connection must be the connection to the Vault that the client app is trying to download files from. Second, add the files you want to acquire (aka download) to the settings instance using the AcquireFilesSettings.AddEntityToAcquire() method. Of course, there are several other settings and extensibility points that can be tweaked. More details on the other setting's properties can be found in the SDK documentation. Once the settings are complete, call the appropriate AcquireFiles[Async]() method and pass in the settings as a parameter. An example of an acquire workflow using the VDF can be seen in the "VaultBrowserSample" sample app that comes packaged with the SDK.
Moving from the 2013 SDK Download API to the 2014 Download API
For developers who are most interested in performing a direct port from the 2013 SDK to the 2014 SDK, they will likely focus on using the non-GUI, synchronous download method, FileManager.AcquireFiles(). This is because the previous versions of SDK didn't provide any GUI or asynchronous components or methods and so it is likely that the client applications to be updated will already have some sort of existing GUI or code to which files to download and/or checkout. Most 2013 applications probably downloaded files from the Vault using the DocumentService's DownloadFile() method. This method simply pulls down the bytes for a given file in Vault. Some code using it might look something like this:
The code above downloads the bytes for a given file from Vault and writes them to disk at a certain location. Some code that uses the VDF to accomplish the same goal would likely look something like this:
