Media Services

Binary file service. Serves Perfion file and image type binaries, but does not allow any image processing. The service will only deliver the original file content and it has an option to either show file content in line (e.g. in internet browser) or define it as an attachment which will force users to download the file instead of rendering file content inline.

Any requested files will be saved in a cache and the service will use the cached file next time the same request is sent.

Binary image service. Serves Perfion file and image type binaries and allows image processing. Image processing is possible only when using Perfion image type binaries. The image service will serve Perfion file type binaries, but such binaries will be served as if they were requested via the File service. This means that image processing is not supported for such requests.

The service has an option to either show file content inline (e.g. in a browser) or stream the content as an attachment available for download.

Any processed images will be saved in a cache and the service will use the cached file next time the same request is sent.

The image service can optionally add watermark to the images based on configuration and the request parameters. Please refer to the Image Watermarking section for more details.

Media service ID. The parameter is optional for database based media service and required for Perfion Cloud based media service.

The ID is a standard GUID identifier, e.g. ‘8e118ad2-70eb-430f-8cd0-ca9a8408f897’.

Parameter key in Web.Config file: Perfion.MediaServiceId

Media services name.

Optional parameter. Used only with Perfion Cloud based media service.

Parameter key in Web.Config file: Perfion.MediaServiceName

Boolean parameter which defines if the media service is enabled.

Parameter key in Web.Config file: Perfion.IsActive. It is optional for Web.Config and if not define will have a default value ‘true’, e.g. the media service is enabled.

Connection string of Perfion database. Used only with database based media services.

Note that connection string should be blank when using Perfion Cloud based media services.

Parameter name in Web.Config file: connectionStrings ->add element with a name ”perfionConn” e.g.:

Perfion Storage Service URL. Parameter is optional and used only when media service should serve binaries from the Perfion Cloud by using Storage Service.

Note that this parameter will only be used if PerfionDBConnectionString is not defined.

Parameter key in Web.Config file: Perfion.StorageServiceUrl

Perfion Storage Service API Key. Parameter is optional and used only when media service should serve binaries from the Perfion Cloud by using Storage Service.

Note that this parameter will only be used if PerfionDBConnectionString is not defined.

Parameter key in Web.Config file: Perfion.StorageServiceKey

Image watermark related parameter which defined how the watermark image must be applied.

It is an integer number. Values:

• 0 (default) – watermark image is disabled and will not be applied.
• 1 – watermark image is enabled and will be applied regardless of how big the target image is.
• larger than 1 – watermark image will be applied only if the resulting image dimension on either side is larger than watermark range value. The value is defined in pixels.

The parameter is optional.

Parameter key in Web.Config file: Perfion.WatermarkRange

Defines the path to the image that should be used as watermark. Note that the path is relative to the image service (e.g. Image.aspx) file.

The parameter is optional.

Parameter key in Web.Config file: Perfion.Watermark

The path to an image which will be used when there is no image to show, e.g. when image ID used in request is not found.

The parameter is optional and if not defined, the image services will use a default image.

The path is relative to the image service (e.g. Image.aspx) file.

Parameter key in Web.Config file: Perfion.NoImageFoundImage

The parameter allows to control Cache-Control HTTP header for media services response. Values correspond to .NET HttpCacheability supported values:

• Server (default). Specifies that the response is cached only at the origin server.
• NoCache. Sets the Cache-Control: no-cache header.
• Private. Sets Cache-Control: private to specify that the response is cacheable only on the client and not by shared (proxy server) caches.
• Public. Sets Cache-Control: public to specify that the response is cacheable by clients and shared (proxy) caches.
• ServerAndNoCache. Applies the settings of both Server and NoCache to indicate that the content is cached at the server but all others are explicitly denied the ability to cache the response.
• ServerAndPrivate. Indicates that the response is cached at the server and at the client but nowhere else. Proxy servers are not allowed to cache the response.

The parameter is optional. If not define will use “Server” value.

For more information refer to Microsoft .NET documentation: HttpCacheability Enum

Parameter key in Web.Config file: Perfion.FileHttpCacheability

The parameter is used with media cache files which are stored locally in the server file system to determine how long the request should wait while trying to read the cache file if it is occupied by other processes (e.g. because other request are handling the file).

The parameter is used only with database media services.

