docs-desktop/dotnet-desktop-guide/framework/wpf/controls/how-to-use-the-image-element.md

title, description, ms.date, ms.custom, dev_langs, helpviewer_keywords, ms.assetid

title	description	ms.date	ms.custom	dev_langs	helpviewer_keywords	ms.assetid
How to: Use the Image Element	Learn how to use the Image Element.	03/30/2017	devdivchpfy22	csharp vb	controls [WPF], Image Image control [WPF] rendering images [WPF]	5b92e74b-1b56-4756-ac64-d5e9e08d9854

How to: Use the Image Element

This example shows how to include images in an application by using the xref:System.Windows.Controls.Image element.

Define an image

The following example shows how to render an image 200 pixels wide. In this Extensible Application Markup Language (XAML) example, both attribute syntax and property tag syntax are used to define the image. For more information on attribute syntax and property syntax, see Dependency Properties Overview. A xref:System.Windows.Media.Imaging.BitmapImage is used to define the image's source data and is explicitly defined for the property tag syntax example. In addition, the xref:System.Windows.Media.Imaging.BitmapImage.DecodePixelWidth%2A of the xref:System.Windows.Media.Imaging.BitmapImage is set to the same width as the xref:System.Windows.FrameworkElement.Width%2A of the xref:System.Windows.Controls.Image. This is done to ensure that the minimum amount of memory is used rendering the image.

Note

In general, if you want to specify the size of a rendered image, specify only the xref:System.Windows.FrameworkElement.Width%2A or the xref:System.Windows.FrameworkElement.Height%2A but not both. If you only specify one, the image's aspect ratio is preserved. Otherwise, the image may unexpectedly appear stretched or warped. To control the image's stretching behavior, use the xref:System.Windows.Controls.Image.Stretch%2A and xref:System.Windows.Controls.Image.StretchDirection%2A properties.

Note

When you specify the size of an image with either xref:System.Windows.FrameworkElement.Width%2A or xref:System.Windows.FrameworkElement.Height%2A, you should also set either xref:System.Windows.Media.Imaging.BitmapImage.DecodePixelWidth%2A or xref:System.Windows.Media.Imaging.BitmapImage.DecodePixelHeight%2A to the same respective size.

The xref:System.Windows.Controls.Image.Stretch%2A property determines how the image source is stretched to fill the image element. For more information, see the xref:System.Windows.Media.Stretch enumeration.

[!code-xamlImageElementExample_snip#ImageSimpleExampleInlineMarkup]

Render an image

The following example shows how to render an image 200 pixels wide using code.

Note

Setting xref:System.Windows.Media.Imaging.BitmapImage properties must be done within a xref:System.Windows.Media.Imaging.BitmapImage.BeginInit%2A and xref:System.Windows.Media.Imaging.BitmapImage.EndInit%2A block.

[!code-csharpImageElementExample_snip#ImageSimpleExampleInlineCode1] [!code-vbImageElementExample_snip#ImageSimpleExampleInlineCode1]

See also

• Imaging Overview