Kentico CMS 7.0 Developer's Guide

Using CMS.IO

Using CMS.IO

 Previous topic Next topic Mail us feedback on this topic!  

Using CMS.IO

 Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

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.

 

This topic describes the similarities and differences between the two libraries and presents examples of CMS.IO usage.

 

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 how new instances of objects are created. 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. On the highlighted line 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 classes, class members and methods that are used rather seldom. Additionally, CMS.IO doesn't contain any definitions of exceptions. You will need to use System.IO exceptions or implement your own.

 

Working with streams

 

CMS.IO comes with its own set of streams and the associated readers and writers. These streams are not interchangeable with streams provided by System.IO. This can pose problems e.g. 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.SiteProvider;

...

MetaFileInfo mfi = new MetaFileInfo();

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

 

First, it creates a MetaFileInfo object, which represents a generic system file used throughout the CMS. 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, the StreamWrapper.New() method has to be called 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 a XmlWriter object from a CMS.IO.Stream. Since XmlWriter is a system object, it expects that its Create method will be supplied with a System.IO.Stream. An instance of the GereralStream class, which inherits from System.IO.Stream, has to be passed to the method, as shown on the highlighted line.

 

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

 

•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

 

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

 

StorageHelper

 

•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.

•ExternalStorageName - this property returns the name of the storage provider set by CMSExternalStorageName web.config key. See the Configuration section of the next chapter for more information.

 

The complete list of CMS.IO members can be found in the Kentico CMS API Reference.