Asynchronní vzor založený na úlohách (klepnutím)Task-based asynchronous pattern (TAP)

Asynchronní vzor založený na úlohách (klepněte) je založen na System.Threading.Tasks.Task a System.Threading.Tasks.Task<TResult> typech v oboru názvů System.Threading.Tasks, které slouží k reprezentaci libovolných asynchronních operací.The Task-based Asynchronous Pattern (TAP) is based on the System.Threading.Tasks.Task and System.Threading.Tasks.Task<TResult> types in the System.Threading.Tasks namespace, which are used to represent arbitrary asynchronous operations. TAP je doporučený asynchronní návrh vzoru pro nový vývoj.TAP is the recommended asynchronous design pattern for new development.

Pojmenovávání, parametry a návratové typyNaming, parameters, and return types

TAP používá jedinou metodu k reprezentaci zahájení a dokončení asynchronní operace.TAP uses a single method to represent the initiation and completion of an asynchronous operation. To se liší od vzoru asynchronního programovacího modelu (APM nebo IAsyncResult) a asynchronního vzoru založeného na událostech (EAP).This contrasts with both the Asynchronous Programming Model (APM or IAsyncResult) pattern and the Event-based Asynchronous Pattern (EAP). APM vyžaduje Begin a End metody.APM requires Begin and End methods. Protokol EAP vyžaduje metodu, která má příponu Async a také vyžaduje jednu nebo více událostí, typy delegátů obslužné rutiny události a typy odvozené od EventArg.EAP requires a method that has the Async suffix and also requires one or more events, event handler delegate types, and EventArg-derived types. Asynchronní metody v klepnutím zahrnují příponu Async za názvem operace pro metody, které vracejí neočekávané typy, například Task, Task<TResult>, ValueTaska ValueTask<TResult>.Asynchronous methods in TAP include the Async suffix after the operation name for methods that return awaitable types, such as Task, Task<TResult>, ValueTask, and ValueTask<TResult>. Například asynchronní operace Get, která vrací Task<String>, může být pojmenována GetAsync.For example, an asynchronous Get operation that returns a Task<String> can be named GetAsync. Pokud přidáváte metodu klepněte na třídu, která již obsahuje název metody EAP s příponou Async, použijte místo toho příponu TaskAsync.If you're adding a TAP method to a class that already contains an EAP method name with the Async suffix, use the suffix TaskAsync instead. Například pokud třída již má metodu GetAsync, použijte název GetTaskAsync.For example, if the class already has a GetAsync method, use the name GetTaskAsync. Pokud metoda spustí asynchronní operaci, ale nevrátí očekávaný typ, jeho název by měl začínat Begin, Startnebo některé jiné operace, aby bylo možné navrhnout, že tato metoda nevrací nebo nevyvolává výsledek operace.If a method starts an asynchronous operation but does not return an awaitable type, its name should start with Begin, Start, or some other verb to suggest that this method does not return or throw the result of the operation.  

Metoda klepnutí vrátí buď System.Threading.Tasks.Task, nebo System.Threading.Tasks.Task<TResult>, na základě toho, zda odpovídající synchronní metoda vrátí typ void nebo typ TResult.A TAP method returns either a System.Threading.Tasks.Task or a System.Threading.Tasks.Task<TResult>, based on whether the corresponding synchronous method returns void or a type TResult.

Parametry metody klepnutí by měly odpovídat parametrům jeho synchronního protějšku a měly by být zadány ve stejném pořadí.The parameters of a TAP method should match the parameters of its synchronous counterpart and should be provided in the same order. Parametry out a ref však nejsou z tohoto pravidla vyňaty a je třeba se jim vyhnout zcela.However, out and ref parameters are exempt from this rule and should be avoided entirely. Všechna data, která by byla vrácena pomocí out nebo ref parametru, by měla být vrácena jako součást TResult vrácená Task<TResult>a měla by použít řazenou kolekci členů nebo vlastní datovou strukturu pro přizpůsobení více hodnot.Any data that would have been returned through an out or ref parameter should instead be returned as part of the TResult returned by Task<TResult>, and should use a tuple or a custom data structure to accommodate multiple values. Měli byste také zvážit přidání parametru CancellationToken i v případě, že se synchronní protějšek metody klepnutí na ni nenabídne.You should also consider adding a CancellationToken parameter even if the TAP method's synchronous counterpart does not offer one.

