Dans cette page, vous trouverez la documentation sur la librairie CopyFileExtensions ainsi que sur la manière de l'utiliser.

Sommaire


 

Présentation générale

Le Framework .NET ne permet pas (encore) de copier des fichiers avec une information sur l'avancement. Il faut passer par l'API windows CopyFileEx pour réaliser cela.

Ce projet fournit au développeur un wrapper permettant d'utiliser cette API facilement. Ce travail repose sur une implémentation du wrapper fournie

 

Fonctionnalités disponibles

Copie des Fichiers

La librairie permet en premier lieu de faire la copie des fichiers en faisant un wrapper de l'API CopyFileEX.
La copie est effectuée dans un BackgroundWorker. Le developpeur n'a donc plus à gérer le thread de la copie.

Options de copies

La librairie permet différentes options de copies :
  • None : Pas d'options particulières définies. Il est impossible de reprendre une copie arrêtée avec cette option.
  • FailIfDestinationExists : Si le fichier de destination existe déjà, la copie ne s'effectuera pas et renverra une erreur.
  • Restartable : Option pour permettre de stopper une copie en cours dans le but de la reprendre plus tard.
  • AllowDecryptedDestination
  • All : Option par défaut. C'est les trois cas précédents.

Évènements renvoyés

Dans le cas où l'on n'utilise pas les contrôles utilisateurs, deux évènements sont renvoyés lors de la copie :
  • CopyFileCallback : évènement soulevé à chaque pas de progression de la copie. Cet évènement permet donc de connaitre le pourcentage d'avancement.
  • CopyFileTerminate : évènement soulevé à la fin, l'annulation ou l'arrêt de la copie. Cet évènement permet entre autres de connaître l'état de la copie lorsqu'il survient : copie réussie ou avec erreur.

Dans le cas où on utilise les controles utilisateurs, aucun évènement n'est disponible. Par contre, on peut connaitre l'état de la copie en fonction de la couleur du contrôle ou en interrogeant la variable CopyState (cf. usageUserControl)

 

Utilisation

Avant toute chose, vous devez inclure la dll FileCopyExtensions comme référence à votre projet. Pour cela :
  • faire un clic droit sur le projet, puis choisissez Ajouter une référence (ou Add a reference) : AddReference.png
  • Allez dans l'onglet Parcourir et allez chercher la dll que vous avez téléchargée (par défaut, elle s'appelle FileCopyExtension.dll)

Utilisation de la classe FileCopyExtension

Commencez par inclure le namespace FileCopyExtension dans votre code.
Définissez ensuite les évènements auxquels vous voulez vous abonner.
Instanciez-les avant d'appeler la fonction de copie (CopyFile)
Exemples:
C#
using FileCopyExtensions;
using System.IO;

namespace WinFormCS
{
    /// <summary>
    /// Classe montrant un exemple d'utilisation de la librairie
    /// </summary>
    class Exemple
    {
        // DEFINITION DES VARIABLES
        private event CopyFileCallback CopyProgress;    // Evenement pour la progression
        private event CopyFileTerminate CopyEnd;        // Evenement pour la fin de la copie


        /// <summary>
        /// Constructeur par défautt
        /// </summary>
        public Exemple()
        {
            FileInfo fichierSource = new FileInfo(@"Le\Chemin\vers\mon\fichier\MonFichier.irc");    // Définition du fichier source
            FileInfo DossierDest = new FileInfo(@"Le\Dossier\De\Destination\NouveauNom.cri");                      // Définition du repertoire de destination avec le nouveau nom du fichier

            CopyProgress += new CopyFileCallback(Exemple_CopyProgress);
            CopyEnd += new CopyFileTerminate(Exemple_CopyEnd);

            // Lancement de la fonction de copie dans un BackgroundWorker
            FileCopyExtensions.FileCopyExtensions.CopyFile(fichierSource, DossierDest, CopyFileOptions.All, CopyProgress, CopyEnd);
        }

        /// <summary>
        /// Fonction qui sera executée lorsque la copie sera terminée
        /// </summary>
        /// <param name="success">Booléen qui vaut vrai si la copie s'est terminé avec succès, faux sinon</param>
        void Exemple_CopyEnd(bool success)
        {
            // Code que j'effectue à la fin de la copie (message, etc.)
            // ...
        }

        /// <summary>
        /// Fonction qui sera appelée à chaque evenements de la progression
        /// </summary>
        /// <param name="source">Fichier source</param>
        /// <param name="destination">Dossier de destination</param>
        /// <param name="state"></param>
        /// <param name="totalFileSize">Nombre de bytes total du fichier</param>
        /// <param name="totalBytesTransferred">Nombre de bytes transféré</param>
        /// <returns>Action a faire pendant la copie (on continue, on s'arrete, etc.)</returns>
        CopyFileCallbackAction Exemple_CopyProgress(FileInfo source, FileInfo destination, object state, long totalFileSize, long totalBytesTransferred)
        {
            // Code que je veux effectuer (mise à jour d'une barre de progression, etc.)
            // ...

            // Suivant la valeur de retour, on continue ou pas la copie
            return CopyFileCallbackAction.Continue;
        }
    }
}

VB
Imports FileCopyExtensions
Imports System.IO

