C# Cancellationtoken (Jak to działa dla deweloperów)

Jak to działa?

Zasadniczo token CancellationToken jest przekazywany do zadania lub metody, która okresowo sprawdza, czy zgłoszono żądanie anulowania. W takim przypadku zadanie może zostać płynnie zakończone, co zwolni zasoby i poprawi responsywność aplikacji. Jest to szczególnie przydatne w przypadkach takich jak generowanie plików PDF, gdzie tworzenie złożonych dokumentów może zająć dużo czasu.

Korzystając z CancellationTokens, unikasz potencjalnych wad zadań, które działają niepotrzebnie długo, takich jak marnowanie zasobów systemowych i słabe wrażenia użytkownika.

Wewnętrzne tokeny anulowania

W języku C# wewnętrzny token anulowania odnosi się do tokenu anulowania, który jest tworzony i zarządzany w ramach konkretnej klasy lub metody, a nie przekazywany z zewnętrznego źródła. Pozwala to na dokładniejszą kontrolę nad anulowaniem zadań w ramach pojedynczego komponentu, umożliwiając mu monitorowanie i reagowanie na żądania anulowania pochodzące z wewnątrz.

Użycie wewnętrznego tokenu anulowania jest szczególnie przydatne w sytuacjach, gdy chcesz zamknąć logikę anulowania bez ujawniania jej użytkownikom klasy, zachowując w ten sposób przejrzysty interfejs. Takie podejście może zwiększyć modułowość kodu i ułatwić zarządzanie złożonymi, asynchronicznymi przepływami pracy, jednocześnie wykorzystując elastyczność zapewnianą przez szerszą strukturę CancellationToken.

1. Unikaj niepotrzebnego obciążenia

Jeśli użytkownik nie potrzebuje już zamówionego pliku PDF, nie ma powodu, aby proces był kontynuowany. Korzystając z CancellationToken, można zatrzymać zadanie generowania pliku PDF, zapobiegając nadmiernemu obciążeniu serwerów i poprawiając ogólną wydajność aplikacji.

2. Poprawa komfortu użytkowania

W aplikacjach desktopowych generowanie plików PDF może odbywać się w wątku interfejsu użytkownika, co może spowodować zawieszenie interfejsu, jeśli zadanie trwa długo. Dzięki zastosowaniu CancellationToken użytkownicy mogą anulować zadanie i zachować responsywność aplikacji.

3. Poprawa skalowalności

W aplikacjach internetowych, w których wielu użytkowników generuje pliki PDF jednocześnie, kluczowa jest skalowalność. CancellationToken pozwala bezpiecznie anulować niepotrzebne zadania, zwalniając zasoby w celu wydajnej obsługi innych żądań.

Krok 1: Konfiguracja IronPDF w projekcie

Aby rozpocząć korzystanie z IronPDF, należy najpierw zainstalować program. Jeśli jest już zainstalowany, możesz przejść do następnej sekcji; W przeciwnym razie poniższe kroki opisują sposób instalacji biblioteki IronPDF.

Za pośrednictwem konsoli menedżera pakietów NuGet

Aby zainstalować IronPDF za pomocą konsoli menedżera pakietów NuGet, otwórz program Visual Studio i przejdź do konsoli menedżera pakietów. Następnie uruchom następujące polecenie:

Install-Package IronPdf

Za pośrednictwem menedżera pakietów NuGet dla Solution

Po uruchomieniu programu Visual Studio przejdź do "Narzędzia -> Menedżer pakietów NuGet -> Zarządzaj pakietami NuGet dla rozwiązania" i wyszukaj IronPDF. Teraz wystarczy wybrać projekt i kliknąć "Zainstaluj", a IronPDF zostanie dodany do projektu.

Po zainstalowaniu IronPDF wystarczy dodać odpowiednią instrukcję using na początku kodu, aby rozpocząć korzystanie z IronPDF:

using IronPdf;

using IronPdf;

Imports IronPdf

Krok 2: Wykorzystanie tokenów anulowania w metodzie asynchronicznego generowania plików PDF

Przejdźmy do konkretnej realizacji. W tym przykładzie wygenerujemy prosty plik PDF z HTML przy użyciu IronPDF, ale z tokenem CancellationToken, który pozwala na anulowanie zadania w razie potrzeby.

using IronPdf;
using System;
using System.Threading;
using System.Threading.Tasks;

