BackgroundUploader Classe

Définition

public ref class BackgroundUploader sealed

/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class BackgroundUploader final

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BackgroundUploader final

[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class BackgroundUploader

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Networking.BackgroundTransfer.IBackgroundUploaderFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BackgroundUploader

function BackgroundUploader(completionGroup)

Public NotInheritable Class BackgroundUploader

Héritage

Object Platform::Object IInspectable BackgroundUploader

Attributs

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implémente

IBackgroundTransferBase

Configuration requise pour Windows

Exemples

L’exemple suivant montre comment configurer et commencer une opération de chargement de base.

using Windows.Foundation; 
using Windows.Networking.BackgroundTransfer;
using Windows.Storage.Pickers;
using Windows.Storage;

private async void StartUpload_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri uri = new Uri(serverAddressField.Text.Trim());
        FileOpenPicker picker = new FileOpenPicker();
        picker.FileTypeFilter.Add("*");
        StorageFile file = await picker.PickSingleFileAsync();

        BackgroundUploader uploader = new BackgroundUploader();
        uploader.SetRequestHeader("Filename", file.Name);

        UploadOperation upload = uploader.CreateUpload(uri, file);

        // Attach progress and completion handlers.
        HandleUploadAsync(upload, true);
    }
    catch (Exception ex)
    {
        LogException("Upload Error", ex);
    }
}

Remarques

Après l’arrêt de l’application, une application doit énumérer toutes les instances UploadOperation existantes au prochain démarrage à l’aide de GetCurrentUploadsAsync. Lorsqu’une application UWP utilisant le transfert en arrière-plan est arrêtée, les téléchargements incomplets persistent en arrière-plan. Si l’application est redémarrée après l’arrêt et que les opérations de la session précédente ne sont pas énumérées et re-attachées à la session actuelle, elles restent incomplètes et continuent d’occuper les ressources. Une fois énumérées, les opérations de chargement PUT sont automatiquement redémarrées et les opérations de chargement POST sont terminées.

Lorsque vous implémentez une bibliothèque pour les opérations de transfert en arrière-plan, et que cette même bibliothèque est utilisée par d’autres applications ou composants, spécifiez une chaîne de nom degroupe unique (par exemple, un GUID) lors de la création de chargements. Un chargement avec une chaîne de nom de groupe ne peut être énuméré qu’en fournissant la chaîne correspondante à GetCurrentDownloadsAsync(String), et n’apparaîtra pas dans les appels GetCurrentDownloadsAsync sans. Cela garantit que les autres applications qui implémentent cette même bibliothèque pour les chargements ne verront pas vos chargements

Les opérations de chargement via FTP ne sont pas prises en charge.

Des problèmes de sécurité peuvent exister lorsque les opérations de chargement nécessitent un nom d’utilisateur et un mot de passe pour l’authentification. Si le modèle d’authentification à utiliser est pris en charge par WinINet, utilisez les propriétés ServerCredential ou ProxyCredential . Ces valeurs seront enregistrées en toute sécurité dans WinVault. Pour plus d’informations sur les méthodes d’authentification prises en charge, consultez Gestion de l’authentification.

Si le modèle d’authentification n’est pas pris en charge par WinINet, utilisez HttpClient pour implémenter l’authentification personnalisée et obtenir un jeton sécurisé (cookie) spécifique au chargement. Définissez l’en-tête approprié pour que la valeur du jeton sécurisé soit utilisée pour le transfert en arrière-plan. Le service doit limiter la validité du jeton sécurisé uniquement au fichier en cours de chargement.

Les services de chargement qui nécessitent que le nom d’utilisateur et le mot de passe soient définis en texte clair dans un en-tête personnalisé pour chaque fichier de chargement ne sont pas sécurisés. Le transfert en arrière-plan met en cache les en-têtes en texte clair pendant la durée de l’opération dans le dossier de l’application.

Notifications toast

La classe BackgroundUploader dans Windows 8.1 et Windows Server 2012 R2 prend en charge les options permettant à l’utilisateur de recevoir des notifications de vignette et de toast lorsqu’un transfert est terminé ou échoue.

Une application qui utilise Windows.Networking.BackgroundTransfer pour communiquer via une notification toast doit déclarer qu’elle est compatible Toast dans le fichier manifeste de l’application. Le paramètre compatible Toast se trouve sous la section Notifications de l’onglet Application . Définissez l’option compatible Toast sur « Oui » afin que l’application puisse recevoir des notifications toast.

Si la prise en charge toast n’est pas activée dans le manifeste de l’application, tous les paramètres toast de l’espace de noms Windows.Networking.BackgroundTransfer seront ignorés en mode silencieux et aucune notification toast ne sera reçue par l’application.

Pour plus d’informations sur les notifications toast, consultez Envoi de notifications toast et Comment accepter des notifications toast.

Gestion des exceptions

