Annuncio di un'esperienza unificata di riferimento per .NET in docs.microsoft.com

Questo articolo è stato scritto da Jeff Sandquist, General Manager del team Azure Growth and Ecosystem.

Quasi un anno fa, abbiamo pilotato la documentazione di riferimento di .NET Core su docs.microsoft.com. Oggi siamo lieti di annunciare l'esperienza di riferimento dell'API .NET unificata. Sappiamo che la produttività degli sviluppatori è fondamentale: da uno sviluppatore hobbysta, a un'azienda. Con questa mente, abbiamo collaborato strettamente con il team Xamarin per standardizzare il modo in cui si documenta, individuare e esplorare le API .NET in Microsoft.

Tutte le documentazione di .NET - in un'unica posizione

In precedenza, se si vuole trovare un oggetto . SDK basato su NET fornito da Microsoft, è stato necessario dedicare tempo con il motore di ricerca preferito, cercando di trovare sia il luogo in cui è possibile scaricarlo, sia individuare la documentazione dell'API pertinente.

In futuro, si prevede di avere tutto . SDK compatibili con NET unificati e ricercabili in un'unica posizione: https://docs.microsoft.com/dotnet/api. È disponibile la documentazione di riferimento per .NET Framework, .NET Core, .NET Standard e Xamarin, nonché la documentazione per i pacchetti NuGet di Azure. Nei mesi da venire, si aggiungeranno altri SDK a questa esperienza.

Introduzione al browser API

L'obiettivo principale è quello di portare un'esperienza intelliSense simile a quella di cercare tutte le API .NET da un Web browser. È possibile cercare uno spazio dei nomi, una classe, un metodo o un'interfaccia digitando il nome completo o parziale direttamente nella pagina browser API.

Se non si è certi di quale SDK appartiene a un tipo specifico, un membro o uno spazio dei nomi, è sufficiente selezionare Tutte le API nell'elenco a discesa ambito API e cercare in tutti i documenti di riferimento disponibili. In alternativa, se si vuole limitare la ricerca, è possibile selezionare un framework o un SDK specifici e la relativa versione, ad esempio .NET Framework 4.7 e cercare solo all'interno di tale set di API.

L'esperienza del browser API è integrata anche nella parte superiore del sommario per . API basate su NET, che consentono di trovare rapidamente qualsiasi API indipendentemente dalla documentazione di riferimento:

Una volta che si è in uno spazio dei nomi specifico, il browser API è con ambito solo alla famiglia di API connesse insieme, quindi la ricerca restituisce sempre i risultati migliori possibili in base al contesto.

Supporto per il controllo delle versioni

Non è più necessario chiedersi se un tipo dispone di membri disponibili in una versione specifica di .NET Framework o del pacchetto NuGet di Archiviazione di Azure: tutto ciò che è necessario fare è modificare la versione dal controllo Browser API e il contenuto verrà modificato di conseguenza:

Costruito con Open Source in mente

Per compilare il browser API, sono stati usati standard e strumenti aperti. Al suo interno, docFX è stato sfruttato: la toolchain di generazione di documentazione aperta, insieme all'applicazione mdoc di Xamarin.

Tutta la documentazione di riferimento gestita viene ora generata automaticamente dai file binari che vengono forniti in NuGet o fanno parte delle distribuzioni principali del framework, ad esempio .NET Framework o .NET Core.

L'infrastruttura di integrazione continua consente di avere una documentazione accurata per le API più recenti che ora possono essere pubbliche entro ore dal rilascio, aperte per i contributi. È stata anche standardizzata tutta la documentazione dell'API .NET nel formato ECMAXML, che crea una rappresentazione API coerente e completa indipendentemente dalla documentazione dell'SDK. Inoltre, non è necessario conoscere le intricanze del formato di file, come è possibile contribuire al contenuto in Markdown, incorporato in documenti generati automaticamente. I contributi della community per la documentazione di riferimento saranno abilitati entro il mese successivo.

Concentrarsi sul contenuto

Oltre alle nuove esperienze, abbiamo ottimizzato anche il contenuto di riferimento per essere più individuabile e leggibile. È stato aggiornato il sommario per essere sempre incentrato sullo spazio dei nomi. Se si esplorano informazioni su uno spazio dei nomi, un tipo o un membro, verrà sempre visualizzato solo lo spazio dei nomi padre con tutti i relativi tipi figlio & i rispettivi membri raggruppati:

Ciò significa che le pagine di riferimento sono decluttered e mostrano prima di tutto le informazioni più importanti, ad esempio le panoramica generali e gli esempi , tutto a colpo d'occhio.

Verranno inoltre visualizzati esempi rilevanti per l'utente direttamente dall'inizio, filtrati nel linguaggio di programmazione preferito. Non è più necessario scorrere fino alla parte inferiore della pagina per trovare tali elementi.

Guidata dai commenti e suggerimenti

Questo è solo l'inizio dell'esperienza di documentazione di riferimento. Vogliamo sentire il vostro feedback su come possiamo rendere la nostra documentazione più coinvolgente, utile e ottenere il vostro modo più veloce possibile. Passare al sito UserVoice e comunicare come è possibile migliorare l'esperienza del browser API. Puoi anche contattarci su Twitter, @docsmsft, per aggiornamenti rapidi.