public class PdfGenerator
{
    public async Task GeneratePdfWithCancellation(CancellationToken token)
    {
        var Renderer = new ChromePdfRenderer();
        try
        {
            // Check for cancellation before starting
            token.ThrowIfCancellationRequested();

            // Simulating a long task that can be checked for cancellation periodically
            for (int i = 0; i < 10; i++)
            {
                // Simulating a piece of work (this could be part of a larger HTML rendering)
                await Task.Delay(500); // Simulate chunk processing

                // Periodically check for cancellation in long-running operations
                if (token.IsCancellationRequested)
                {
                    Console.WriteLine("Cancellation requested. Throwing exception.");
                    token.ThrowIfCancellationRequested();  // This will trigger an OperationCanceledException
                }
            }

            // Simulate PDF creation after the long process
            var pdf = await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>");

            // Save the PDF after ensuring no cancellation occurred
            pdf.SaveAs("output.pdf");
            Console.WriteLine("PDF generated successfully.");
        }
        catch (OperationCanceledException)
        {
            // Handle task cancellation
            Console.WriteLine("PDF generation was canceled.");
        }
        catch (Exception ex)
        {
            // Handle other exceptions
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }
}

public class Program
{
    public static async Task Main(string[] args)
    {
        // Create a CancellationTokenSource
        var cancellationTokenSource = new CancellationTokenSource();

        // Create our cancellation token
        var token = cancellationTokenSource.Token;

        // Start the PDF generation task
        var pdfGenerator = new PdfGenerator();
        Task pdfTask = pdfGenerator.GeneratePdfWithCancellation(token);

        // Simulate a cancellation scenario
        Console.WriteLine("Press any key to cancel PDF generation...");
        Console.ReadKey();

        // Cancel the task by calling Cancel() on the CancellationTokenSource
        cancellationTokenSource.Cancel();

        try
        {
            // Await the task to handle any exceptions, such as cancellation
            await pdfTask;
        }
        catch (OperationCanceledException)
        {
            // Confirm the cancellation
            Console.WriteLine("The PDF generation was canceled.");
        }
        finally
        {
            cancellationTokenSource.Dispose();
        }

        Console.WriteLine("Program finished.");
    }
}

using IronPdf;
using System;
using System.Threading;
using System.Threading.Tasks;

public class PdfGenerator
{
    public async Task GeneratePdfWithCancellation(CancellationToken token)
    {
        var Renderer = new ChromePdfRenderer();
        try
        {
            // Check for cancellation before starting
            token.ThrowIfCancellationRequested();

            // Simulating a long task that can be checked for cancellation periodically
            for (int i = 0; i < 10; i++)
            {
                // Simulating a piece of work (this could be part of a larger HTML rendering)
                await Task.Delay(500); // Simulate chunk processing

                // Periodically check for cancellation in long-running operations
                if (token.IsCancellationRequested)
                {
                    Console.WriteLine("Cancellation requested. Throwing exception.");
                    token.ThrowIfCancellationRequested();  // This will trigger an OperationCanceledException
                }
            }

            // Simulate PDF creation after the long process
            var pdf = await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>");

            // Save the PDF after ensuring no cancellation occurred
            pdf.SaveAs("output.pdf");
            Console.WriteLine("PDF generated successfully.");
        }
        catch (OperationCanceledException)
        {
            // Handle task cancellation
            Console.WriteLine("PDF generation was canceled.");
        }
        catch (Exception ex)
        {
            // Handle other exceptions
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }
}

public class Program
{
    public static async Task Main(string[] args)
    {
        // Create a CancellationTokenSource
        var cancellationTokenSource = new CancellationTokenSource();

        // Create our cancellation token
        var token = cancellationTokenSource.Token;

        // Start the PDF generation task
        var pdfGenerator = new PdfGenerator();
        Task pdfTask = pdfGenerator.GeneratePdfWithCancellation(token);

        // Simulate a cancellation scenario
        Console.WriteLine("Press any key to cancel PDF generation...");
        Console.ReadKey();

        // Cancel the task by calling Cancel() on the CancellationTokenSource
        cancellationTokenSource.Cancel();

        try
        {
            // Await the task to handle any exceptions, such as cancellation
            await pdfTask;
        }
        catch (OperationCanceledException)
        {
            // Confirm the cancellation
            Console.WriteLine("The PDF generation was canceled.");
        }
        finally
        {
            cancellationTokenSource.Dispose();
        }

        Console.WriteLine("Program finished.");
    }
}

Imports IronPdf
Imports System
Imports System.Threading
Imports System.Threading.Tasks

Public Class PdfGenerator
	Public Async Function GeneratePdfWithCancellation(ByVal token As CancellationToken) As Task
		Dim Renderer = New ChromePdfRenderer()
		Try
			' Check for cancellation before starting
			token.ThrowIfCancellationRequested()

			' Simulating a long task that can be checked for cancellation periodically
			For i As Integer = 0 To 9
				' Simulating a piece of work (this could be part of a larger HTML rendering)
				Await Task.Delay(500) ' Simulate chunk processing

				' Periodically check for cancellation in long-running operations
				If token.IsCancellationRequested Then
					Console.WriteLine("Cancellation requested. Throwing exception.")
					token.ThrowIfCancellationRequested() ' This will trigger an OperationCanceledException
				End If
			Next i

			' Simulate PDF creation after the long process
			Dim pdf = Await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>")

