In dem Beitrag C#: FTP-Übertragung (Up- und Download) mit Standard .NET-Funktionalität (FtpWebRequest / FtpWebResponse) wurde beschrieben wie man mit async/await eine Datei via FTP Up- bzw. Downloaden kann. Gerade bei solchen Operationen (die potentiell länger dauern können) ist es sehr hilfreich etwas über den aktuellen Status zu erfahren. Besonders aus Usability-Sicht ist dies bei modernen Anwendungen unerlässlich (sei es bei Desktop-Anwendungen oder Smartphone Apps). Bei längeren andauernden Funktionen/Methoden soll die Anwendung ständig bedienbar bleiben und den Benutzer über die wichtigsten Parameter der aktuellen Operation informieren (z.B. Übertragene Dateigröße, Restdauer, …). In vielen Fällen soll der Anwender auch die Möglichkeit haben den Vorgang abzubrechen. In diesem Artikel werden nun einige Möglichkeiten aufgezeigt wie man solche Szenarien realisieren kann.
Benachrichtigung über den Fortschritt
Werden innerhalb einer Anwendung länger dauernde Funktionen/Methoden ausgeführt möchte man den Anwender oftmals über den aktuellen Fortschritt informieren. Solchen Operationen sind häufig
- Netzwerkzugriffe (Upload/Download)
- Zugriffe auf die Festplatte
- Datenbankzugriffe
- …
Im einfachsten Fall übergibt man der asynchronen Methode dafür einen Action-Delegaten, der immer dann aufgerufen wird wenn sich der Status ändert. Das könnte in etwa so aussehen:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
async Task DoSomething(Action<int> onProgressPercentChanged) { return Task.Run (() => { for (int i = 0; i < 1000; i++) { if (i % 10 == 0 && onProgressPercentChanged != null) onProgressPercentChanged.Report(i / 10); // Do something ... } }); } |
Wie im Beispiel zu sehen wird der asynchronen Methode ein Action<int>-Delegate namens „onProgressChanged“ übergeben. Dieser Delegate wird dann bei Statusänderungen aufgerufen (Zeile 11). Um den Status jetzt über einen Progressbar zu visualisieren:
|
1 2 3 4 5 6 |
... Action<int> progress = i => Console.WriteLine (i + " %"); await DoSomething(progress); ... |
Hier wird ein einfacher Action<T>-Delegate mittels Lambda-Ausdruck initialisiert und an die asynchrone Methode übergeben. Diese Vorgehensweise eignet sich sehr gut für Konsoleanwendungen. Für WPF- oder WinForrms-Anwendungen ist dieses Konstrukt aber nur bedingt geeignet. Grund: Der Fortschritt wird im Workerthread ausgewertet und zurückgeliefert. In WPF- bzw. WinForms-Anwendungen muss das UI aber zwingend im UI-Thread aktualisiert werden (versucht man ein Control aus einem Workerthread heraus zu aktualisieren kommt es zu einer Exception). Innerhalb des .NET-Frameworks gibt es dafür aber eine Lösung: Das Interface IProgress<T> und die Klasse Progress<T>, welche dieses Interface implementiert.
IProgress<T> und Progress<T>
Alle asynchronen Methoden, die über den Fortschritt informieren sollen, erhalten einen Parameter vom Typ IProgress<T> (T kann hier ein beliebiger Typ sein). Dabei sollte dieser Parameter nach den „normalen“ Parametern stehen. Das IProgress<T>-Interface ist wie folgt definiert:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
// Summary: // Represents progress of an asynchronous operation. // // Type parameters: // T: // Specifies the type of the progress data. public interface IProgress<T> { // Summary: // Reports that progress has changed and provides the new progress value. // // Parameters: // value: // The new progress value. void Report(T value); } |
Wie zu erkennen enthält die Schnittstelle lediglich eine Report-Methode und glücklicherweise stellt uns das .NET-Framework auch gleich schon eine Implementierung dieser Schnittstelle bereit (in Form der Klasse Progress<T>):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
// Summary: // Provides an System.IProgress<T> that invokes callbacks for each reported // progress value. // // Type parameters: // T: // Specifies the type of the progress report value. public class Progress<T> : IProgress<T> { // Summary: // Initializes the System.Progress<T> object. public Progress(); // // Summary: // Initializes the System.Progress<T> object with the specified callback. // // Parameters: // handler: // A handler to invoke for each reported progress value. This handler will be // invoked in addition to any delegates registered with the System.Progress<T>.ProgressChanged // event. Depending on the System.Threading.SynchronizationContext instance // captured by the System.Progress<T> at construction, it is possible that this // handler instance could be invoked concurrently with itself. public Progress(Action<T> handler); // Summary: // Raised for each reported progress value. public event EventHandler<T> ProgressChanged; // Summary: // Reports a progress change. // // Parameters: // value: // The value of the updated progress. protected virtual void OnReport(T value); } |
Die Verwendung ist dann ganz einfach. In folgendem Beispiel handelt es sich um eine einfache WPF-Anwendung, die lediglich zwei Controls enthält: Einen Button, um eine Aktion zu starten und eine ProgressBar, um den Fortschritt zu visualisieren:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
private async void DoSomething(IProgress<int> onProgressChanged) { try { btnStart.IsEnabled = false; for (int i = 0; i <= 5; i++) { if (onProgressChanged != null) onProgressChanged.Report(i * 20); // C# 6.0: onProgressChanged?.Report(i * 20); await Task.Delay(TimeSpan.FromSeconds(1)); } MessageBox.Show("Operation completed!"); } catch (OperationCanceledException) { MessageBox.Show("Operation cancelled!"); } catch (Exception) { MessageBox.Show("Operation completed with error."); throw; } finally { btnStart.IsEnabled = true; progressBar.Value = 0; } } |
Diese Methode hat nur einen Parameter vom Typ IProgress<T>. In Zeile 10 wird die Report-Methode aufgerufen, um über den Fortschritt zu informieren. Damit auf die Fortschrittsmeldung reagiert werden kann benötigt man noch eine Instanz der Klasse Progress<T>. Um die ProgressBar zu aktualisieren könnte dies in etwa wie folgt aussehen:
|
1 2 3 4 5 6 7 |
... var progress = new Progress<int>(percentage => progressBar.Value = percentage); await DoSomething(progress); ... |
Hier wird mit einem Lambda-Ausdruck ein Action<T>-Delegate erzeugt und dem Konstruktor der Klasse Progress<T> mitgegeben. Der Delgate übernimmt dabei die Aktualisierung der ProgressBar. Das schöne an der Klasse Progress<T> ist, dass direkt bei der Erzeugung ein Mapping auf den SynchronziationContext erfolgt. Ab diesem Zeitpunkt wird dann auch dieser SynchronziationContext verwendet und das Statusupdate erfolgt somit im richtigen Thread (UI-Thread um das UI zu aktualisieren). Aus diesem Grund kann das IProgress<T>-Interface aus jedem beliebigen Thread heraus aufgerufen werden und man braucht sich keine weiteren Gedanken darüber zu machen, ob man sich im richtigen Thread befindet. Das hier gezeigt Beispielprogramm steht am Ende Artikels als Download bereit.
Hinweis:
Der generische Parameter T kann ja ein beliebiger Typ sein. Der Typ int bietet sich z.B. für einfache Prozentangaben an. In anderen Szenarien werden eventuell mehr Informationen benötigt und man erstellt sich eine eigene Klasse für diese Informationen. Hier gilt es zu beachten, dass das Objekt potentiell in einem anderen Thread verwendet werden kann, als der Thread, in dem es erzeugt wurde. Für solche Szenarien bieten sich immutable-Typen an. immutable-Typen sind, wie der Name vermuten lässt, nach ihrer Erzeugung nicht mehr veränderbar (bei Gelegenheit werde ich mal einen separaten Artikel zu diesen Typen schreiben).
Möglichkeit die Operation abzubrechen
In manchen Situationen möchte man dem Anwender die Möglichkeit bieten eine laufende Operation abzubrechen. Auch dafür stellt das .NET-Framework entsprechende Klassen bereit. Der Abbruch einer asynchronen Methode kann mit einem sogenannten CancellationToken realisiert werden. Damit eine asynchrone Methode abgebrochen werden kann, wird diese um einen Parameter vom Typ CancellationToken erweitert. Dieser Parameter sollte nach den „normalen“ Parametern der Methode stehen. Um ein solches CancellationToken zu erzeugen kann die Klasse CancellationTokenSource genutzt werden (diese Klasse ist eine Art Hilfsklasse, um ein CancellationToken zu erzeugen). Wir erweitern einfach das obige Beispiel zum Starten einer Aktion um einen Cancel-Button und geben der asynchronen Methode einen zusätzlichen Parameter vom Typ CancellationToken:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
private async void DoSomething(IProgress<int> onProgressChanged, CancellationToken token) { try { btnStart.IsEnabled = false; btnCancel.IsEnabled = true; for (int i = 0; i <= 5; i++) { if (onProgressChanged != null) onProgressChanged.Report(i * 20); await Task.Delay(TimeSpan.FromSeconds(1), token); } MessageBox.Show("Operation completed!"); } catch (OperationCanceledException) { MessageBox.Show("Operation cancelled!"); } catch (Exception) { MessageBox.Show("Operation completed with error."); throw; } finally { btnStart.IsEnabled = true; btnCancel.IsEnabled = false; progressBar.Value = 0; } } private void btnCancel_Click(object sender, RoutedEventArgs e) { cts.Cancel(); } |
In Zeile 1 wurde ein neuer Parameter vom CancellationToken eingefügt. In Zeile 13 wird die eigentliche asynchrone Operation gestartet, welcher das CancellationToken mitgegeben wird. Im EventHandler für den Cancel-Button (Zeile 37) wird die Cancel-Methode der CancellationTokenSource-Klasse aufgerufen. Durch den Aufruf der Cancel-Methode wird das erzeugte Token in den Canceled-Status versetzt und eine Exception vom Typ OperationCanceledException ausgelöst (mehr Informationen dazu unter [5] – MSDN – How to: Cancel a Task and Its Children). Die oben gezeigte Methode kann dann wie folgt aufgerufen werden:
|
1 2 3 4 5 6 7 8 9 10 |
private void btnStart_Click(object sender, RoutedEventArgs e) { // Cancellation token cts = new CancellationTokenSource(); // Progress var progress = new Progress<int>(p => progressBar.Value = p); // Start asyn operation this.DoSomething(progress, cts.Token); } |
Hier sieht man nun den EventHandler für den Start-Button. Hier wird einfach nur eine Instanz der Klasse CancellationTokenSource erzeugt, um ein entsprechendes CancellationToken zu generieren. Für die Statusrückmeldung wird in Zeile 6, via Lambda-Ausdruck, ein Action<T>-Delegate erzeugt. Diese Objekte werden dann der eigentlichen asynchronen Operation in Zeile 9 übergeben.
Beispiel FTP-Übertragung
Im Beitrag C#: FTP-Übertragung (Up- und Download) mit Standard .NET-Funktionalität (FtpWebRequest / FtpWebResponse) wurde eine Möglichkeit zum Up- bzw. Download von Dateien via FTP beschrieben. Dieses Beispiel soll nun um die folgenden Features erweitert werden:
- Fortschrittsrückmeldung über die aktuell übertragenen Bytes
- Möglichkeit die Übertragung abzubrechen
Hier mal die angepassten Methoden für den Up- bzw. Download. Ich spare mir an dieser Stelle einfach mal die Kommentare (mit den obigen Informationen sollten die gemachten Änderungen einfach nachvollziehbar sein). Bei weitere Fragen, Anregungen oder Kommentare stehe ich natürlich gerne zur Verfügung.
Upload
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
public static async Task FtpUploadAsync(Uri ftpSite, string uploadFile, IProgress<int> onProgressChanged, CancellationToken token) { int totalBytes = 0; Console.WriteLine($"Uploading {uploadFile} to {ftpSite.AbsoluteUri}..."); try { FileInfo fileInfo = new FileInfo(uploadFile); FtpWebRequest request = (FtpWebRequest)WebRequest.Create(ftpSite); request.Method = WebRequestMethods.Ftp.UploadFile; request.UseBinary = true; request.ContentLength = fileInfo.Length; request.Credentials = new NetworkCredential("anonymous", "anonymous"); byte[] byteBuffer = new byte[4096]; using (Stream requestStream = await request.GetRequestStreamAsync()) { using (FileStream fileStream = new FileStream(uploadFile, FileMode.Open, FileAccess.Read, FileShare.Read, 4096, useAsync: true)) { int bytesRead = 0; do { bytesRead = await fileStream.ReadAsync(byteBuffer, 0, byteBuffer.Length); if (bytesRead > 0) { // Report progress onProgressChanged?.Report(totalBytes += bytesRead); // Write file to local hdd await requestStream.WriteAsync(byteBuffer, 0, bytesRead, token); } } while (bytesRead > 0); } } using (FtpWebResponse response = (FtpWebResponse)await request.GetResponseAsync()) { Console.WriteLine(response.StatusDescription); } Console.WriteLine($"Uploaded {uploadFile} to {ftpSite.AbsoluteUri}..."); } catch (OperationCanceledException) { Console.Write("Upload cancelled!"); } catch (WebException e) { Console.WriteLine($"Failed to upload {uploadFile} to {ftpSite.AbsoluteUri}."); Console.WriteLine(((FtpWebResponse)e.Response).StatusDescription); Console.WriteLine(e); throw; } } |
Download
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
public async Task DownloadFileAsync(Uri ftpSite, string targetPath, IProgress<int> onProgressChanged, CancellationToken token) { try { int totalBytes = 0; FtpWebRequest request = (FtpWebRequest)WebRequest.Create(ftpSite); request.Credentials = new NetworkCredential("anonymous", "anonymous"); request.Method = WebRequestMethods.Ftp.DownloadFile; using (FtpWebResponse response = (FtpWebResponse)await request.GetResponseAsync()) { Stream data = response.GetResponseStream(); Console.WriteLine($"Downloading {ftpSite.AbsoluteUri} to {targetPath}..."); byte[] byteBuffer = new byte[4096]; using (FileStream output = new FileStream(targetPath, FileMode.OpenOrCreate, FileAccess.ReadWrite, FileShare.ReadWrite, 4096, useAsync: true)) { int bytesRead = 0; do { bytesRead = await data.ReadAsync(byteBuffer, 0, byteBuffer.Length); if (bytesRead > 0) { // Report progress onProgressChanged?.Report(totalBytes += bytesRead); // Upload await output.WriteAsync(byteBuffer, 0, bytesRead, token); } } while (bytesRead > 0); } Console.WriteLine($"Downloaded {ftpSite.AbsoluteUri} to {targetPath}"); } } catch(OperationCanceledException) { Console.Write("Download cancelled!"); } catch (WebException e) { Console.WriteLine($"Failed to download {ftpSite.AbsoluteUri} to {targetPath}"); Console.WriteLine(e); throw; } } |
Damit wären wir auch schon am Ende des Artikels. Gerade durch die im .NET-Framework bereitgestellten Klassen werden die asynchrone Programmierung und die damit verbundenen Tätigkeiten, wie z.B. Fortschrittsbenachrichtigungen und Abbruch-Möglichkeit, deutlich vereinfacht. Weitere Informationen können den unten stehenden Weblinks entnommen werden.
Literaturverzeichnis und Weblinks
| Abk. | Quelle |
|---|---|
| [1] | MSDN - IProgress<T> IProgress<T>-Schnittstelle |
| [2] | MSDN - Progress<T> Progress<T>-Klasse |
| [3] | MSDN - CancellationTokenSource CancellationTokenSource-Klasse |
| [4] | MSDN - CancellationToken CancellationToken-Struktur |
| [5] | MSDN - How to: Cancel a Task and Its Children How to: Cancel a Task and Its Children |
Beispiel-Code
[wpdm_package id=’1444′]
Login