Inviare il manifesto al repository

Articolo
10/05/2023

Dopo aver creato un manifesto del pacchetto che descrive l'applicazione, sei pronto per inviare il manifesto al repository di Gestione pacchetti di Windows. Si tratta di un repository pubblico che contiene una raccolta di manifesti a cui può accedere lo strumento winget. Per inviare il manifesto, dovrai caricarlo nel repository open source GitHub https://github.com/microsoft/winget-pkgs.

Dopo aver inviato una richiesta pull per aggiungere un nuovo manifesto al repository GitHub, un processo automatizzato convaliderà il file manifesto e verificherà che il pacchetto sia conforme ai criteri di Gestione pacchetti di Windows e non sia noto come dannoso. Se la convalida ha esito positivo, il pacchetto verrà aggiunto al repository pubblico di Gestione pacchetti di Windows, in modo che possa essere individuato dallo strumento client winget. Tieni presente la distinzione tra i manifesti nel repository open source GitHub e nel repository pubblico di Gestione pacchetti di Windows.

Importante

Microsoft si riserva il diritto di rifiutare un invio per qualsiasi motivo.

Convalida del manifesto

Quando invii un manifesto al repository GitHub https://github.com/microsoft/winget-pkgs, il manifesto viene automaticamente convalidato e valutato per la sicurezza dell'ecosistema Windows. I manifesti possono anche essere esaminati manualmente.

Per altre informazioni sul processo di convalida, vedere la sezione relativa al processo di convalida di seguito.

Come inviare il manifesto

Per inviare un manifesto al repository, segui questa procedura.

Passaggio 1: Convalidare il manifesto

Lo strumento winget fornisce il comando validate per confermare che il manifesto è stato creato correttamente. Per convalidare il manifesto, usa questo comando.

winget validate \<path-to-the-manifests>

Se la convalida ha esito negativo, usa gli errori per individuare il numero di riga ed eseguire una correzione. Dopo la convalida del manifesto, puoi inviarlo al repository.

Passaggio 2: Testare il manifesto con la Sandbox di Windows

Il repository di Gestione pacchetti di Windows include uno script che installerà Gestione pacchetti di Windows in una Sandbox per testare gli invii di manifesti. Per eseguire lo script di PowerShell, passare al repository winget-pkgs. Da PowerShell, immettere il comando seguente:

powershell .\Tools\SandboxTest.ps1 manifests\m\Microsoft\VisualStudioCode\1.56.0

Potrebbe essere necessario aggiornare questo script con il tracciato corretto del file manifesto: .\Tools\SandboxTest.ps1 <path to manifest or manifest folder>

Vedere lo script di test sandbox completo nel repository winget-pkgs.

Passaggio 3: Clonare il repository

Per creare un fork del repository della community di Gestione pacchetti di Windows e clonare il repository nel computer locale:

Passare a https://github.com/microsoft/winget-pkgs nel browser e selezionare Fork.
Dal prompt dei comandi di Windows o PowerShell, usa il comando seguente per clonare il fork.
```
git clone <your-fork-name>
```
Se si eseguono più invii, creare un ramo anziché un fork. Attualmente è consentito un solo file manifesto per invio.
```
git checkout -b <branch-name>
```

Passaggio 4: Aggiungere il manifesto al repository locale

Occorre aggiungere i file manifesto al repository nella struttura di cartelle seguente:

manifests / letter / publisher / application / version

La cartella manifests è la cartella radice per tutti i manifesti nel repository.
La cartella letter è la prima lettera del nome dell'autore in lettere minuscole. Ad esempio, m dell'autore Microsoft.
La cartella publisher indica il nome della società che pubblica il software, ad esempio Microsoft.
La cartella application indica il nome dell'applicazione o dello strumento, ad esempio VSCode.
La cartella version indica il nome dell'applicazione o dello strumento. Ad esempio, 1.0.0.

I valori PackageIdentifier e PackageVersion nel manifesto devono corrispondere all'autore, ai nomi delle applicazioni e alla versione nel tracciato della cartella del manifesto. Per altre informazioni, vedi Creare il manifesto del pacchetto.

Passaggio 5: Inviare il manifesto al repository remoto

A questo punto, sei pronto per eseguire il push del nuovo manifesto al repository remoto.

