Assets

Many applications need to include assets such as bitmaps and resource dictionaries in their executable and refer to these assets from XAML.

Including assets

Assets can be included in an application by using the <AvaloniaResource> item in your project file. The MVVM Application template by default includes all files in the Assets directory as an <AvaloniaResource>:

<ItemGroup>
  <AvaloniaResource Include="Assets\**"/>
</ItemGroup>

You can include whatever files you want by adding additional <AvaloniaResource> elements.

You will notice that we're referring to assets here whereas the MSBuild item is called an Avalonia resource. Assets are internally stored as .NET resources but because the term "resource" conflicts with XAML resources we'll refer to them as "assets" throughout.

Referencing assets

Assets can be referenced in XAML by specifying their relative path:

<Image Source="icon.png"/>
<Image Source="images/icon.png"/>
<Image Source="../icon.png"/>

Or their rooted path:

<Image Source="/Assets/icon.png"/>

If the asset is located in a different assembly to the XAML file then use the avares: URL scheme. For example if the asset is contained in an assembly called MyAssembly.dll then you would use:

<Image Source="avares://MyAssembly/Assets/icon.png"/>

Referencing manifest resources

Assets can also be included in .NET applications by using the <EmbeddedResource> MSBuild item which causes the file to be included in the assembly as a manifest resource.

You can reference manifest resources using the resm: URL scheme:

<Image Source="resm:MyApp.Assets.icon.png"/>

Or if the resource is embedded in a different assembly to the XAML file:

<Image Source="resm:MyApp.Assets.icon.png?assembly=MyAssembly"/>

The name of the asset is automatically generated by MSBuild from the assembly name, the file path and the filename - all separated with periods. If Avalonia is unable to find a manifest resource, check the resource name using Assembly.GetManifestResourceNames.

Loading assets from code

Assets can be loaded from code using the IAssetLoader interface:

var assets = AvaloniaLocator.Current.GetService<IAssetLoader>();
var bitmap = new Bitmap(assets.Open(new Uri(uri)));