Anunciamos uma experiência de referência do .NET unificada no docs.microsoft.com

Esta mensagem foi escrita por Jeff Sandquist, diretor-geral da equipa de Desenvolvimento e Ecossistema do Azure.

Há quase um ano, pilotámos a documentação de referência do .NET Core sobre docs.microsoft.com. Hoje temos o prazer de anunciar a nossa experiência de referência unificada da API .NET. Sabemos que a produtividade dos programadores é essencial, desde os amadores, startups e empresas. Tendo isso em conta, criámos uma parceria com a equipa Xamarin de forma a padronizar a forma como documentamos, detetamos e navegamos nas APIs do .NET na Microsoft.

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

Anteriormente, se quisesse procurar um SDK baseado em .NET fornecido pela Microsoft, teria de despender algum tempo no seu motor de busca preferido para tentar descobrir o local onde poderia transferir o SDK e a documentação da API relevante.

Daqui para a frente, planeamos ter todos . SDKs compatíveis com NET unificados e pesquisáveis num único local: https://docs.microsoft.com/dotnet/api. Nesse local, encontrará documentação de referência para o .NET Framework, .NET Core, .NET Standard e Xamarin, bem como documentação para os nossos pacotes do Azure NuGet. Nos próximos meses iremos adicionar mais SDKs a esta experiência.

Apresentamos o Localizador de APIs

O nosso principal objetivo é proporcionar uma experiência semelhante ao IntelliSense, para procurar todas as APIs do .NET a partir de um browser. Pode procurar um espaço de nomes, classe, método ou interface ao escrever o seu nome completo ou parcial diretamente na página do Localizador de APIs.

Se não tiver a certeza a que SDK pertence um tipo específico, membro ou espaço de nomes, pode simplesmente selecionar Todas as APIs na lista pendente âmbito da API e procurar em todos os documentos de referência disponíveis. Em alternativa, se quiser limitar a sua pesquisa, pode selecionar uma arquitetura ou SDK específico, bem como a respetiva versão , por exemplo, .NET Framework 4.7 e procurar apenas nesse conjunto de APIs.

A experiência do Localizador de APIs também está integrada na parte superior do índice de APIs baseadas no .NET, o que lhe permite localizar rapidamente qualquer API, independentemente de onde se encontrar na documentação de referência:

Assim que estiver num espaço de nomes específico, o Localizador de APIs só apresenta o âmbito da família de APIS que estão interligadas, para que a sua pesquisa apresente apenas os melhores resultados com base no contexto.

Suporte do controlo de versões

Já não tem de se questionar se um determinado tipo tem membros disponíveis numa versão específica do .NET Framework ou do pacote do Azure Storage NuGet, pois agora só tem de alterar a versão no controlo do Localizador de APIs e os conteúdos serão ajustados em conformidade:

Criado a pensar na opção Open Source

Para criar o Localizador de APIs, utilizámos normas e ferramentas open source. Essencialmente, tirámos partido do DocFX, um conjunto de ferramentas de criação de documentação open source, juntamente com a aplicação mdoc da Xamarin.

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

A nossa infraestrutura de integração contínua permite-nos ter documentação precisa das APIs mais recentes, que agora podem ser disponibilizadas publicamente poucas horas depois de serem lançadas para permitir a colaboração. Também padronizámos toda a documentação da API do .NET no formato ECMAXML, que cria uma representação consistente e abrangente da API, independentemente do SDK documentado. Além disso, não precisa de saber as complexidades do formato de ficheiro, uma vez que pode contribuir com conteúdos em Markdown, incorporados em documentos gerados automaticamente. As contribuições da comunidade para a documentação de referência serão ativadas no próximo mês.

Foco nos conteúdos

Além das novas experiências, também otimizámos os conteúdos de referência de forma a ser mais fácil de os encontrar e ler. Atualizámos o índice para que o foco se encontre sempre no espaço de nomes. Quer esteja a procurar informações sobre um espaço de nomes, tipo ou membro, iremos sempre mostrar apenas o espaço de nomes principal com todos os tipos subordinados e os seus membros agrupados:

Isto significa que as páginas de referência serão organizadas de forma a apresentar-lhe as informações importantes em primeiro lugar, como as descrições gerais e os exemplos, tudo organizado.

Também poderá ver exemplos relevantes para si no início, filtrados para a sua linguagem de programação preferencial: já não terá de deslocar-se até a parte inferior da página para encontrar esses resultados.

Orientado para o feedback

Este é apenas o início da renovação da experiência da documentação de referência. Queremos receber o seu feedback sobre como podemos tornar a nossa documentação mais interessante, útil e que responda às suas perguntas o mais rapidamente possível. Aceda ao nosso site do UserVoice e diga-nos como podemos melhorar a experiência do Localizador de APIs. Também pode contactar-nos sempre no Twitter, @docsmsft, para obter atualizações rápidas.