Parlare con dispositivi USB, iniziare a terminare (app UWP)

  • Articolo

Questo articolo fornisce una procedura dettagliata end-to-end per la creazione di un'app UWP che parla con un dispositivo USB.

Usare le API Windows Runtime per scrivere app UWP che consentono agli utenti di accedere al dispositivo USB periferico. Tali app possono connettersi a un dispositivo in base ai criteri specificati dall'utente, ottenere informazioni sul dispositivo, inviare dati al dispositivo e al contrario ottenere flussi di dati dal dispositivo e eseguire il polling dei dati per i dati di interruzione.

In questo articolo viene descritto come l'app UWP può implementare tali attività e collegarsi ad esempi che illustrano l'uso di classi incluse in Windows.Devices.Usb. Verranno descritte le funzionalità del dispositivo necessarie nel manifesto dell'app e come avviare l'app quando il dispositivo si connette. Verrà inoltre illustrato come eseguire un'attività di trasferimento dati in background anche quando l'app sospende per conservare la durata della batteria.

Procedura dettagliata: scrittura di un'app UWP per i dispositivi USB

Seguire i passaggi descritti in questo articolo o passare direttamente all'esempio di accesso al dispositivo USB personalizzato. L'esempio complementare implementa tutti i passaggi qui, ma per mantenere le operazioni in movimento, non viene illustrato il codice. Alcuni passaggi hanno una sezione Trova nell'esempio per trovare rapidamente il codice. La struttura dei file di origine dell'esempio è semplice e flat in modo da poter trovare facilmente il codice senza dover eseguire il drill-down di più livelli di file di origine. Tuttavia, è consigliabile suddividere e organizzare il proprio progetto in modo diverso.

Installare il driver Microsoft WinUSB

Installare il driver WinUSB fornito da Microsoft come driver di funzione per il dispositivo.

Guida introduttiva:Installazione di WinUSB (Winusb.sys)

È possibile installare Winusb.sys in questi modi:

  • Quando si connette il dispositivo, si potrebbe notare che Windows carica automaticamente Winusb.sys perché il dispositivo è un dispositivo WinUSB.
  • Installare il driver specificando la classe di dispositivo fornita dal sistema in Gestione dispositivi.
  • Installare il driver usando un INF personalizzato. È possibile ottenere INF in uno dei due modi seguenti:
    • Ottenere l'INF dal fornitore dell'hardware.
    • Scrivere un inF personalizzato che fa riferimento al file Winusb.inf fornito da Microsoft. Per altre informazioni, vedere Installazione di WinUSB (Winusb.sys).

Ottenere informazioni sul dispositivo

Ottenere il GUID dell'interfaccia del dispositivo, l'ID hardware e le informazioni sulla classe del dispositivo.

È possibile ottenere queste informazioni dal produttore del dispositivo.

  • Identificatori fornitore e prodotto

    In Gestione dispositivi visualizzare le proprietà del dispositivo. Nella scheda Dettagli visualizzare il valore della proprietà Id hardware . Questo valore è una combinazione di questi due identificatori. Ad esempio, per il dispositivo SuperMUTT, l'ID hardware è "USB\VID_045E&PID_F001"; l'ID fornitore è "0x045E" e l'ID prodotto è "0xF001".

  • Classe del dispositivo, sottoclasse e codici di protocollo

  • GUID dell'interfaccia del dispositivo

In alternativa, è possibile visualizzare le informazioni del Registro di sistema. Per altre informazioni, vedere Voci del Registro di sistema dei dispositivi USB.

Determinare se il set di API USB consente la classe del dispositivo, la sottoclasse e il protocollo

È possibile scrivere un'app UWP, se la classe del dispositivo, la sottoclasse e il codice del protocollo del dispositivo si trova nell'elenco seguente:

  • name:cdcControl, classId:02 * *
  • name:physical, classId:05 * *
  • name:personalHealthcare, classId:0f 00 00
  • name:activeSync, classId:ef 01 01
  • name:palmSync, classId:ef 01 02
  • name:deviceFirmwareUpdate, classId:fe 01 01
  • name:irda, classId:fe 02 00
  • name:measurement, classId:fe 03 *
  • name:vendorSpecific, classId:ff * *

