Comment simplifier la sauvegarde de fichiers dans vos applications MAUI avec l'outil FileSaver du MAUI Community Toolkit ?
Introduction
Le MAUI Community Toolkit offre une multitude d'outils pour enrichir vos applications. Parmi eux, le FileSaver se distingue par sa capacité à simplifier considérablement la gestion des fichiers. En temps normal, écrire du code pour sauvegarder un fichier implique de gérer manuellement les flux de données, les permissions sur différentes plateformes, et les erreurs potentielles liées au stockage. Le FileSaver automatise ces tâches complexes, permettant ainsi aux développeurs de se concentrer sur d'autres aspects de leur application. Grâce à son interface unifiée, il assure une expérience cohérente sur toutes les plateformes supportées par MAUI, tout en réduisant le risque d'erreurs.
Installer et Activer le MAUI Community Toolkit
Pour utiliser le MAUI Community Toolkit, il est nécessaire de l'ajouter comme dépendance dans votre projet. Vous pouvez l'installer via NuGet en exécutant la commande suivante dans la console du gestionnaire de paquets :
dotnet add package CommunityToolkit.Maui
Ensuite, dans votre fichier MauiProgram.cs, activez le toolkit en ajoutant UseMauiCommunityToolkit() à votre MauiApp builder :
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder.UseMauiApp<App>().UseMauiCommunityToolkit();
return builder.Build();
}
}
Utilisation du FileSaver
Le FileSaver permet d'enregistrer des fichiers en toute simplicité. Voici comment l'utiliser dans une application MAUI :
Sauvegarde d'un petit fichier
async Task SaveSmallFile(CancellationToken cancellationToken)
{
using var stream = new MemoryStream(Encoding.Default.GetBytes("Bonjour depuis le Community Toolkit !"));
var fileSaverResult = await FileSaver.Default.SaveAsync("exemple.txt", stream, cancellationToken);
if (fileSaverResult.IsSuccessful)
{
await Toast.Make($"Le fichier a été sauvegardé avec succès à l'emplacement : {fileSaverResult.FilePath}").Show(cancellationToken);
}
else
{
await Toast.Make($"La sauvegarde du fichier a échoué avec l'erreur : {fileSaverResult.Exception.Message}").Show(cancellationToken);
}
}
Sauvegarde d'un fichier volumineux
async Task SaveLargeFile(CancellationToken cancellationToken)
{
var buffer = new byte[8192]; // Buffer de 8KB
using var stream = await GetLargeFileStreamAsync(); // Méthode pour obtenir un Stream de fichier volumineux
var fileSaverResult = await FileSaver.Default.SaveAsync("fichier_volumineux.bin", stream, cancellationToken, buffer);
if (fileSaverResult.IsSuccessful)
{
await Toast.Make($"Fichier volumineux sauvegardé avec succès à : {fileSaverResult.FilePath}").Show(cancellationToken);
}
else
{
await Toast.Make($"Échec de la sauvegarde du fichier volumineux : {fileSaverResult.Exception.Message}").Show(cancellationtoken);
}
}
Méthodes du FileSaver
Le FileSaver propose plusieurs méthodes clés pour sauvegarder des fichiers, qui sont toutes basées sur l'interface IFileSaver :
- SaveAsync(string fileName, Stream fileStream, CancellationToken cancellationToken = default) : Enregistre un fichier avec le nom et le flux de données spécifiés.
- SaveAsync(string fileName, Stream fileStream, CancellationToken cancellationToken, byte[] buffer) : Enregistre un fichier volumineux en utilisant un buffer personnalisé pour lire les données par morceaux.
- EnsureSuccess() : Méthode de l'objet FileSaverResult qui lève une exception si l'opération de sauvegarde a échoué. Cela permet de gérer les erreurs de manière plus centralisée et de garantir que l'opération est correctement prise en charge.
Propriétés du FileSaverResult
Le résultat de la méthode SaveAsync est encapsulé dans un objet FileSaverResult, qui possède plusieurs propriétés utiles pour gérer la sauvegarde des fichiers :
- IsSuccessful : Un booléen qui indique si la sauvegarde du fichier a réussi.
- FilePath : Le chemin complet du fichier sauvegardé. Cette propriété est remplie uniquement si l'opération a été un succès.
- Exception : Une exception qui contient des détails sur l'erreur survenue lors de la tentative de sauvegarde du fichier. Cette propriété est remplie uniquement si l'opération a échoué.
Gestion des Permissions
Sur certaines plateformes, des permissions spécifiques sont nécessaires pour accéder au système de fichiers. Par exemple :
- Android : Vous devez configurer le fichier AndroidManifest.xml pour déclarer les permissions nécessaires, notamment READ_EXTERNAL_STORAGE et WRITE_EXTERNAL_STORAGE, selon le niveau de l'API cible.
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
- iOS : Aucun paramétrage spécifique n'est nécessaire pour accéder au système de fichiers local.
- Windows : Vous devez vérifier que votre application dispose des autorisations nécessaires pour accéder aux dossiers de l'utilisateur, comme PicturesLibrary ou DocumentsLibrary.
Injection de Dépendance
Le FileSaver peut également être utilisé dans le cadre de l'injection de dépendances pour être accessible en tant que service dans toute votre application. Pour cela, configurez-le dans le fichier MauiProgram.cs :
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder.UseMauiApp<App>().UseMauiCommunityToolkit();
builder.Services.AddSingleton<IFileSaver>(FileSaver.Default);
return builder.Build();
}
}
Une fois cela fait, vous pouvez injecter IFileSaver dans vos vues ou services et l'utiliser comme suit :
public class MyFileService
{
private readonly IFileSaver _fileSaver;
public MyFileService(IFileSaver fileSaver)
{
_fileSaver = fileSaver;
}
public async Task SaveDataAsync(string fileName, Stream data, CancellationToken cancellationToken)
{
var result = await _fileSaver.SaveAsync(fileName, data, cancellationToken);
if (!result.IsSuccessful)
{
// Gérer l'erreur
throw result.Exception;
}
}
}
Conclusion
Le FileSaver du MAUI Community Toolkit est un outil précieux pour toute application nécessitant la sauvegarde de fichiers, en simplifiant non seulement le processus de sauvegarde mais aussi la gestion des permissions à travers les différentes plateformes supportées. Grâce à ses méthodes robustes et à la gestion des dépendances, il s'intègre facilement dans tout projet MAUI. La méthode EnsureSuccess ajoute une couche supplémentaire de sécurité en garantissant que toute opération échouée est gérée de manière explicite. Pour plus de détails et d'exemples, consultez la documentation officielle.
Stay Tuned !