Un certain nombre d’erreurs peuvent provoquer des exceptions lors d’une opération de chargement. Vous devez écrire du code pour gérer les exceptions lorsque vous appelez des méthodes sur cette classe. Les exceptions peuvent résulter d’erreurs de validation de paramètres, d’échecs de résolution de noms et d’erreurs réseau. Des exceptions aux erreurs réseau (perte de connectivité, échecs de connexion et autres erreurs HTTP, par exemple) peuvent se produire à tout moment. Ces erreurs donnent lieu à la levée d’exceptions. Si elle n’est pas gérée par votre application, une exception peut entraîner l’arrêt de l’ensemble de votre application par le runtime.

Une application peut utiliser hresult de l’exception pour déterminer l’erreur qui a provoqué l’exception. Une application peut ensuite décider comment gérer l’exception en fonction du code d’erreur. La méthode BackgroundTransferError.GetStatus peut convertir la plupart des valeurs HRESULT retournées en valeur d’énumération WebErrorStatus . La plupart des valeurs d’énumération WebErrorStatus correspondent à une erreur retournée par l’opération cliente HTTP ou FTP native. Une application peut filtrer sur des valeurs d’énumération WebErrorStatus spécifiques pour modifier son comportement en fonction de la cause de l’exception.

Certaines valeurs HRESULT ne peuvent pas être converties en valeur d’énumération WebErrorStatus . Lorsqu’une opération POST en arrière-plan est annulée, une exception est levée. L’opération n’est pas redémarrée. Pour plus d’informations, consultez UploadOperation.StartAsync

Pour plus d’informations sur les exceptions réseau, consultez Gestion des exceptions dans les applications réseau.

Conseils de débogage

L’arrêt d’une session de débogage dans Microsoft Visual Studio est comparable à la fermeture de votre application ; les chargements PUT sont mis en pause et les chargements POST sont arrêtés. Même pendant le débogage, votre application doit énumérer, puis redémarrer ou annuler les chargements persistants. Par exemple, votre application peut annuler l’énumération des opérations de chargement persistantes, au démarrage, si les opérations précédentes n’ont pas d’intérêt pour cette session de débogage.

Vous pouvez faire en sorte que votre application annule l’énumération des opérations de téléchargement/chargement au démarrage durant une session de débogage, si les opérations précédentes n’ont pas d’intérêt pour cette session de débogage. Notez que s’il existe des mises à jour de projet Microsoft Visual Studio, telles que des modifications apportées au manifeste de l’application, et que l’application est désinstallée et redéployée, GetCurrentUploadsAsync ne peut pas énumérer les opérations créées à l’aide du déploiement d’application précédent.

Pour plus d’informations, consultez Débogage et test d’applications UWP .

Quand vous utilisez le transfert en arrière-plan durant le développement, il arrive que les caches internes des opérations de transfert actives et terminées se désynchronisent. Cela peut entraîner l’incapacité à démarrer de nouvelles opérations de transfert ou à interagir avec les opérations et les objets BackgroundTransferGroup existants. Dans certains cas, toute tentative d’interaction avec des opérations existantes peut déclencher un blocage. Cela peut se produire si la propriété TransferBehavior a la valeur Parallel. Ce problème ne se produit que dans certains scénarios de développement et n’est pas applicable à l’utilisateur final de votre application.

Quatre scénarios d’utilisation de Microsoft Visual Studio peuvent provoquer ce problème.

• Vous créez un projet avec le même nom d’application qu’un projet existant, mais dans un autre langage (en passant du C++ au C#, par exemple).
• Vous modifiez l’architecture cible (en passant de l’architecture x86 à x64, par exemple) dans un projet existant.
• Vous modifiez la culture (en passant de la culture neutre à fr-FR, par exemple) dans un projet existant.
• Vous ajoutez ou supprimez une fonctionnalité du manifeste du package (en ajoutant l’authentification en entreprise, par exemple) dans un projet existant. La maintenance régulière de l’application, notamment les mises à jour du manifeste qui entraînent l’ajout ou la suppression de fonctionnalités, ne déclenche pas ce problème pour les déploiements de votre application destinés à l’utilisateur final.

Pour contourner ce problème, désinstallez complètement toutes les versions de l’application, puis redéployez-la en utilisant le nouveau langage, la nouvelle architecture, la nouvelle culture ou la nouvelle fonctionnalité. Cela peut être effectué via l’écran d’accueil ou à l’aide de PowerShell et de l’applet de Remove-AppxPackage commande.

Constructeurs

Propriétés

Méthodes

S’applique à

Voir aussi

• UploadOperation
• Gestion des exceptions dans les applications réseau
• Comment opter pour les notifications toast
• Démarrage rapide : Charger un fichier
• Exemple de transfert en arrière-plan
• Exemple de transfert en arrière-plan (Windows 8.x)