.NET'te görev tabanlı zaman uyumsuz desen (TAP): Giriş ve genel bakış

.NET'de görev tabanlı zaman uyumsuz desen, yeni geliştirme için önerilen zaman uyumsuz tasarım desenidir. System.Threading.Tasks ad alanında zaman uyumsuz işlemleri temsil eden Task ve Task<TResult> türlerine dayanır.

Adlandırma, parametreler ve dönüş türleri

TAP, bir zaman uyumsuz işlemin başlangıcını ve tamamlanmasını temsil etmek için tek bir yöntem kullanır. Bu yaklaşım hem Zaman Uyumsuz Programlama Modeli (APM veya IAsyncResult) deseni hem de Olay Tabanlı Zaman Uyumsuz Desen (EAP) ile karşıttır. APM için Begin ve End yöntemleri gerekir. EAP, son eki Async olan bir yöntem gerektirir ve ayrıca bir veya daha fazla olay, olay işleyicisi temsilci türleri ve EventArg türetilmiş türler gerektirir. TAP'deki zaman uyumsuz yöntemler, Async, Task, Task<TResult> ve ValueTask gibi beklenebilir türler döndüren yöntemlerin adından sonra ValueTask<TResult> son ekini içerir. Örneğin, bir Get döndüren zaman uyumsuz bir işlem Task<String> olarak adlandırılabilir.GetAsync EAP yöntemi adını Async içeren bir sınıfa tap yöntemi ekliyorsanız bunun yerine son eki TaskAsync kullanın. Örneğin, sınıfın zaten bir GetAsync yöntemi varsa adını GetTaskAsynckullanın. Bir yöntem zaman uyumsuz bir işlem başlatıyor, ancak beklenebilir bir tür döndürmüyorsa, bu yöntemin işlemin sonucunu döndürmediğini veya oluşturmadığını belirtmek için adı Begin, Start veya başka bir fiil ile başlamalıdır.

Bir TAP yöntemi, karşılık gelen zaman uyumlu yöntemin System.Threading.Tasks.Task veya tür System.Threading.Tasks.Task<TResult> döndürdüğüne bağlı olarak ya bir System.Threading.Tasks.Task ya da bir döndürür.

Tap yönteminin parametreleri, zaman uyumlu karşılık geleninin parametreleriyle eşleşmeli ve aynı sırada sağlanmalıdır. out Ancak ve ref parametreleri bu kuraldan muaftır ve tamamen kaçınılmalıdır. out veya ref parametresinin döndürdüğü her türlü veri, Task<TResult> tarafından döndürülen TResult'nin bir parçası olmalı ve birden fazla değeri barındırmak için bir tuple veya özel bir veri yapısı kullanılmalıdır. Ayrıca, TAP yönteminin zaman uyumlu karşılığı bir CancellationToken parametresi sunmuyor olsa da bir CancellationToken parametresi eklemeyi göz önünde bulundurun.

Yalnızca görevlerin oluşturulmasına, işlemesine veya birleşimine (yöntemin zaman uyumsuz amacının yöntem adında veya yöntemin ait olduğu türün adında net olduğu) ayrılmış yöntemlerin bu adlandırma düzenine uyması gerekmez. Bu tür yöntemler genellikle birleştirici olarak adlandırılır. Birleştiricilere örnek olarak WhenAll ve WhenAny verilebilir ve Görev Tabanlı Zaman Uyumsuz Deseni Kullanma makalesinin Yerleşik Görev Tabanlı Birleştiricileri Kullanma bölümünde ele alınmaktadır.

TAP söz diziminin, Zaman Uyumsuz Programlama Modeli (APM) ve Olay Tabanlı Zaman Uyumsuz Desen (EAP) gibi eski zaman uyumsuz programlama desenlerinde kullanılan söz diziminden nasıl farklı olduğunu gösteren örnekler için bkz. Zaman Uyumsuz Programlama Desenleri.

