Унифицированная справка по .NET — теперь на сайте docs.microsoft.com

Автор записи — Джефф Сэндквист (Jeff Sandquist), директор подразделения группы по развитию и экосистеме Azure.

Почти год назад мы запустили пилотный проект справочной документации по .NET Core на сайте docs.microsoft.com. Сегодня мы рады объявить о выпуске унифицированной системы справочных материалов по API .NET. Мы понимаем, что производительность является ключевым фактором для разработчиков — от разработчиков-любителей, до стартапов и предприятий. Учитывая это, мы тесно сотрудничаем с командой Xamarin, чтобы стандартизировать способы документирования и поиска API-интерфейсов .NET, а также навигации по ним в Майкрософт.

Вся документация по .NET в одном расположении

Ранее, если вам нужно было найти пакет SDK на основе NET, поставляемый корпорацией Майкрософт, вам требовалось время, чтобы определить, откуда можно скачать его, а также найти соответствующую документацию по API в предпочитаемой вами поисковой системе.

В дальнейшем мы планируем объединить все совместимые с .NET пакеты SDK и сделать их доступными для поиска в одном расположении: https://docs.microsoft.com/dotnet/api. Здесь вы найдете справочную документацию по .NET Framework, .NET Core, .NET Standard и Xamarin, а также документацию по нашим пакетам NuGet для Azure. В ближайшие месяцы мы добавим в этот интерфейс больше пакетов SDK.

Знакомство с браузером API

Наша основная цель — обеспечить возможность поиска в веб-браузере всех интерфейсов API .NET с помощью IntelliSense. Вы можете выполнить поиск пространства имен, класса, метода или интерфейса. Для этого введите полное имя или часть имени непосредственно на странице браузера API.

Если вы не знаете, к какому пакету SDK относится конкретный тип, элемент или пространство имен, просто выберите элемент Все API в раскрывающемся списке "Область API" и выполните поиск по всем доступным справочным документам. Кроме того, если вы хотите ограничить поиск, можно выбрать конкретную платформу или пакет SDK, а также версию, например .NET Framework 4.7, и выполнить поиск только в рамках этого набора API-интерфейсов.

Кроме того браузер API интегрирован в верхнюю часть содержания для API на основе .NET. Это позволяет быстро найти любой API независимо от расположения в справочной документации:

В определенном пространстве имен браузер API ограничивается только семейством связанных друг с другом интерфейсов API. Поэтому после поиска всегда возвращаются лучшие из возможных результаты на основе контекста.

Поддержка управления версиями

Вам больше не нужно беспокоиться о том, доступны ли элементы типа в определенной версии .NET Framework или пакете NuGet Службы хранилища Azure. Все, что вам нужно сделать, — это изменить версию из элемента управления браузера API. После этого содержимое будет изменено соответствующим образом:

Разработка по принципу открытого кода

Мы создали браузер API с помощью открытых стандартов и средств. Как основу мы использовали DocFX (открытую цепочку инструментов для создания документации), а также приложение Xamarin mdoc.

Вся наша управляемая справочная документация теперь создается автоматически из двоичных файлов, которые поставляются в NuGet или входят в состав основных дистрибутивов платформы, таких как .NET Framework или .NET Core.

Наша инфраструктура непрерывной интеграции позволяет получить точную документацию по новейшим интерфейсам API, которые теперь могут становиться общедоступными и открытыми для публикаций через несколько часов после выпуска. Кроме того, мы стандартизировали документацию по API .NET, используя формат ECMAXML. Он позволяет создать единообразное и комплексное представление API, независимо от документируемого пакета SDK. Более того, вам не нужно вникать в тонкости формата файлов, так как вы можете добавлять содержимое в разметку Markdown, внедренную в автоматически создаваемые документы. Поддержка участия сообщества в создании документации будет включена в течение следующего месяца.

Фокусировка на содержимом

Помимо реализации новых возможностей, мы оптимизировали справочные материалы, чтобы их было проще искать и изучать. Мы обновили оглавление таким образом, чтобы оно всегда было ориентировано на пространство имен. Независимо от того, просматриваете ли вы сведения о пространстве имен, типе или члене, мы всегда будем показывать только родительское пространство имен со всеми его дочерними типами & соответствующими сгруппированных элементов:

Это означает, что справочные страницы будут упорядочены таким образом, что сначала в компактном представлении будут отображаться наиболее важные сведения, например общие обзоры и примеры.

Кроме того, в самом начале будут отображаться соответствующие примеры, отфильтрованные по выбранному языку. Вам больше не нужно будет прокручивать страницу, чтобы найти их.

Разработка на основе отзывов

Это только начало модернизации справочной документации. Мы ждем ваших отзывов, которые помогут сделать документацию еще более интересной и полезной, чтобы вы могли как можно быстрее добиться своей цели с ее помощью. Зайдите на сайт UserVoice и сообщите нам, как можно улучшить возможности браузера API. Кроме того, вы можете быстро получить новости в Twitter, @docsmsft.