Usare il comando commit per aggiungere file ed eseguire il commit della modifica e fornire informazioni sull'invio.
```
git commit -m "Submitting ContosoApp version 1.0.0" --all
```
Usa il comando push per eseguire il push delle modifiche nel repository remoto.
```
git push
```

Passaggio 6: Creare una richiesta pull

Dopo il push delle modifiche, tornare a https://github.com/microsoft/winget-pkgs e creare una richiesta pull per unire il fork o il ramo al ramo principale.

screenshot of pull request tab

Processo di invio

Quando si crea una richiesta pull, viene avviato un processo automatico che convalida i manifesti e verifica la richiesta pull. Durante questo processo verranno eseguiti test sul programma di installazione e sui file binari installati per convalidare l'invio.

Vengono aggiunte etichette alle richieste pull, in modo da tenere traccia dello stato di avanzamento. Per altre informazioni sulle etichette e sul processo, vedere la sezione etichette delle richieste pull di seguito.

Al termine, l'invio verrà esaminato manualmente da un moderatore e, dopo l'approvazione, l'applicazione verrà aggiunta al catalogo di Gestione pacchetti di Windows.

Se si verifica un errore durante il processo, si riceverà una notifica e le etichette e il bot aiuteranno a correggere l'invio. Per l'elenco degli errori comuni, vedere la sezione relativa al processo di convalida seguente.

Processo di convalida

Quando si crea una richiesta pull per inviare il manifesto al repository di Gestione pacchetti Windows, viene avviato un processo automatico che convalida il manifesto ed elabora la richiesta pull. Le etichette di GitHub vengono usate per condividere lo stato di avanzamento e consentire la comunicazione con Microsoft.

Aspettative di invio

Tutti gli invii di applicazioni al repository di Gestione pacchetti di Windows dovrebbero aderire ai criteri del repository di Gestione pacchetti di Windows.

Aspettative relative agli invii:

Il manifesto è conforme ai requisiti dello schema.
Tutti gli URL nel manifesto portano a siti Web sicuri.
Il programma di installazione e l'applicazione sono privi di virus. Il pacchetto può essere identificato come malware per errore. Se si ritiene che si tratti di un falso positivo, puoi inviare il programma di installazione al team di Microsoft Defender per l'analisi.
L'applicazione viene installata e disinstallata correttamente sia per gli amministratori che per i non-amministratori.
Il programma di installazione supporta modalità non interattive.
Tutte le voci del manifesto sono accurate e non fuorvianti.
Il programma di installazione proviene direttamente dal sito Web dell'editore.

Per un elenco completo dei criteri, vedere Criteri di Gestione pacchetti di Windows.

Etichette della richiesta pull

Durante la convalida, una serie di etichette viene applicata alle richieste pull per indicarne lo stato di avanzamento. Alcune etichette inviteranno all'azione, mentre altre verranno indirizzate al team di progettazione di Gestione pacchetti di Windows.

Etichette di stato

Nella tabella seguente vengono descritte le etichette di stato che è possibile riscontrare.

Etichetta	Dettagli
Pipeline di Azure riuscita	Il manifesto ha completato il superamento del test. È in attesa di approvazione. Se non si verificano problemi durante il superamento del test, verrà approvato automaticamente. Se un test non va a buon fine, potrebbe essere contrassegnato per la revisione manuale.
Causa del blocco	Questa etichetta indica che la richiesta pull non può essere approvata perché si verifica un problema di blocco. Spesso è possibile individuare il problema di blocco dall'etichetta di errore inclusa.
Richiede attenzione	Questa etichetta indica che la richiesta pull deve essere esaminata dal team di sviluppo di Gestione pacchetti di Windows. Ciò è dovuto a un test non superato che richiede una revisione manuale o a un commento aggiunto alla richiesta pull dalla community.
Feedback autore richiesto	Indica che si è verificato un errore durante l'invio. La richiesta pull viene riassegnata al mittente. Se il problema non si risolve entro 10 giorni, il bot chiuderà la richiesta pull. Le etichette Feedback autore richiesto vengono in genere aggiunte quando si è verificato un errore con la richiesta pull che deve essere aggiornata o se la persona che esamina la richiesta pull ha una domanda.
Convalida completata	Indica che il superamento del test è stato completato correttamente e che la richiesta pull verrà unita.

