dotnet / dotnet/docs-maui

Update the `migrate custom renderer page` with better more current examples

Open
#1,467 2 comments 1 reaction 5 assignees Claimed by @jsuarezruiz View on GitHub
doc-enhancement dotnet-maui/tech dotnet-mobile/prod Pri1 upgrade-from-xamarin
Dominant language
No language data
Stars
282
Forks
265
Avg merge
2d 2h
Merged PRs (30d)
19

Description

I feel like this doc is a bit confusing and doesn't quite guide users to what they are looking for. If we want to show migration, then I think we need to have the renderer equivalent on that doc to show a start point and end point.  This doc just feels like a TLDR of a doc explaining what a handler is but not about how to migrate a renderer to a handler.

I think a doc about migrating a custom renderer should have a couple sections covering the paths.

## Sections

### Easy path of just converting a basic Renderer to Mappers

Here's an example of a renderer someone created inheriting from EntryRenderer in order to set a few properties

```C#
MyCustomEntryRenderer : EntryRenderer
...
override OnPropertyChanged
{
if (propertyName == "TextColor")
}
```

Then show how that code can easily be shifted to a handler using a mapper. Drawing the comparison between the replacement parts

```C#
EntryHandler.Mapper.(Modify/Append/Prefix)("TextColor")
```
- If that doesn't work try using a shim, and please log a bug
- If that doesn't work, please log a bug
- Are you still confused? Create a discussion [here](https://github.com/dotnet/maui/discussions/categories/upgrading-from-xamarin)

#### Areas that match between renderers/handlers
- Mappers -> override OnElementPropertyChanged
- returning your own platform view -> Handler.CreatePlatformViewFactory
- This is also relevant if users are overriding a platform method. For example, in the code if they are overriding `UIView.WillMoveToWindow` the way to do that in the `handler` architecture is to use `PlatformViewFactory` to supply an inherityed view and override it there. (Except for UIButton which is special)
- Dispose -> subscribe to `Loaded/Unloaded` or watch for the `WindowChanged` property on the VirtualView (this is a little bit messy right now but we can provide some samples). Disconnect/ConnectHandler won't behave like they expect them to currently if they are wanting a replacement for `dispose`.
- We can also use some samples here showing how to inherit from the platform control.

### Larger path if user is inheriting from VisualElementRenderer

- If your VER is too complicated currently to just convert to a handler based on (link to docs talking about handlers and comparing to renderers) then we have these options for you
- try using our handler based VisualElementRenderer that's based on a handler
- here we should make sure to clarify the use of "AddHandler" vs "AddCompatibiltiyRenderer"
- If that doesn't work try using a shim and please log a bug
- If that doesn't work, please log a bug
- Are you still confused? Create a discussion [here](https://github.com/dotnet/maui/discussions/categories/upgrading-from-xamarin)

### Samples
As we add scenarios/samples to this doc we should also accompany them with samples in our maui-samples repository.

- How do I access the NavigationBar on iOS?
- How do I replace the ViewController of a Page?

---
#### Document Details

⚠ *Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.*

* ID: 125882c9-c32b-e41d-c39d-6b63b7799499
* Version Independent ID: 125882c9-c32b-e41d-c39d-6b63b7799499
* Content: [Migrate a custom renderer to a .NET MAUI handler - .NET MAUI](https://learn.microsoft.com/en-us/dotnet/maui/migration/renderer-to-handler?view=net-maui-7.0)
* Content Source: [docs/migration/renderer-to-handler.md](https://github.com/dotnet/docs-maui/blob/main/docs/migration/renderer-to-handler.md)
* Product: **dotnet-mobile**
* Technology: **dotnet-maui**
* GitHub Login: @davidbritch
* Microsoft Alias: **dabritch**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.