Metody, které jsou odčleněny výhradně na vytváření, manipulaci nebo kombinaci úloh (kde je asynchronní záměr metody jasný v názvu metody nebo v názvu typu, ke kterému patří metoda), nemusí následovat po tomto vzoru názvů. Tyto metody jsou často označovány jako kombinátory.Methods that are devoted exclusively to the creation, manipulation, or combination of tasks (where the asynchronous intent of the method is clear in the method name or in the name of the type to which the method belongs) need not follow this naming pattern; such methods are often referred to as combinators. Příklady kombinátory zahrnují WhenAll a WhenAnya jsou popsány v tématu použití integrovaného oddílu založeného na úlohách kombinátory článku, který spotřebovává asynchronní vzor založený na úlohách.Examples of combinators include WhenAll and WhenAny, and are discussed in the Using the Built-in Task-based Combinators section of the article Consuming the Task-based Asynchronous Pattern.

Příklady, jak se syntaxe klepnutí liší od syntaxe používané v zastaralých asynchronních vzorech programování, jako je asynchronní programovací model (APM) a asynchronní vzor založený na událostech (EAP), naleznete v tématu asynchronní programovací vzory.For examples of how the TAP syntax differs from the syntax used in legacy asynchronous programming patterns such as the Asynchronous Programming Model (APM) and the Event-based Asynchronous Pattern (EAP), see Asynchronous Programming Patterns.

Inicializace asynchronní operaceInitiating an asynchronous operation

Asynchronní metoda, která je založena na TAP, zvládne malé množství práce synchronně, například validaci argumentů a spouštění asynchronní operace před vrácením výsledné úlohy.An asynchronous method that is based on TAP can do a small amount of work synchronously, such as validating arguments and initiating the asynchronous operation, before it returns the resulting task. Synchronní práce by měly být neustále udržovány na minimu, aby asynchronní metody mohly vracet rychle.Synchronous work should be kept to the minimum so the asynchronous method can return quickly. Mezi důvody pro rychlý návrat patří:Reasons for a quick return include the following:

  • Asynchronní metody mohou být vyvolány z vlákna uživatelského rozhraní (UI) a dlouhotrvající synchronní práce může mít negativní dopad na odezvu aplikace.Asynchronous methods may be invoked from user interface (UI) threads, and any long-running synchronous work could harm the responsiveness of the application.

  • Je možné spustit několik asynchronních metod současně.Multiple asynchronous methods may be launched concurrently. Proto by jakékoli dlouhotrvající práce v synchronní části asynchronní metody mohly zpožďovat zahájení jiné asynchronní operace, a tím zmenšit výhody souběžnosti.Therefore, any long-running work in the synchronous portion of an asynchronous method could delay the initiation of other asynchronous operations, thereby decreasing the benefits of concurrency.

V některých případech je množství práce potřebné k dokončení operace menší než množství práce potřebné ke spuštění operace asynchronně.In some cases, the amount of work required to complete the operation is less than the amount of work required to launch the operation asynchronously. Příkladem takového scénáře je čtení z datového proudu, kde lze operaci čtení naplnit daty, která jsou již uložena do vyrovnávací paměti.Reading from a stream where the read operation can be satisfied by data that is already buffered in memory is an example of such a scenario. Operace v těchto případech může být dokončena synchronně a může vrátit úlohu, která již byla dokončena.In such cases, the operation may complete synchronously, and may return a task that has already been completed.

VýjimkyExceptions

