Anunciando uma experiência de referência unificada do .NET em docs.microsoft.com

Esta postagem foi redigida por Jeff Sandquist, gerente geral da Equipe de ecossistema e desenvolvimento do Microsoft Azure.

Há quase um ano, nós testamos a documentação de referência do .NET Core em docs.microsoft.com. Hoje, estamos felizes em anunciar nossa experiência unificada de referência de API do .NET. Compreendemos que a produtividade do desenvolvedor é fundamental — seja um desenvolvedor amador, uma startup ou uma empresa. Com isso em mente, firmamos uma parceria com a equipe do Xamarin para padronizar o processo de documentação, descoberta e navegação em APIs do .NET na Microsoft.

Toda a documentação do .NET em um só lugar

Anteriormente, caso quisesse encontrar um SDK baseado em .NET fornecido pela Microsoft, você teria que passar algum tempo usando seu mecanismo de pesquisa de preferência para descobrir o local de onde baixá-lo, além da documentação de API relevante.

No futuro, planejamos ter todos os SDKs compatíveis com .NET unificados e pesquisáveis em um só lugar:https://docs.microsoft.com/dotnet/api. Lá, você encontrará documentação de referência para .NET Framework, .NET Core, .NET Standard e Xamarin, bem como documentação para nossos pacotes NuGet do Azure. Nos próximos meses, adicionaremos mais SDKs a essa experiência.

Introdução ao Navegador de API

Nosso principal objetivo é oferecer uma experiência semelhante ao IntelliSense para pesquisar todas as APIs do .NET a partir de um navegador da Web. Para pesquisar um namespace, classe, método ou interface, basta digitar o seu nome completo ou parcial diretamente na página do Navegador de API.

Se você não tiver certeza a qual SDK um tipo, membro ou namespace específico pertence, basta selecionar Todas as APIs na lista suspensa de escopo da API e pesquisar em todos os documentos de referência disponíveis. Alternativamente, se você quiser limitar sua pesquisa, poderá selecionar uma estrutura ou SDK específico, bem como sua versão — digamos, .NET Framework 4.7 —, e pesquisar somente nesse conjunto de APIs.

A experiência do Navegador de API também está integrada na parte superior do sumário para APIs baseadas em .NET, permitindo que você encontre rapidamente qualquer API, não importa onde você esteja na documentação de referência:

Quando você estiver em um namespace específico, o Navegador de API terá como escopo apenas a família de APIs conectadas, de modo que sua pesquisa sempre retornará os melhores resultados possíveis com base em seu contexto.

Suporte para controle de versão

Você não precisa mais se perguntar se um tipo tem membros disponíveis em uma versão específica do .NET Framework ou no pacote NuGet do Armazenamento do Azure, tudo o que você precisa fazer é alterar a versão do controle do Navegador de API e o conteúdo será ajustado de acordo:

Criar com o código aberto em mente

Para criar o Navegador de API, utilizamos padrões e ferramentas abertos. Em sua essência, aproveitamos o DocFX — a cadeia de ferramentas de geração de documentação aberta — juntamente com o aplicativo mdoc do Xamarin.

Toda a nossa documentação de referência gerenciada agora é gerada automaticamente a partir de binários fornecidos no NuGet ou que fazem parte das principais distribuições de estrutura, como .NET Framework ou .NET Core.

Nossa infraestrutura de integração contínua nos permite ter uma documentação precisa para as APIs mais recentes que agora podem ser públicas poucas horas após o lançamento, abertas para contribuições. Também padronizamos toda a documentação da API .NET no formato ECMAXML, que cria uma representação consistente e abrangente da API, independentemente do SDK estar documentado. Além disso, você não precisa estar a par das complexidades do formato de arquivo, pois pode contribuir com conteúdo no Markdown, inserido em documentos gerados automaticamente. As contribuições da comunidade para documentação de referência serão habilitadas no próximo mês.

Foco no conteúdo

Além das novas experiências, também otimizamos o conteúdo de referência para ser mais detectável e legível. Atualizamos o sumário para estar sempre focado no namespace. Se você estiver navegando informações sobre um namespace, tipo ou membro, sempre mostraremos apenas o namespace pai com todos os seus tipos filhos & seus respectivos membros agrupados:

As páginas de referência são organizadas e mostram as informações mais importantes primeiro, como visões gerais e exemplos — de forma facilmente compreensível com um só olhar.

Você também verá exemplos relevantes desde o início, filtrados para a linguagem de programação de sua escolha — não é mais preciso rolar até o final da página para encontrá-los.

Orientação por comentários

Este é apenas o começo da nossa reformulação da experiência de documentação de referência. Queremos ouvir seus comentários sobre como podemos tornar nossa documentação mais envolvente e útil para que você possa prosseguir o mais rápido possível. Acesse o site do UserVoice e informe como podemos melhorar nossa experiência com o Navegador da API. Você também pode sempre entrar em contato conosco pelo Twitter, @docsmsft, para atualizações rápidas.