Asenkron davranış, dönüş türleri ve adlandırma

anahtar async sözcüğü, bir yöntemi başka bir iş parçacığında zaman uyumsuz olarak çalıştırmaya zorlamaz. Etkinleştirir await ve yöntem, tamamlanmamış bir bekleme durumu ile karşılaşana kadar zaman uyumlu bir şekilde çalışır. Yöntem tamamlanmamış bir beklenebilir değere ulaşmazsa, eşzamanlı olarak tamamlanabilir.

Çoğu API için şu dönüş türlerini tercih edin:

  • Değer üretmeyen zaman uyumsuz işlemler için kullanın Task .
  • Bir değer üreten zaman uyumsuz işlemler için kullanın Task<TResult> .
  • ValueTask Veya yalnızca ölçümler ayırma baskısını gösterdiğinde ve tüketicilerin ek kullanım kısıtlamalarını işleyebildiği durumlarda kullanınValueTask<TResult>.

TAP adlandırmayı tahmin edilebilir tutun:

  • Async ekini, beklenebilir türleri döndüren yöntemler için kullanın.
  • Senkron yöntemlere Async eklemeyin.
  • Yeni MethodNameAsync aşırı yüklemeyi mevcut `MethodName`'in yanına ekleyin. Zaman uyumlu API'yi kaldırmayın veya yeniden adlandırmayın. İki seçeneği de korumak, arayanların bozucu bir değişiklik olmaksızın kendi hızlarında geçiş yapmalarını sağlar.

Zaman uyumsuz işlem başlatma

TAP'yi temel alan zaman uyumsuz bir yöntem, örneğin, bağımsız değişkenleri doğrulama ve zaman uyumsuz işlemi başlatma gibi az miktarda işi zaman uyumlu olarak yaptıktan sonra, elde edilen görevi döndürebilir. Eşzamansız yöntemin hızla dönebilmesi için eşzamanlı çalışmayı en düşük düzeyde tutun. Hızlı iadenin nedenleri şunlardır:

  • Kullanıcı arabirimi (UI) iş parçacıklarından zaman uyumsuz yöntemler çağırabilirsiniz ve uzun süre çalışan zaman uyumlu çalışmalar uygulamanın yanıt verme hızına zarar verebilir.
  • Aynı anda birden çok asenkron yöntem başlatabilirsiniz. Bu nedenle, zaman uyumsuz bir yöntemin zaman uyumlu bölümünde uzun süre çalışan herhangi bir çalışma, diğer zaman uyumsuz işlemlerin başlatılmasını geciktirerek eşzamanlılığın avantajlarını azaltabilir.

Bazı durumlarda, işlemi tamamlamak için gereken çalışma miktarı, işlemi zaman uyumsuz olarak başlatmak için gereken çalışma miktarından daha azdır. Okuma işleminin bellekte zaten arabelleğe alınmış veriler tarafından karşılanabildiği bir akıştan okumak, böyle bir senaryoya örnektir. Böyle durumlarda işlem zaman uyumlu bir şekilde tamamlanabilir ve zaten tamamlanmış bir görevi döndürebilir.

Özel durumlar

