All files from Digizuite are served using the media pipelines. From DFS 9.0.0 the media pipeline has been redesigned, however, the old is still there for compatibility reasons.
It is configurable which one is used and this is controlled by a config parameter in DFS.Settings.config:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <settings> <setting name="DFS.MediaPipeline" value="dfsmedia"/> </settings> </sitecore> </configuration>
There are two options
- dfsmedia - the new implementation
- media - the old implementation
The default value is dfsmedia.
This section describes the new dfsmedia pipeline and its capabilities.
Understanding the request
The new dfsmedia pipeline is accessible on the following endpoint: http(s)://<sitecore>/dfsmedia
The syntax of the URL is: dfsmedia/[SiloId]/[AssetId]-[Quality]/resize/[Width]x[Height]/compress/[0-100]/options/[Options]
If a parameter is not optional, it may be discarded, but it has to follow the order above. For instance if you want to compress only, then the following scheme is used:
dfsmedia/[SiloId]/[AssetId]-[Quality]/compress/[0-100]
Each parameter is described as follows:
Field | Description |
---|---|
SiloId | This is the Id of the silo that has the asset requested. |
AssetId | Is the Id of the asset that is requested. |
Quality | Overrides the quality specified in the Sitecore field. Quality supports both 'by name' and 'by id' |
Resize * | Only applies to image assets. One of the concepts and principles when using a DAM system is to use specific qualities for every use. If images are needed in different sizes, it should be configured in Digizuite™ DAM. However, there is a resize feature. Width How wide the image will be in pixels. Height How high the image will be in pixels. By default a resize does not keep aspect ratio, but you can set an option to keep aspect ratio. |
Compress * | Only applies to image assets. Indicates whether the asset should be saved using a worse quality, thereby reducing the physical size. from 0-100 is allowed, where 0 is the worst quality, but least physical storage. |
Options * | Options is a dash ("-") separate list and can contain these options: download - Will download the asset requested. keepaspectratio - Will enforce aspect ratio on from the original asset, if a resize is requested. upscaleallowed - Will allow upscaling an image. The default is to disallow that. |
*Optional
Understanding the DigizuiteMediaCache
The DigizuiteMediaCache is where everything, except videos, is saved. Below is a flow chart how it works when requesting media from the DFS mediahandler.
The cache location is configurable and is located in DFS.Settings.config.
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <settings> <!-- Path to DAM For Sitecore MediaCache. The following is supported: -UNC (\\server\example\cahcepath) -Full path (C:\example\cachepath) -Relative path (/App_Data/cachepath) --> <setting name="DFS.CacheLocation" value="/App_Data/DigizuiteMediaCache"/> </settings> </sitecore> </configuration>
The default location is in the website root under App_Data/DigizuiteMediaCache/.
Files are cached based on the request made to the asset. An example request could be: http(s)://<sitecore url>/dfsmedia/29a605d46a3340418c16542f7272c3ec/110-50035
According to the specification of the URL, this request has the following properties:
- AssetSiloId: 29a605d46a3340418c16542f7272c3ec
- AssetId: 110
- FormatId: 50035
The cache is then build using a naming scheme. Each asset is placed in a sub-folder which has the name of the assetid. In the case of the example, the path in which the file is saved would be App_Data/DigizuiteMediaCache/110
The filename is then constructed based on the given properties using the following scheme:
{Assetid}_{formatid}_{width}_{height}_{options}.{extension}
where width, height and options are not used, if not requested (i.e. not used in the example), which means in the example, the requested asset would have the following name:
110_50035.{extension}
The extension is retrieved from the file saved in the cache. The naming scheme enable unique names and hence the extension can be extracted from the file in the cache. Originally, the file is saved with the correct extension based on what is served from the Digizuite.
UNC path
The dfsmedia pipeline also supports having a centralized cache, which means multiple servers can have the same cache. This decreases storage, but also performance, because files are then cached on a UNC which is slower than having it locally. This is something each client has to have an opinion on.
Implementation
The new dfsmedia pipeline is implemented as a httphandler, using a pipeline in Sitecore. This pipeline is located in the DFS.Services.config file:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <pipelines> <DFS.Services.DFSMedia> <processor type="DFS.Services.Pipelines.DFSMedia.CheckSecurity, DFS.Services" /> <processor type="DFS.Services.Pipelines.DFSMedia.GetMediaFromCache, DFS.Services" /> <processor type="DFS.Services.Pipelines.DFSMedia.GetMediaPrerequisites, DFS.Services" /> <processor type="DFS.Services.Pipelines.DFSMedia.GetMediaFromDigizuite, DFS.Services" /> <processor type="DFS.Services.Pipelines.DFSMedia.ResizeImage, DFS.Services" /> <processor type="DFS.Services.Pipelines.DFSMedia.SaveToCache, DFS.Services" /> </DFS.Services.DFSMedia> </pipelines> </sitecore> </configuration>
Each step is explained as follows:
Pipeline name | Description |
---|---|
DFS.Services.Pipelines.DFSMedia.CheckSecurity | This pipeline looks up the asset in the index using the context user. If the user does not have access, the asset is not returned and the pipeline is stopped. |
DFS.Services.Pipelines.DFSMedia.GetMediaFromCache | This pipelines constructs a unique name based on the request and checks if the requested asset exists in the cache. |
DFS.Services.Pipelines.DFSMedia.GetMediaPrerequisites | If the asset is not cached, it needs to be requested from Digizuite. This pipeline gets all the prerequisites for requiring the asset in Digizuite |
DFS.Services.Pipelines.DFSMedia.GetMediaFromDigizuite | This pipeline executes the request towards Digizuite |
DFS.Services.Pipelines.DFSMedia.ResizeImage | If a resize or #compres?? is requested, the bytes are processed here |
DFS.Services.Pipelines.DFSMedia.SaveToCache | This pipeline saves the asset to the cache |
This pipeline may be modified according to customer needs.
Hint
Commenting out the security part of the pipeline increases performance of the cost of security, but for content delivery servers for public websites, this is typically not important and therefore it may be beneficial to comment out this step.
Extending the pipeline
If the pipeline is to be extended, for instance if some custom processing needs to be done to the image, then this may be done in between any of the steps above.
The pipeline step should have the following construction:
public class PipelineName : ProcessorBase<DFSMediaPipelineArgs> { public override void Process(DFSMediaPipelineArgs args) { if (args.Result.StopPipeline) { return; } if (args.Request.Download) { return; } if (args.Result.Cached) { return; } //code goes here } }
Remember to include the custom step in the configuration file!
The object DFSMediaPipelineArgs contains a Request and a Result. These two objects has the following properties:
Request
Parameter | Type | Description |
---|---|---|
AssetSiloId | string | Id of the asset silo from which the asset should be fetched |
AssetId | string | Id of the requested asset |
FormatId | string | Id of the format requested |
DestinationId | string | Digizuite id of the destination - where to get the asset from |
BaseUrl | string | BaseUrl of the Digizuite |
AccessKey | string | AccessKey to the Digizuite |
MimeType | string | Mimetype of the requested asset |
Width | string | If a resize of the asset is requested, then this property contains the new width |
Height | string | If a resize of the asset is requested, then this property contains the new height |
Download | bool | If a download is requested, then this property is true |
KeepAspectRatio | bool | if the aspect ratio should be kept, then this property is true |
UpscaleAllowed | bool | if upscale is allowed, then this property is true |
Compress | string | If the image should be compressed, then this has a value between 0 and 100 |
Result
Parameter | type | Description |
---|---|---|
ResultPath | string | Path to the directory in which the asset is cached |
FileName | string | Name of the cached asset |
Cached | bool | Boolean to indicate whether the asset is cached |
ResultStream | Task<Stream> | Handle for the result stream used to get the asset from Digizuite |
ResizeBytes | byte[] | If the image is resized and/or compressed, this array contains the result bytes |
DownloadUrl | string | Redirect URL for download requests |
StopPipeline | bool | If the pipeline should be aborted, for instance due to security violation, then this is true |
Asset | AssetIndexable | Asset model from the index |
StatusCode | HttpStatusCode | Status code used to indicate the request status. |
Changing the URL
If the new "dfsmedia" pipeline is used, it is possible to use another prefix for the media URL. An example could be that one wanted the company name instead of dfsmedia as the media URL prefix. This can be done doing the following:
- Change setting: DFS.MediaPipeline to new prefix (e.g. company name) in config file DFS.Settings.config
- Change path in httphandler section in web.config (See DFS 10.1.0 - 3 Setting up Sitecore section 3.1) to be the new prefix
- Change trigger in customHandlers section in DFS.Services.config to be the new prefix
- Resynchronize the silo
Doing this ensures the following URL scheme: http(s)://<sitecore url>/<new prefix>/29a605d46a3340418c16542f7272c3ec/110-50035
Manually deleting cache entries
The cache is invalidating if the image in Digizuite is re-transcoded. The cache invalidation results in all the entries for the given asset, being deleted. If one wishes to manually clear the cache this is also an option. There are two ways in which this can be accomplished:
- Manually deleting the folder in the cache (i.e. delete the folder that has the asset ID of the asset that should be deleted).
- Use the Administration DAM for Sitecore dashboard, it has a function called Image cache where you can delete the cache from through UI. DFS 10.1.0 - Administration dashboard