CKFinder is an Ajax application with a frontend written entirely in JavaScript. It communicates with the server through JSON messages. On the server side, there is a "connector" written in a specific server language, which handles the frontend requests. The following diagram illustrates it:

Application structure overview

CKFinder NuGet Packages

The CKFinder 3 for ASP.NET connector is divided into the following NuGet libraries:

CKSource.CKFinder – The Javascript client package of CKFinder.
CKSource.CKFinder.Connector.Config – The library that adds support for defining CKFinder settings using the XML configuration file.
CKSource.CKFinder.Connector.Core – The core library of the CKFinder connector.
CKSource.CKFinder.Connector.Host.Owin – The library required for integration of the CKFinder connector as an OWIN middleware.
CKSource.CKFinder.Connector.KeyValue.FileSysyten – The library that adds cache support in the connector.
CKSource.CKFinder.Connector.Logs.NLog – The logging adapter for NLog.
CKSource.FileSystem – The main file system library with common code for specific file system adapters.
CKSource.FileSystem.Amazon – The Amazon S3 file system adapter.
CKSource.FileSystem.Azure – The AzureStorage file system adapter.
CKSource.FileSystem.Dropbox – The Dropbox file system adapter.
CKSource.FileSystem.Ftp – The FTP file system adapter.
CKSource.FileSystem.Local – The local file system adapter.

Each application should reference at least the following packages:

CKSource.CKFinder.Connector.Core
CKSource.CKFinder.Connector.Host.Owin
CKSource.FileSystem
Any combination of CKSource.FileSystem.* packages

CKSource.CKFinder

This package contains the JavaScript part of CKFinder.

CKSource.CKFinder.Connector.Config

Support for the configuration file. Handles both application configuration (Web.config, App.config) and standalone file types.

Exports the CKSource.CKFinder.Connector.Config namespace.

The most important LoadConfig method is implemented in the ConnectorBuilderConfigExtensions class. It is important to register all available file systems in the FileSystemFactory class before calling LoadConfig.

CKSource.CKFinder.Connector.Core

The core library responsible for handling commands, publishing events and loading plugins.

Exports the CKSource.CKFinder.Connector.Core namespace.

The most important class included in this package is ConnectorBuilder which should be used to set up the connector.

Hosting Packages

A group of possible hosting packages. CKFinder may be hosted in Owin or in a WebApi environment.

Only one of these packages should be used in a project.

CKSource.CKFinder.Connector.Host.Owin

Hosting in Owin environment.

Exports the CKSource.CKFinder.Connector.Host.Owin namespace.

The most important class included in this package is OwinConnectorFactory which should be used to build the connector in the Build method.

Key-value Store Packages

Packages that provide various adapters for the key-value store. CKFinder uses key-value stores for caching.

Only one of these packages should be used in a project.

CKSource.CKFinder.Connector.KeyValue.FileSystem

File system based adapter for the key-value store.

Exports the CKSource.CKFinder.Connector.KeyValue.FileSystem namespace.

Provides FileSystemKeyValueStoreProvider.

CKSource.CKFinder.Connector.KeyValue.EntityFramework

An entity framework adapter for the key-value store.

Important: This key-value store adapter may cause performance issues and is deprecated. Please use CKSource.CKFinder.Connector.KeyValue.FileSystem instead.

Exports the CKSource.CKFinder.Connector.KeyValue.EntityFramework namespace.

Provides EntityFrameworkKeyValueStoreProvider.

Logging Packages

CKSource.CKFinder.Connector.Logs.NLog

NLog adapter for logging in CKFinder.

Exports CKSource.CKFinder.Connector.Logs.NLog namespace.

The most important class included in this package is NLogLoggerAdapterFactory which should be provided to the LoggerManager.LoggerAdapterFactory property.

File System Packages

CKSource.FileSystem

Common classes for all file systems.

Exports the CKSource.FileSystem namespace.

CKSource.FileSystem.Amazon

An Amazon S3 file system adapter.

Exports the CKSource.FileSystem.Amazon namespace.

CKSource.FileSystem.Azure

An Azure Storage file system adapter.

Exports the CKSource.FileSystem.Azure namespace.

CKSource.FileSystem.Dropbox

A Dropbox file system adapter.

Exports the CKSource.FileSystem.Dropbox namespace.

CKSource.FileSystem.Ftp

A FTP file system adapter.

Exports the CKSource.FileSystem.Ftp namespace.

CKSource.FileSystem.Local

A local file system adapter.

Exports the CKSource.FileSystem.Local namespace.

Events

The CKFinder ASP.NET connector provides a set of events that can be used for changing the default application behavior. Each of the events is identified by its unique type, and can be listened to by any number of listeners.

