search

MudBlazor / MudBlazor

Blazor Component Library based on Material design with an emphasis on ease of use. Mainly written in C# with Javascript kept to a bare minimum it empowers .NET developers to easily debug it if needed.
http://mudblazor.com
MIT License
7.23k stars 1.18k forks source link

v7.0.0 Migration Guide #8447

Open henon opened 1 month ago

henon commented 1 month ago

MudBlazor version 7.0.0 brings a ton of breaking changes which we can't postpone any longer as we strive for more consistency and necessary improvements. This migration guide shall make the upgrade process as easy as possible for you.

Note: Please limit discussion strictly to migration or reporting errors in this guide. Discussion about the changes itself belong in the linked PRs and will be deleted in this issue. If you want to give general feedback about version 7.0.0 you are welcome to do it in MudBlazor v7 Feedback.

[!NOTE] v7.0.0 is currently in preview stage, you will find the nuget if you check the Include prerelease checkbox in Visual Studio. Please expect a few more breaking changes until we finally enter the release-candidate stage.

[!WARNING] Many parameters have been renamed to make the API more consistent, i.e. IsEnabled => Enabled. Please be aware that the compiler will NOT throw errors for unknown parameters in razor because of attribute splatting. This means, that you have to be extra careful when migrating your application from v6.x.x to v7.0.0. This is why we added an illegal parameter detection logic in MudComponentBase which will throw a runtime exception if you forgot to rename any parameters in your razor files. Of course you'll still have to make sure you test all your UI by rendering every component. You can opt-out of this behavior by setting MudGlobal.EnableIllegalRazorParameterDetection = false in your app at startup. If you derived your own components from our MudComponentBase you can override the detection function DetectIllegalRazorParametersV7() for your own components. #8771

How to Use this Guide

Since the guide itself is quite lengthy you probably won't need to read it all. But you should read all the Warning boxes as they are very important.

It is probably best if you just compile your app against the v7 nuget and use browser search to find the new parameter or method name for the renamed parameters in this guide. Once your app runs again make sure you run all your tests to find additional problems in razor which will surface as ArgumentExceptions. If you don't have full test coverage then it is advised that you do a full manual test by visiting every razor component of your UI.

.NET 6 is not supported any longer

If you need .NET 6 support you can stay on the latest v6.x.x version. If you need any bug fixes in v6 please PR and we'll release v6 updates for you.

For more details see #8441

ICommand no longer supported

This concerns the components: MudBaseButton, MudButton, MudIconButton, MudFab, MudChip, MudListItem, MudBaseSelectItem, MudNavLink, MudMenu, MudMenuItem, MudOverlay, MudTreeViewItem, MudTableBase, MudTable

For more details see #8436

Unified Breakpoint Services

The services SubscriptionInfo, ResizeService, ResizeListenerService, ResizeBasedService and BreakpointService have been removed and are replaced entirely by BrowserViewportService.

For more details see #8467

Service Configuration

Some MudBlazor services hat config methods where you could directly pass options. These have been removed in favor of overloads where you pass an Action<SomeServiceOptions> which then manipuluates the options. The removed overloads are:

For details see #8531

Async Protected Methods now bear the Async Postfix

Several protected async methods were renamed to bear the Async postfix to comply with our naming rules. For the most part we don't list them here as they are not important for most users except those few who derived own components from ours.

Changes to Inputs

These changes concern MudTextField, MudInput and all inheriting from MudBaseInput

If an input has no label, it now automatically shrinks in height by 4px: image image

For details see #8476 and #8540

Pickers

This concerns the components MudPicker, MudColorPicker, MudBaseDatePicker, MudDatePicker, MudDateRangePicker, MudTimePicker

For details see #8506 and #8517

IMudStateHasChanged related

To force a render update cast the component in question to IMudStateHasChanged and call StateHasChanged() on it. Other public ways to force a refresh have been removed

Accessability Changes

Renamed Components

Gray is the new Grey

All usage of grey was renamed to gray in Colors, Palette and in css variables and classes. For more Details see #8452

MudTheme

MudThemeProvider

Before (v6.x.x):

<MudThemeProvider/>
<MudDialogProvider/>
<MudSnackbarProvider/>

After (v7.x.x):

<MudThemeProvider/>
<MudPopoverProvider/>
<MudDialogProvider/>
<MudSnackbarProvider/>

Icons

See #8421, #8536 for more details.

Inverted Negative Parameters

For more consistency negative parameter names were renamed and inverted. You need to do the same, make sure to invert the boolean value or condition for these parameters! This change concerns the components: MudButton, MudSelectItem, MudFab, MudToggleIconButton, MudCheckBox, MudListItem, MudMenu, MudNavGroup, MudRadio, MudRatingItem, MudSwitch, MudToggleGroup, MudList, MudListItem, AppBar, ToolBar, ExpansionPanel and possibly some others as well:

Other changes

MudAutocomplete

MudChipSet and MudChip

Both are now generic and MudChipSet<T> selection is now data driven which means that it only selects values not MudChips.

