Lexical.FileProvider.Package.Abstractions
Lexical.FileProviders.Package.Abstractions is a class library that contains interfaces for implementing package loaders for the IPackageFileProvider. IPackageLoader interface is divided into multiple interfaces.
IPackageLoader is the interface classes that load package files into file providers.
/// <summary>
/// Interace for loaders that read package files, such as .zip, as <see cref="IFileProvider"/>s.
///
/// The implementing class must implement one or more of the following sub-interfaces:
/// <list type="bullet">
/// <item><see cref="IPackageLoaderOpenFile"/></item>
/// <item><see cref="IPackageLoaderLoadFile"/></item>
/// <item><see cref="IPackageLoaderUseStream"/></item>
/// <item><see cref="IPackageLoaderLoadFromStream"/></item>
/// <item><see cref="IPackageLoaderUseBytes"/></item>
/// </list>
/// </summary>
public interface IPackageLoader
{
/// <summary>
/// The file extension(s) this format can open.
///
/// The string is a regular expression.
/// For example "\.zip" or "\.zip|\.7z|\.tar\.gz"
///
/// Pattern will be used as case insensitive, so the case doesn't matter, but lower is preferred.
///
/// Do not add named groups. For example "(?<name>..)".
///
/// Unnamed groups are, however, allowed. For example: "\.zip(\.tmp)?"
/// </summary>
String FileExtensionPattern { get; }
}
IPackageLoaderOpenFile is an interface for reading content from open files.
/// <summary>
/// Package loader that can open a package file as <see cref="IFileProvider"/>.
/// </summary>
public interface IPackageLoaderOpenFile : IPackageLoader
{
/// <summary>
/// Open a package file and keep it open until the file provider is disposed.
/// Return <see cref="IFileProvider"/> that represents the contents of the open file.
///
/// The caller is responsible for disposing the returned file provider if it implements <see cref="IDisposable"/>.
/// </summary>
/// <param name="filepath">data to read from</param>
/// <param name="packageInfo">(optional) Information about packge that is being opened</param>
/// <returns>file provider</returns>
/// <exception cref="Exception">If there was unexpected error, such as IOException</exception>
/// <exception cref="InvalidOperationException">If this load method is not supported.</exception>
/// <exception cref="IOException">Problem with io stream</exception>
/// <exception cref="PackageException.LoadError">The when file format is erronous, package will not be opened as directory.</exception>
IFileProvider OpenFile(string filepath, IPackageLoadInfo packageInfo = null);
}
IPackageLoaderLoadFile is an interface for loading from files.
/// <summary>
/// Package loader that cab load a package file completely.
/// </summary>
public interface IPackageLoaderLoadFile : IPackageLoader
{
/// <summary>
/// Load a package file completely. The implementation must close the file before the call returns.
/// Return <see cref="IFileProvider"/> that represents the contents of the open file.
///
/// The caller is responsible for disposing the returned file provider if it implements <see cref="IDisposable"/>.
/// </summary>
/// <param name="filepath">data to read from</param>
/// <param name="packageInfo">(optional) Information about packge that is being opened</param>
/// <returns>file provider</returns>
/// <exception cref="Exception">If there was unexpected error, such as IOException</exception>
/// <exception cref="InvalidOperationException">If this load method is not supported.</exception>
/// <exception cref="IOException">Problem with io stream</exception>
/// <exception cref="PackageException.LoadError">The when file format is erronous, package will not be opened as directory.</exception>
IFileProvider LoadFile(string filepath, IPackageLoadInfo packageInfo = null);
}
IPackageLoaderUseStream is an interface for using stream as open content source.
/// <summary>
/// Package loader that can open <see cref="Stream"/> to access contents of a package file.
/// </summary>
public interface IPackageLoaderUseStream : IPackageLoader
{
/// <summary>
/// Use an open <paramref name="stream"/> to read contents from a package file.
/// Return a <see cref="IFileProvider"/> that represent the contents.
///
/// The returned file provider takes ownership of the stream, and must close the <paramref name="stream"/> along with the provider.
///
/// <paramref name="stream"/> must be readable and seekable, <see cref="Stream.CanSeek"/> must be true.
///
/// The caller is responsible for disposing the returned file provider if it implements <see cref="IDisposable"/>.
///
/// Note, open stream cannot be read concurrently from two threads and must be locked with mutually exclusive lock if two reads attempted.
/// </summary>
/// <param name="stream">stream to read data from. Stream must be disposed along with the returned file provider.</param>
/// <param name="packageInfo">(optional) Information about packge that is being opened</param>
/// <returns>file provider that can be disposable</returns>
/// <exception cref="Exception">If there was unexpected error, such as IOException</exception>
/// <exception cref="InvalidOperationException">If this load method is not supported.</exception>
/// <exception cref="IOException">Problem with io stream</exception>
/// <exception cref="PackageException.LoadError">The when file format is erronous, package will not be opened as directory.</exception>
IFileProvider UseStream(Stream stream, IPackageLoadInfo packageInfo = null);
}
IPackageLoaderLoadFromStream is an interface for loading content from stream.
/// <summary>
/// Package loader that can load a package completely from an open <see cref="Stream"/>.
/// </summary>
public interface IPackageLoaderLoadFromStream : IPackageLoader
{
/// <summary>
/// Read package completely from <paramref name="stream"/> and return representation of contents as <see cref="IFileProvider"/>.
/// The implementation and the returned <see cref="IFileProvider"/> does not take ownership of the stream.
///
/// The returned file provider can be left to be garbage collected and doesn't need to be disposed.
/// </summary>
/// <param name="stream">stream to read data from. Stream doesn't need to be closed by callee, but is allowed to do so.</param>
/// <param name="packageInfo">(optional) Information about packge that is being opened</param>
/// <returns>file provider</returns>
/// <exception cref="Exception">If there was unexpected error, such as IOException</exception>
/// <exception cref="InvalidOperationException">If this load method is not supported.</exception>
/// <exception cref="IOException">Problem with io stream</exception>
/// <exception cref="PackageException.LoadError">The when file format is erronous, package will not be opened as directory.</exception>
IFileProvider LoadFromStream(Stream stream, IPackageLoadInfo packageInfo = null);
}
IPackageLoaderUseBytes is an interface for loading content from stream.
/// <summary>
/// Package loader that can load a package completely from an bytes.
/// </summary>
public interface IPackageLoaderUseBytes : IPackageLoader
{
/// <summary>
/// Load file provider from bytes.
///
/// The caller is responsible for disposing the returned file provider if it implements <see cref="IDisposable"/>.
/// </summary>
/// <param name="data">data to read from</param>
/// <param name="packageInfo">(optional) Information about packge that is being opened</param>
/// <returns>file provider</returns>
/// <exception cref="Exception">If there was unexpected error, such as IOException</exception>
/// <exception cref="InvalidOperationException">If this load method is not supported.</exception>
/// <exception cref="IOException">Problem with io stream</exception>
/// <exception cref="PackageException.LoadError">The when file format is erronous, package will not be opened as directory.</exception>
IFileProvider UseBytes(byte[] data, IPackageLoadInfo packageInfo = null);
}
IPackageLoadInfo is an interface for loading content from stream.
/// <summary>
/// Optional hints about the package that is being loaded.
/// </summary>
public interface IPackageLoadInfo
{
/// <summary>
/// (optional) Path within package file provider.
/// </summary>
string Path { get; }
/// <summary>
/// (Optional) Last modified UTC date time.
/// </summary>
DateTimeOffset? LastModified { get; }
/// <summary>
/// File length, or -1 if unknown
/// </summary>
long Length { get; }
}
ITempFileProvider
Temp file provider is attached to package file provider options.
// Create temp options
TempFileProviderOptions tempFileOptions = new TempFileProviderOptions { Directory = "%tmp%", Prefix = "package-", Suffix = ".tmp" };
// Create temp provider
ITempFileProvider tempFileProvider = new TempFileProvider(tempFileOptions);
// Try to create temp file
using (var tempFile = tempFileProvider.CreateTempFile())
Console.WriteLine(tempFile.Filename);
// Attach temp provider
fileProvider.SetTempFileProvider(tempFileProvider).Options.SetTempFileSnapshotLength(1073741824);
ITempProvider is an interface for creating temp files.
/// <summary>
/// Temporary file provider.
/// </summary>
public interface ITempFileProvider : IDisposable
{
/// <summary>
/// Create a new unique 0-bytes temp file that is not locked.
/// </summary>
/// <exception cref="IOException">if file creation failed</exception>
/// <exception cref="ObjectDisposedException">if provider is disposed</exception>
/// <returns>handle with a filename. Caller must dispose after use, which will delete the file if it still exists.</returns>
ITempFileHandle CreateTempFile();
}
/// <summary>
/// A handle to a temp file name.
///
/// Dispose the handle to delete it.
///
/// If temp file is locked, Dispose() throws an <see cref="IOException"/>.
///
/// Failed deletion will still be marked as to-be-deleted.
/// There is another delete attempt when the parent <see cref="ITempFileProvider"/> is disposed.
/// </summary>
public interface ITempFileHandle : IDisposable
{
/// <summary>
/// Filename to 0 bytes temp file.
/// </summary>
String Filename { get; }
}