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

Esta postagem foi escrita por Den Delimarsky, Gerenciador de Programas na Divisão de Nuvem + IA.

Estamos entusiasmados em 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 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 todas as APIs do .NET enviadas pela Microsoft, incluir suporte profundo para controle de versão, usar e executar exemplos de código de API, habilitar facilmente atualizações de API usando automação e dar suporte a contribuições da comunidade.

docs.microsoft.com habilita essa experiência para:

• .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 do .NET, SDKs e pacotes NuGet enviados pela Microsoft

Pesquisar todas as APIs do Microsoft .NET em um só lugar com o Navegador de API do .NET

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

de pesquisa do Navegador de API do .NET

Suporte ao 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 do pacote NuGet de Armazenamento do Azure – tudo o que você precisa fazer é alterar a versão do controle navegador de API e o conteúdo será ajustado adequadamente:

seletor de versão do de documentos do .NET

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 entidades por seu respectivo tipo: Propriedades, campos , métodos e eventos.

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

de pesquisa na página do Navegador de API do .NET

Os clientes também nos disseram que, quando você está dentro de páginas de referência de API, às vezes pode ser difícil encontrar download, configuração e outra documentação útil para uma API. Como você pode ver na imagem abaixo, o do SDK do .NET do Azure combina artigos e documentação de referência, tudo em um sumário!

URLs intuitivas

Quando lançamos originalmente docs.microsoft.com, um dos nossos objetivos era ter URLs hierárquicas claras, consistentes e intuitivas. Se você se lembrar de usar o MSDN, algumas URLs do .NET foram estruturadas da seguinte maneira:

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

Tornou muito difícil entender o que é esse conteúdo, apenas olhando para ele.

O link acima agora se torna o seguinte:

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

Aqui estão apenas algumas das regras de URL do nosso Book of 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

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

Assim como o MSDN, o Docs dá suporte a todos os idiomas do .NET, incluindo C#, VB, F#e C++

seletor de idioma

Executar exemplos interativamente no navegador

Ao trabalhar com código, a melhor maneira de aprender é realmente escrever código – queríamos ter certeza de que você pode fazer isso diretamente no navegador. Há um ano, lançamos o recurso Try .NETe, ao longo do ano, o integramos em vários artigos. Seguindo em frente, continuaremos integrando essa funcionalidade em ainda mais documentos de API, permitindo que você experimente sem sair da página.

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

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

Para fazer isso, fizemos parceria com a equipe de engenharia do Xamarin para desenvolver e usar 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 vínculo fosse interrompido - todos os links do MSDN que possam ser integrados a produtos, postagens de blog e outros sites devem funcionar corretamente e apontar os usuários para o novo local, com a ajuda de um de redirecionamento padrão do301.

Pronto para contribuições da comunidade

Todo o conteúdo migrado agora é de software livre, no repositório dotnet/dotnet-api-docs no GitHub. Mas você não precisa procurar arquivos para fazer suas contribuições – basta acessar qualquer uma das páginas da API do .NET e clicar em Editare você será levado diretamente para o arquivo para o qual gostaria de fazer alterações.

Queremos seus comentários

Esperamos que você aproveite o novo formato de conteúdo- envie-nos seus comentários sobre do GitHub ou do Twitter.