You can create and use a custom client-side Blazor component for a specific ViewModel column in a Turnkey application; this page is for developers who build the component and deploy its assemblies and browser artifacts.

Blazor is the client-side UI engine used by Turnkey through the appl controller. Use this extension mechanism when one tagged ViewModelColumn needs its own renderer. For replacing standard Blazor component types more broadly, use Blazor IComponentTypeSwitchBroker instead.

What you build

A Blazor extension component is a Razor component compiled into a .NET assembly. Turnkey needs both:

• the component assembly for server-side use; and
• the files generated for browser execution, including the WebAssembly files and their compressed variants.

For example, a Razor Class Library can contain a component named Component1. You then configure a ViewModelColumn to render that component instead of its standard Blazor renderer.

Create the component project

1. Create a Blazor application project. This application is the shell that Visual Studio builds into browser-ready output.
2. Create a Razor Component project (Razor Class Library) for the reusable component.
3. Add a project reference from the Blazor application project to the Razor Component project.
4. Add the MDriven.SharedInterfaces.WebAssembly NuGet package to the Razor Component project.
5. Create your Razor component in the Razor Component project.

The application project must reference the component project. Building the application then creates the additional files that the browser needs to load the component.

Use MDCompBase when available

Reference MDriven.Components.WebAssembly and inherit from MDCompBase at the start of the component file. This is the preferred approach because it supplies the parameters that make the component a full MDriven Turnkey component.

@inherits MDCompBase

<div class="my-component">
  This component is defined in the component library.
</div>

Declare the Turnkey parameters when not using MDCompBase

If you do not inherit from MDCompBase, declare the parameters expected by Turnkey in your component. These parameters provide component metadata, binding context, rendering context, and the current ViewClient.

@using System.Xml.Linq
@using MDriven.SharedInterfaces.WebAssembly

<div class="my-component">
  This component is defined in the component library.
</div>

@code {
  [Parameter]
  public string CompType { set; get; }

  [Parameter]
  public XElement XElement { set; get; }

  [Parameter]
  public string BindInfoColumn { set; get; }

  [Parameter]
  public string BindInfoNesting { set; get; }

  [Parameter]
  public IVMClassObject ContextIVMClassObject { set; get; }

  [Parameter]
  public string RendersAction { set; get; }

  [Parameter]
  public string RendersActionThatUseAbstractAction { set; get; }

  /// <summary>
  /// When the component is used as a grid cell, it should normally avoid rendering its label and similar surrounding UI.
  /// </summary>
  [Parameter]
  public bool IsGridCell { set; get; }

  [Parameter]
  public bool IsGridEditable { set; get; }

  [CascadingParameter(Name = "ViewClient")]
  public IViewClient? ViewClient { get; set; }

  [Parameter]
  public string FlexStyling { get; set; }
}

Build the browser artifacts

Build the solution, then locate both the component assembly and the browser artifacts produced by the Blazor application build.

The component library produces a .dll in its build output. The Blazor application also produces browser-loadable files under a path similar to:

bin\Debug\net8.0\wwwroot\_framework

The .wasm file is the WebAssembly format executed in the browser. Include its .wasm.gz variant as well; Turnkey uses the compressed file to conserve bandwidth. You may need to publish the Blazor application to cause all required files to be generated.

To copy resolved NuGet dependencies, including transitive dependencies, to the regular build output directory, add the following property to the Blazor application project:

<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>

This places the DLLs and WebAssembly-related output together under a build folder such as bin\Debug\net8.0, which makes deployment easier.

Deploy to Turnkey

1. In the Turnkey application, create or open the EXT_ComponentsRazor folder.
2. Copy the component DLL and the generated browser artifacts into that folder.
3. Include all assemblies required by the component, not only the assembly that contains the Razor component.
4. Include the .wasm and .wasm.gz files generated for the browser.
5. Restart or reload the application as required by your deployment workflow, then open the Blazor page and inspect the browser console for loading errors.

The component DLL and the browser-executable files are both required: one is used when running server-side and the other is used in the browser.

JavaScript and CSS files

Turnkey also scans EXT_ComponentsRazor for *.js and *.css files. It references these early in the Blazor index-page load process.

When a Razor component uses a script, use the Razor JavaScript naming convention component.razor.js. At runtime, Turnkey looks for component scripts in this pattern:

./EXT_ComponentsRazor/CompName/script1.razor.js

The same location pattern applies to .js.map, .ts, and .css files.

Attach the component to a ViewModelColumn

Use a tagged value to select the custom component for one column.

1. Open the ViewModel in MDriven Designer.
2. Select the ViewModelColumn that should render with the custom component.
3. Add the tagged value Blazor_Ext_Component.
4. Set its value to the assemblies followed by the component type, separated by semicolons.
5. Run the ViewModel through the Blazor client and check the browser console if the component does not render.

The tagged-value value has this format:

