Getting Started

roastedamoeba edited this page Apr 1, 2012 · 6 revisions
Clone this wiki locally

Note that the Website project, included in the repository, is a useful example of a website project that uses DynamicImage.

Using NuGet

By far the easiest way of getting started is to install the DynamicImage package from NuGet:

The package will make the necessary changes to your web.config, so you can skip down to Use DynamicImage in your pages.

If you're using ASP.NET MVC, then you'll also want to get the MVC-specific package:

There are also several extensions available:

Not using NuGet

Download

You can also download the latest release of DynamicImage from the Downloads page. You'll need to copy the assemblies, usually into some kind of "lib" or "Libraries" folder in your project.

Configure your project

In Visual Studio, add a reference from your project to SoundInTheory.DynamicImage.dll.

Configure web.config

Add the PresentationFramework assembly. This is needed so that you can specify colours by their names, for example, within markup.

<system.web>
	<compilation targetFramework="4.0">
		<assemblies>
			<add assembly="PresentationCore, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
		</assemblies>
	</compilation>
</system.web>

Add DynamicImageModule to the list of modules. Which section you add this to depends on whether you are using IIS7 in Integrated Mode, or IIS7 in Classic Mode or a previous version of IIS.

  • For IIS7 Integrated Mode:

      <system.webServer>
      	<modules>
      		<add name="DynamicImageModule" type="SoundInTheory.DynamicImage.DynamicImageModule, SoundInTheory.DynamicImage"/>
      	</modules>
      </system.webServer>
    
  • For IIS7 Classic Mode and previous versions of IIS7:

      <system.web>
      	<httpModules>
      		<add name="DynamicImageModule" type="SoundInTheory.DynamicImage.DynamicImageModule, SoundInTheory.DynamicImage"/>
      	</httpModules>
      </system.web>
    

Configure caching with the dynamicImage section:

<configSections>
	<sectionGroup name="soundInTheory">
		<section name="dynamicImage" type="SoundInTheory.DynamicImage.Configuration.DynamicImageSection"/>
	</sectionGroup>
</configSections>

<soundInTheory>
	<dynamicImage>
		<caching mode="Custom" customProvider="XmlCacheProvider" storeMissingImagesInCache="false">
			<providers>
				<add name="XmlCacheProvider" type="SoundInTheory.DynamicImage.Caching.XmlCacheProvider, SoundInTheory.DynamicImage"/>
			</providers>
		</caching>
	</dynamicImage>
</soundInTheory>

So a whole web.config file might look like this:

<?xml version="1.0"?>
<configuration>
	<configSections>
		<sectionGroup name="soundInTheory">
			<section name="dynamicImage" type="SoundInTheory.DynamicImage.Configuration.DynamicImageSection"/>
		</sectionGroup>
	</configSections>
	<system.web>
		<compilation debug="true" targetFramework="4.0">
			<assemblies>
				<add assembly="PresentationCore, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
			</assemblies>
		</compilation>
		<httpModules>
			<add name="DynamicImageModule" type="SoundInTheory.DynamicImage.DynamicImageModule, SoundInTheory.DynamicImage"/>
		</httpModules>
	</system.web>
	<system.webServer>
		<modules>
			<add name="DynamicImageModule" type="SoundInTheory.DynamicImage.DynamicImageModule, SoundInTheory.DynamicImage"/>
		</modules>
	</system.webServer>
	<soundInTheory>
		<dynamicImage>
			<caching mode="Custom" customProvider="XmlCacheProvider" storeMissingImagesInCache="false">
				<providers>
					<add name="XmlCacheProvider" type="SoundInTheory.DynamicImage.Caching.XmlCacheProvider, SoundInTheory.DynamicImage"/>
				</providers>
			</caching>
		</dynamicImage>
	</soundInTheory>
</configuration>

Use DynamicImage in your pages

Now you're ready to use DynamicImage. If you're using ASP.NET MVC, then you can use the DynamicImageTag HTML helper method:

@Html.DynamicImageTag(b => b.WithLayer(
	LayerBuilder.Image.SourceFile("~/Assets/Images/AutumnLeaves.jpg")
		.WithFilter(FilterBuilder.Resize.ToWidth(200))
	))

If you want to generate images in a controller or service layer, you can use the fluent interface:

string imageUrl = new CompositionBuilder()
	.WithLayer(LayerBuilder.Image.SourceFile("myimage.png")
		.WithFilter(FilterBuilder.Resize.ToWidth(800))
	)
	.WithLayer(LayerBuilder.Text.Text("Hello World")
		.WithFilter(FilterBuilder.OuterGlow)
	).Url;

When you access the page in a web browser, you should see the resized image. As long as you configured caching as described above, the image will also be cached file in ~/App_Data/DynamicImage.