			' Save the PDF after ensuring no cancellation occurred
			pdf.SaveAs("output.pdf")
			Console.WriteLine("PDF generated successfully.")
		Catch e1 As OperationCanceledException
			' Handle task cancellation
			Console.WriteLine("PDF generation was canceled.")
		Catch ex As Exception
			' Handle other exceptions
			Console.WriteLine($"An error occurred: {ex.Message}")
		End Try
	End Function
End Class

Public Class Program
	Public Shared Async Function Main(ByVal args() As String) As Task
		' Create a CancellationTokenSource
		Dim cancellationTokenSource As New CancellationTokenSource()

		' Create our cancellation token
		Dim token = cancellationTokenSource.Token

		' Start the PDF generation task
		Dim pdfGenerator As New PdfGenerator()
		Dim pdfTask As Task = pdfGenerator.GeneratePdfWithCancellation(token)

		' Simulate a cancellation scenario
		Console.WriteLine("Press any key to cancel PDF generation...")
		Console.ReadKey()

		' Cancel the task by calling Cancel() on the CancellationTokenSource
		cancellationTokenSource.Cancel()

		Try
			' Await the task to handle any exceptions, such as cancellation
			Await pdfTask
		Catch e1 As OperationCanceledException
			' Confirm the cancellation
			Console.WriteLine("The PDF generation was canceled.")
		Finally
			cancellationTokenSource.Dispose()
		End Try

		Console.WriteLine("Program finished.")
	End Function
End Class

Wynik konsoli

Wynik w formacie PDF

W tym przykładzie pokazujemy, jak użyć CancellationToken w programie napisanym w języku C#, aby anulować długotrwałe zadanie generowania pliku PDF za pomocą IronPDF. Kod jest podzielony na dwie części: proces generowania pliku PDF (klasa PdfGenerator) oraz główną logikę programu (klasa Program).

• Klasa PdfGenerator: Ta klasa zawiera metodę, która symuluje generowanie pliku PDF, obsługując jednocześnie anulowanie za pomocą obiektu CancellationToken.
• Tworzymy źródło tokenu anulowania w metodzie main za pomocą CancellationTokenSource(), a następnie tworzymy obiekt tokenu, przekazując do niego właściwość Token obiektu CancellationTokenSource.
• ChromePdfRenderer jest wykorzystywany z biblioteki IronPDF do renderowania treści HTML do dokumentu PDF.
• Metoda GeneratePdfWithCancellation jest asynchroniczna (async) i zwraca obiekt typu Task. Ta metoda akceptuje CancellationToken (token) w celu obsługi anulowania zadania poprzez żądanie anulowania.
• CancellationToken pozwala nam bezpiecznie anulować długotrwałe operacje. Jednak anulowanie ma charakter kooperacyjny, co oznacza, że samo zadanie musi okresowo sprawdzać status tokenu.
• W tym kodzie symulujemy długotrwałe zadanie z okresowymi kontrolami anulowania. Kluczową kwestią jest to, że ręcznie sprawdzamy, czy nie nastąpiło anulowanie (token.IsCancellationRequested) podczas procesu generowania pliku PDF, gotowi do uruchomienia metody anulowania, jeśli zostanie do niej przekazany token.
• Jeśli użytkownik naciśnie klawisz sygnalizujący anulowanie programu, zadanie zostanie płynnie zatrzymane i wygeneruje wyjątek OperationCanceledException, uniemożliwiając zakończenie generowania pliku PDF w odpowiedni i terminowy sposób.
• Wynikowy plik PDF jest zapisywany jako "output.pdf", o ile nie nastąpiło anulowanie, które uniemożliwiłoby programowi wykonanie całego procesu zadania.

1. Aplikacje internetowe

W aplikacjach internetowych użytkownicy często inicjują działania, takie jak generowanie raportów w formacie PDF. Jeśli jednak użytkownik opuści stronę lub zamknie przeglądarkę, system może to wykryć i użyć CancellationToken do zatrzymania procesu generowania pliku PDF.

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource)

Ta prosta implementacja pozwala serwerom internetowym na bardziej efektywne skalowanie poprzez niepoświęcanie zasobów na zadania, które nie są już potrzebne.

2. Raporty długoterminowe

W aplikacjach do raportowania użytkownicy mogą żądać eksportu dużych zbiorów danych do formatu PDF. Jeśli użytkownik zmieni zdanie lub wprowadzi nieprawidłowe zapytanie, CancellationToken pozwala na anulowanie zadania w trakcie jego wykonywania, zapobiegając marnowaniu zasobów.

3. Usługi w tle

W usługach działających w tle lub mikrousługach zadania wymagające znacznej ilości czasu, takie jak generowanie dużych partii plików PDF, można zarządzać bardziej efektywnie przy użyciu CancellationToken. Gdy usługa ma zostać wyłączona lub ograniczona, zadania w toku mogą zostać poprawnie anulowane, co gwarantuje, że żadne dane nie zostaną utracone ani uszkodzone.