---
title: Files API and CMS.IO
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

**CMS.IO** is a namespace that serves as an interlayer between the business layer of Xperience and storage used for physical files. `CMS.IO` is used throughout the system instead of the default `System.IO` library provided by .NET in order to be compatible with various types of storage systems.

`CMS.IO` contains abstractions that access file storage by means of a provider object. Depending on the storage type that you use for your files, the system utilizes one of the following providers:

- **File system storage** – used by default for files stored in the Windows file system. The provider is a wrapper for the standard `System.IO` library.
- **Azure storage** – used when storing files in [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md).
- **Amazon storage** – used when storing files in the [Amazon S3](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/amazon-s3.md) storage service.

The following diagram demonstrates how `CMS.IO` accesses different types of file storage via provider objects:

![CMS.IO abstraction layer](https://docs.kentico.com/docsassets/documentation/files-api-and-cms-io/CMS_IO_Diagram.png "CMS.IO abstraction layer")

`CMS.IO` also includes a **storage path registry** (`IStoragePathRegistry`) that tracks which file system paths require shared or cloud-based storage. Xperience modules register their paths, and the system maps them to the appropriate provider based on your hosting environment. See [Storage path mapping](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md) for details.

> **Note:** This documentation assumes that you are familiar with the `System.IO` library and know how to use it to manipulate files and directories. [Learn how to use System.IO](https://docs.microsoft.com/en-us/dotnet/api/system.io).

## 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 code doesn't depend on a single file system type.

## Similarities between CMS.IO and System.IO

### Classes

- Directory
- DirectoryInfo
- File
- FileInfo
- FileStream
- Path
- StreamReader
- StreamWriter
- StringReader
- StringWriter

### Enumerations

- FileAccess
- FileAttributes
- FileMode
- FileShare
- SearchOption

> **Info:** **Other classes and enumerations**
>
> For classes and enumerations not implemented by `CMS.IO`, we recommend using the standard implementations from the `System.IO` namespace (for example [System.IO.Stream](https://msdn.microsoft.com/en-us/library/system.io.stream\(v=vs.110\).aspx)). Xperience expects these types across its API.

## 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. Note that the `StreamWriter` class used in the example is also a member of `CMS.IO`, not `System.IO`.

```csharp
using CMS.IO;

...

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

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

There are a number of types that 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` doesn't define exceptions. You need to use exceptions from `System.IO`, or implement custom ones.

### Helper methods

`CMS.IO` contains 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 subdirectories.
- **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, if missing.