Add README.md (initial commit)

Author: ITHitBuild

README.md

@@ -0,0 +1,51 @@
+
+<h1>Virtual File System Sample in .NET, C#</h1>
+<p>This sample implements a virtual file system with synchronization support, on-demand loading,&nbsp;selective offline files support, upload and download progress, and error reporting. It synchronizes files and folders both from remote storage to the user file system and from the user file system to remote storage. It is written in .NET Core, C#.&nbsp;&nbsp;</p>
+<p>To simulate the remote storage, this sample is using a folder in the local file system on the same machine.&nbsp;</p>
+<p>The purpose of this sample is to demonstrate the major features of the IT Hit User File System for .NET and provide patterns for its programming. You will use this sample as a starting point for creating an OneDrive-like file system for your DMS/CRM/ERP and will reprogram it to publish data from your real storage instead of the local file system.</p>
+<p>You can download this sample and a trial license in the&nbsp;<a href="https://www.userfilesystem.com/download/" title="IT Hit User File System for .NET Download">product download area</a>.</p>
+<h2>Requirements</h2>
+<ul>
+    <li>.NET Core 3.1 or later.</li>
+    <li>Microsoft Windows 10 Creators Update or later version.</li>
+    <li>NTFS file system.</li>
+</ul>
+<h2>Configuring the Sample</h2>
+<p>By default, the sample will use the <span class="code">\RemoteStorage\</span> folder, located under the project root, to simulate the remote storage file structure. It will mount the user file system under the <span class="code">%USERPROFILE%\VFS\</span> folder (typically&nbsp;<span class="code">C:\Users\&lt;username&gt;\VFS\</span>).</p>
+<p>To specify the folder that will be used for remote storage simulation edit the&nbsp;<span class="code">"RemoteStorageRootPath"</span> parameter in <span class="code">appsettings.json</span>. This could be either an absolute path or a path relative to the application root.</p>
+<p>To specify the user file system folder edit the&nbsp;<span class="code">"UserFileSystemRootPath"</span> parameter&nbsp;in <span class="code">appsettings.json</span>.</p>
+<h2>Setting the License</h2>
+<p>To run the example, you will need a valid IT Hit User File System Engine for .NET License. You can download the license in&nbsp;the&nbsp;<a href="https://www.userfilesystem.com/download/" title="IT Hit User File System for .NET Download">product download area</a>.&nbsp;Note that the Engine is fully functional with a trial license and does not have any limitations. The trial license is valid for one month and the engine will stop working after this. You can check the expiration date inside the license file.&nbsp;Download the license file and specify it's content in&nbsp;<span class="code">License</span>&nbsp;field in&nbsp;<span class="code">appsettings.json</span>&nbsp;file.</p>
+<p>You can also run the sample&nbsp;without explicitly specifying a license&nbsp;for 5 days. In this case,&nbsp;the&nbsp;Engine will automatically request the trial license from the IT Hit website https://www.userfilesystem.com. Make sure it is accessible via firewalls if any. After 5 days the Engine will stop working. To extend the trial period you will need to download a license in a&nbsp;<a href="/download/" title="IT Hit User File System for .NET Download">product download area</a>&nbsp;and specify it in&nbsp;<span class="code">appsettings.json</span></p>
+<h2>Running the Sample</h2>
+<p>To run the sample open the project in Visual Studio and run the project in a debug mode.&nbsp;In the debug mode this sample provides additional support for the development and testing convenience. When starting in the debug mode, it will automatically create a folder in which the virtual file system will reside, register the user file system with the platform and then open&nbsp;two instances of Windows File Manager, one of which will show a user file system and another a folder simulating remote storage:</p>
+<p>&nbsp;<a class="link-over-img" href="https://www.userfilesystem.com/media/1985/virtualfilesysteminitialrun.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1985/virtualfilesysteminitialrun.png" alt="Virtual File System Sample Initial Run" rel="116795"></a></p>
+<p>You can start managing and editing files in the <span class="code">\RemoteStorage\</span> folder immediately after the Windows File Managers open and will see all changes being propagated to the user file system. You can also edit documents and manage file structure in the user file system and all changes will automatically appear in the remote storage folder.</p>
+<p>This sample implements on-demand loading. After running the sample all files and folders are marked with a cloud icon<a class="link-over-img" href="https://www.userfilesystem.com/media/1988/offilefile.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1988/offilefile.png" alt="Offline File" rel="116798"></a>, which means that the content of this file or folder is not available locally but instead resides in the remote location. Even though the file shows the correct size in the Size column, the file occupies zero bytes on disk. You can open the file Properties dialog to check the "Size on disk" value. You can see in the console log that only root folder files and folders placeholders are being created when Windows File Manager listed the root folder content. Folders located deeper in the hierarchy is not loaded, until their content is being requested by platform file system calls.&nbsp;</p>
+<p>When any application is accessing the file, located under the <span class="code">\VFS\</span> folder, opening it for reading or writing, the operating system redirects the call to this sample, which loads file content from the remote storage folder. The file becomes marked with a green check-mark on a white background icon<a class="link-over-img" href="https://www.userfilesystem.com/media/1986/localfile.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1986/localfile.png" alt="Local File" rel="116799"></a>, which means the file content is present on the local disk:</p>
+<p style="text-align: center;"><a class="link-over-img" href="https://www.userfilesystem.com/media/1983/localcloudfile.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1983/localcloudfile.png" alt="Local Cloud File. Green check-mark on a white background icon means the file content is present on the local disk." rel="116801"></a></p>
+<p>The Windows File Manager provides the "Always keep on this device" and "Free up space" context menus, which are standard menus provided by Windows OS. If you select the&nbsp;"Always keep on this device" the file or entire folder structure will be recursively loaded to the local disk and all files content will be loaded to local disk and will become available offline. All files and folders are be marked with a pinned file icon<a class="link-over-img" href="https://www.userfilesystem.com/media/1989/pinnedfile.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1989/pinnedfile.png" alt="Pinned File" rel="116800"></a>. Pinned files will not be deleted from the drive even if it runs low on space.</p>
+<p style="text-align: center;"><a class="link-over-img" href="https://www.userfilesystem.com/media/1982/alwayskeeponthisdevice.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1982/alwayskeeponthisdevice.png" alt="Always keep on this device menu will load all files to a loacal disk and will keep them from purging on low disk space." rel="116802"></a></p>
+<p>To remove content from the local disk select the "Free up space" menu. It will restore the cloud icon<a class="link-over-img" href="https://www.userfilesystem.com/media/1988/offilefile.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1988/offilefile.png" alt="Offline File" rel="116798"></a>.</p>
+<p>When a large file is being downloaded from the remote storage, this sample submits progress reports to the operation system, to show a standard Windows "Downloading" dialog. At the same time, the Windows File Manager also shows progress in the files list view:</p>
+<p style="text-align: center;"><a class="link-over-img" href="https://www.userfilesystem.com/media/1984/cloudfiledownloadprogress.png"><img id="__mcenew" src="https://www.userfilesystem.com/media/1984/cloudfiledownloadprogress.png" alt="Large file download from the remote storage show progress reports in Windows File Manager and Files View" rel="116804"></a></p>
+<h2>Microsoft Office Documents Synchronization</h2>
+<p>This sample supports the synchronization of the MS Office documents, avoiding the creation of the temporary files in remote storage. Note that for the sake of simplicity this sample filters MS Office temporary files only during user file system to remote storage synchronization. It is expected that MS Office temporary files are not created in remote storage and you do not need to synchronize them from server to client. Do NOT edit MS Office files directly in the folder simulating the remote storage.</p>
+<h2 id="nav_stoppingthesample" class="heading-link">Stopping the Sample<a class="list-link d-inline" href="#nav_stoppingthesample"></a></h2>
+<p>You can exit the sample running in the debug mode in 2 ways:</p>
+<ul>
+    <li>If you press 'q' the user file system will be unregistered. All files and folders downloaded on disk will be converted into the regular files and folders. The offline files and folders will disappear. This simulates your application's uninstallation process.</li>
+    <li>If you press any other key, the application will exit without unregistering the user file system. All files and folders placeholders, their attributes, and states remain in the user file system, even though most of the functionality, such as downloading file content or listing folder content for offline folders are unavailable. You can start this sample again to continue managing documents. This simulates the machine reboot or application failure.</li>
+</ul>
+<h2>How the Sample Works</h2>
+<h3></h3>
+<p>Initially, when you start the application, the user file system does not contain any file of folder placeholders, except the sync root folder. The content of the folders is populated only when any application is listing folder content. The content of files is loaded only when an application is opening a file for reading or writing.</p>
+<h3>Platform File System Operations Handling</h3>
+<p>Folders content listing, file reads, move/rename and delete is performed by the VfsEngine and VfsFile and VfsFolder classes.&nbsp;&nbsp;</p>
+<p>When any application is listing folder content, the VfsEngine class creates the VfsFolder class instance that corresponds to the requested folder.</p>
+<p>The initial folder content listing is done inside VfsFolder.GetChildrenAsync() call. As soon as the folder content is populated with placeholders during the first access, the&nbsp;GetChildrenAsync() is never called again. Instead, to update the folder content, this sample monitors changes in the remote storage and applies them to the user file system. See the "Remote Storage to User File System Synchronization" section below.</p>
+<h3>Hydration/Dehydration via Windows File Manager Commands</h3>
+<h3>Remote Storage to User File System Synchronization</h3>
+<p>Remote storage is simulated by the dedicated folder in the file system. The sample monitors changes in it using&nbsp;RemoteStorageMonitor class that generates events and applies corresponding changes in the user file system. The&nbsp;RemoteStorageMonitor class is using FileSystemWatcher which can monitor the creation, update of file content and attributes, deletion, and rename. The&nbsp;FileSystemWatcher class can NOT monitor the move event. In your real-life application, you will replace the&nbsp;FileSystemWatcher with web sockets ar any other technology that will send events from your server to all connected clients.</p>
+<h3>User File System to Remote Storage Synchronization</h3>
+<p>VfsFile.Close() and&nbsp;</p>