''' <summary>
''' Classe montrant un exemple d'utilisation de la librairie
''' </summary>
''' <remarks></remarks>
Public Class Exemple
    ' DEFINITION DES VARIABLES
    Dim CopyProgress As CopyFileCallback    ' Evenement pour la progression
    Dim CopyEnd As CopyFileTerminate        ' Evenement pour la fin de la copie

    ''' <summary>
    ''' Constructeur par défaut
    ''' </summary>
    ''' <remarks></remarks>
    Sub Exemple()
        Dim fichierSource As FileInfo = New FileInfo("Le\Chemin\vers\mon\fichier\MonFichier.irc")
        Dim DossierDest As FileInfo = New FileInfo("Le\Dossier\De\Destination\NouveauNom.cri")

        CopyProgress = New CopyFileCallback(AddressOf Exemple_CopyProgress)
        CopyEnd = New CopyFileTerminate(AddressOf Exemple_CopyEnd)

        ' Lancement de la fonction de copie dans un BackgroundWorker
        FileCopyExtensions.FileCopyExtensions.CopyFile(fichierSource, DossierDest, CopyFileOptions.All, CopyProgress, CopyEnd)
    End Sub

    ''' <summary>
    ''' Fonction qui sera executée lorsque la copie sera terminée
    ''' </summary>
    ''' <param name="succes">Booléen qui vaut vrai si la copie s'est terminé avec succès, faux sinon</param>
    ''' <remarks></remarks>
    Private Sub Exemple_CopyEnd(succes As Boolean)
        'Code que j'effectue à la fin de la copie (message, etc.)
        '...

    End Sub

    ''' <summary>
    ''' Fonction qui sera appelée à chaque evenements de la progression
    ''' </summary>
    ''' <param name="source">Fichier source</param>
    ''' <param name="destination">Dossier de destination</param>
    ''' <param name="state"></param>
    ''' <param name="totalFileSize">Nombre de bytes total du fichier</param>
    ''' <param name="totalBytesTransferred">Nombre de bytes transféré</param>
    '''<returns>Action a faire pendant la copie (on continue, on s'arrete, etc.)</returns>
    ''' <remarks></remarks>
    Private Function Exemple_CopyProgress(source As FileInfo, destination As FileInfo, state As Object, totalFileSize As Long, totalBytesTransferred As Long) As CopyFileCallbackAction
        ' Code que je veux effectuer (mise à jour d'une barre de progression, etc.)
        ' ...

        ' Suivant la valeur de retour, on continue ou pas la copie
        Return CopyFileCallbackAction.Continue
    End Function

End Class


 

Utilisation du contrôle utilisateur

Utiliser le controle utilisateur permet de gagner du temps, car toutes les opérations décrites ci-dessus sont déjà effectuées. De plus, la présentation d'une progressBar pendant la copie est très naturelle.

Note : Pour que le contrôle utilisateur apparaisse dans la fenêtre Boite à outils, faite un clic droit dans cette fenêtre et sélectionnez Choisir les éléments. AddTool.png
Si vous faite du .NET (C# ou VB) sélectionnez l'onglet Composants .NET framework puis cliquez sur Parcourir et allez sélectionner la dll CopyFileExtension.dll. Si vous êtes en Wpf, effectuez la même manipulation, mais sélectionner l'onglet Composants Wpf au lieu de Composants .NET framework. Le contrôle apparaît alors dans la Boite à outils.
Une fois que vous avez placé le controle sur votre fenêtre, il faut lui donner deux informations : le fichier source et le dossier/fichier de destination. Pour cela, utilisez les propriétés FileSource et FolderDestination du controle.
Note : Pour la destination, plusieurs options s'offre à vous
* FolderDestination contient le chemin vers un repertoire : dans ce cas, le fichier de destination portera le même nom et extension que le fichier source.
* FolderDestination contient le chemin et un nom de fichier : le fichier source sera copié en utilisant ce nouveau nom et/ou extension dans le repertoire FolderDestination.
* FolderDestination contient le chemin vers un repertoire et la variable FileDestName contient le nom du fichier dans le repertoire de destination : le fichier source sera copié dans le dossier FolderDestination avec le nom et l'extension précisé dans FileDestName.
La copie se lance en appelant la fonction runCopy du controle. Cette fonction prend un paramètre optionnel en entrée : les options de copie (cf Options de copies)

Fonctions disponibles
Le controle utilisateur expose les fonctions suivantes :
  • stopCopy : Permet d'arrêter la copie. Si l'option Restartable est activée, une reprise est possible.
  • cancelCopy : Annule la copie, i.e. le fichier de destination est supprimé.

Comportement de la progressBar (uniquement disponible en WPF)
La couleur de la progressBar change en fonction de l'état de la copie.
Couleur Signification
vert UserControl_Progress.png La copie est en cours
gris UserControl_Progress_CopyStop.png la copie est arrêtée mais pourra être reprise (un appel de la fonction stopCopy a été effectué)
bleu UserControl_Progress_CopyCorrect.png La copie est terminée avec succès
jaune UserControl_Progress_CopyCancel.png La copie est arrêtée mais ne pourra pas être reprise (un appel de la fonction canceCopy a été effectué)
rouge UserControl_Progress_CopyError.png La copie s'est terminé avec une erreur (ATTENTION : ce cas peut survenir si vous voulez copier un fichier qui existe déjà dans le repertoire de destination).


Propriété du Controle
Deux propriétés sont disponibles pour le controle. Elles sont accessibles dans le groupe de propriété Configuration :
  • Vertical : Spécifie si le label se trouve sous la progressBar ou à droite.
Vertical = true Vertical = false
UserControl_ProgressVertical.png UserControl_ProgressHorizontal.png
  • ShowProgress : Spécifie si le label est visible ou pas.

Last edited Jul 29, 2012 at 6:55 PM by iivxsiuol, version 21

Comments

No comments yet.