Asynchronní metoda by měla vyvolat výjimku z volání asynchronní metody pouze jako odpověď na chybu použití.An asynchronous method should raise an exception to be thrown out of the asynchronous method call only in response to a usage error. Chyby použití by se nikdy neměly objevit v produkčním kódu.Usage errors should never occur in production code. Například Pokud předáte odkaz s hodnotou null (Nothing v Visual Basic), protože jeden z argumentů metody způsobí chybový stav (obvykle reprezentovaný ArgumentNullException výjimkou), můžete změnit volající kód, aby se zajistilo, že odkaz s hodnotou null není nikdy předán.For example, if passing a null reference (Nothing in Visual Basic) as one of the method’s arguments causes an error state (usually represented by an ArgumentNullException exception), you can modify the calling code to ensure that a null reference is never passed. U všech ostatních chyb by měly být výjimky, ke kterým dochází při spuštění asynchronní metody, přiřazeny vrácené úloze i v případě, že se asynchronní metoda dokončí synchronně předtím, než je úloha vrácena.For all other errors, exceptions that occur when an asynchronous method is running should be assigned to the returned task, even if the asynchronous method happens to complete synchronously before the task is returned. Úloha obvykle obsahuje nanejvýš jednu výjimku.Typically, a task contains at most one exception. Pokud však úloha představuje více operací (například WhenAll), může být k jedné úloze přidruženo více výjimek.However, if the task represents multiple operations (for example, WhenAll), multiple exceptions may be associated with a single task.

Cílové prostředíTarget environment

Při implementaci metody TAP můžete určit, kde dochází k asynchronnímu spouštění.When you implement a TAP method, you can determine where asynchronous execution occurs. Úlohy můžete spouštět ve fondu vláken, implementovat je pomocí asynchronního I/O (bez vázání na vlákno pro většinu spuštění operace), spustit je na konkrétním vlákně (například vlákně UI) nebo použít libovolný počet potenciálních kontextů.You may choose to execute the workload on the thread pool, implement it by using asynchronous I/O (without being bound to a thread for the majority of the operation’s execution), run it on a specific thread (such as the UI thread), or use any number of potential contexts. Metoda klepnutí může dokonce mít nic ke spuštění a může vrátit Task, která představuje výskyt podmínky jinde v systému (například úkol, který představuje data přicházející do struktury dat zařazené do fronty).A TAP method may even have nothing to execute, and may just return a Task that represents the occurrence of a condition elsewhere in the system (for example, a task that represents data arriving at a queued data structure).