Etichette errori

Nella tabella seguente vengono descritte le etichette di errore che è possibile riscontrare. Non tutti i casi di errore verranno assegnati immediatamente. Alcuni possono attivare la convalida manuale.

Etichetta	Dettagli
Errore di convalida binario	L'applicazione inclusa in questa richiesta pull non è riuscita a superare il test dell'analisi dei programmi di installazione. Questo test è progettato per garantire che l'applicazione venga installata in tutti gli ambienti senza avvisi. Per altri dettagli su questo errore, vedere la sezione Errore di convalida binaria di seguito.
Timeout analisi degli errori	Il test di convalida binaria è scaduto. La richiesta pull verrà assegnata a un tecnico di Gestione pacchetti di Windows per indagare.
Errore di corrispondenza hash	Non è stato possibile elaborare il manifesto inviato perché l'hash InstallerSha256 fornito per InstallerURL non corrisponde. Aggiornare InstallerSha256 nella richiesta pull e riprovare.
Errore disponibilità programma di installazione	Il servizio di convalida non è riuscito a scaricare il programma di installazione. Questo problema può essere correlato agli intervalli IP di Azure bloccati oppure l'URL del programma di installazione potrebbe non essere corretto. Verificare che InstallerURL sia corretto e riprovare. Se si ritiene che ci sia un errore, aggiungere un commento e la richiesta pull verrà assegnata a un tecnico di Gestione pacchetti di Windows per indagare.
Errore di convalida del programma di installazione del manifesto	Esistono incoerenze o valori non presenti nel manifesto durante la valutazione di un pacchetto MSIX.
Errore percorso del manifesto	I file manifesto devono essere inseriti in una struttura di cartelle specifica. Questa etichetta indica un problema nel tracciato dell'invio. Ad esempio, la struttura di cartelle non è nel formato richiesto. Aggiornare il manifesto e il tracciato, quindi inviare nuovamente la richiesta pull.
Errore di convalida del manifesto	il manifesto inviato contiene un errore di sintassi. Risolvere il problema di sintassi nel manifesto e inviare di nuovo. Per informazioni dettagliate sul formato e sullo schema del manifesto, vedere Formato richiesto.
Errore richiesta pull	La richiesta pull non è valida perché non tutti i file inviati si trovano nella cartella del manifesto o nella richiesta pull sono presenti più pacchetti o versioni. Aggiornare la richiesta pull per risolvere il problema e riprovare.
Errore di convalida dell'URL	Il test di convalida degli URL non è riuscito a individuare l'URL e ha risposto con un codice di stato dell'errore HTTP (403 o 404) o il test di reputazione URL non è riuscito. È possibile identificare l'URL in questione esaminando i dettagli del controllo della richiesta pull. Per risolvere questo problema, aggiornare gli URL in questione per risolvere il codice di stato dell'errore HTTP. Se il problema non è dovuto a un codice di stato dell'errore HTTP, è possibile inviare l'URL per la revisione per evitare l'errore di reputazione.
Errore validazione del Defender	Durante i test dinamici, Microsoft Defender ha segnalato un problema. Per riprodurre questo problema, installare l'applicazione, quindi eseguire un'analisi completa di Microsoft Defender. Se è possibile riprodurre il problema, correggere il file binario o inviarlo per l'analisi per ottenere assistenza sui falsi positivi. Se non è possibile riprodurre il problema, aggiungere un commento in modo che i tecnici di Gestione pacchetti di Windows possano analizzarlo.
Dominio di convalida	Il test ha determinato il dominio se InstallerURL non corrisponde al dominio previsto. I criteri di Gestione pacchetti di Windows richiedono che InstallerUrl provenga direttamente dal percorso di rilascio dell'ISV. Se si ritiene che si tratti di un rilevamento errato, aggiungere un commento alla richiesta pull in modo che i tecnici di Gestione pacchetti di Windows possano analizzarlo.
Errore di convalida	La convalida di Gestione pacchetti di Windows non è riuscita durante l'approvazione manuale. Esaminare il commento allegato per i passaggi successivi.
Errore di convalida eseguibile	Durante i test di installazione, il test non è riuscito a individuare l'applicazione primaria. Assicurarsi che l'applicazione venga installata correttamente in tutte le piattaforme. Se l'applicazione non installa un'applicazione, ma deve comunque essere inclusa nel repository, aggiungere un commento alla richiesta pull in modo che i tecnici di Gestione pacchetti di Windows possano indagare.
Verifica dell'hash di convalida non riuscita	Durante i test di installazione, l'applicazione non viene installata perché InstallerSha256 non corrisponde più all'hash InstallerURL. Ciò può verificarsi se l'applicazione si trova dietro un URL di reindirizzamento e il programma di installazione è stato aggiornato senza aggiornare InstallerSha256. Per risolvere questo problema, aggiornare l'InstallerSha256 associato a InstallerURL e inviarlo di nuovo.
Errore convalida HTTP	L'URL usato per il programma di installazione non usa il protocollo HTTPS. Aggiornare InstallerURL per usare HTTPS e inviare di nuovo la richiesta pull.
URL di convalida indiretta	L'URL non proviene direttamente dal server ISV. Il test ha determinato che è stato usato un redirector. Ciò non è consentito poiché i criteri di Gestione pacchetti di Windows richiedono che InstallerUrl provenga direttamente dal percorso di rilascio dell'ISV. Rimuovere il reindirizzamento e inviare di nuovo.
Errore di installazione della convalida	Durante la convalida manuale di questo pacchetto, si è verificato un errore generale. Esaminare il commento allegato per i passaggi successivi.
Conflitto di convalida unione	Non è stato possibile convalidare il pacchetto a causa di un conflitto di unione. Risolvere il conflitto di unione e inviare nuovamente la richiesta pull.
Dipendenza convalida MSIX	Il pacchetto MSIX ha una dipendenza dal pacchetto che non è stato possibile risolvere. Aggiornare il pacchetto per includere i componenti mancanti o aggiungere la dipendenza al file manifesto e inviare di nuovo la richiesta pull.
URL di convalida non approvato	Il test ha determinato il dominio se InstallerURL non corrisponde al dominio previsto. I criteri di Gestione pacchetti di Windows richiedono che InstallerUrl provenga direttamente dal percorso di rilascio dell'ISV.
Convalida automatica non riuscita	Durante l'installazione, il test ha raggiunto il timeout. Ciò è probabilmente dovuto alla mancata installazione invisibile dell'applicazione. Potrebbe anche essere dovuto ad altri errori rilevati e all'arresto del test. Verificare che sia possibile installare il manifesto senza l'input dell'utente. Se si ha bisogno di assistenza, aggiungere un commento alla richiesta pull e i tecnici di Gestione pacchetti Windows indagheranno.
Errore di disinstallazione della convalida	Durante i test di disinstallazione, l'applicazione non è stata rimossa completamente dopo la disinstallazione. Esaminare il commento allegato per ulteriori dettagli.
Dipendenza convalida VCRuntime	Il pacchetto ha una dipendenza dal runtime C++ che non è stato possibile risolvere. Aggiornare il pacchetto per includere i componenti mancanti o aggiungere la dipendenza al file manifesto e inviare di nuovo la richiesta pull.

