5.0.0 Migration Guide

[Keboo]

This is a living document that is expected to be a guide for updating from 4.9.0 to 5.0.0. All feedback is welcome here, however if you are running into a specific issue with the migration, please open a new issue rather than commenting here.

This will cover the most common upgrade issues. You can find a list of breaking changes on issue: #2255.
Anything that was previously marked as Obsolete in the 4.9.0 or earlier release has been removed.

Main Defaults Resource Dictionary Renamed

Because we are still supporting both Material Design 2 and Material Design 3 styles, the previous MaterialDesignTheme.Defaults.xaml resource dictionary has been replaced with MaterialDesign2.Defaults.xaml and MaterialDesign3.Defaults.xaml. In your main App.xaml replace with one of those two dictionaries. If you want your app to still use the same previous look and feel, the MaterialDesign2.Defaults.xaml resource dictionary most closely resembles the defaults from the 4.9.0 release.

Brush Renames

To better facilitate the addition of new brushes as well as to make adjusting individual components, the library has adopted a new naming scheme for brush resources.

1. All brush resources will now start with the MaterialDesign.Brush. prefix.
2. Theme color brushes (Primary and Secondary) will be in the form MaterialDesign.Brush.<Primary|Secondary>.[Light|Dark]. Corresponding foreground colors, will have a .Foreground suffix added. For example MaterialDesign.Brush.Secondary.Light or MaterialDesign.Brush.Primary.Foreground.
3. "Accent" has been replaced with "Secondary" on all brushes.

For anyone wishing to avoid needing to do the brush rename at the time of upgrade, there is an additional resource dictionary that you can include that maps the old brush resource names to the new names. This would typically get placed in the merged resource dictionary of your App.xaml.

<ResourceDictionary Source="pack://application:,,,/MaterialDesignThemes.Wpf;component/Themes/MaterialDesignTheme.ObsoleteBrushes.xaml" />

Be aware that this should be considered a temporary solution to allow time to do the full migration. It is not expected to be maintained long term and is subject to have items removed from it on future releases.

There is also a migration script that can be run on your repository that will attempt to locate brush resources and update them. Be aware this only looks for {StaticResource xxx} and {DynamicResource xxx} references for brushes. You can find the script in the repository here

See #2435 for more additional details.

Style renames

To standardize on naming, all usages of "Accent" in the style keys were replaced with "Secondary". For many style keys, simply making this one change will appropriately update it.

1. All obsolete styles have been removed.
2. "MaterialDesignNavigatilRailTabControl" fixed the typo and is now "MaterialDesignNavigationRailTabControl"

For anyone wishing to avoid needing to do the style rename at the time of upgrade, there is an additional resource dictionary that you can include that maps the old styles keys to the new names. This would typically get placed in the merged resource dictionary of your App.xaml.

<ResourceDictionary Source="pack://application:,,,/MaterialDesignThemes.Wpf;component/Themes/MaterialDesignTheme.ObsoleteStyles.xaml" />

Be aware that this should be considered a temporary solution to allow time for you to do the full migration. It is not expected to be maintained long term and is subject to have items removed from it on future releases.

There is also a migration script that can be run on your repository that will attempt to locate style resources and update them. Be aware this only looks for {StaticResource xxx} and {DynamicResource xxx} style references. You can find the script in the repository here

ShadowAssist replaced by ElevationAssist

The ShadowAssist was previously marked as Obsolete in the 4.9.0 release and has been completely removed int he 5.0.0 release.
To fix any usages simply update from ShadowAssist to ElevationAssist and ShadowDepth to Elevation. The old values map to the new ones as follows:
ShadowDepth.Depth0 => Elevation.Dp0
ShadowDepth.Depth1 => Elevation.Dp2
ShadowDepth.Depth2 => Elevation.Dp3 or Elevation.Dp4
ShadowDepth.Depth3 => Elevation.Dp7 or Elevation.Dp8
ShadowDepth.Depth4 => Elevation.Dp12 or Elevation.Dp16
ShadowDepth.Depth5 => Elevation.Dp16 or Elevation.Dp24

