Using EPiServer VirtualPathUnifiedProvider

Searching the Internet for EPiServer's VirtualPathUnifiedProvider, I didn't find much information.
So here I'm going to show you some basic examples how you can use it in your EPiserver projects.

VirtualPathUnifiedProvider inherits from asp.net VirtualPathProvider, and adds new functionality. It serves as a base class to all unified providers like VirtualPathNativeProvider, VirtualPathVersioningProvider. It is not ment to be used directly therefore it is abstract and you can use it to implement your own file system, for example a database file system. The most important classes which this provider works with are UnifiedDirectory, UnifiedFile, UnifiedSummary, UnifiedVersion.

Accessing files and folders.

VirtualPathUnifiedProvider vpp =
            System.Web.Hosting.HostingEnvironment.VirtualPathProvider as VirtualPathUnifiedProvider;

        if (vpp != null)
        {
            // get all file names in a directory
            List<string> fileNames = new List<string>();
            UnifiedDirectory dir = vpp.GetDirectory("/upload") as UnifiedDirectory;
            if (dir != null)
            {
                System.Collections.IEnumerable allFiles = dir.Files;
                foreach (UnifiedFile file in allFiles)
                {
                    fileNames.Add(file.Name);
                }
            }
            // get all subdirectories
            List<string> subdirectoryNames = new List<string>();
            if (dir != null)
            {
                System.Collections.IEnumerable allSubDirs = dir.Directories;
                foreach (UnifiedDirectory subDir in allSubDirs)
                {
                    subdirectoryNames.Add(subDir.Name);
                }
            }
        }

The check here for vpp is neccessary because the current registered provider can be of another type.
GetDirectory is base method of VirtualDirectory. If it doesn't find such directory it's result will vary depending of your custom provider implementation. For example it can be null, or MapPathBasedVirtualDirectory.

Creating file and subdirectories is straightforward:
if (dir != null)
{
// create new file
    UnifiedFile newFile = dir.CreateFile("CustomContentFile.txt");
    using (Stream fs = newFile.Open(FileMode.Create, FileAccess.ReadWrite, FileShare.None))
    {
        using (StreamWriter writer = new StreamWriter(fs))
        {
            writer.WriteLine("Custom content");
     }
}
  // Create and copy subdirectory
if (dir != null)
{
    UnifiedDirectory subdir1 = dir.CreateSubdirectory("subdirectory1");
    UnifiedDirectory subdir2 = dir.CreateSubdirectory("subdirectory2");
    subdir2.CopyTo(VirtualPathUtility.Combine(subdir1.VirtualPath, subdir2.Name));
  }
}

FileMode options here can vary. It can be either Create or CreateNew. FileMode.Open can be used if the file already exists and you want to write to it, instead of creating a new one. When copying a directory, the new path has to be specified. This is why the destination path of subdir1 is combined with the name of subdir2.

System.Web.VirtualPathUtility is used for file and directory related operations. It has various helper methods like Combine, GetDirectory, GetExtension, GetFileName, IsAbsolute, etc. 

This example renames already existing file:

UnifiedFile customFile = vpp.GetFile("/Upload/CustomContentFile.txt") as UnifiedFile;
if (customFile != null)
{
    string destinationDir = VirtualPathUtility.GetDirectory(customFile.VirtualPath);
    customFile.MoveTo(VirtualPathUtility.Combine(destinationDir, "NewFilename.txt"));
}

MoveTo can be used either for renaming or moving a file. If destination directory is the same as the source file directory - the file name will be changed, otherwise the file will be moved to the new location.

These are some of the basic operations, which you can do with VirtualPathUnifiedProvider. However, if you create a custom implementation, its behavior can be slightly different. One great way to test it is by EPiServer's file manager. If everything works fine there, then these examples  should work also.