Etichette dei criteri di contenuto

Nella tabella seguente sono elencate le etichette dei criteri di contenuto. Se viene aggiunta una di queste etichette, un elemento nei metadati del manifesto ha attivato una revisione aggiuntiva del contenuto manuale per verificare che i metadati si attengano ai criteri di Gestione pacchetti di Windows.

Etichetta	Dettagli
Policy-Test-2.1	Vedere Requisiti generali per il contenuto.
Policy-Test-2.2	Vedere Contenuto inclusi nomi, logo, contenuto originale e di terze parti
Policy-Test-2.3	Vedere Rischio di danni.
Policy-Test-2.4	Vedere Contenuti diffamatori, calunniosi, infamanti o minacciosi.
Policy-Test-2.5	Vedere Contenuto offensivo.
Policy-Test-2.6	Vedere Alcool, tabacco, armi e droghe.
Policy-Test-2.7	Vedere Contenuto per adulti.
Policy-Test-2.8	Vedere Attività illegali.
Policy-Test-2.9	Vedere Contenuti volgari eccessivi o inappropriati.
Policy-Test-2.10	Vedere Requisiti per paesi/aree geografiche specifici.
Policy-Test-2.11	Vedere Classificazioni in base all'età.
Policy-Test-2.12	Vedere Contenuto generato dall'utente.