Creare un progetto di Visual Studio di base

Creare un progetto di Visual Studio di base che è possibile estendere in questa esercitazione.

Per altre informazioni, vedere Introduzione alle app UWP.

Aggiungere funzionalità del dispositivo USB al manifesto dell'app

Informazioni su come aggiungere funzionalità del dispositivo USB al manifesto dell'app.

Guida introduttiva:Come aggiungere funzionalità del dispositivo USB al manifesto dell'app

Aprire il file Package.appxmanifest in un editor di testo e aggiungere l'elemento DeviceCapability con attributo Name impostato su "usb" come illustrato in questo esempio.

Nota

Non è possibile modificare la funzionalità del dispositivo USB in Visual Studio. È necessario fare clic con il pulsante destro del mouse sul file Package.appxmanifest in Esplora soluzioni e scegliere Apri con..., quindi editor XML (Testo). Il file viene aperto in formato XML normale.

<Capabilities>
  <!--When the device's classId is FF * *, there is a predefined name for the class.
      You can use the name instead of the class id.
      There are also other predefined names that correspond to a classId.-->
  <m2:DeviceCapability Name="usb">
    <!--SuperMutt Device-->
    <m2:Device Id="vidpid:045E 0611">
      <!--<wb:Function Type="classId:ff * *"/>-->
      <m2:Function Type="name:vendorSpecific"/>
    </m2:Device>
  </m2:DeviceCapability>
</Capabilities>

Trovarlo nell'esempio: Le funzionalità del dispositivo USB si trovano nel file Package.appxmanifest.

Aprire il dispositivo per la comunicazione

Estendere l'app per aprire il dispositivo per la comunicazione.

Guida introduttiva:Come connettersi a un dispositivo USB (app UWP)

  1. Trovare il dispositivo creando una stringa AQS (Advanced Query Syntax) che contiene i criteri di ricerca per trovare il dispositivo nella raccolta di dispositivi enumerata.
  2. Aprire il dispositivo in uno dei due modi seguenti:
  3. Ottenere l'istanza del dispositivo dalla proprietà DeviceInformation.Id .
  4. Chiamare FromIdAsync passando la stringa dell'istanza del dispositivo e recuperando l'oggetto UsbDevice .

Trovarlo nell'esempio: Vedere i file denominati Scenario1_DeviceConnect.

Studiare il layout del dispositivo USB

Studiare il layout del dispositivo USB.

Esaminare i concetti di base di USB sulla configurazione del dispositivo e sull'esecuzione dei trasferimenti di dati: Concetti per tutti gli sviluppatori USB.

Visualizzare il descrittore di configurazione del dispositivo, i descrittori dell'interfaccia per ogni impostazione alternativa supportata e i descrittori dell'endpoint. Usando USBView, è possibile esplorare tutti i controller USB e i dispositivi USB connessi a essi e controllare anche la configurazione del dispositivo.

Ottenere e visualizzare i descrittori USB nell'interfaccia utente

Estendere l'app per ottenere e visualizzare i descrittori USB nell'interfaccia utente.

Avvio rapido:Come ottenere descrittori USB (app UWP)

Trovarlo nell'esempio: Vedere i file denominati Scenario5_UsbDescriptors.

Inviare trasferimenti di controllo USB definiti dal fornitore

Estendere l'app per inviare trasferimenti di controllo USB definiti dal fornitore.

Guida introduttiva:Come inviare una richiesta di trasferimento del controllo USB (app UWP)

  1. Ottenere il comando fornitore dalla specifica hardware del dispositivo.
  2. Creare un oggetto UsbSetupPacket e popolare il pacchetto di installazione impostando varie proprietà.
  3. Avviare un'operazione asincrona per inviare il trasferimento del controllo da questi metodi a seconda della direzione del trasferimento:

Trovarlo nell'esempio: Vedere i file denominati Scenario2_ControlTransfer.

Leggere o scrivere dati bulk

Estendere l'app per leggere o scrivere dati bulk.