AssemblyNameWithoutExtension;AdditionalAssemblyIfNeededWithoutExtension;AsManyAssembliesAsNeededWithoutExtension;TheTypeOfTheComponent

For example, if the component is in an assembly named RazorClassLibrary1.dll, and no additional assemblies are needed, the value ends with the component's .NET type name:

RazorClassLibrary1;Namespace.Component1

Do not include the .dll extension in an assembly name. Add further required assembly names before the component type, each separated by a semicolon.

Goal	Use
Override one tagged ViewModelColumn	Set Blazor_Ext_Component on that column.
Replace one or more standard Blazor component types across the UI	Use Blazor IComponentTypeSwitchBroker.

Develop against a local component folder

During development, you often need to rebuild the component and test it in Turnkey repeatedly. Add the EXT_ComponentsRazorPath attribute to MDrivenServerOverride to make Turnkey search one or more additional component directories.

Separate multiple paths with semicolons. Turnkey searches these paths in addition to the default component location.

If component scripts are kept outside the deployed component folder during development, set EXT_ComponentsRazorPathForJSScripts on MDrivenServerOverride. This attribute also accepts multiple semicolon-separated paths.

Troubleshooting

Symptom	Check
The component does not render	Confirm that Blazor_Ext_Component is set on the intended ViewModelColumn and that the final type name is correct.
Assembly loading fails	Confirm that every required assembly is copied to EXT_ComponentsRazor, with assembly names in the tagged value written without .dll.
Browser-side loading fails	Confirm that the generated .wasm and .wasm.gz files are deployed. Publish the Blazor application if a regular build did not generate all needed files.
A component script is not found during development	Check the component.razor.js name and configure EXT_ComponentsRazorPathForJSScripts when the script is outside the runtime component folder.
The custom renderer affects more columns than intended	Use Blazor_Ext_Component only on the selected ViewModelColumn. For intentional global replacement, use Blazor IComponentTypeSwitchBroker.

See also

• Documentation:Blazor
• Documentation:Blazor IComponentTypeSwitchBroker
• Documentation:EXT Components
• Documentation:Component

Create a custom Blazor component

MDriven Turnkey can inject a custom component on specifically tagged ViewModel columns in the Blazor client. If the goal is to replace standard components more broadly, see the documentation for Blazor IComponentTypeSwitchBroker.

Components for this integration must be built as Blazor WebAssembly components.

Build the component library

1. Create a Razor component library and add it as a project reference from the Blazor application.
2. Add the MDriven.SharedInterfaces.WebAssembly NuGet package to the component project.
3. Create a Razor component that declares the parameters supplied by MDriven Turnkey.

@using System.Xml.Linq
@using MDriven.SharedInterfaces.WebAssembly

<div class="my-component">
    This component is defined in the component library.
</div>

@code {
  [Parameter]
  public string CompType { set; get; }

  [Parameter]
  public XElement XElement { set; get; }

  [Parameter]
  public string BindInfoColumn { set; get; }

  [Parameter]
  public string BindInfoNesting { set; get; }

  [Parameter]
  public IVMClassObject ContextIVMClassObject { set; get; }

  [Parameter]
  public string RendersAction { set; get; }

  [Parameter]
  public string RendersActionThatUseAbstractAction { set; get; }

  /// <summary>
  /// A component used as a grid cell will normally avoid rendering its label and similar content.
  /// </summary>
  [Parameter]
  public bool IsGridCell { set; get; }

  [Parameter]
  public bool IsGridEditable { set; get; }

  [CascadingParameter(Name = "ViewClient")]
  public IViewClient? ViewClient { get; set; }

  [Parameter]
  public string FlexStyling { get; set; }
}

As an alternative to declaring these parameters in every component, reference MDriven.Components.WebAssembly and add @inherits MDCompBase at the beginning of the component file.

Prepare the build output

Building the component produces an assembly in the build output folder. Building the Blazor application also produces browser-run files under its wwwroot/_framework output. A publish may be required to produce all needed files.

Add the following property to the application project to copy resolved NuGet package dependencies, including transitive dependencies, to the regular build output directory:

<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>

Copy the component assembly and the required Blazor WebAssembly output files into the Turnkey application's EXT_ComponentsRazor folder. The source documentation specifically identifies the WebAssembly file and its gzipped .wasm.gz counterpart; the gzipped file is used to conserve bandwidth.

Attach the component

Tag the intended ViewModel column according to the component-extension configuration described in the MDriven documentation. When the Blazor client renders that tagged column, it can use the custom component and provide the parameters shown above.

Global component replacement

A tagged-column component is intended for a selected ViewModel column. To blanket-replace all, or selected, standard Blazor components using custom switch logic, use Blazor IComponentTypeSwitchBroker.

See also

• Documentation:Blazor
• Documentation:Blazor IComponentTypeSwitchBroker
• Documentation:EXT ComponentsBlazor