Compartilhar via


IAsyncOperationWithProgress<TResult,TProgress> Interface

Definição

Representa uma operação assíncrona que pode relatar atualizações de progresso para os chamadores. Esse é o tipo de retorno para muitos Windows Runtime métodos assíncronos que têm resultados e também relatam o progresso.

public interface class IAsyncOperationWithProgress : IAsyncInfo
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
template <typename TResult, typename TProgress>
struct IAsyncOperationWithProgress : IAsyncInfo
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
public interface IAsyncOperationWithProgress<TResult,TProgress> : IAsyncInfo
Public Interface IAsyncOperationWithProgress(Of TResult, TProgress)
Implements IAsyncInfo

Parâmetros de tipo

TResult
TProgress
Derivado
Atributos
Implementações

Requisitos do Windows

Família de dispositivos
Windows 10 (introduzida na 10.0.10240.0)
API contract
Windows.Foundation.FoundationContract (introduzida na v1.0)

Comentários

IAsyncOperationWithProgress<TResult,TProgress> é o tipo de retorno para muitos métodos assíncronos Windows Runtime que têm um resultado após a conclusão e também dão suporte a notificações que relatam o progresso (aos quais os chamadores podem assinar atribuindo um retorno de chamada para Progresso). Isso constitui cerca de 100 APIs de Windows Runtime diferentes. AS APIs que não relatam o progresso (mas têm um resultado) usam outra interface, IAsyncOperation<TResult>.

Quando você usa métodos que retornam IAsyncOperationWithProgress<TResult,TProgress> (com uma restrição específica de TResult ) no código do aplicativo, você geralmente não acessa o valor retornado de IAsyncOperationWithProgress diretamente. Isso ocorre porque você quase sempre usa a sintaxe awaitable específica da linguagem. Nesse caso, o valor retornado aparente do método é o tipo fornecido como o parâmetro TResult . Para obter mais informações, consulte Programação assíncrona ou um dos guias específicos da linguagem para Windows Runtime programação assíncrona (chamar APIs assíncronas em C# ou Visual Basic, C++, JavaScript).

Não é comum usar IAsyncOperationWithProgress<TResult,TProgress> diretamente, mesmo que você não use uma sintaxe aguardável específica da linguagem. Cada um dos idiomas tem pontos de extensão que geralmente são mais fáceis de usar do que a interface Windows Runtime. O JavaScript tem WinJS.Promise e a sintaxe then/done . O .NET tem o método de extensão AsTask e, depois que iAsyncOperationWithProgress<TResult,TProgress> é convertido em um TResult> de Tarefa<, é mais fácil obter o resultado, cancelar, receber notificação sobre a conclusão e assim por diante. Para C++/CX, você pode encapsular as chamadas usando o runtime de simultaneidade (e usar create_task). Em outras palavras, IAsyncOperationWithProgress<TResult,TProgress> pode ser considerada infraestrutura de nível de runtime, que cada uma das linguagens usa como uma estrutura para dar suporte a modelos de programação assíncrona ou sintaxe aguardada.

Especificamente, se você quiser lidar com o progresso no código .NET, use a assinatura AsTask que em um uso de extensão tem um único parâmetro de referência IProgress . (Nesse uso, a unidade de progresso já está restrita e corresponde ao método IAsyncOperationWithProgress que você está usando.) Forneça um objeto que implemente o IProgress e a implementação do método Report seja invocada sempre que o método Windows Runtime relatar uma notificação de progresso.

Para monitorar o progresso da ação (se não estiver usando as técnicas específicas do idioma descritas acima), defina a propriedade Progress , fornecendo-lhe o nome de um método que implementa o delegado AsyncOperationProgressHandler<TResult,TProgress> .

Funções de extensão C++/WinRT

Observação

Existem funções de extensão nos tipos de projeção C++/WinRT para determinadas APIs de Windows Runtime. Por exemplo, winrt::Windows::Foundation::IAsyncAction é o tipo de projeção C++/WinRT para IAsyncAction. As funções de extensão não fazem parte da superfície da ABI (interface binária do aplicativo) dos tipos de Windows Runtime reais, portanto, elas não são listadas como membros das APIs de Windows Runtime. Mas você pode chamá-los de dentro de qualquer projeto C++/WinRT. Consulte Funções C++/WinRT que estendem apIs de Windows Runtime.

TResult get() const;

Aguarda de forma síncrona a conclusão da operação e retorna o valor concluído. Gera uma exceção correspondente se a operação é cancelada ou insere um estado de erro. Você não deve chamá-lo de um apartamento de thread único. Para obter mais informações e exemplos de código mostrando como chamar get, consulte Gravar uma corrotina.

AsyncStatus wait_for(TimeSpan const& timeout) const;

Aguarda de forma síncrona a conclusão da operação ou o tempo limite especificado. Retorna o estado de IAsyncOperationWithProgress ou AsyncStatus::Started se o tempo limite tiver decorrido. Se a ação não atingiu o tempo limite, chame GetResults para obter os resultados da operação. Para obter mais informações e exemplos de código mostrando como chamar wait_for, consulte Tempos limite assíncronos facilitado.

Herança de interface

IAsyncOperationWithProgress<TResult,TProgress> herda IAsyncInfo. Os tipos que implementam IAsyncOperationWithProgress<TResult,TProgress> também implementam os membros da interface de IAsyncInfo:

Anotações aos implementadores

Assim como ao chamar os métodos existentes, há maneiras específicas de definir métodos assíncronos que não usam IAsyncOperationWithProgress<TResult,TProgress> diretamente. Se estiver escrevendo código usando .NET, seu método poderá retornar um TResult> de Tarefa<. Para C++/CX, você pode usar o runtime de simultaneidade. No entanto, se você estiver definindo um componente, poderá usar atarefaTarefa/ internamente, mas deverá retornar uma das interfaces Windows Runtime para seus métodos públicos. Os tipos de suporte assíncronos específicos da linguagem (e muitos outros tipos específicos de linguagem que você pode usar convencionalmente no código) não podem ser usados para a área de superfície pública de um componente Windows Runtime.

Propriedades

Completed

Obtém ou define o delegado que é chamado quando a operação é concluída.

ErrorCode

Obtém uma cadeia de caracteres que descreve uma condição de erro da operação assíncrona.

(Herdado de IAsyncInfo)
Id

Obtém o identificador da operação assíncrona.

(Herdado de IAsyncInfo)
Progress

Obtém ou define o método que manipula as notificações de progresso.

Status

Obtém um valor que indica o status da operação assíncrona.

(Herdado de IAsyncInfo)

Métodos

Cancel()

Cancela a operação assíncrona.

(Herdado de IAsyncInfo)
Close()

Fecha a operação assíncrona.

(Herdado de IAsyncInfo)
GetResults()

Retorna os resultados da operação.

Aplica-se a

Confira também