Xamarin.Forms Image Tutorial

Artikel
Developer (Beginner)
10 minutes to complete

Before attempting this tutorial, you should have successfully completed the:

Build your first Xamarin.Forms app quickstart.
StackLayout tutorial.

In this tutorial, you learn how to:

Create a Xamarin.Forms Image in XAML.
Customize the Image appearance.
Display a local image file from each platform project.

You will use Visual Studio 2019, or Visual Studio for Mac, to create a simple application that demonstrates how to display an image and customize its appearance. The following screenshots show the final application:

You'll also use XAML Hot Reload for Xamarin.Forms to see UI changes without rebuilding your application.

Create a image

9 minutes remaining

Visual Studio
Visual Studio for Mac

To complete this tutorial you should have Visual Studio 2019 (latest release), with the Mobile development with .NET workload installed. In addition, you will require a paired Mac to build the tutorial application on iOS. For information about installing the Xamarin platform, see Installing Xamarin. For information about connecting Visual Studio 2019 to a Mac build host, see Pair to Mac for Xamarin.iOS development.

Launch Visual Studio, and create a new blank Xamarin.Forms app named ImageTutorial.

Important

The C# and XAML snippets in this tutorial requires that the solution is named ImageTutorial. Using a different name will result in build errors when you copy code from this tutorial into the solution.

For more information about the .NET Standard library that gets created, see Anatomy of a Xamarin.Forms application in the Xamarin.Forms Quickstart Deep Dive.
In Solution Explorer, in the ImageTutorial project, double-click MainPage.xaml to open it. Then, in MainPage.xaml, remove all of the template code and replace it with the following code:
```
<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ImageTutorial.MainPage">
    <StackLayout Margin="20,35,20,20">
        <Image Source="https://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Papio_anubis_%28Serengeti%2C_2009%29.jpg/200px-Papio_anubis_%28Serengeti%2C_2009%29.jpg"
               HeightRequest="300" />
    </StackLayout>
</ContentPage>
```
This code declaratively defines the user interface for the page, which consists of an Image in a StackLayout. The Image.Source property specifies the image to display, via a URI. The Image.Source property is of type ImageSource, which enables images to be sourced from files, URIs, or resources. For more information, see Displaying images in the Images in Xamarin.Forms guide.

The HeightRequest property specifies the height of the Image in device-independent units.

Note

It's not necessary to set the WidthRequest property in this example. This is because, by default, the Image maintains the aspect ratio of the image.
In the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator:

Note

The Image view automatically caches downloaded images for 24 hours. For more information, see Downloaded image caching in the Images in Xamarin.Forms guide.

To complete this tutorial you should have Visual Studio for Mac (latest release), with iOS and Android platform support installed. In addition, you will also require Xcode (latest release). For more information about installing the Xamarin platform, see Installing Xamarin.

Launch Visual Studio for Mac, and create a new blank Xamarin.Forms app named ImageTutorial.

Important

The C# and XAML snippets in this tutorial requires that the solution is named ImageTutorial. Using a different name will result in build errors when you copy code from this tutorial into the solution.

For more information about the .NET Standard library that gets created, see Anatomy of a Xamarin.Forms application in the Xamarin.Forms Quickstart Deep Dive.
In Solution Pad, in the ImageTutorial project, double-click MainPage.xaml to open it. Then, in MainPage.xaml, remove all of the template code and replace it with the following code:
```
<?xml version="1.0" encoding="utf-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ImageTutorial.MainPage">
    <StackLayout Margin="20,35,20,20">
        <Image Source="https://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Papio_anubis_%28Serengeti%2C_2009%29.jpg/200px-Papio_anubis_%28Serengeti%2C_2009%29.jpg"
               HeightRequest="300" />
    </StackLayout>
</ContentPage>
```
This code declaratively defines the user interface for the page, which consists of an Image in a StackLayout. The Image.Source property specifies the image to display, via a URI. The Image.Source property is of type ImageSource, which enables images to be sourced from files, URIs, or resources. For more information, see Displaying images in the Images in Xamarin.Forms guide.

The HeightRequest property specifies the height of the Image in device-independent units.

Note

It's not necessary to set the WidthRequest property in this example. This is because, by default, the Image maintains the aspect ratio of the image.
In the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator:

Note

The Image view automatically caches downloaded images for 24 hours. For more information, see Downloaded image caching in the Images in Xamarin.Forms guide.

Customize appearance

6 minutes remaining

Visual Studio
Visual Studio for Mac

In MainPage.xaml, modify the Image declaration to customize its appearance:
```
<Image Source="https://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Papio_anubis_%28Serengeti%2C_2009%29.jpg/200px-Papio_anubis_%28Serengeti%2C_2009%29.jpg"
       Aspect="Fill"
       HeightRequest="{OnPlatform iOS=300, Android=250}"
       WidthRequest="{OnPlatform iOS=300, Android=250}"
       HorizontalOptions="Center" />
```
This code sets the Aspect property, which defines the scaling mode of the image, to Fill. The Fill member is defined in the Aspect enumeration, and stretches the image to completely fill the view, regardless of whether the image is distorted. For more information about image scaling, see Displaying images in the Images in Xamarin.Forms guide.

