What is a file session?

After you created the files store, you can start using your file system. There are two ways to work with files on the client side. The first one is to use the low level commands that make calls directly to the RavenFS server. However, the session is the primary way to interact with RavenFS. In order to perform any file operation by using this mechanism, you need to obtain the IAsyncFilesSession object from the files store. The work model with the session usage is straightforward. You need to open the session, register some file operations, and finally apply changes to the remote RavenFS server.

using (IAsyncFilesSession session = store.OpenAsyncSession())
{
	using (Stream content = File.OpenRead(@"C:\intro.avi"))
	{
		session.RegisterUpload("/movies/intro.avi", content);

		await session.SaveChangesAsync();
	}
}

using (IAsyncFilesSession session = store.OpenAsyncSession())
{
	FileHeader file = await session.LoadFileAsync("/movies/intro.avi");

	using (Stream content = await session.DownloadAsync(file.FullPath))
	{
		/* ... */
	}

	if (file.CreationDate < DateTime.Now.AddDays(-1))
		session.RegisterFileDeletion(file);
	
	await session.SaveChangesAsync();
}

All registered modifications are applied when the SaveChangesAsync is called. It means that the stream object passed to the RegisterUpload needs to be available to read at the moment of the SaveChangesAsync call (cannot be disposed).

Note that the session does not load the files with content. It simply retrieves and operates on the file headers. If you want to get the file's content, you have to download it explicitly.

Unit of Work

The session implements the Unit of Work pattern. That has the following implications:

• a single file (identified by its full path) always resolves to the same instance in the context of the same session

Assert.Same(await session.LoadFileAsync("/movies/intro.avi"), await session.LoadFileAsync("/movies/intro.avi"));

• the session keeps track of all files you have loaded and when you call the SaveChangesAsync, all the changes made to those files are sent to the server.

using (IAsyncFilesSession session = store.OpenAsyncSession())
{
	FileHeader file = await session.LoadFileAsync("/movies/intro.avi");

	file.Metadata.Add("Owner", "James");

	await session.SaveChangesAsync(); // will sent the metadata update to the file system
}