Fork me on GitHub

There are two ways you can create an image with DynamicImage: using the object model directly, or using the fluent API. In most cases the fluent API is easier to work with, but if you want more control, you can drop down to the object model. This page describes the object model, and the next one describes the fluent API.


DynamicImage has a hierarchy of layers and filters that can be used to create an image. The hierarchy looks like this:

  • Composition
    • Layers
      • Filters
    • Filters (global filters that apply to the composition)

The class you start with is a Composition:

Composition composition = new Composition();
// ...

// If you want to use the image directly, bypassing caching:
GeneratedImage generatedImage = composition.GenerateImage();
// If you want to cache the image:
string url = ImageUrlGenerator.GetImageUrl(composition);

There are a number of configurable properties on a Composition:

  • AutoSize
  • Width
  • Height
  • ImageFormat
  • JpegCompressionLevel
  • Fill

The Fill class is worth mentioning in more detail, because it appears in several places in DynamicImage. It has the following properties:

  • Type (Solid or Gradient)
  • BackgroundColor
  • GradientColorStart
  • GradientColorEnd
  • GradientAngle


Once you have a Composition object, you need to add an image or text. This is done with a Layer. DynamicImage includes several layer types, and it is straightforward to write your own.

Composition composition = new Composition();
composition.Layers.Add(new ImageLayer { SourceFileName = "tulips.jpg" });
composition.Layers.Add(new TextLayer { Text = "Hello World" });

The built-in layer types are:

More layer types are available via extensions:

Layers have the following properties:

  • Visible
  • Anchor (anchor the layer to a side or corner of the composition)
  • X (offset in relation to the composition)
  • Y (offset in relation to the composition)
  • AnchorPadding
  • Padding
  • BlendMode


Filters let you modify layers. Filters are quite flexible - some change the size of a layer, while others modify the individual pixel colours. You can combine filters to produce interesting effects. Filters can be applied both to layers (they will affect just that layer) and compositions (they will be applied globally after all layers have been composited).

Composition composition = new Composition();
composition.Filters.Add(new DropShadowFilter());

ImageLayer layer = new ImageLayer { SourceFileName = "tulips.jpg" };
layer.Filters.Add(new ResizeFilter { Mode = ResizeMode.UseWidth, Width = 200 });
layer.Filters.Add(new GrayscaleFilter());