IAsyncActionWithProgress<TProgress> Interface

Definição

Namespace:

Windows.Foundation

Representa uma ação assíncrona que pode relatar atualizações de progresso aos chamadores. Esse é o tipo de retorno para todos os Windows Runtime métodos assíncronos que não têm um objeto de resultado, mas relatam o progresso para ouvintes de retorno de chamada.

public interface class IAsyncActionWithProgress : IAsyncInfo

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(527282776, 59395, 18593, 149, 70, 235, 115, 83, 57, 136, 132)]
template <typename TProgress>
struct IAsyncActionWithProgress : IAsyncInfo

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(527282776, 59395, 18593, 149, 70, 235, 115, 83, 57, 136, 132)]
public interface IAsyncActionWithProgress<TProgress> : IAsyncInfo

Public Interface IAsyncActionWithProgress(Of TProgress)
Implements IAsyncInfo

Parâmetros de tipo

TProgress

Atributos

ContractVersionAttribute GuidAttribute

Implementações

IAsyncInfo

Requisitos do Windows

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

Exemplos

Por exemplo, código C++/WinRT que ilustra como manipular o evento Progress , consulte Tipos de delegado para ações e operações assíncronas.

Comentários

IAsyncActionWithProgress<TProgress> é o tipo de retorno para todos os métodos assíncronos Windows Runtime que não comunicam um objeto de resultado, mas permitem que um aplicativo marcar o progresso da ação. Não há quase tantos desses como há métodos que usam IAsyncAction. IAsyncAction As APIs não relatam o progresso e não têm um resultado.

Quando você usa métodos que retornam IAsyncActionWithProgress<TProgress> no código do aplicativo, você geralmente não acessa o valor retornado de IAsyncAction diretamente. Isso ocorre porque você quase sempre usa a sintaxe aguardável específica do idioma. Nesse caso, o valor retornado aparente do método é void. 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 IAsyncActionWithProgress<TProgress> diretamente, mesmo que você não use uma sintaxe aguardável específica do idioma. Cada uma das linguagens 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 with onProgress . O .NET tem os métodos de extensão AsTask e, depois que o TProgress IAsyncActionWithProgress<> é convertido em uma Tarefa, é mais fácil cancelar, receber notificação após a conclusão, usar IProgress<T> e assim por diante. Para C++/CX, você pode encapsular as chamadas usando o runtime de simultaneidade (e usar create_task). Em outras palavras, IAsyncActionWithProgress<TProgress> pode ser considerada infraestrutura de nível de runtime, que cada uma das linguagens usa como uma estrutura para dar suporte a sintaxe aguardável ou modelos de programação assíncrona à sua maneira.

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 IAsyncActionWithProgress que você está usando.) Forneça um objeto que implementa IProgress e a implementação do método Report é invocada sempre que o método Windows Runtime relata uma notificação de progresso.

Para monitorar o progresso da ação (se não estiver usando as técnicas específicas de linguagem descritas acima), defina a propriedade Progress , fornecendo-lhe o nome de um método que implementa o delegado AsyncActionProgressHandler<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 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, não são listadas como membros das APIs Windows Runtime. Mas você pode chamá-los de dentro de qualquer projeto C++/WinRT. Confira Funções do C++/WinRT que estendem apIs de Windows Runtime.

void get() const;

Aguarda de forma síncrona a conclusão da ação. Gera uma exceção correspondente se a ação for cancelada ou entra em 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 Escrever uma corrotina.

AsyncStatus wait_for(TimeSpan const& timeout) const;

Aguarda de forma síncrona a conclusão da ação ou o tempo limite especificado. Retorna o estado de IAsyncActionWithProgress 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 açã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

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

• Método Cancel
• Método Close
• Propriedade ErrorCode
• Propriedade Id
• Propriedade Status

Observações aos implementadores

Assim como acontece com a chamada dos métodos existentes, há maneiras específicas de definir métodos assíncronos que não usam IAsyncActionWithProgress<TProgress> diretamente. Se estiver escrevendo código usando o .NET, seu método poderá retornar uma Tarefa. Para C++/CX, você pode usar o runtime de Simultaneidade. No entanto, se você estiver definindo um componente, poderá usar atarefaTask/ internamente, mas deverá retornar uma das interfaces Windows Runtime para seus métodos públicos. Os tipos de suporte assíncrono 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 açã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 de retorno de chamada que recebe a notificação 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 ação.

Confira também

• IAsyncInfo
• IAsyncAction