Correspondence of old parameters to the new selection mode (#8722):

MultiSelection Mandatory SelectionMode
true * SelectionMode.MultiSelection
false true SelectionMode.SingleSelection
false false SelectionMode.ToggleSelection

[!WARNING]
Due to the unification of selection features over all components the default selection mode of MudChipSet has changed. Prior to v7 chips could be selected off by default. In v7 the default is SelectionMode.SingleSelection (like for all other components that support parameter SelectionMode) which does not allow to de-select chips by clicking again. Set to SelectionMode.ToggleSelection for that. #8722

MudColorPicker

MudDialog

The changes below concern the classes MudDialog, MudDialogOptions, MudDialogInstance and MudDialogProvider and DialogResult

MudDrawer

MudExpansionPanels

For more details see #8446

MudExpansionPanel

For more details see #8446

MudFileUpload

MudFormComponent

This concerns all inputs which inhert from MudFormComponent, such as MudTextField, MudCheckBox, MudSwitch, MudFileUpload, etc.

MudGrid

[!WARNING] To unify spacing accross the library the default spacing unit in MudGrid was changed (halved from 8px to 4px). To keep the gaps the same as in v6 you need to double the value of the Spacing parameter. #8910

If you didn't set a value vor Spacing, you don't have to do anything as we already doubled the default value. Of course the maximum allowable spacing has also been increased from 10 to 20.

MudList

MudList and MudListItem are now generic <T> so you can bind any type to SelectedValue. This means you now must specify T, even if you don't use the selection feature. #8613

MudRadioGroup

MudSelect

MudSnackbar

MudSwipeArea

MudTable

MudTreeView

[!WARNING]
MudTreeViewItem: Parameter ExpandedIcon was removed. Use ExpandButtonIcon instead to set a custom glyph for the expand button. This is not to be confused with the new parameter IconExpanded which is a new feature to allow showing an alternate icon in expanded state instead of Icon. #8661

MudDrawer

MudDataGrid

For more details see #8548, #8317, #8892

MudMenu

MudMenuItem:

Seanxwy commented 1 month ago

When is it expected to be released

henon commented 1 month ago

I expect the first pre-release towards the end of April, no sooner. It greatly depends on how busy the team is with their day-to-day jobs.

igotinfected commented 3 weeks ago

@henon the FileUploadButtonTemplateContext.ClearAsync marked as required property. part is no longer applicable since the template context was removed

henon commented 3 weeks ago

@henon the FileUploadButtonTemplateContext.ClearAsync marked as required property. part is no longer applicable since the template context was removed

Thanks, I removed it.

Conman-123 commented 3 weeks ago

Under the "Other Changes" heading the info about the Snackbar changes could be moved to be under the "Snackbar" heading with the other snackbar related stuff.

gyanverma2 commented 3 weeks ago

I do not understand what is the use of name change of so many property for a stable framework. Its like thanos snap .. gone

henon commented 3 weeks ago

I do not understand what is the use of name change of so many property for a stable framework. Its like thanos snap .. gone

@gyanverma2 TLDR; you may choose to keep using v6.x.x and as long as people submit bugfix PRs and .net version upgrades for the v6 branch it will live on.

We are not abandoning v6 if you still need it. Just don't expect us to support or innovate on it (it just isn't possible with such a small team), the community will have to do the minimum that's necessary to keep it alive and we'll do our part by reviewing and merging your PRs against the v6 branch.

We know very well that breaking changes are a burden for users! That's why we have kept mudblazor stable for years and avoided all breaking changes in that time period. But consistency does matter too, and many users have complained about it. Also, the design errors we made over the years are really hampering us and hinder innovation. We needed to break at some point in time and that time is now.

In the future, there will be other breaking changes as the library has to evolve. Maybe it was wrong to wait so long. Maybe we should have made a small set of breaking changes at regular intervals instead of doing a big break like this. And we'll ask the community if we should break more often in the future with smaller change-sets.

In any case, we do our best to help anyone migrate. That's why we are tracking all the changes in this document. You can compile your app, see what compiler errors you get and do a quick Ctrl+F find in this guide to see what you have to change. Also, we added an illegal parameter detection for razor parameters so when you execute your app you'll get runtime errors for all the parameters you forgot to update. We decided that this way (failing fast instead of silently ignoring errors) is the easiest way for you to migrate if you want. You don't have to though.

zackasattackas commented 2 weeks ago

I just want to say that I am very excited for this release! Huge thank you to everyone who contributed their time and energy to making this happen 🙏

stephajn commented 2 weeks ago

I'm glad that you've been giving Obsolete warnings throughout the lifetime of v6.x. I wish the Blazor compiler did more to help raise those when compiling, but that's on Microsoft to fix.

You guys have done a fantastic job, and thank you for only breaking on a major release, and not a minor one like Microsoft's Graph package. You're doing a fantastic job, and this migration guide is invaluable!

henon commented 2 weeks ago

I'm glad that you've been giving Obsolete warnings throughout the lifetime of v6.x.

Yes, but not all breaking changes we made in v7 have been preceeded by obsoletion warnings. While working on v7 we discovered a lot more inconsistencies and rectified them on the spot.

I wish the Blazor compiler did more to help raise those when compiling, but that's on Microsoft to fix.

Yes, but we have added runtime exceptions for renamed parameters and there is also a new approach in the works by @peterthorpe81 who is tinkering with a compile time analyzer: https://github.com/MudBlazor/MudBlazor/pull/8771#issuecomment-2087717291

digitaldirk commented 1 week ago

Some things I ran into that I could not find in this guide: DialogOptions - DisableBackdropClick -> BackdropClick, this needs to be added to the inverted negative parameters section?

MudDatePicker - datePicker.Close() -> await datePicker.CloseAsync

For MudList and MudListItem I couldn't set T in my project. I restarted Visual Studio then it started working, just an FYI if anyone encounters this.

henon commented 1 week ago

Thanks for reporting @digitaldirk, I've updated the guide.

digitaldirk commented 1 week ago

Minor one for MudColorPicker - ShowToolbar is now defaulted to true so you need to set that to false to get previous default.

henon commented 1 week ago

Minor one for MudColorPicker - ShowToolbar is now defaulted to true so you need to set that to false to get previous default.

Hmm, maybe we should revert that to false? Sounds like an oversight to me. Edit: done in f98e9a1b

ScarletKuro commented 1 day ago

Created a discussion topic MudBlazor v7 Feedback