Документация по API для .NET перемещена с MSDN на сайт docs.microsoft.com
Автор этой публикации — Дэн Делимарски (Den Delimarsky), руководитель программ в подразделении по облачным вычислениям и искусственному интеллекту.
Рады объявить о завершении переноса всей документации по .NET Framework для 11 языковых стандартов из MSDN на сайт docs.microsoft.com. Чтобы вы могли получить представление об объеме и масштабе этой миграции, мы представили в содержимом, касающемся .NET Framework, 9 млн документов по API. Это составляет 20 % всего объема библиотеки MSDN.
Целью является обеспечение единообразного, современного и согласованного интерфейса для поиска и навигации по всем API-интерфейсам .NET, поставляемым корпорацией Майкрософт, включая комплексную поддержку управления версиями, использование и выполнение примеров кода API, простое включение обновлений API путем автоматизации и поддержку участия сообщества в создании документации.
docs.microsoft.com поддерживает это интерфейс для следующих решений:
- .NET Framework (версии 1.1–4.7.2);
- .NET Core (версии 1.0–2.1);
- .NET Standard (версии 1.0–2.0);
- все API-интерфейсы .NET, пакеты SDK и пакеты NuGet, поставляемые Майкрософт.
Централизованный поиск всех API-интерфейсов Microsoft .NET с помощью браузера API .NET
С вами бывало такое, что вам нужен был конкретный API, но вы просто не знали, с чего начать поиск? Мы создали специальный индекс поиска API, позволяющий быстро находить необходимые API-интерфейсы в считаные секунды с помощью фильтров продуктов и версий, — браузер API .NET.
Поддержка управления версиями
Вам больше не нужно беспокоиться о том, доступны ли элементы типа в определенной версии .NET Framework или пакете NuGet Службы хранилища Azure. Все, что вам нужно сделать, — это изменить версию из элемента управления браузера API. После этого содержимое будет изменено соответствующим образом:
Улучшенная организация
Слева в оглавлении содержимое группируется по пространству имен и типам сущностей в этом пространстве имен. Например, при выборе класса вы увидите, что сущности группируются по соответствующему типу: Свойства, Поля, Методы и События.
Кроме того, вы можете выполнить поиск с помощью браузера API .NET и даже фильтрацию по конкретной версии API прямо в содержании. Это упрощает поиск нужного вам конкретного API.
Помимо прочего, клиенты сообщили нам, что на страницах справочных материалов по API иногда бывает трудно найти сведения о скачивании, настройке и другую полезную документацию по API. Как видно на изображении ниже, в общем содержании для Azure SDK для .NET объединены статьи и справочная документация.
Интуитивно понятные URL-адреса
Когда мы первоначально запустили docs.microsoft.com, одной из наших целей была реализация четких, согласованных и интуитивно понятных иерархических URL-адресов. Если вы помните, в MSDN некоторые URL-адреса .NET были структурированы следующим образом:
https://msdn.microsoft.com/library/8kszeddc(v=vs.110).aspx
По такому адресу было очень сложно понять, что собой представляет содержимое.
Приведенная выше ссылка теперь выглядит так:
https://docs.microsoft.com/dotnet/api/system.array.sort
Вот лишь некоторые из правил составления URL-адресов из нашей книги URL-адресов, которые помогают создавать согласованные и интуитивно понятные URL-адреса для .NET:
Пространства имен
Шаблон: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}
Например: https://docs.microsoft.com/dotnet/api/system.collections.generic/.
Классы
Шаблон: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}
Например: https://docs.microsoft.com/dotnet/api/system.flagsattribute.
Методы
Шаблон: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}
Например: https://docs.microsoft.com/dotnet/api/system.decimal.add.
Отображение примеров в начале документов
Беседуя с клиентами, мы определили одно общее требование: для них очень важны высококачественные, лаконичные и функциональные примеры кода. На сайте MSDN примеры содержались в конце страницы. Чтобы просмотреть первый пример для типа, иногда нужно было прокрутить страницу более 20 раз. В Документации примеры размещены в самом начале, как показано ниже:
Как и MSDN, Документация поддерживает все языки .NET, включая C#, VB, F# и C++.
Интерактивный запуск примеров в браузере
При работе с кодом лучший способ обучения — написание кода. Мы задались целью предоставить такую возможность прямо в браузере. Год назад мы разработали функцию ознакомления с .NET, а через год интегрировали ее в ряд статей. В дальнейшем мы будем продолжать интегрировать эту функцию в еще большее число документов по API. Это позволит вам экспериментировать, не закрывая страницу.
Поддержка стандартных инструментов автоматического создания содержимого
Вся документация по API на сайте docs.microsoft.com создается автоматически. Это позволяет нам без труда документировать всю область API и сократить время, требующееся для выпуска обновлений, и их частоту с недель до минут. Это гарантирует, что вы будете получать качественную документацию по всем API-интерфейсам .NET.
С этой целью мы сотрудничаем с командой разработчиков Xamarin и используем mdoc для создания всей справочной документации по .NET.
Перенаправление на docs.microsoft.com по ссылкам на MSDN
Когда мы начали миграцию, нам нужно было избежать повреждения ссылок. Требовалось, чтобы все ссылки на MSDN, интегрированные в продукты, записи блога и другие сайты, работали правильно и направляли пользователей в новое расположение путем стандартного перенаправления 301.
Готовность к участию сообщества в создании документации
Все перенесенное содержимое теперь предоставляется с открытым кодом в репозитории dotnet/dotnet-api-docs в GitHub. При этом вам не нужно искать файлы, чтобы поучаствовать в создании документации. Просто перейдите на любую страницу API .NET и нажмите кнопку Правка. Вы перейдете непосредственно к файлу, в который хотите внести изменения.
Ждем ваших отзывов
Мы надеемся, что вам понравится новый формат содержимого. Отправляйте нам отзывы в GitHub или Twitter.