Etichette interne

Nella tabella seguente sono elencate le etichette di errori interni. Quando si verificano errori interni, la richiesta pull verrà assegnata ai tecnici di Gestione pacchetti di Windows per indagare.

Etichetta	Dettagli
Dominio errore interno	Si è verificato un errore durante la convalida del dominio dell'URL.
Analisi dinamica degli errori interni	Si è verificato un errore durante la convalida dei file binari installati.
Criteri parole chiave degli errori interni	Si è verificato un errore durante la convalida del manifesto.
Errore interno manifesto	Si è verificato un errore durante la convalida del manifesto.
Errore interno no architetture	Si è verificato un errore perché il test non è riuscito a determinare l'architettura dell'applicazione.
Errore interno nessuna architettura supportata	Si è verificato un errore perché l'architettura corrente non è supportata.
Errore interno PR	Si è verificato un errore durante l'elaborazione della richiesta pull.
Analisi statica errore interno	Si è verificato un errore durante l'analisi statica dei programmi di installazione.
Errore interno URL	Si è verificato un errore durante la convalida della reputazione dei programmi di installazione.
Errore interno	È stato riscontrato un errore generico o un errore sconosciuto durante il superamento del test.

Errore di convalida binario

Se la convalida della richiesta pull non supera il testInstallers Scan e riceve un'etichetta Errore convalida file binario, significa che l'applicazione non è riuscita a eseguire l'installazione in tutti gli ambienti.

Test Installers Scan

Per offrire un'eccellente esperienza utente di installazione delle applicazioni, Gestione pacchetti di Windows deve garantire che tutte le applicazioni vengano installate nei PC senza errori, indipendentemente dall'ambiente. Un test chiave consiste nel garantire che tutte le applicazioni vengano installate senza avvisi in varie configurazioni antivirus comuni. Windows offre il programma antivirus Microsoft Defender predefinito, ma molti clienti aziendali e utenti usano altri software antivirus.

Ogni invio al repository di Gestione pacchetti di Windows viene eseguito tramite diversi programmi antivirus. Questi programmi hanno algoritmi di rilevamento virus diversi per identificare applicazioni potenzialmente indesiderate (PUA) e malware.

Risolvere gli errori di convalida binari

Se la convalida di un'applicazione non va a buon fine, Microsoft tenta prima di tutto di verificare con il fornitore antivirus se il software contrassegnato è un falso positivo. In molti casi, dopo la notifica e la convalida, il fornitore dell'antivirus aggiorna l'algoritmo e l'applicazione supera il test.

In alcuni casi, il fornitore dell'antivirus non è in grado di determinare se l'anomalia del codice rilevato è un falso positivo. In questo caso, l'applicazione non può essere aggiunta al repository di Gestione pacchetti di Windows. La richiesta pull viene rifiutata con un'etichetta Errore di convalida binario.

Se si ottiene un'etichetta Errore di convalida binario nella richiesta pull, aggiornare il software per rimuovere il codice rilevato come PUA.

A volte, gli strumenti originali usati per il debug e le attività di basso livello vengono visualizzati come dal software antivirus. Ciò è dovuto al fatto che il codice di debug necessario ha una firma simile al software indesiderato. Anche se questa procedura di codifica è legittima, il repository di Gestione pacchetti di Windows purtroppo non può consentire queste applicazioni.

Risoluzione dei problemi relativi all'invio

Se l'invio di Gestione pacchetti di Windows non va a buon fine, è possibile usare le etichette descritte in precedenza per esaminare il motivo dell'errore.

Per analizzare gli errori delle richieste pull, seguire questa procedura:

Viene visualizzato un errore di richiesta pull nella parte inferiore della pagina Web con la stringa Alcuni controlli non sono riusciti. Selezionare il collegamento Dettagli accanto a una convalida non riuscita per passare alla pagina Pipeline di Azure.
Nella pagina Pipeline di Azure, selezionare il collegamento 0 errori/0 avvisi.
Nella pagina successiva selezionare il processo non riuscito.
Nella pagina successiva viene visualizzato l'output del processo non riuscito. L'output dovrebbe aiutare a identificare la modifica che è necessario apportare per correggere il manifesto.

Nell'esempio seguente l'errore si è verificato durante l'attività Convalida installazione.