Optional parameter. The default value is 5000 milliseconds.

Parameter key in Web.Config file: Perfion.BinaryCache_ReaderTimeOut

The parameter is used with media cache files which are stored locally in the server file system to determine how long the request should wait while trying to write (e.g. create/update) the cache file if it is occupied by other processes (e.g. because other request are handling the file).

The parameter is used only with database media services.

Optional parameter. The default value is 5000 milliseconds.

Parameter key in Web.Config file: Perfion.BinaryCache_WriteTimeOut

The parameter allows to specify the limit of the disk space which is considered as critically low for media service to operate. If server disk space becomes lower than this parameter defines, the media service will show an error about too low disk space.

The media services can generate large cache files in local disc and if there is not enough space, the media service will fail. The use of this parameter prevents such failure and allows identifying the real problem earlier before the whole server could stop responding or crash.

Optional parameter. The default value is 100 MB.

The parameter is used only with database based media services.

Parameter key in Web.Config file: Perfion.DiskSpaceLimitInMb

The parameter defines HTTP caching header expiration time.

Optional parameter. The default value is 300000 milliseconds (5 minutes).

Parameter key in Web.Config file: Perfion.BinaryCache_CachingTime

The parameter defines the location where media services cache and log files will be located.

Optional parameter. The Default value is “Cache”.

The parameter is used only with database based media services.

Parameter key in Web.Config file: Perfion.CacheStoragePath

The parameter defines the logging level. Media services if fails will write log data and this parameter determines how detailed this data should be. Values:

• Error. The log record will be created only when the request to media service failed.
• Warning. The log record will be created only when the request to media service failed or have warnings.
• Info. The log record will be created for each media service request.
• Debug. The log record will be created for each media service request including much more detailed information which is typically not logged and used only for debugging purposes.

Optional parameter. The Default value is “Error”.

Note that logging can also be forced by using service request URL parameters.

Parameter key in Web.Config file: Perfion.LogLevel

This is the most common media services type which is setup to use a single Perfion database as a source of binary data. The media service will use the local server’s file system to store cached binary data.

The database based media services will be enabled if there is Perfion database connection string provided in media services configuration.

This type of media services can be used only if Perfion Cloud Storage feature is in use and there is Perfion Storage Service set up in the Perfion Cloud. If this feature is enabled, then all Perfion binary data can be migrated from Perfion database to the Perfion Cloud storage and media service can be used to retrieve this Cloud based binary data directly without using access to Perfion database. Perfion Cloud Storage feature allows storing binary data in the Perfion Cloud from multiple Perfion databases, so setting up media services for Cloud binaries would allow accessing all of those binaries by using Perfion Storage Service interface.

The database based media services will be enabled if Perfion database connection string provided in media services configuration is removed and instead one specifies StorageServiceUrl and StorageServiceKey parameters. The media services will use the Storage Service as a proxy service to access the data stored in Perfion Cloud storage.

This type of media services will use caching which will be based on Perfion Cloud storage and cache files will be saved at the same place where the source data is located.

The parameter specifies the ID of Perfion binary. The binary can be of file or image type. The binary ID value can be found via a standard API data query as described in the manual Perfion Query Reference.

The parameter is mandatory for all media service requests.

Value: binary data ID (GUID identifier)

Defines requested binary data as attachment.

All binary data served by media services are declared as inline content. This means that if the image is requested using internet browser, then that image in most case will be rendered directly in the internet browser’s window. This is a default behavior, but the actual behavior will depend on the application which handles the response. Some binary data content cannot be rendered inline and the application may ask to download the requested binary file to disk. If it is an internet browser, then by adding the action parameter will cause the browser to open a file Save As dialog, allowing the user to save the file to disk.

Value: save

HTTP MIME type of the output stream, e.g. a label used to identify a type of data.

Using this parameter one can overwrite the MIME type of data. By default media services will select MIME type based on binary data file extension or from ‘format’ parameter.

Value: a valid HTTM MIME type.

Some examples of valid HTTP MIME type values: jpg, bin, gif, etc.

Removes binary data from cache before serving the response. This will lead that the binary data will be retrieved from the source and the new binary cache data will be created (depends on media service type).

Value: 1

Overwrites the original binary file name with the name provided as parameter value.

Value: new file name

Forces media services to log information about the request.

