MAUI essentials (MEs) are used to leverage the users’ device when they’re using the trellispark MAUI application. The features in MEs functionality often needs to be implemented differently when on the website. Following these standards will keep your MEs implementation clean and consistent making it easy to implement in any component.
This article will cover various steps that are required to implement MEs functionality and the standards to be followed.
Interface
Each MEs implementation will require an interface. The interface will reside in the Shared project in the Interfaces folder. Ensure the following standards are met when building your interfaces.
All MEs interfaces must contain an IsAvailable Boolean that only provides a getter.
Why? – This Boolean will be used in components to check if the user is using the trellispark MAUI application and if they can access MEs functionality.
public interface IMaps
{
public bool IsAvailable { get; }
}All methods in MEs interfaces must be a Task that returns a string OR an object that contains a string property for an error message.
Why? – The string (or string property on an object) will contain a user-friendly error message that can be displayed in a notification if something goes wrong. Returning a string or object allows the component that called the method to check if the string or string property contains a value and to display a notification to the user, so they receive visual feedback that something went wrong.
// Return a string.
public Task<string> OpenMap();
// Return an object.
public class FileInformation
{
public MemoryStream FileData { get; set; } = new();
public string ErrorMessage { get; set; } = "";
}
public Task<FileInformation> OpenFile(FileInformation data);Services
Two services need to be created for MEs to provide implementation for the methods in the interface. MEs are only available when using the MAUI application, so you will need to provide a separate services implementation that blocks the action if the user is on the website.
IMPORTANT NOTE: Remember to declare your services as a Singleton in the MauiProgram.cs file for MAUI and the Program.cs file for the websites. Also inject the services in the _Imports.razor files.
UX-WASM-Services
To provide implementation to block the action on the website create a new service in the UX-WASM-Services projects WASM MAUI Services folder. Ensure the following standards are met when building your service.
IMPORTANT NOTE: All services must implement a MEs interface.
Provide implementation for the IsAvailable Boolean that returns false.
Why? – Components will check this property on the service to determine if they can use MEs functionality and block access if not permitted.
public bool IsAvailable
{
get { return false; }
}Provide implementation for interface methods that return a user friendly message back that the service is not available.
Why? – MEs functionality is not available on the website, so returning a string will inform the user they cannot do the requested action on the website.
public Task<string> OpenMap()
{
return Task.FromResult("Map not available");
}UX-MAUI-Services
To provide implementation MEs on a MAUI device, create a new service in the UX-MAUI-Services project. Ensure the following standards are met when building your service.
IMPORTANT NOTE: All services must implement a MEs interface.
Provide implementation for the IsAvailable Boolean that returns true.
Why? – Components will check this property on the service to determine if they can use MEs functionality. This allows access.
public bool IsAvailable
{
get { return true; }
}Add a constructor that accepts an HttpClient and UserState s?o that error messages can be logged.
Why? – If an error occurs, then we want to log the error and the constructor arguments, and have it populated through dependency injection.
private HttpClient Http;
private UserState User;
public ServiceName(HttpClient httpService, UserState userData)
{
Http = httpService;
User = userData;
}Provide implementation for interface methods that return a correct string and log if an error occurs (methods must be declared as async to correctly return strings and log errors).
Why? – Returning a correct string will allow the component to know if the action was successful or failed. And if the action failed correctly, then log the issue so it can be resolved.
public async Task<string> OpenMap()
{
try
{
// Open map code...
return "";
}
catch (Exception ex)
{
await User.Log(1, "ServiceName.OpenMap - Unknown", ex.ToString());
return "Failed to open map!";
}
}