The OnPlatform markup extension enables you to customize UI appearance on a per-platform basis. In this example, the markup extension is used to set the HeightRequest and WidthRequest properties to 300 device-independent units on iOS and to 250 device-independent units on Android. For more information about the OnPlatform markup extension, see OnPlatform markup extension in the Consuming XAML Markup Extensions guide.

In addition, the HorizontalOptions property specifies that the image will be horizontally centered.
If the application is still running, save the changes to the file and the application user interface will automatically be updated in your simulator or emulator. Otherwise, in the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen remote iOS simulator or Android emulator:

In Visual Studio, stop the application.

In MainPage.xaml, modify the Image declaration to customize its appearance:
```
<Image Source="https://upload.wikimedia.org/wikipedia/commons/thumb/f/fc/Papio_anubis_%28Serengeti%2C_2009%29.jpg/200px-Papio_anubis_%28Serengeti%2C_2009%29.jpg"
       Aspect="Fill"
       HeightRequest="{OnPlatform iOS=300, Android=250}"
       WidthRequest="{OnPlatform iOS=300, Android=250}"
       HorizontalOptions="Center" />
```
This code sets the Aspect property, which defines the scaling mode of the image, to Fill. The Fill member is defined in the Aspect enumeration, and stretches the image to completely fill the view, regardless of whether the image is distorted. For more information about image scaling, see Displaying images in the Images in Xamarin.Forms guide.

The OnPlatform markup extension enables you to customize UI appearance on a per-platform basis. In this example, the markup extension is used to set the HeightRequest and WidthRequest properties to 300 on iOS and to 250 on Android. For more information about the OnPlatform markup extension, see OnPlatform markup extension in the Consuming XAML Markup Extensions guide.

In addition, the HorizontalOptions property specifies that the image will be horizontally centered.
If the application is still running, save the changes to the file and the application user interface will automatically be updated in your simulator or emulator. Otherwise, in the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator:

In Visual Studio for Mac, stop the application.

Display a local image

4 minutes remaining

Image files can be added to platform projects and referenced from Xamarin.Forms shared code. This method of distributing images is required when images are platform-specific, such as when using different resolutions on different platforms, or slightly different designs.

In this exercise, you will modify the ImageTutorial solution to display a local image, rather than an image downloaded from a URI. The local image is the Xamarin logo, which should be downloaded by clicking the button below.

Download XamarinLogo.png

Important

To use a single image across all platforms, the same filename must be used on every platform, and it should be a valid Android resource name (i.e. only lowercase letters, numerals, the underscore, and the period are allowed).

Visual Studio
Visual Studio for Mac

In Solution Explorer, in the ImageTutorial.iOS project, expand Asset Catalogs, and double-click Assets to open it. Then, in the Assets.xcassets tab, click the Plus button and select Add Image Set:
In the Assets.xcassets tab, select the new image set and the editor will be displayed:
Drag XamarinLogo.png from your file system to the 1x box for the Universal category:
In the Assets.xcassets tab, right-click the new image set's name and rename it to XamarinLogo:

Save and close and Assets.xcassets tab.
In Solution Explorer, in the ImageTutorial.Android project, expand the Resources folder. Then, drag XamarinLogo.png from your file system to the drawable folder:

Note

Visual Studio will automatically set the build action for the image to AndroidResource.
In the ImageTutorial project, in MainPage.xaml, modify the Image declaration to display the local XamarinLogo file:
```
<Image Source="XamarinLogo"
       WidthRequest="{OnPlatform iOS=300, Android=250}"
       HorizontalOptions="Center" />
```
This code sets the Source property to the local file to display. The WidthRequest property is set to 300 device-independent units on iOS, and 250 device-independent units on Android. In addition, the HorizontalOptions property specifies that the image will be horizontally centered.

Note

For PNG images on iOS, the .png extension can be omitted from the filename specified in the Source property. For other image formats, the extension is required.
In the Visual Studio toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator:

In Visual Studio, stop the application.

For more information about local images, see Local images in the Images in Xamarin.Forms guide.

In Solution Pad, in the ImageTutorial.iOS project, double-click Assets.xcassets to open it. Then, in the Assets List, right-click and select New Image Set:
In the Assets List, select the new image set and the editor will be displayed:
Drag XamarinLogo.png from your file system to the 1x box for the Universal category:
In the Assets List, double-click the new image set's name and rename it to XamarinLogo:
In Solution Pad, in the ImageTutorial.Android project, expand the Resources folder. Then, drag XamarinLogo.png from your file system to the drawable folder.
In the Add File to Folder dialog, select OK.

Note

Visual Studio for Mac will automatically set the build action for the image to AndroidResource.
In the ImageTutorial project, in MainPage.xaml, modify the Image declaration to display the local XamarinLogo file:
```
<Image Source="XamarinLogo"
       WidthRequest="{OnPlatform iOS=300, Android=250}"
       HorizontalOptions="Center" />
```
This code sets the Source property to the local file to display. The WidthRequest property is set to 300 device-independent units on iOS, and 250 device-independent units on Android. In addition, the HorizontalOptions property specifies that the image will be horizontally centered.

Note

For PNG images on iOS, the .png extension can be omitted from the filename specified in the Source property. For other image formats, the extension is required.
In the Visual Studio for Mac toolbar, press the Start button (the triangular button that resembles a Play button) to launch the application inside your chosen iOS simulator or Android emulator:

In Visual Studio for Mac, stop the application.

For more information about local images, see Local images in the Images in Xamarin.Forms guide.