Guida introduttiva:Come inviare una richiesta di trasferimento bulk USB (app UWP)

  1. Ottenere l'oggetto pipe bulk (UsbBulkOutPipe o UsbBulkInPipe).
  2. Configurare la pipe bulk per impostare i parametri dei criteri.
  3. Configurare il flusso di dati usando l'oggetto DataReader o DataWriter .
  4. Avviare un'operazione di trasferimento asincrona chiamando DataReader.LoadAsync o DataWriter.StoreAsync.
  5. Ottenere i risultati dell'operazione di trasferimento.

Trovarlo nell'esempio: Vedere i file denominati Scenario4_BulkPipes.

Ottenere i dati di interruzione hardware

Estendere l'app per ottenere i dati di interruzione hardware.

Guida introduttiva:Come inviare una richiesta di trasferimento di interruzioni USB (app UWP)

  1. Ottenere l'oggetto pipe di interruzione (UsbInterruptInPipe o UsbInterruptOutPipe).
  2. Implementare il gestore di interruzioni per l'evento DataReceived .
  3. Registrare il gestore eventi per avviare la ricezione dei dati.
  4. Annullare la registrazione del gestore eventi per interrompere la ricezione dei dati.

Trovarlo nell'esempio: Vedere i file denominati Scenario3_InterruptPipes.

Selezionare un'impostazione dell'interfaccia che non è attualmente attiva

Estendere l'app per selezionare un'impostazione dell'interfaccia che non è attualmente attiva.

Guida introduttiva:Come selezionare un'impostazione dell'interfaccia USB (app UWP)

Quando il dispositivo viene aperto per la comunicazione, viene selezionata l'interfaccia predefinita e la relativa prima impostazione. Se si vuole modificare questa impostazione, seguire questa procedura:

  1. Ottenere l'impostazione attiva di un'interfaccia USB usando il valore UsbInterfaceSetting.Selected .
  2. Impostare un'impostazione dell'interfaccia USB avviando un'operazione asincrona chiamando UsbInterfaceSetting.SelectSettingAsync.

Chiudere il dispositivo

Estendere l'app per chiudere il dispositivo.

Guida introduttiva:Come connettersi a un dispositivo USB (app UWP)

Al termine dell'uso dell'oggetto UsbDevice, chiudere il dispositivo.

Le app C++ devono rilasciare il riferimento usando la parola chiave delete . Le app C#/VB devono chiamare il metodo UsbDevice.Dispose . Le app JavaScript devono chiamare UsbDevice.Close.

Trovarlo nell'esempio: Vedere i file denominati Scenario1_DeviceConnect.

Creare un pacchetto di metadati del dispositivo

Creare un pacchetto di metadati del dispositivo per l'app.

Tool:Creazione guidata metadati dispositivo

  • Se è installato Windows Driver Kit (WDK), aprire Creazionemetadati> del dispositivo driver>.
  • Se è installato l'SDK autonomo, lo strumento si trova in <install_path>\bin\x86\DeviceMetadataWizardexe.

Associare l'app al dispositivo seguendo la procedura descritta nella procedura guidata. Immettere queste informazioni sul dispositivo:

  • Nella pagina Informazioni dispositivo immettere Nome modello, Produttore e Descrizione.
  • Nella pagina Informazioni hardware immettere l'ID hardware del dispositivo.

Per dichiarare l'app come app con privilegi per il dispositivo, seguire queste istruzioni:

  1. Nella pagina Informazioni app immettere il nome del pacchetto, il nome del server di pubblicazione e l'ID app UWP nel gruppo di applicazioni Con privilegi.

    Screenshot di Visual Studio, che mostra metatdata del dispositivo per le app con privilegi.

    Nota

    Non controllare l'opzione Access custom driver .Do not check the Access custom driver option.

  2. Aprire la scheda Fine . Selezionare la casella di controllo Copia pacchetti nell'archivio metadati locale del sistema .

  3. Connettere il dispositivo, in Pannello di controllo, aprire Visualizza dispositivi e stampanti e verificare che l'icona del dispositivo sia corretta.

Trovarlo nell'esempio: Vedere la cartella DeviceMetadata.

Implementare l'attivazione di AutoPlay

