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

Esta mensagem foi escrita por Den Delimarsky, Gestor de Programas na Divisão Cloud + IA.

Temos o entusiasmo em anunciar a migração concluída de toda a documentação do .NET Framework em 11 regiões do MSDN para docs.microsoft.com. Para compreender o volume e o dimensionamento desta migração, o conteúdo .NET Framework representa mais de 9 milhões de documentos de API ou 20% do volume de toda a Biblioteca MSDN.

O objetivo é proporcionar uma experiência unificada, moderna e consistente para localizar e navegar em todas as APIs .NET enviadas pela Microsoft, incluir suporte profundo para controlo de versões, utilizar e executar exemplos de código da API, ativar facilmente atualizações de API através da automatização e suportar contribuições da comunidade.

docs.microsoft.com permite esta 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 ,NET, SDKs e pacotes NuGet enviados pela Microsoft

Pesquise todas as APIs .NET da Microsoft num único local com o Browser de API .NET

Alguma vez esteve numa situação em que estava à procura de uma API, mas não sabe por onde começar? Criámos um índice de pesquisa de API dedicado, permitindo-lhe encontrar rapidamente as APIs necessárias em segundos, com filtros de produtos e versões – o Browser de API .NET.

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:

Organização melhorada

No índice esquerdo, o conteúdo é agrupado por espaço de nomes e tipos de entidades nesse espaço de nomes. Quando seleciona uma classe, por exemplo, verá que agrupamos entidades pelo respetivo tipo: Propriedades, Campos, Métodos e Eventos.

Em alternativa, também pode procurar com a ajuda do Browser de API .NET e até filtrar uma versão de API específica, tudo a partir do índice, facilitando a localização da API exata que procura.

Os clientes também nos disseram que, quando está nas páginas de referência da API, por vezes pode ser difícil encontrar transferência, configuração e outra documentação útil para uma API. Como pode ver na imagem abaixo, o SDK .NET do Azure combina artigos e documentação de referência, tudo num único índice!

URLs intuitivos

Quando inicialmente lançámos docs.microsoft.com, um dos nossos objetivos era ter URLs hierárquicos claros, consistentes e intuitivos. Se se lembrar de utilizar o MSDN, alguns URLs .NET foram estruturados da seguinte forma:

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

Tornou-se muito difícil compreender o que é este conteúdo, só de olhar para ele.

A ligação acima torna-se agora a seguinte:

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

Seguem-se apenas algumas das regras de URL do nosso Livro de URLs para garantir URLs consistentes e intuitivos para .NET:

Espaços de nomes

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 das entrevistas com os clientes é a importância de exemplos de código de alta qualidade, sucintas e funcionais para APIs. No MSDN, foram incluídos exemplos no final de uma página, o que significa que, em alguns exemplos, teria de deslocar para baixo mais de 20 vezes para ver o primeiro exemplo de um tipo. No Docs, os exemplos são os primeiros, conforme mostrado abaixo:

Tal como o MSDN, o Docs suporta todas as linguagens .NET, incluindo C#, VB, F#e C++

Executar exemplos interativamente no browser

Ao trabalhar com código, a melhor forma de aprender é escrever código. Queríamos ter a certeza de que o pode fazer diretamente a partir do browser. Há um ano, implementámos a funcionalidade Experimentar .NET e, ao longo do ano, integrámo-la em vários artigos. Daqui para a frente, vamos continuar a integrar esta funcionalidade em ainda mais documentos de API, permitindo-lhe experimentar sem sair da página.

Suportado pelas ferramentas de geração automática padrão

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

Para tal, estabelecemos uma parceria com a equipa de engenharia da Xamarin para desenvolver e utilizar o mdoc para gerar toda a documentação de Referência do .NET.

Ligações MSDN – redirecionar para docs.microsoft.com

À medida que iniciámos a migração, quisemos garantir que não existem ligações quebradas– todas as ligações MSDN que possam estar integradas em produtos, publicações de blogue e outros sites devem funcionar corretamente e apontar os utilizadores para a nova localização, com a ajuda de um redirecionamento padrão 301.

Pronto para contribuições da comunidade

Todos os conteúdos migrados estão agora open source, no repositório dotnet/dotnet-api-docs no GitHub. No entanto, não tem de procurar ficheiros para fazer as suas contribuições. Basta aceder a qualquer uma das páginas da API .NET e clicar em Editar e será direcionado diretamente para o ficheiro para o qual pretende fazer alterações.

Queremos o seu feedback

Esperamos que desfrute do novo formato de conteúdo. Envie-nos o seu feedback no GitHub ou no Twitter.