Volající metody klepnutí může blokovat čekání na provedení metody klepnutí synchronním čekáním na výsledný úkol nebo může spustit další (pokračování) kód po dokončení asynchronní operace.The caller of the TAP method may block waiting for the TAP method to complete by synchronously waiting on the resulting task, or may run additional (continuation) code when the asynchronous operation completes. Tvůrce kódu pokračování má kontrolu nad tím, kde se spustí kód.The creator of the continuation code has control over where that code executes. Kód pro pokračování můžete vytvořit buď explicitně, prostřednictvím metod Task třídy (například ContinueWith) nebo implicitně pomocí jazykové podpory založené na pokračováních (například await v C#Await Visual Basic AwaitValue v F#).You may create the continuation code either explicitly, through methods on the Task class (for example, ContinueWith) or implicitly, by using language support built on top of continuations (for example, await in C#, Await in Visual Basic, AwaitValue in F#).

Stav úlohyTask status

Třída Task poskytuje životní cyklus pro asynchronní operace a tento cyklus je reprezentován výčtem TaskStatus.The Task class provides a life cycle for asynchronous operations, and that cycle is represented by the TaskStatus enumeration. Pro podporu rohových případů typů, které jsou odvozeny z Task a Task<TResult>a pro podporu oddělení konstrukce od plánování, třída Task zpřístupňuje metodu Start.To support corner cases of types that derive from Task and Task<TResult>, and to support the separation of construction from scheduling, the Task class exposes a Start method. Úlohy, které jsou vytvořeny pomocí veřejných Task konstruktory, jsou označovány jako studené úlohy, protože začínají jejich životní cyklus v neplánovaném Created stavu a jsou plánovány pouze v případě, že je na těchto instancích volána Start.Tasks that are created by the public Task constructors are referred to as cold tasks, because they begin their life cycle in the non-scheduled Created state and are scheduled only when Start is called on these instances.

Všechny ostatní úlohy zahájí svůj životní cyklus v horkém stavu, což znamená, že asynchronní operace, které představují, již byly iniciovány a jejich stav úlohy je jiná hodnota výčtu než TaskStatus.Created.All other tasks begin their life cycle in a hot state, which means that the asynchronous operations they represent have already been initiated and their task status is an enumeration value other than TaskStatus.Created. Všechny úlohy, které jsou vráceny z metod TAP, musí být aktivovány.All tasks that are returned from TAP methods must be activated. Pokud metoda klepnutí interně používá konstruktor úkolu k vytvoření instance úkolu, který má být vrácen, metoda klepnutí musí volat Start na objektu Task před jeho vrácením.If a TAP method internally uses a task’s constructor to instantiate the task to be returned, the TAP method must call Start on the Task object before returning it. Příjemci metody klepnutí můžou bezpečně předpokládat, že vrácená úloha je aktivní a neměla by se pokoušet o volání Start na všech Task, které se vrátí z metody klepnutí.Consumers of a TAP method may safely assume that the returned task is active and should not try to call Start on any Task that is returned from a TAP method. Volání Start na aktivní úloze má za následek výjimku InvalidOperationException.Calling Start on an active task results in an InvalidOperationException exception.

Zrušení (volitelné)Cancellation (optional)

Pro implementátory asynchronní metody i příjemce asynchronní metody je v TAP zrušení volitelné.In TAP, cancellation is optional for both asynchronous method implementers and asynchronous method consumers. Pokud operace umožňuje zrušení, zveřejňuje přetížení asynchronní metody, která přijímá token zrušení (CancellationToken instance).If an operation allows cancellation, it exposes an overload of the asynchronous method that accepts a cancellation token (CancellationToken instance). Podle konvence má parametr název cancellationToken.By convention, the parameter is named cancellationToken.

public 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

Asynchronní operace sleduje tento token kvůli žádostem o zrušení.The asynchronous operation monitors this token for cancellation requests. Pokud obdrží žádost o zrušení, může vyhovět žádosti a operaci zrušit.If it receives a cancellation request, it may choose to honor that request and cancel the operation. Pokud výsledkem požadavku na zrušení je předčasně ukončena práce, metoda klepnutí vrátí úlohu, která skončí ve stavu Canceled. k dispozici není žádný výsledek a není vyvolána žádná výjimka.If the cancellation request results in work being ended prematurely, the TAP method returns a task that ends in the Canceled state; there is no available result and no exception is thrown. Canceled stav se považuje za konečný (dokončený) stav úlohy společně s Faulted a RanToCompletion stavy.The Canceled state is considered to be a final (completed) state for a task, along with the Faulted and RanToCompletion states. Proto pokud je úkol ve stavu Canceled, jeho vlastnost IsCompleted vrátí true.Therefore, if a task is in the Canceled state, its IsCompleted property returns true. Když se úloha dokončí ve stavu Canceled, všechna pokračování zaregistrovaná v rámci úlohy se naplánují nebo spustí, pokud není možnost pokračování, jako je třeba NotOnCanceled, nedošlo k odhlášení z pokračování.When a task completes in the Canceled state, any continuations registered with the task are scheduled or executed, unless a continuation option such as NotOnCanceled was specified to opt out of continuation. Jakýkoli kód, který asynchronně čeká na zrušený úkol prostřednictvím použití funkcí jazyka, pokračuje v běhu, ale přijímá OperationCanceledException nebo výjimku z něj odvozenou.Any code that is asynchronously waiting for a canceled task through use of language features continues to run but receives an OperationCanceledException or an exception derived from it. Kód, který je blokován synchronně čekáním na úlohu prostřednictvím metod, jako je například Wait a WaitAll také i nadále běžet s výjimkou.Code that is blocked synchronously waiting on the task through methods such as Wait and WaitAll also continue to run with an exception.

Pokud token zrušení požadoval zrušení před tím, než je volána metoda klepnutí, která přijímá tento token, metoda klepnutí by měla vrátit úlohu Canceled.If a cancellation token has requested cancellation before the TAP method that accepts that token is called, the TAP method should return a Canceled task. Pokud je však požadováno zrušení při spuštěné asynchronní operaci, asynchronní operace nemusí přijmout žádost o zrušení.However, if cancellation is requested while the asynchronous operation is running, the asynchronous operation need not accept the cancellation request. Vrácený úkol by měl končit ve stavu Canceled pouze v případě, že operace skončí v důsledku požadavku na zrušení.The returned task should end in the Canceled state only if the operation ends as a result of the cancellation request. Pokud je požadováno zrušení, ale výsledek nebo výjimka jsou stále vyprodukovány, úloha by měla skončit ve RanToCompletion nebo Faultedm stavu.If cancellation is requested but a result or an exception is still produced, the task should end in the RanToCompletion or Faulted state.

Pro asynchronní metody, které chtějí vystavit možnost zrušit první a nejpřednější, nemusíte poskytovat přetížení, které nepřijímá token zrušení.For asynchronous methods that want to expose the ability to be cancelled first and foremost, you don't have to provide an overload that doesn’t accept a cancellation token. Pro metody, které nelze zrušit, neposkytujte přetížení, která přijímají token zrušení. To pomáhá volajícímu určit, zda je skutečně možné zrušit cílovou metodu.For methods that cannot be canceled, do not provide overloads that accept a cancellation token; this helps indicate to the caller whether the target method is actually cancelable. Kód příjemce, který není žádoucí pro zrušení, může volat metodu, která přijímá CancellationToken a jako hodnotu argumentu zadat None.Consumer code that does not desire cancellation may call a method that accepts a CancellationToken and provide None as the argument value. None je funkčně ekvivalentní výchozímu CancellationToken.None is functionally equivalent to the default CancellationToken.

Vytváření sestav průběhu (volitelné)Progress reporting (optional)

Některé asynchronní operace těží z poskytování oznámení o průběhu. Ta se obvykle používají k aktualizaci uživatelského rozhraní informacemi o průběhu asynchronní operace.Some asynchronous operations benefit from providing progress notifications; these are typically used to update a user interface with information about the progress of the asynchronous operation.

V klepněte, průběh je zpracován prostřednictvím rozhraní IProgress<T>, které je předáno asynchronní metodě jako parametr, který je obvykle pojmenován progress.In TAP, progress is handled through an IProgress<T> interface, which is passed to the asynchronous method as a parameter that is usually named progress. Poskytnutí rozhraní průběhu při volání asynchronní metody pomáhá eliminovat konflikty časování, které jsou výsledkem nesprávného použití (to znamená, když obslužným rutinám, které jsou nesprávně zaregistrovány po zahájení operace, chybí aktualizace).Providing the progress interface when the asynchronous method is called helps eliminate race conditions that result from incorrect usage (that is, when event handlers that are incorrectly registered after the operation starts may miss updates). Důležitější je, že rozhraní průběhu podporuje různé implementace průběhu podle náročnosti kódu.More importantly, the progress interface supports varying implementations of progress, as determined by the consuming code. Náročný kód se bude například starat pouze o nejnovější aktualizaci průběhu nebo může chtít mít všechny aktualizace ve vyrovnávací paměti nebo může chtít vyvolat akci pro každou aktualizaci nebo může chtít řídit, zda je volání zařazeno do konkrétního vlákna.For example, the consuming code may only care about the latest progress update, or may want to buffer all updates, or may want to invoke an action for each update, or may want to control whether the invocation is marshaled to a particular thread. Všech těchto možností lze dosáhnout pomocí různých implementací rozhraní přizpůsobených potřebám konkrétního příjemce.All these options may be achieved by using a different implementation of the interface, customized to the particular consumer’s needs. Stejně jako u zrušení, klepnutí na implementace by měly poskytnout parametr IProgress<T>, pouze pokud rozhraní API podporuje oznámení o průběhu.As with cancellation, TAP implementations should provide an IProgress<T> parameter only if the API supports progress notifications.

Pokud například metoda ReadAsync popsaná výše v tomto článku dokáže podávat sestavy o mezilehlém pokroku ve formě počtu přečtených bajtů, může zpětné volání průběhu představovat IProgress<T> rozhraní:For example, if the ReadAsync method discussed earlier in this article is able to report intermediate progress in the form of the number of bytes read thus far, the progress callback could be an IProgress<T> interface:

public 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 

Pokud metoda FindFilesAsync vrátí seznam všech souborů, které splňují konkrétní vzor hledání, zpětné volání průběhu může poskytnout odhad procentuální hodnoty dokončené práce a také aktuální sadu částečných výsledků.If a FindFilesAsync method returns a list of all files that meet a particular search pattern, the progress callback could provide an estimate of the percentage of work completed as well as the current set of partial results. To může provést buď s uspořádanou n-ticí:It could do this either with a tuple:

public 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))