Estendere l'app implementando l'attivazione autoPlay per avviare l'app quando il dispositivo si connette al sistema.

Avvio rapido:Registrare un'app per un dispositivo AutoPlay

È possibile aggiungere funzionalità autoplay in modo che l'app venga avviata quando il dispositivo si connette al sistema. È possibile abilitare La riproduzione automatica per tutte le app UWP (con privilegi o in caso contrario).

  1. Nel pacchetto di metadati del dispositivo è necessario specificare come il dispositivo deve rispondere a una notifica autoPlay. Nella scheda Windows Info selezionare l'opzione dell'app per dispositivi UWP e immettere le informazioni sull'app, come illustrato di seguito:

  2. Nel manifesto dell'app aggiungere la dichiarazione del dispositivo AutoPlay e avviare le informazioni, come illustrato di seguito:

    Screenshot che mostra il manifesto dell'app con 'Dichiarazioni' selezionato e 'AutoPlay Device' aggiunto.

  3. Nel metodo OnActivated della classe App verificare se il dispositivo ha attivato l'app. In caso affermativo, il metodo riceve un valore di parametro DeviceEventArgs contenente il valore della proprietà DeviceInformation.Id . Questo è lo stesso valore descritto in Apri il dispositivo per la comunicazione.

Trovarlo nell'esempio: Vedere i file denominati Riproduzione automatica. Per JavaScript, vedere default.js.

Implementare un'attività in background

Estendere l'app per implementare un'attività in background che può eseguire trasferimenti di lunghezza nel dispositivo, ad esempio l'aggiornamento del firmware senza che l'app venga sospesa.

Per implementare l'attività in background, sono necessarie due classi.

La classe di attività in background implementa l'interfaccia IBackgroundTask e contiene il codice effettivo creato per sincronizzare o aggiornare il dispositivo periferico. La classe di attività in background viene eseguita quando l'attività in background viene attivata e dal punto di ingresso fornito nel manifesto dell'applicazione dell'app.

Nota

Infrastruttura delle attività in background del dispositivo fornita da Windows 8.1. Per altre informazioni sulle attività in background di Windows, vedere Supporto dell'app con attività in background.

Classe attività in background

  1. Implementa l'interfaccia IBackgroundTask richiesta dall'infrastruttura attività in background di Windows.
  2. Ottiene l'istanza deviceUseDetails passata alla classe nel metodo Run e usa questa istanza per segnalare lo stato di avanzamento all'app di Microsoft Store e per registrare gli eventi di annullamento.
  3. Il metodo Run chiama anche i metodi OpenDevice privati e WriteToDeviceAsync che implementano il codice di sincronizzazione del dispositivo in background.

L'app UWP registra e attiva un'attività in background DeviceUseTrigger. Registrazione dell'app, trigger e gestione dello stato di avanzamento in un'attività in background.

Nota