Code renames

All extension method classes have had their "Mixin" suffix replaced with an "Extensions" suffix. In most cases, this will be a transparent change, unless you are invoking the extension method directly as a static method.

[longkimkao]

Hello, how can i change the height of textbox outline ?

[Keboo]

I assume you are looking to change the thickness of the outline? If so, the property you want to change is BorderThickness

[longkimkao]

Thank for your reply.
I mean reduce the height of this textbox, change the height from this

to this

i use poperty height, fontsize, padding. But i thing MaterialDesign will have property to do that.

[Keboo]

It sounds like you are likely already on the right path. The Padding property is the biggest contributor toward that default height. To get a look similar to your picture you are probably looking to do about Padding="8" or similar.

[maydoc]

Hi, regarding ShadowAssist.ShadowEdges, I'm getting an error that it doesn't exist, what name was it changed to?

[Keboo]

It was functionally removed in #3217 and was removed in the 5.0.0 because it was no longer be respected by any of the controls. If it is still in use in your project, you can simply wrap the control and clip it to achieve the same visual effect.

[mohsen-id]

hi, What is the best way to access these PrimaryXXX colors in version 5?

[Keboo]

The brushes were renamed, but the colors are still available and can be referenced the same as before. However, be aware that all of the "Accent" resource dictionaries did have their names changed to be "Secondary" instead. Beyond that, all of the color resource dictionaries should be unchanged. You can see all of them here: https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/tree/master/MaterialDesignColors.Wpf/Themes

[mohsen-id]

Thanks for reply.
The link goes to 404 - page not found!

I migrated to version 5 and in some parts of the code I used Static Resource PrimaryXXX colors that do not exist now. If I add MaterialDesignColor.XXX.xaml as a ResourceDictionary to App.xaml, it affects BundledTheme and changes the Foreground color for example.

What is the best way to access these PrimaryXXX colors in version 5?

my App.xaml:
<ResourceDictionary.MergedDictionaries> <md:BundledTheme BaseTheme="Light" PrimaryColor="DeepOrange" SecondaryColor="Lime" /> <ResourceDictionary Source="pack://application:,,,/MaterialDesignThemes.Wpf;component/Themes/MaterialDesign3.Defaults.xaml" /> </ResourceDictionary.MergedDictionaries>

[Keboo]

My apologies on the link we just recently redid the repo structure, which broke the link. Here is the updated one.

https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/tree/master/src/MaterialDesignColors.Wpf/Themes

As for accessing the colors, this works for me, and I am not seeing the issue with the theme problems you describe.

App.xaml

<Application.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <materialDesign:BundledTheme BaseTheme="Inherit"
                                   ColorAdjustment="{materialDesign:ColorAdjustment}"
                                   PrimaryColor="DeepPurple"
                                   SecondaryColor="Lime" />

      <ResourceDictionary Source="pack://application:,,,/MaterialDesignColors;component/Themes/MaterialDesignColor.Amber.xaml" />

      <ResourceDictionary Source="pack://application:,,,/MaterialDesignThemes.Wpf;component/Themes/MaterialDesign2.Defaults.xaml" />
    </ResourceDictionary.MergedDictionaries>
...

Then in my application:

<Button Style="{StaticResource MaterialDesignFloatingActionMiniLightButton}"
        ToolTip="MaterialDesignFloatingActionMiniLightButton">
  <Button.Background>
    <SolidColorBrush Color="{DynamicResource Primary400}" />
  </Button.Background>
  <materialDesign:PackIcon Width="{StaticResource IconSize}"
                            Height="{StaticResource IconSize}"
                            Kind="Alarm" />
</Button>

In the demo app, this then looks something like this (first button is now using the Amber color).