Using CMS.IO

Working with CMS.IO is in most aspects the same as working with System.IO. We recommend using CMS.IO instead of System.IO in your code so that your custom functionality is not dependent on a single file system type.

Similarities between CMS.IO and System.IO

Classes

The following classes defined by CMS.IO are identical in function to their respective counterparts in the System.IO library:

• Directory
• DirectoryInfo
• File
• FileInfo
• FileStream
• MemoryStream
• Path
• StreamReader
• StreamWriter
• StringReader
• StringWriter

Enumerations

The following enumerations are also identical:

• FileAccess
• FileAttributes
• FileMode
• FileShare
• SearchOption
• SeekOrigin

Differences between CMS.IO and System.IO

The most significant difference is in the creation of new instances of objects. Instead of a constructor, each class contains a New() method, which accepts the same parameters as the class’ constructor.

The following example shows how to write text into a file. You can see that the instance of the FileInfo class is created using the New() method. Please note that the StreamWriter class used in the example is also a member of CMS.IO, not System.IO.

using CMS.IO;

...

FileInfo fi = FileInfo.New("MyFile.txt");

using (StreamWriter sw = fi.CreateText())
{
    sw.WriteLine("Hello world!");
}

There are a number of types which can be found in System.IO, but are not implemented in CMS.IO. These include seldom used classes, class members and methods. Additionally, CMS.IO does not contain any definitions of exceptions. You need to use System.IO exceptions or implement your own.

Working with streams

CMS.IO provides its own set of streams and associated readers and writers. These streams are not interchangeable with streams provided by System.IO. This can pose problems, for example when a method accepts an object of type CMS.IO.Stream as a parameter, while you only have a System.IO.Stream available, and vice versa. However, CMS.IO provides classes that help work around the incompatibilities.

The following example shows how to store a System.IO.Stream object in a property that expects a CMS.IO.Stream.

using CMS.IO;
using CMS.DataEngine;

...

MetaFileInfo mfi = new MetaFileInfo();
mfi.InputStream = StreamWrapper.New(FileUploadControl.PostedFile.InputStream);

The example creates a MetaFileInfo object, which represents a generic system file used throughout Kentico. The object has the InputStream property, which is of the CMS.IO.Stream type. To store the InputStream of a file uploaded via the standard ASP.NET upload control in that property, call the StreamWrapper.New() method to encapsulate the System.IO.Stream in the CMS.IO.Stream.

The next example demonstrates the opposite approach — passing a CMS.IO.Stream to a method that accepts only objects of the System.IO.Stream type.

using System.Xml;
using CMS.IO;

...

Stream myStream = null;
XmlWriter xml = null;

myStream = FileStream.New("MyFile.xml", FileMode.Append);
xml = XmlWriter.Create(GeneralStream.New(myStream));

The example creates an XmlWriter object from a CMS.IO.Stream. Since XmlWriter is a system object, the Create method expects a System.IO.Stream parameter. Pass an of the GeneralStream class (inherits from System.IO.Stream) to the method.

Helper methods

CMS.IO contains a number of additional methods and properties, which simplify operations with files and directories. The following list describes the most useful methods:

DirectoryHelper class

• void DeleteDirectoryStructure(string path) - deletes the directory specified by the path parameter and all underlying directories.
• void EnsureDiskPath(string path, string startingPath) - checks whether all directories between startingPath and path exist and creates them if necessary.
• void EnsurePathBackslash(string path) - adds a backslash to the end of the path specified if the backslash is missing.

Directory class

• void PrepareFilesForImport(string path) - converts all physical media file names to lower case to ensure compatibility with case-sensitive file systems.

StorageHelper class

• IsExternalStorage - this property indicates if the application is using a storage other than the default Windows file system. Returns true if the CMSExternalStorageName web.config key is set. See Configuring file system providers for more information.