Il codice di esempio che segue può essere applicato all'attività in background DeviceServicingTrigger usando gli oggetti corrispondenti. L'unica differenza tra i due oggetti trigger e le relative API corrispondenti sono i controlli dei criteri effettuati da Windows.

  1. Crea oggetti DeviceUseTrigger e BackgroundTaskRegistration.
  2. Verifica se le attività in background sono state registrate in precedenza da questa applicazione di esempio e le annulla chiamando il metodo Unregister nell'attività.
  3. Registra l'attività in background sincronizzata con il dispositivo. Il metodo SetupBackgroundTask viene chiamato dal metodo SyncWithDeviceAsync nel passaggio successivo.
    1. Inizializza DeviceUseTrigger e lo salva per un uso successivo.
    2. Crea un oggetto BackgroundTaskBuilder e usa le relative proprietà Name, TaskEntryPoint e SetTrigger per registrare l'oggetto DeviceUseTrigger dell'app e il nome dell'attività in background. La proprietà TaskEntryPoint dell'oggetto BackgroundTaskBuilder è impostata sul nome completo della classe di attività in background che verrà eseguita quando viene attivata l'attività in background.
    3. Registra gli eventi di completamento e avanzamento dall'attività in background in modo che l'app di Microsoft Store possa fornire aggiornamenti di completamento e avanzamento all'utente.
  4. Il metodo SyncWithDeviceAsync privato registra l'attività in background che si sincronizza con il dispositivo e avvia la sincronizzazione in background.

    1. Chiama il metodo SetupBackgroundTask dal passaggio precedente e registra l'attività in background che verrà sincronizzata con il dispositivo.

    2. Chiama il metodo StartSyncBackgroundTaskAsync privato che avvia l'attività in background.

    3. Chiude l'handle dell'app al dispositivo per assicurarsi che l'attività in background sia in grado di aprire il dispositivo all'avvio.

      Nota

      L'attività in background dovrà aprire il dispositivo per eseguire l'aggiornamento in modo che l'app di Microsoft Store debba chiudere le connessioni al dispositivo prima di chiamare RequestAsync

    4. Chiama il metodo RequestAsync dell'oggetto DeviceUseTrigger che avvia l'attività in background e restituisce l'oggetto DeviceTriggerResults da RequestAsync usato per determinare se l'attività in background è stata avviata correttamente.

      Nota

      Windows verifica che siano stati completati tutti i controlli necessari dei criteri di avvio delle attività. Se tutti i controlli dei criteri vengono completati, l'operazione di aggiornamento viene ora eseguita come attività in background all'esterno dell'app di Microsoft Store, consentendo all'app di essere sospesa in modo sicuro mentre l'operazione è in corso. Windows applica anche eventuali requisiti di runtime e annulla l'attività in background se tali requisiti non vengono più soddisfatti.

    5. Usa l'oggetto DeviceTriggerResults restituito da StartSyncBackgroundTaskAsync per determinare se l'attività in background è stata avviata correttamente. Un'istruzione switch viene usata per controllare il risultato da DeviceTriggerResults.

  5. Implementa un gestore eventi OnSyncWithDeviceProgress privato che aggiornerà l'interfaccia utente dell'app con lo stato di avanzamento dall'attività in background.
  6. Implementa un gestore eventi OnSyncWithDeviceCompleted privato per gestire la transizione dalle attività in background all'app in primo piano al termine dell'attività in background.
    1. Usa il metodo CheckResults dell'oggetto BackgroundTaskCompletedEventArgs per determinare se eventuali eccezioni sono state generate dall'attività in background.
    2. L'app riaprirà il dispositivo da usare dall'app in primo piano ora che l'attività in background è stata completata e aggiorna l'interfaccia utente per notificare all'utente.
  7. Implementa i gestori eventi privati dall'interfaccia utente per avviare e annullare l'attività in background.
    1. Il gestore eventi privato Sync_Click chiama il metodo SyncWithDeviceAsync descritto nei passaggi precedenti.
    2. Il gestore eventi privato CancelSync_Click chiama il metodo CancelSyncWithDevice privato per annullare l'attività in background.
  8. Il metodo CancelSyncWithDevice privato annulla la registrazione e annulla le sincronizzazioni attive dei dispositivi in modo che il dispositivo possa essere riaperto usando il metodo Unregister nell'oggetto BackgroundTaskRegistration.

Trovarlo nell'esempio: Vedere i file denominati Scenario7_Sync file. La classe in background viene implementata in IoSyncBackgroundTask.

Eseguire il kit di certificazione delle app di Windows

Eseguire il kit di certificazione dell'app Windows.

Uso di Windows App Certification Kit

Consigliato. L'esecuzione del kit di certificazione delle app di Windows consente di assicurarsi che l'app soddisfi i requisiti di Microsoft Store. È consigliabile eseguirla ogni volta che si aggiungono funzionalità principali all'app.

Interfaccia utente dell'app UWP, iniziare a terminare (XAML)

Altre informazioni sulla progettazione dell'interfaccia utente dell'app UWP.

Roadmap per le app UWP con C# e Visual Basic eRoadmap per le app UWP con C++

Altre informazioni sulla creazione di app UWP con C++, C#o Visual Basic in generale.

Programmazione asincrona (app UWP)

Informazioni su come rendere reattive le tue app quando funzionano che potrebbero richiedere un periodo di tempo esteso.

API importanti