Documentação da API do .NET movida do MSDN para docs.microsoft.com

Este post foi escrito por Den Delimarsky, gerente de programa da Divisão Cloud + AI.

Temos o prazer de anunciar a migração completa de toda a documentação do .NET Framework em 11 localidades do MSDN para docs.microsoft.com. Para entender o volume e a escala dessa migração, o conteúdo do .NET Framework representa mais de 9 milhões de documentos de API ou 20% do volume de toda a Biblioteca MSDN.

O objetivo é fornecer uma experiência unificada, moderna e consistente para localizar e navegar em todas as APIs do .NET fornecidas pela Microsoft, incluir suporte profundo para controle de versão, usar e executar amostras de código de API, habilitar facilmente atualizações de API usando automação e dar suporte a contribuições da comunidade.

O docs.microsoft.com habilita a experiência para o:

• .NET Framework (versões 1.1 - 4.7.2)
• .NET Core (versões 1.0 – 2.1)
• .NET Standard (versões 1.0 – 2.0)
• E todas as APIs, SDKs e pacotes NuGet do .NET enviados pela Microsoft

Pesquise todas as APIs do Microsoft .NET em um único lugar com o Navegador de API do .NET

Você já esteve em uma situação em que está procurando uma API, mas simplesmente não sabe por onde começar? Desenvolvemos um índice de pesquisa de API dedicado, permitindo que você encontre rapidamente as APIs necessárias em segundos, com filtros de produto e versão — o Navegador de API do .NET.

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:

Organização aprimorada

No sumário à esquerda, o conteúdo é agrupado por namespace e tipos de entidades dentro desse namespace. Ao selecionar uma classe, por exemplo, você verá que agrupamos as entidades por seu respectivo tipo: Propriedades, Campos, Métodos e Eventos.

Alternativamente, você também pode pesquisar com a ajuda do Navegador de API do .NET e até filtrar uma versão específica da API, tudo a partir do sumário, facilitando a localização da API exata que você está procurando.

Os clientes também informaram que, quando você está nas páginas de referência da API, às vezes pode ser difícil encontrar informações sobre download, configuração e outras documentações úteis para uma API. Como você pode ver na imagem abaixo, o SDK do Azure .NET combina artigos e documentação de referência, tudo em um sumário!

URLs intuitivas

Quando lançamos originalmente o docs.microsoft.com, um de nossos objetivos era ter URLs hierárquicas claras, consistentes e intuitivas. Relembrando o uso do MSDN, algumas URLs do .NET tinham a seguinte estruturação:

https://msdn.microsoft.com/library/8kszeddc(v=vs.110).aspx

Entender o que é esse conteúdo só pela aparência é muito difícil.

O link acima agora torna-se:

https://docs.microsoft.com/dotnet/api/system.array.sort

Aqui estão apenas algumas das regras de URL do nosso Livro de URLs para garantir URLs consistentes e intuitivas para o .NET:

Namespaces

Padrão: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}

Exemplo: https://docs.microsoft.com/dotnet/api/system.collections.generic/

Classes

Padrão: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}

Exemplo: https://docs.microsoft.com/dotnet/api/system.flagsattribute

Métodos

Padrão: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}

Exemplo: https://docs.microsoft.com/dotnet/api/system.decimal.add

Exemplos primeiro

Algo consistente que ouvimos em entrevistas com clientes é a importância de exemplos de código de alta qualidade, sucintos e funcionais para APIs. No MSDN, os exemplos foram incluídos no final de uma página, o que significa que em alguns exemplos você precisaria rolar para baixo mais de 20 vezes para ver o primeiro exemplo de um tipo. No Docs, os exemplos aparecem primeiro, conforme mostrado abaixo:

Assim como o MSDN, o Docs dá suporte a todas as linguagens .NET, incluindo C#, VB, F# e C++

Execute exemplos interativamente no navegador

Ao trabalhar com código, a melhor maneira de aprender é realmente escrever código — queremos garantir que você possa fazer isso imediatamente no navegador. Há um ano, lançamos o recurso Try .NET e, ao longo do ano, o integramos em vários artigos. No futuro, continuaremos integrando essa funcionalidade em ainda mais documentos da API, permitindo que você experimente sem sair da página.

Com suporte por ferramentas padrão de geração automática

Toda a documentação da API no docs.microsoft.com é gerada automaticamente, o que nos permite documentar facilmente toda a superfície da API e melhorar drasticamente o tempo e a frequência das atualizações de semanas para minutos. Isso garante que você obtenha documentação de API de qualidade para todas as APIs do .NET.

Para fazer isso, firmamos uma parceria com a equipe de engenharia do Xamarin para desenvolver e usar o mdoc para gerar toda a documentação de referência do .NET.

Links do MSDN — redirecionamento para docs.microsoft.com

Quando iniciamos a migração, queríamos garantir que nenhum link fosse quebrado — todos os links do MSDN que pudessem ser integrados em produtos, postagens de blog e outros sites deveriam funcionar corretamente e direcionar os usuários para o novo local, com a ajuda de um padrão de redirecionamento 301.

Pronto para contribuições da comunidade

Todo o conteúdo migrado agora é de código aberto, no repositório dotnet/dotnet-api-docs no GitHub. Mas não é preciso procurar arquivos para fazer suas contribuições — basta ir a qualquer uma das páginas da API do .NET e clicar em Editar, e você será levado diretamente ao arquivo em que deseja fazer alterações.

Seus comentários são muito importantes para nós

Esperamos que você goste do novo formato de conteúdo — envie-nos seus comentários no GitHub ou Twitter.