BlazorBindings.Maui

BlazorBindings.Maui allows you to build native and hybrid mobile applications for Android, iOS, Windows, macOS, and Tizen using C#, .NET, and the Blazor programming model.

Instead of using HTML/CSS for the UI, you use Razor syntax to define components that render as native MAUI UI controls. This enables you to use familiar web development patterns (like component-based architecture and Razor syntax) while producing high-performance native mobile interfaces.

The generator automatically maps MAUI member types to Blazor [Parameter] types based on the following rules:

Classification can be overridden using attributes like ContentProperties, NonContentProperties, or CommandEvents.

The Component Generator is a .NET global tool (dotnet-generate-maui-blazor-components) used to automatically generate Blazor wrapper components for .NET MAUI types. You can install it globally or locally via NuGet.

# Global installation
dotnet tool install -g BlazorBindings.Maui.ComponentGenerator

# Local installation (requires a tool manifest)
dotnet tool install BlazorBindings.Maui.ComponentGenerator

To begin building your first application, follow the official documentation guide:

https://dreamescaper.github.io/MobileBlazorBindingsDocs

To tell the generator which MAUI types to wrap, place assembly-level attributes in your project (conventionally in Properties/Elements.cs). You can target a single type or an entire assembly.

// Generate a wrapper for a single MAUI type
[assembly: GenerateComponent(typeof(MyCustomView))]

// Generate wrappers for every public MAUI Element in an assembly
[assembly: GenerateComponentsFromAssembly(typeof(SomeThirdPartyControl))]

Since all generated classes are declared as partial, you can add custom logic in a hand-written companion file. The generated static constructor automatically calls a partial void RegisterAdditionalHandlers() method. You can implement this method to perform custom event wiring or add helpers.

// Button.cs (hand-written)
namespace BlazorBindings.Maui.Elements;

public partial class Button
{
    // Add extra helpers, override HandleParameter, etc.
    partial void RegisterAdditionalHandlers()
    {
        // custom event wiring
    }
}

You can define native mobile UI components using Razor syntax. The markup uses mobile-specific components (like StackLayout, Label, and Button) instead of HTML elements. The logic is handled in a @code block, just like in standard Blazor development.

Example of a native counter component:

<StackLayout>
    <Label FontSize="30">You pressed @count times </Label>
    <Button Text="+1" OnClick="@HandleClick" />
</StackLayout>

@code {
    int count;

    void HandleClick()
    {
        count++;
    }
}

Use the [GenerateComponent] attribute to fine-tune how a specific MAUI type is exposed as a Blazor component. This allows you to include/exclude members, handle generics, rename properties, and map commands to events.

// Exclude a property
[assembly: GenerateComponent(typeof(AvatarView), 
    Exclude = [nameof(AvatarView.CornerRadius)])]

// Map an ICommand to an EventCallback
[assembly: GenerateComponent(typeof(VirtualizeListView), 
    Exclude = [nameof(VirtualizeListView.LayoutManager)],
    CommandEvents = [$"{nameof(VirtualizeListView.ThresholdCommand)}:OnThreshold"])]

// Make object-typed event args generic
[assembly: GenerateComponent(typeof(VirtualizeListView), 
    GenericProperties = [
        nameof(VirtualizeListView.OnItemTapped),
        nameof(VirtualizeListView.OnItemAppearing),
        nameof(VirtualizeListView.OnItemDisappearing)])]

Use the [GenerateComponentsFromAssembly] attribute to generate wrappers for all qualifying public types in a specific assembly. By default, it targets types derived from Microsoft.Maui.Controls.Element.

[assembly: GenerateComponentsFromAssembly(
    typeof(Syncfusion.Maui.Core.SfView),
    TypeNamePrefix = "Sf",
    Exclude = [typeof(SfInternalHelper)])]

Use the following flags when running dotnet-generate-maui-blazor-components:

| Argument / Option | Description |
|---|---|
| `project-path` (positional) | Path to the `.csproj` file to process. Defaults to the first `.csproj` found in the current directory. |
| `-o`, `--out-path` | Directory where generated files are written. Defaults to `../Elements` relative to the project file. |
| `--keep-existing-files` | Do not delete `*.generated.cs` files from a previous run before writing new ones. Defaults to `false`. |

Execute the tool by pointing it to a .csproj file. You can specify an output directory and decide whether to preserve existing generated files.

dotnet-generate-maui-blazor-components [project-path] [options]

# Example usage:
dotnet-generate-maui-blazor-components src/MyControls/MyControls.csproj -o src/MyControls.Blazor/Elements

The Entry<T> element is a Blazor component that wraps a native MAUI Entry control. It allows you to bind text input to strongly-typed values (such as string, int, double, etc.) instead of just strings.

It supports two-way binding via the Text parameter and the TextChanged EventCallback.

<Entry @bind-Text="myNumber" />

@code {
    private int myNumber;
}