Zaman uyumsuz bir yöntem, yalnızca bir kullanım hatasına yanıt olarak zaman uyumsuz bir yöntem çağrısından doğrudan bir özel durum fırlatmalıdır. Üretim kodunda hiçbir zaman kullanım hataları oluşmamalıdır. Örneğin, yöntemin bağımsız değişkenlerinden biri olarak null başvuru (Nothing Visual Basic'te) geçirmek hata durumuna neden oluyorsa (genellikle bir ArgumentNullException özel durumla gösterilir), null başvurunun hiçbir zaman geçirilmediğini sağlamak için çağıran kodu değiştirebilirsiniz. Diğer tüm hatalar için, zaman uyumsuz bir yöntem çalışırken oluşan özel durumları, görev döndürülmeden önce bile zaman uyumsuz yöntem zamanı uyumlu bir şekilde tamamlansa dahi, döndürülen göreve atayın. Genellikle, bir görev en fazla bir özel durum içerir. Ancak, görev birden çok işlemi temsil ederse (örneğin, WhenAll), tek bir görevle birden çok özel durum ilişkilendirilebilir.

Hedef ortam

Bir TAP yöntemi uyguladığınızda, zaman uyumsuz yürütmenin nerede gerçekleştiğini belirleyebilirsiniz. İş yükünü iş parçacığı havuzunda yürütmeyi, zaman uyumsuz G/Ç kullanarak uygulamayı (işlemin yürütülmesinin çoğunluğu için bir iş parçacığına bağlı olmadan), belirli bir iş parçacığında çalıştırmayı (ui iş parçacığı gibi) veya herhangi bir sayıda olası bağlamı kullanmayı seçebilirsiniz. TAP yönteminin hiç yürütülecek bir şeyinin olmaması ve sadece sistemin başka bir yerinde bir koşulun oluşumunu temsil eden bir Task döndürmesi mümkündür (örneğin, kuyruğa alınmış bir veri yapısına gelen veriyi temsil eden bir görev).

TAP yöntemini çağıran, sonuçta elde edilen görevi zaman uyumlu bir şekilde bekleyerek TAP yönteminin tamamlanmasını beklemeyi engelleyebilir veya zaman uyumsuz işlem tamamlandığında ek (devamlılık) kodu çalıştırabilir. Devamlılık kodunu oluşturan, bu kodun nerede yürütüleceği üzerinde denetime sahiptir. Devamlılık kodunu açıkça oluşturabilirsiniz. Task sınıfındaki yöntemler aracılığıyla (örneğin, ContinueWith) veya örtük olarak, devamlılıkların üzerine kurulu dil desteğini kullanarak (örneğin, C# dilinde await, Visual Basic Await, Visual Basic AwaitValue).

Görev durumu

Task sınıfı, zaman uyumsuz işlemler için bir yaşam döngüsü sağlar ve bu döngü TaskStatus numaralandırma tipi tarafından temsil edilir. Task ve Task<TResult> türlerinden türetilen türlerin köşe durumlarını desteklemek ve yapının zamanlamadan ayrılmasını sağlamak için, Task sınıfı bir Start yöntemi ortaya koyar. Halk Task oluşturucular tarafından oluşturulan görevler, yaşam döngülerine zamanlanmamış durumda başladıkları ve ancak bu örneklerde Created çağrıldıklarında zamanlandıkları için Start olarak adlandırılır.

Diğer tüm görevler yaşam döngülerine aktif durumda başlar; bu, temsil ettikleri asenkron işlemlerin zaten başlatıldığı ve görev durumlarının TaskStatus.Created dışındaki bir numaralandırma değeri olduğu anlamına gelir. TAP yöntemlerinden döndürülen tüm görevler etkinleştirilmelidir. TAP yöntemi, döndürülecek görevin örneğini oluşturmak için bir görevin oluşturucusunu dahili olarak kullanıyorsa, döndürmeden önce Start nesnesi üzerinde Task çağrısı yapması gerekir. TAP yöntemi tüketicileri, döndürülen işlemin aktif olduğunu ve TAP yönteminden döndürülen herhangi bir Start üzerinde Task çağırmayı denememelidir. Start'nin etkin bir görevde çağrılması bir InvalidOperationException özel durumla sonuçlanır.

Görev etkinleştirmeden sonra çalışma ve unutma ömrü ve sahiplik sorunları hakkında rehberlik için bkz. Zaman uyumsuz yöntemleri canlı tutma.

İptal (isteğe bağlı)

TAP'de iptal, hem zaman uyumsuz yöntem uygulayıcıları hem de zaman uyumsuz yöntem tüketicileri için isteğe bağlıdır. İşlem iptale izin veriyorsa, bir iptal belirteci (CancellationToken örnek) kabul eden zaman uyumsuz yöntemin aşırı yüklemesini ortaya çıkarır. Kurala göre parametresi olarak adlandırılır cancellationToken.

public static Task ReadAsync(byte[] buffer, int offset, int count,
                             CancellationToken cancellationToken)

Public Function ReadAsync(buffer As Byte(), offset As Integer, count As Integer,
                          cancellationToken As CancellationToken) As Task

Asenkron işlem, iptal istekleri için bu belirteci izler. bir iptal isteği alırsa, bu isteği yerine getirmek ve işlemi iptal etmek isteyebilir. İptal isteği işin erken sona ermesine yol açarsa, TAP yöntemi Canceled durumunda sona eren bir görev döndürür; kullanılabilir bir sonuç yoktur ve istisna fırlatmaz. Durum Canceled, Faulted ve RanToCompletion durumlarıyla birlikte bir görevin son (tamamlanmış) durumu olarak kabul edilir. Bu nedenle, bir görev Canceled durumundaysa, IsCompleted özelliği true değerini döndürür. Görev Canceled durumunda tamamlandığında, devamı iptal etmek için bir NotOnCanceled devamlılık seçeneği belirtilmediyse, göreve kayıtlı olan tüm devamlılıklar zamanlanır veya yürütülür. Dil özelliklerini kullanarak eşzamanlı olmayan bir şekilde iptal edilen bir görevi bekleyen tüm kodlar çalışmaya devam eder, ancak bu özel durumdan türetilmiş bir OperationCanceledException veya özel durum alır. Wait ve WaitAll gibi yöntemler aracılığıyla, görev üzerinde zaman uyumlu olarak beklerken engellenen kod, bir istisna ile çalışmaya devam eder.

İptal belirteci, belirteci kabul eden TAP yöntemi çağrılmadan önce iptal isteğinde bulunursa, TAP yöntemi bir Canceled görev döndürmelidir. Ancak, zaman uyumsuz işlem çalışırken iptal istenirse, zaman uyumsuz işlemin iptal isteğini kabul etmesi gerekmez. Geri dönen görev, yalnızca iptal isteğinin Canceled sonucu olarak işlemin sona ermesi durumunda bitmelidir. İptal istenirse ancak yine de bir sonuç veya özel durum oluşturulursa, görevin RanToCompletion veya Faulted durumunda bitmesi gerekir.

Öncelikli olarak iptal edilme özelliğini kullanıma sunmak isteyen zaman uyumsuz yöntemler için, iptal belirtecini kabul etmeyen bir aşırı yükleme sağlamanız gerekmez. İptal edilmeyecek yöntemler için iptal belirteci kabul eden aşırı yüklemeler sağlamayın; bu, çağıranın hedef yöntemin gerçekten iptal edilebilir olup olmadığını belirtmeye yardımcı olur. İptali istemeyen tüketici kodu, CancellationToken kabul eden bir yöntemi çağırabilir ve bağımsız değişken değeri olarak None sağlayabilir. None , işlevsel olarak varsayılan CancellationTokenile eşdeğerdir.

İlerleme raporlama (isteğe bağlı)

Bazı zaman uyumsuz işlemler, ilerleme bildirimleri sağlamanın avantajını sunar. Genellikle, bir kullanıcı arabirimini zaman uyumsuz işlemin ilerleme durumuyla ilgili bilgilerle güncelleştirmek için bu bildirimleri kullanın.

TAP'te, bir IProgress<T> arabirim aracılığıyla ilerlemeyi yönetin. Bu arabirimi genellikle progress adlı bir parametre olarak zaman uyumsuz yönteme geçirin. Zaman uyumsuz yöntemi çağırırken ilerleme arabirimini sağladığınızda, yanlış kullanımdan kaynaklanan yarış koşullarını ortadan kaldırmaya yardımcı olursunuz. Bu yarış koşulları, işlem başladıktan ve güncelleştirmeleri kaçırdıktan sonra olay işleyicileri yanlış kaydedildiğinde oluşur. Daha da önemlisi, ilerleme arabirimi, tüketen kod tarafından belirlenen farklı ilerleme uygulamalarını destekler. Örneğin, tüketen kod yalnızca en son ilerleme güncellemesiyle ilgilenebilir veya tüm güncellemeleri arabelleğe almak, her güncelleme için bir eylemi çağırmak veya çağrının belirli bir iş parçacığına aktarılıp aktarılmadığını kontrol etmek isteyebilir. Tüm bu seçeneklere, belirli bir tüketicinin ihtiyaçlarına göre özelleştirilmiş farklı arabirim uygulamaları kullanılarak ulaşılabilir. İptalde olduğu gibi, TAP uygulamaları yalnızca API ilerleme bildirimlerini destekliyorsa bir IProgress<T> parametre sağlamalıdır.

Örneğin, bu makalenin ReadAsync önceki bölümlerinde açıklanan yöntem, ara ilerleme durumunu şu ana kadar okunan bayt sayısı biçiminde bildirebiliyorsa, ilerleme geri çağırması bir IProgress<T> arabirim olabilir:

public static Task ReadAsync(byte[] buffer, int offset, int count,
                             IProgress<long> progress)

Public Function ReadAsync(buffer As Byte(), offset As Integer, count As Integer,
                          progress As IProgress(Of Long)) As Task

Bir FindFilesAsync yöntem, belirli bir arama desenini karşılayan tüm dosyaların listesini döndürürse, ilerleme geri araması tamamlanan çalışma yüzdesi ve geçerli kısmi sonuç kümesini tahmin edebilir. Bu bilgiler bir demet ile sağlanabilir

public static Task<ReadOnlyCollection<FileInfo>> FindFilesAsync(
    string pattern,
    IProgress<Tuple<double, ReadOnlyCollection<List<FileInfo>>>> progress)

Public Function FindFilesAsync(
    pattern As String,
    progress As IProgress(Of Tuple(Of Double, ReadOnlyCollection(Of List(Of FileInfo))))) As Task(Of ReadOnlyCollection(Of FileInfo))

veya API'ye özgü bir veri türüyle:

public static Task<ReadOnlyCollection<FileInfo>> FindFilesAsync(
    string pattern,
    IProgress<FindFilesProgressInfo> progress)

Public Function FindFilesAsync(
    pattern As String,
    progress As IProgress(Of FindFilesProgressInfo)) As Task(Of ReadOnlyCollection(Of FileInfo))

İkinci durumda, özel veri türüne genellikle ProgressInfo son eklenir.

TAP uygulamaları progress parametresini kabul eden aşırı yüklemeler sağlıyorsa, bağımsız değişkenin null olmasına izin vermelidir. Atlarsanız null, hiçbir ilerleme bildirilmez. TAP uygulamaları ilerleme durumunu nesneye Progress<T> zaman uyumlu olarak bildirmelidir ve bu da zaman uyumsuz yöntemin hızla ilerlemeyi sağlamasına olanak tanır. Ayrıca, ilerleme tüketicisinin bilgileri en iyi nasıl ve nerede işleyeceğini belirlemesine olanak tanır. Örneğin, ilerleme örneği geri çağırmaları hazırlamayı ve yakalanan eşitleme bağlamında olayları tetiklemeyi seçebilir.

IProgress<T> implementasyonları

.NET, Progress<T>'i uygulayan IProgress<T> sınıfını sağlar. Progress<T> sınıfı aşağıdaki gibi bildirilir:

public class Progress<T> : IProgress<T>
{
    public Progress();
    public Progress(Action<T> handler);
    protected virtual void OnReport(T value);
    public event EventHandler<T>? ProgressChanged;
}

Örneği Progress<T>, zaman uyumsuz işlem her ilerleme güncellemesini bildirdiğinde tetiklenen bir ProgressChanged olayı kullanıma sunar. ProgressChanged olayı, örnek başlatıldığında Progress<T> örneğinin yakaladığı SynchronizationContext nesnesinde tetiklenir. Senkronizasyon bağlamı mevcut değilse, iş parçacığı havuzunu hedefleyen varsayılan bir bağlam kullanılır. İşleyicileri bu olayla kaydedebilirsiniz. Kolaylık sağlamak için oluşturucuya Progress<T> tek bir işleyici de sağlayabilirsiniz. Bu işleyici, ProgressChanged olaya yönelik bir olay işleyicisi gibi davranır. olay işleyicileri yürütülürken zaman uyumsuz işlemin gecikmesini önlemek için ilerleme güncelleştirmeleri zaman uyumsuz olarak oluşturulur. Başka bir IProgress<T> uygulama farklı semantikler uygulamayı seçebilir.

Sağlanacak aşırı yüklemeleri seçme

Bir TAP uygulaması hem isteğe bağlı CancellationToken hem de isteğe bağlı IProgress<T> parametreleri kullanıyorsa, dört adede kadar aşırı yükleme gerektirebilir:

public Task MethodNameAsync(…);
public Task MethodNameAsync(…, CancellationToken cancellationToken);
public Task MethodNameAsync(…, IProgress<T> progress);
public Task MethodNameAsync(…,
    CancellationToken cancellationToken, IProgress<T> progress);

Public MethodNameAsync(…) As Task
Public MethodNameAsync(…, cancellationToken As CancellationToken cancellationToken) As Task
Public MethodNameAsync(…, progress As IProgress(Of T)) As Task
Public MethodNameAsync(…, cancellationToken As CancellationToken,
                       progress As IProgress(Of T)) As Task

Ancak birçok TAP uygulaması iptal veya ilerleme özellikleri sağlamadığından tek bir yöntem gerektirir:

public Task MethodNameAsync(…);

Public MethodNameAsync(…) As Task

TAP uygulaması iptali veya ilerlemeyi destekliyor ancak ikisini birden desteklemiyorsa iki aşırı yükleme sağlayabilir:

public Task MethodNameAsync(…);
public Task MethodNameAsync(…, CancellationToken cancellationToken);

// … or …

public Task MethodNameAsync(…);
public Task MethodNameAsync(…, IProgress<T> progress);

Public MethodNameAsync(…) As Task
Public MethodNameAsync(…, cancellationToken As CancellationToken) As Task

' … or …

Public MethodNameAsync(…) As Task
Public MethodNameAsync(…, progress As IProgress(Of T)) As Task

Bir TAP uygulaması hem iptal hem de ilerlemeyi destekliyorsa, dört aşırı yüklemeyi de ortaya çıkarabilir. Ancak, yalnızca aşağıdaki ikisini sağlayabilir:

public Task MethodNameAsync(…);
public Task MethodNameAsync(…,
    CancellationToken cancellationToken, IProgress<T> progress);

Public MethodNameAsync(…) As Task
Public MethodNameAsync(…, cancellationToken As CancellationToken,
                       progress As IProgress(Of T)) As Task

Eksik iki ara bileşimi telafi etmek için, geliştiriciler None veya varsayılan CancellationToken değerini cancellationToken parametresi olarak ve null değerini progress parametresi olarak geçirebilirler.

TAP yönteminin her kullanımının iptali veya ilerlemeyi desteklemesini bekliyorsanız, ilgili parametreyi kabul etmeyen aşırı yüklemeleri atlayabilirsiniz.

İptal veya ilerleme durumunu isteğe bağlı hale getirmek için birden çok aşırı yüklemeyi kullanıma açmaya karar verirseniz, iptali veya ilerlemeyi desteklemeyen aşırı yüklemeler, iptali veya ilerlemeyi destekleyen aşırı yüklemeye None veya null parametreleri geçmiş gibi davranmalıdır.

  • Last updated on