To attach a listener to the event, you can use the event aggregator object stored in the application dependency injection container:

var eventAggregator = componentResolver.Resolve<IEventAggregator>();
eventAggregator.Subscribe<BeforeCommandEvent>(next => async messageContext => 
    {
        /* TODO: Add your event listener logic. */
        
        await next(messageContext); /* Call the next event handler. */
 
        /* TODO: Add your event listener logic. */
    });

It is possible to stop event propagation by not calling the next event handler.

To remove an event listener, call the Unsubscribe method:

var eventAggregator = componentResolver.Resolve<IEventAggregator>();
var subscription = eventAggregator.Subscribe<BeforeCommandEvent>(/* event handler */);
eventAggregator.Unsubscribe(subscription);

Unsubscription may be done in the event handler itself.

BeforeCommand Events

These events are fired after a particular command is resolved, i.e. it is decided which command class should be used to handle the current request.

The parameter passed to event listeners is an object of the BeforeCommandEvent type that carries the following information:

The user data object (like all CKFinder events).
An instance of ICommandRequest (like all CKFinder events).
An instance of the resolved command.

In event listeners it is possible to provide any additional code that will be executed before the command.

To check which command fired the event you should compare the type of the instance of the command with command types:

BeforeCommandEvent beforeCommandEvent;
if (beforeCommandEvent.CommandInstance is FileUploadCommand)
{
  /* This is a FileUploadCommand, do something with it. */
}

The full list of built-in commands is presented in a table below:

Command Type	Description
CopyFiles	Copies files from selected folders.
CreateFolder	Creates a child folder.
DeleteFiles	Deletes given files.
DeleteFolder	Deletes a given folder.
DownloadFile	Downloads a file from the server.
FileUpload	Uploads a file to a given folder.
GetFiles	Returns the list of files for a given folder.
GetFileUrl	Returns a direct URL to a file.
GetFolders	Returns the list of the child folders for a given folder.
GetResizedImages	Returns a list of resized versions of the image file.
ImageEdit	Performs basic image modifications: crop, rotate, resize.
ImageInfo	Returns information about the dimensions of the image file.
ImagePreview	Creates a resized version of the image file.
ImageResize	Creates a resized version of the image file.
Init	This is the first command issued by CKFinder. It returns the general settings of the connector and all configured resource types.
MoveFiles	Moves files from selected folders.
Operation	Tracks the progress of the operation in time-consuming connector commands.
Proxy	Serves a file to the browser without forcing the download. This command is useful in cases where you want to use files without direct access on a web page. These may be files stored on a backend like a private FTP server, or files that are not in the web server root folder. If the backend is defined as a `Proxy`, all links generated by CKFinder will be pointing to the `Proxy` command.
QuickUpload	Uploads a file to the given folder. This command is very similar to FileUpload and it is used to handle uploads from the CKEditor Image or Link dialog window.
RenameFile	Renames a file.
RenameFolder	Renames a folder.
SaveImage	Saves a Base64-encoded PNG image to a file.
Thumbnail	Downloads the thumbnail of an image file.

Intermediate Events

These events are fired inside command classes before any important operations such as uploading a file, renaming, deleting, or moving files and folders take place.

Command	Event Type	Notes
CopyFiles	CopyFileEvent	Fired for every file being copied
CreateFolder	CreateFolderEvent	-
DeleteFiles	DeleteFileEvent	Fired for every file being deleted
DeleteFolder	DeleteFolderEvent	-
DownloadFile	DownloadFileEvent	-
FileUpload	FileUploadEvent	-
GetFiles	-	-
GetFileUrl	-	-
GetFolders	-	-
GetResizedImages	-	-
ImageEdit	ImageEditEvent	-
ImageInfo	-	-
ImagePreview	-	-
ImageResize	ResizeImageEvent	-
Init	-	-
MoveFiles	MoveFileEvent	Fired for every file being moved
Operation	-	-
Proxy	ProxyDownloadEvent	-
QuickUpload	FileUploadEvent	-
RenameFile	RenameFileEvent	-
RenameFolder	RenameFolderEvent	-
SaveImage	SaveImageEvent	-
Thumbnail	-	-

AfterCommand Events

These events are fired after a particular command returned the response.

The parameter passed to event listeners is an object of the AfterCommandEvent type that carries the following information:

The user data object (like all CKFinder events).
An instance of the ICommandRequest (like all CKFinder events).
An instance of the executed command.
A command response object.

In events listeners it is possible to provide any additional code that will be executed after the command, but it is also possible to replace the command result object that is carried inside the event object, so the new provided response object will be used instead.

To check which command fired the event see description of BeforeCommand Events.

Table of Contents