Media services will log failed requests automatically, but one can also force to log a normal request using this parameter. The log data will be located where the binary cache data is located.  

Value: 1

Changes returned image format to defined format.

Value: image format, e.g. JPG, PNG, etc.

Supported image formats: BMP, GIF, JPG/JPEG, PNG, TIFF/TIF, EPS, PSD, PDF, SVG, WEBP, AVIF

Scales the image exactly to the specified resolution.

This parameter cannot be combined with the size or fit parameters. For precision, the parameter value can include a decimal separator (use the period character ‘.’).

Value: decimal number

Defines the size in pixels (width x height). The pixels must be expressed in whole integer numbers, i.e. no decimal points are allowed.

The size can be interpreted in several ways since it is possible to define width and height ratios that are not equivalent to the original image. How the size is interpreted is controlled by the fit parameter. The default behavior is to scale the image to fit within the specified size by keeping the aspect ratio.

Value: <width>x<height>, where width and height are integer numbers.

Controls how to interpret the size parameter behavior. It can only be used together with size parameter.

Value:

• fit (default). Default behavior equivalent to omitting the parameter. Scale the image to fit within the specified size by keeping the aspect ratio.
• exact. Scale the image to fit the specified size exactly. If the specified size does not have the same proportions as the original image, then the image will be stretched in one or the other dimension
• crop. Scale the image to fit the specified size exactly. If the specified size does not have the same proportions as the original image, then the image will be cropped either at the sides or at the top/bottom thereby leaving the contents of the image undistorted
• smart. Scale the image to fit the specified size exactly. If the specified size does not have the same proportions as the original image, then the image is adjusted via a 50% combination of the above exact and crop fitting methods, i.e. the image is cropped a little less and stretched a little less.
• aspectratio. Image is resized to the new size by keeping the aspect ratio so that it fits best and then the remaining area (if the new size does not match the original image aspect ratio) is filled using a color which can be specified using canvascolor parameter.

The requested canvas color of the image. It is only usable when image is resized using size parameter together with fit parameter set to aspectratio.

The color must be specified as RGB or ARGB color code in hexadecimal format by using 6 (RGB) or 8 (ARGB) char color code. In case of 8 char color code, the first 2 characters represent the alpha channel value.

Value: hexadecimal color value, e.g. ccff33.

Adds a color to transparent parts of the image.

This only works when the target image format does not support transparency and the source image format has transparency. In such case the source image transparency will be replaced with background color.

Value: hexadecimal color value, e.g. ccff33.

Image compression quality in percent. 

Supported only for JPG and PNG format images.  

Value: integer value >0 and <=100.

Default value: 90.

TIFF compression method.

Values: LZW (Lempel-Ziv and Welch compression), ZIP (Deflate compression) or None. Default value is LZW.

The parameter can be used only if the target image format is a TIFF image.

The color profile of the target image. It is only usable with images which support color profiles. If specified the image colors will be converted to that color profile and the profile itself will be embedded to the image file.

Values: Original (keep the original color profile), CMYK (Coated FOGRA39), sRGB, AdobeRGB1998, ProPhoto.

The request to use the Point-of-Interest (POI) of the image if it has POI specified in its metadata. If image does not have POI specified or the POI is not used, then POI will be equivalent to value 50x50 which is the center of the image.

Values: 0 (do not use POI) and 1 (use POI). Default value: 0.

The parameter can only be used with size and fit parameters when fit parameter is set to crop or smart.

The request to use the custom Point-of-Interest (POI) of the image. This parameter can only be used if usepoi is used and set to ‘1’. If this parameter is used, then it will overwrite the original image POI value saved as its metadata.

Value is of format <X>x<Y> where X and Y are relative image horizontal and vertical coordinates expressed in %. The reference point is image top right corner which will have value 0x0. The bottom right corner of the image will have value 100x100. The center of the image will have value 50x50.

Values for X and Y coordinates must be integer values >=0 and <=100. 

The parameter can only be used with size and fit parameters when fit parameter is set to crop or smart.

File

Image

ImageW

ImageUncached

Yes

Yes

No

Yes

Yes

Yes

No

Yes

Yes

Yes

Yes

Yes

No

No

No

No

Yes

Yes

Yes

Yes

No

Yes

Yes

Yes