nebo s datovým typem, který je specifický pro rozhraní API:or with a data type that is specific to the API:

public 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))

V druhém případě je zvláštní datový typ obvykle ProgressInfopříponou.In the latter case, the special data type is usually suffixed with ProgressInfo.

Pokud klepnutím na implementace zadáte přetížení, která přijímají parametr progress, musí umožnit, aby byl argument null. v takovém případě se nebude hlásit žádný pokrok.If TAP implementations provide overloads that accept a progress parameter, they must allow the argument to be null, in which case no progress will be reported. Klepnutím na implementace by měl být průběh na objekt Progress<T> synchronně, což umožňuje asynchronní metodě rychle poskytnout průběh a umožnit spotřebiteli postup, jak určit, jak a kde nejlépe zpracovávat informace.TAP implementations should report the progress to the Progress<T> object synchronously, which enables the asynchronous method to quickly provide progress, and allow the consumer of the progress to determine how and where best to handle the information. Například instance průběhu může zvolit zařazování zpětných volání a vyvolat události na zachyceném synchronizačním kontextu.For example, the progress instance could choose to marshal callbacks and raise events on a captured synchronization context.

Implementace > IProgress<TIProgress<T> implementations

.NET Framework 4,5 poskytuje jednu IProgress<T> implementaci: Progress<T>.The .NET Framework 4.5 provides a single IProgress<T> implementation: Progress<T>. Třída Progress<T> je deklarována takto:The Progress<T> class is declared as follows:

public class Progress<T> : IProgress<T>  
{  
    public Progress();  
    public Progress(Action<T> handler);  
    protected virtual void OnReport(T value);  
    public event EventHandler<T> ProgressChanged;  
}  
Public Class Progress(Of T) : Inherits IProgress(Of T)  
    Public Sub New()  
    Public Sub New(handler As Action(Of T))  
    Protected Overridable Sub OnReport(value As T)  
    Public Event ProgressChanged As EventHandler(Of T>  
End Class  

Instance Progress<T> zpřístupňuje událost ProgressChanged, která je vyvolána pokaždé, když asynchronní operace ohlásí aktualizaci průběhu.An instance of Progress<T> exposes a ProgressChanged event, which is raised every time the asynchronous operation reports a progress update. Událost ProgressChanged je vyvolána na objektu SynchronizationContext, který byl zachycen při vytváření instance Progress<T> instance.The ProgressChanged event is raised on the SynchronizationContext object that was captured when the Progress<T> instance was instantiated. Pokud nebyl k dispozici žádný kontext synchronizace, je použit výchozí kontext určený pro fond vláken.If no synchronization context was available, a default context that targets the thread pool is used. Pro tuto událost lze registrovat obslužné rutiny.Handlers may be registered with this event. Jedna obslužná rutina může být také poskytnuta konstruktoru Progress<T> pro usnadnění a chová se stejně jako obslužná rutina události ProgressChanged událost.A single handler may also be provided to the Progress<T> constructor for convenience, and behaves just like an event handler for the ProgressChanged event. Aktualizace průběhu jsou vyvolány asynchronně, aby se předešlo zpoždění asynchronní operace, zatímco se provádějí obslužné rutiny události.Progress updates are raised asynchronously to avoid delaying the asynchronous operation while event handlers are executing. Jiná implementace IProgress<T> by se mohla rozhodnout použít odlišnou sémantiku.Another IProgress<T> implementation could choose to apply different semantics.

Výběr přetížení k poskytnutíChoosing the overloads to provide

Pokud implementace klepnutí používá volitelné CancellationToken a volitelné IProgress<T> parametry, může potenciálně vyžadovat až čtyři přetížení:If a TAP implementation uses both the optional CancellationToken and optional IProgress<T> parameters, it could potentially require up to four overloads:

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  

Mnoho implementací TAP však neposkytuje funkce zrušení ani průběhu, takže vyžadují jedinou metodu:However, many TAP implementations provide neither cancellation or progress capabilities, so they require a single method:

public Task MethodNameAsync(…);  
Public MethodNameAsync(…) As Task  

Pokud implementace TAP podporuje buď zrušení, nebo průběh, ale ne oboje, může poskytnout dvě přetížení:If a TAP implementation supports either cancellation or progress but not both, it may provide two overloads:

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  

Pokud implementace TAP podporuje zrušení i průběh, může poskytnout všechna čtyři přetížení.If a TAP implementation supports both cancellation and progress, it may expose all four overloads. Může však také poskytnout pouze dvě následující:However, it may provide only the following two:

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  

Pro kompenzaci dvou chybějících mezilehlých kombinací můžou vývojáři předat None nebo výchozí CancellationToken pro parametr cancellationToken a null pro parametr progress.To compensate for the two missing intermediate combinations, developers may pass None or a default CancellationToken for the cancellationToken parameter and null for the progress parameter.

Pokud očekáváte, že každé použití metody TAP bude podporovat zrušení nebo průběh, můžete vynechat přetížení, které nepřijímá odpovídající parametr.If you expect every usage of the TAP method to support cancellation or progress, you may omit the overloads that don’t accept the relevant parameter.

Pokud se rozhodnete vystavit více přetížení, aby bylo zrušení nebo průběh volitelné, přetížení, která nepodporují zrušení nebo průběh, by se měla chovat, jako by byla předána None pro zrušení nebo null pro průběh přetížení, který je podporuje.If you decide to expose multiple overloads to make cancellation or progress optional, the overloads that don’t support cancellation or progress should behave as if they passed None for cancellation or null for progress to the overload that does support these.

NázevTitle PopisDescription
Vzory asynchronního programováníAsynchronous Programming Patterns Zavádí tři vzory pro provádění asynchronních operací: synchronní vzor založený na úlohách (TAP), asynchronní programovací model (APM) a asynchronní vzor založený na událostech (EAP).Introduces the three patterns for performing asynchronous operations: the Task-based Asynchronous Pattern (TAP), the Asynchronous Programming Model (APM), and the Event-based Asynchronous Pattern (EAP).
Implementace asynchronního vzoru založeného na úloháchImplementing the Task-based Asynchronous Pattern Popisuje tři způsoby implementace asynchronního vzoru založeného na úlohách (TAP): pomocí kompilátorů jazyka C# a Visual Basic v sadě Visual Studio, ručně nebo kombinací obou metod.Describes how to implement the Task-based Asynchronous Pattern (TAP) in three ways: by using the C# and Visual Basic compilers in Visual Studio, manually, or through a combination of the compiler and manual methods.
Použití asynchronního vzoru založeného na úloháchConsuming the Task-based Asynchronous Pattern Popisuje, jak použít úlohy a zpětná volání k dosažení čekání bez blokování.Describes how you can use tasks and callbacks to achieve waiting without blocking.
Interoperabilita s jinými asynchronními vzory a typyInterop with Other Asynchronous Patterns and Types Popisuje způsob použití asynchronního vzoru založeného na úlohách (TAP) k implementaci asynchronního programovacího modelu (APM) a asynchronního vzoru založeného na událostech (EAP).Describes how to use the Task-based Asynchronous Pattern (TAP) to implement the Asynchronous Programming Model (APM) and Event-based Asynchronous Pattern (EAP).