Microsoft sandcastle runtime что это
Sandcastle
Можно по-разному относится к такой ситуации, но это — тема для совсем другой статьи.
В своем письме Кевин упоминает проект «Sandcastle», над которым работает одна из команд Microsoft, и который преследует (примерно) те же цели, что и NDoc. По убеждению Кевина, «после того, как ‘Sandcastle’ будет выпущен, он станет стандартом де-факто … Это случится в независимости от технических соображений, даже если Sandcastle будет предлагать меньше возможностей …».
Похоже, имеет смысл разобраться, что же это за «убийца NDoc» и чем он может быть нам полезен.
Что такое Sandcastle?
В блоге команды разработки Sandcastle первая запись появилась 27 июля 2006 года.
В качестве цели заявляется: «предоставить разработчикам библиотек классов по всему миру средство простого создания точной и информативной документации общепринятого вида» (вставка от отдела маркетинга?). Свойства Sandcastle:
Интересный документирующий комментарий в шаблоне презентации Sandcastle:
Процесс
Если вам требуется быстро получить результат и вы не хотите влезать во все тонкости, то все дальнейшее изложение можно смело опустить. Возьмите готовый инструмент, например такой как Sandcastle Help File Builder.
Важное отличие этого процесса от процесса NDoc: в Sandcastle основой всегда является сборка, на основе мета-информации сборки строится весь справочник, файл XML-комментариев является необязательным; в NDoc основным источником являются XML-комментарии, мета-информация из сборки используется только для тех объектов, которые упоминаются в файле XML-комментариев.
Подготовка
Действие начинается с работы утилиты MrefBuilder, которая, используя CCI (Common Compiler Infrastructure library — Microsoft.Cci.dll — тот же механизм, что используется в FxCop для получения мета-информации), получает информацию из сборки и выдает ее в выходной файл — Reflection.xml. Этот файл имеет следующую структуру:
Для каждого объекта исходной сборки — пространства имен, класса, свойства, метода и т. п. — здесь есть свой тэг с подробным описанием. В готовом справочнике, каждому тэгу будет соответствовать свой HTML-файл описания.
Формат вызова MrefBuilder:
где /dep указывает сборки, от которых зависят наши сборки, флаг /internal:+ показывает что нужно генерировать документацию для не-public классов/методов.
Пример использования MrefBuilder:
Следующий шаг — дополнение файла Reflection.xml серией «искусственных» тэгов . Для этого используются XSLT-преобразования, которые выполняются утилитой XslTransform. Судя по списку файлов в папке ProductionTransforms, нам уже доступны следующие способы дополнения файла Reflection.xml:
XSLT-преобразование | Описание |
---|---|
AddOverloads.xsl | Добавляет элементы для методов с одним названием и разным набором параметров |
AddMemberLists.xsl | |
AddRoot.xsl | Добавляет корневой элемент , для страницы со списком всех пространств имен (по-видимому, для Sandcastle November CTP этот шаг уже не нужен — элемент создается автоматически) |
AddGuidFilenames.xsl | Добавляет элемент в каждый элемент , в качестве имен файлов задаются глобально уникальные идентификаторы |
AddFriendlyFilenames.xsl | Добавляет элемент с «дружественными» именами файлов: в качестве имен файлов задаются имена, содержащие названия объектов, например для класса — "T_FooNamespace_FooClass" |
AddXamlAttachedMembers.xsl |
Формат вызова XslTransform:
Наконец, готовый Reflection.xml сформирован. На его основе, также при помощи XSLT, создается файл со списком топиков — Manifest.xml, имеющий вид:
Пример преобразования для получения Manifest.xml:
Создание топиков
Теперь, когда вся подготовительная работа проделана, публика разогрета, на сцену выходит суперзвезда этого шоу — BuildAssembler.
Результат работы BuildAssembler — логически группированные HTML-файлы топиков документации, пригодные к использованию компиляторами HTML Help 1.3 либо HTML Help 2.0.
Вызов BuildAssembler выглядит так:
Для каждого топика, указанного в файле Manifest.xml, BuildAssembler выполняет одну и ту же последовательность действий, описанную в файле Sandcastle.config. Типичный набор таких действий выглядит так:
- загрузить «скелет» документа
- загрузить из Reflection.xml данные по описываемому объекту, а также по «родительскому» объекту (например, для класса также загружаются данные по пространству имен) и «дочерним» объектам (например, для класса — по его полям, свойствам и методам)
- загрузить XML-комментарии
- проставить перекрестные ссылки
- выполнить ряд XSLT-преобразований
- сохранить готовый документ
Каждое действие описывается в Sandcastle.config в виде вызова определенного компонента с параметрами.
Sandcastle.config
Итак, центральная часть процесса обработки топиков — это файл Sandcastle.config. Стоит рассмотреть его повнимательнее. Пожалуй, это наиболее интересная часть Sandcastle, и наименее документированная. Мне не удалось найти справочника по используемым компонентам, по-видимому, его вообще (пока) нет в открытом доступе, и все что нам остается — запастись терпением и ждать, либо взять Reflector и влезть с ногами в сборки Sandcastle.
Во время обработки, каждый топик представляет из себя XML-документ в памяти (экземпляр класса XmlDocument). Компоненты, перечисленные в Sandcastle.config — это классы, которые инстанциируются и выполняются один за другим над каждым топиком.
В целом, работа BuildAssembler проходит в несколько фаз:
- Загрузка и разбор файлов Manifest.xml и Sandcastle.config
- Инстанциирование компонентов
- Для каждого топика, описанного в Manifest.xml — выполнение компонентов
Все компоненты являются наследниками абстрактного класса BuildComponent:
При инстанциировании компонента, в его конструктор передается соответствующая этому компоненту секция файла Sandcastle.config. Это позволяет компоненту «прочитать» свои настройки. Для выполнения компонента вызывается метод Apply, в который передается текущий топик (в виде XmlDocument) и идентификатор этого топика.
Одни компоненты изменяют документ, другие управляют потоком выполнения, третьи позволяют загрузить информацию в XML-документ из файла или сохранить текущее состояние документа в файл.
Вот некоторые из «стандартных» компонентов, содержащихся в сборке BuildComponents.dll:
Шаблоны справочника
Помимо логики создания топиков, описанной файлом Sandcastle.config, облик справочника определяется еще целым рядом файлов — это шаблоны страниц, стилевые файлы CSS, скрипты, изображения и т. п. Все эти файлы, плюс собственно Sandcastle.config составляют шаблон справочника .
Перед вызовом BuildAssembler, файлы шаблона копируются в рабочую папку, в которой и выполняется сборка справочника.
В составе Sandcastle, в папке Presentation есть два готовых шаблона:
- vs2005 — стандартный шаблон, с помощью которого оформлена справка по Visual Studio 2005, входящая в состав MSDN Library
- Prototype — прототип/пример шаблона пользователя
Пример получения этих файлов (для простоты, опущено указание путей):
Остается лишь выполнить сборку справочника, используя утилиту hhc.exe из HTML Help Workshop 1.3:
Неприятная особенность: hhc.exe написан таким образом, что он возвращает код возврата «1» в случае удачного завершения, и «0» — в случае ошибки. Это отличается от обычной практики, когда после нормального завершения возвращается «0». Поэтому hhc.exe неудобно использовать с такими средствами сборки как NAnt или MSBuild. К счастью, есть простое решение этой проблемы — использовать «инвертирующий» .BAT-файл:
Это статья-заметка о работе с Sandcastle и SHFB , дабы не забыть самому и рассказать другим.
Инсталяция
Мне важны были прежде всего chm-компиллятор и плагин к VS2012 и VS2013. Кроме этого ещё установится, собственно, сам Sandcastle Help File Builder — это приложение, которое позволяет пользоваться интерфейсом, а не прописывать всё в xml-файлах. За исключением тулбара с редактированием текста (жирный, курсив и т.п.) я не нашёл отличий между SHFB и плагином к студии, а студия ещё и автокомплит с интелисенсом предлагает, так что разработку я постепенно перевёл на неё.
Настройка проекта
Когда всё установлено, можно добавлять проект в солюшн. В студии в темплейтах появился «Documentation/Sandcastle Help File Builder Project», выбираем его, добавляем «Documentation Sources» (ссылку на проект, который документируем), в проекте включаем «XML documentation file», и запускаем билд. Заходим в папку /bin… и ничего там не находим. Всё дело в том, что по-умолчанию Sandcastle создаёт файлы в папке \Help в проектном фолдере.
Чтобы этого избежать, идём в свойства проекта -> Path -> «Help content output path» и меняем на что-нибудь более привычное, например, на «bin\Help\». После билда можно увидеть LastBuild.log (по умолчанию создаётся в output folder) и chm файл. На внешний вид и предупреждения пока не обращайте внимания.
Как только вы добавите Website, вы сможете обнаружить следующую проблему: оба хелпа оказываются в одном фолдере. Ненаглядно, неудобно, и не комильфо. Идём в свойства проекта -> Plug-Ins -> Output Deployment -> Add. Здесь указываем относительные пути для копирования.
Осталось совсем немного, чтобы привести проект в порядок.
В тех местах, где отсутствует документация, в хелпе появляются красные предупреждающие надписи «Missing documentation for . ».
Создадим пару страничек
Для начала удаляем папку Version History со всем содержимым и Welcome.aml страницу из проекта. Структура документации строится именно в файле ContentLayout.content, так что придётся почистить и этот файл.
В большинстве случаев при создании новой страницы документации выбирать придётся тип «Conceptual» (типов много и говорить о них можно долго). При создании новой страницы нужно добавить её в ContentLayout. Возможности конфигурации статических страниц относительно сгенерированого кода и друг друга очень большие, вы сможете дерево топиков составить так, как захотите.
Проблемы начинаются, когда необходимо сослаться на сгенерированные страницы. В этом случае Sandcastle расходится с синтаксисом, который употребляется в метатегах и использует свой:
qualifyHint устанавливается в «true», если нужно показывать сигнатуру метода.
Список большой, и такие вещи приходится просто знать, тут уж ничего не поделаешь.
Хотя можно включить предупреждения «Missing documentation . » и там можно увидеть, в каком виде Sandcastle ожидает название метода.
Tips and Tricks
- Существуют разные шаблоны интерфейса: vs2013, vs2010, vs2005, Hana, Prototype. СтОит попробовать как минимум vs2013 и vs2010 — они обе не deprecated, и их поведение отличается. К примеру, в vs2013 после поиска топик открывается в новой вкладке, что у нас на проекте было критично. Также стоит заметить, что на Webhelp можно ссылаться как на Index.aspx, так и на index.html. Часть функционала во втором случае не будет доступна (например, поиск).
- Чтобы добавить описание к Namespace, включите в него вот такой класс:
VisualStudio оставит этот тэг без внимания, а вот Sandcastle добавит его содержимое в документацию.
Таблицу таких тегов можно найти по ссылке: Sandcastle’s XML Documentation Comments;
Install.
Оговорюсь сразу, что все эти приложения я ставил по default директориям, чтобы потом в куче xml конфигов не исправлять пути. Итак:
Чтобы подружить Drawbridge со связкой Sandcastle+SHFB, используем уличную магию, подсказанную автором SHFB. В директорию к установленному Sandcastle (C:\Program Files\Sandcastle\ProductionTools) добавляем (создаем) файл BuildAssembler.exe.config с содержимым:
Drawbridge наивно полагает, что работать ему предстоит, видимо, в какой-то прежней версии связки Sandcastle+SHFB и потому после установки он просто добавляет объявление своей сборки в одну из директорий SHFB:
C:\Program Files\EWSoftware\Sandcastle Help File Builder\BuildComponents\drawbridgecomponent.config
Но SHFB в GUI его не увидит. Поэтому, чтобы Drawbridge зарегистрировать, нужно содержимое этого конфига, между
That’s all.
Осталось самое интересное: откомментировать проект и сгенерировать документацию.
Hello, world!
Наш HelloWorld:
HelloWorld\sand\HelloWorld.shfbproj | Конфиг для генерирования документации, созданный в SHFB |
HelloWorld\src\HelloWorld.sln | Solution, сам проектик |
HelloWorld\src\HelloWorld\* | Файлы проекта |
HelloWorld\src\HelloWorld\diagram | Сюда я сохранял файлы классов диаграмм из Visual Studio (*.cd) |
HelloWorld\src\HelloWorld\drawbridge | Сюда я сохранял экспортированные в изображения классы диаграмм (*.jpg) |
Пишем простенький Solution:
На картинке выше, для класса Program мы указали, что хотим в его описании видеть диаграмму классов «Person.cd».
Не забываем включать генерацию XML при построении сборки в свойствах проекта, на вкладке Build:
Теперь, если душа поэта просит нарисовать диаграмму классов в Visual Studio – рисуем встроенными средствами.
Сохраняем *.cd в HelloWorld\diagram, и одновременно экспортируем все рисунки в *.jpg в HelloWorld\drawbridge. Легко и непринужденно. =)
Создаем проект построения документации: HelloWorld\sand\HelloWorld.shfbproj, как было описано в предыдущей статье, а в компонентах добавляем «Drawbridge Class Diagram Generator» и соответствующим образом настраиваем его, направляя на папки истинные:
Generating Documentation.
Генерация документации протекает с обильным количеством логов. Если ее строим из GUI через SHFB, то выглядит это подобным образом:
Если операции прошли успешно, то в логах отразятся подобные записи:
Build.
-
Можно какой-нибудь *.cmd файл напрямую натравить:
msbuild.exe HelloWorld.shfbproj
Finally.
Кликабельная диаграмма классов в документации будет выглядеть как ниже на картинке. Тыцкнув на интересный нам класс, мы тут же переходим на соответствующую страницу документации. Приятно. =)
Или даже в виде asp страничек:
P.S.
Накручивая такие бигуди, становится приятно от того, что избавиться от всего этого можно в пару кликов, не задевая комментарии кода. Разве что перестанут работать:
СОДЕРЖАНИЕ
В настоящее время Sandcastle имеет облегченный графический интерфейс пользователя (GUI) в качестве альтернативы проекту MSBuild , пакетному сценарию и сценариям Windows PowerShell , которые также предоставляются. Для Sandcastle также доступны несколько инструментов с графическим интерфейсом пользователя, которые предоставляют дополнительные функции и упрощают его использование. [1]
Visual Studio SDKs на 2005 и 2008 включают в себя старые версии CTP из Sandcastle, [2] , хотя последняя версия доступна на GitHub .
Sandcastle состоит из нескольких программ, не все из которых используются в типичном процессе сборки справки. Ниже перечислены наиболее часто используемые инструменты.
- MrefBuilder использует общую инфраструктуру компилятора (CCI) для отражения управляемых сборок и создания выходного файла.
- XslTransform применяет преобразования XSL к XML-файлу. Обычно указанный входной файл является файлом, созданным MRefBuilder, или является производным от него.
- BuildAssembler выполняет стек компонентов сборки один раз для каждой темы, определенной в XML-манифесте. Стек компонентов сборки определяется в файле XML с расширением .config. Sandcastle предоставляет несколько компонентов сборки, которые используются в стеках компонентов сборки для выполнения таких задач, как создание индексов данных в памяти, разрешение ссылок, включая общий контент, выполнение преобразований XSL и сохранение окончательного вывода в файл.
Поскольку в текущем состоянии Sandcastle сам по себе довольно сложен в использовании, люди придумали инструменты и сценарии, которые могут автоматизировать задачу за них. В этом разделе содержится список таких инструментов и скриптов.
Sandcastle создает HTML-файлы на основе XML в выбранном стиле представления. (Это, однако, не означает, что файлы являются XHTML- совместимыми.) HTML определяется файлами преобразования XSL, которые включены в конкретный используемый стиль представления. Сборка обычно использует только один стиль представления за раз.
Файлы HTML, создаваемые Sandcastle, представляют собой либо концептуальную (пользовательскую) документацию, являющуюся результатом преобразования из тем Microsoft Assistance Markup Language (MAML), либо справочную документацию, которая автоматически создается из данных отражения и комментариев к документации XML. Эти два разных типа вывода HTML используют один и тот же стиль представления и могут быть скомпилированы вместе для создания смешанной пользовательской / справочной документации.
Процессы создания концептуальной документации и справочной документации аналогичны, с одним из основных отличий в том, что концептуальная документация не требует использования программы MRefBuilder.
Концептуальная документация состоит из тем, написанных с использованием схемы типа документа MAML, таких как инструкции, пошаговое руководство, устранение неполадок и ряд других. Sandcastle предоставляет стек концептуальных компонентов сборки (conceptual.config), который разрешает общий контент и ссылки и использует файлы XSL для преобразования элементов MAML в HTML.
Справочная документация создается автоматически для управляемых интерфейсов прикладного программирования (API) из данных отражения и комментариев документации XML. XSL-преобразование «модель документа», обеспечиваемое выбранным стилем представления, применяется для определения файлов, которые будут сгенерированы. Sandcastle предоставляет стек компонентов эталонной сборки (sandcastle.config), который создает индексы данных в памяти, разрешает совместно используемый контент и ссылки и использует XSL для генерации окончательного вывода HTML.
Sandcastle не производит скомпилированный вывод справки (хотя создаваемые им HTML-файлы могут использоваться в качестве входных данных для компиляторов справки HTML, таких как HTML Help Workshop и Microsoft Help 2 ).
Некоторые инструменты используются несколько раз во время одной сборки, например XslTransform и BuildAssembler. В зависимости от требований, другие инструменты и преобразования XSL могут использоваться на различных этапах процесса для изменения вывода Sandcastle.
Приложение Sandcastle было разработано Microsoft для создания масштабируемого и производительного генератора документации для документации по API . Microsoft выпустила Sandcastle как версию Community Technology Preview ( CTP ) в июле 2006 года, за несколько дней до того, как NDoc был объявлен мертвым [3] [4] Автор NDoc, Кевин Даунс, цитировал в электронном письме, отправленном через его список рассылки, причины прекращения работы. разработка его популярного инструмента из-за отсутствия поддержки сообщества, как финансовой, так и в виде вклада в разработку, автоматизированная почтовая бомба атака на его общедоступный адрес электронной почты и адрес списка рассылки NDoc2, а также его впечатление, что Sandcastle «станет стандартом де-факто, а NDoc постепенно превратится в застойную сторону».
В течение сентября 2010 года Sandcastle загружал в среднем 217 загрузок в день [5] , что сделало его одним из 25 самых загружаемых проектов на CodePlex .
6 июня 2008 г. проект SandCastle был удален с веб-сайта CodePlex [6] после того, как в ветке обсуждения на сайте CodePlex было указано, что исходный код недоступен; несмотря на то, что CodePlex требует этого, а проект SandCastle рекламируется как «открытый исходный код». [7] 2 июля проект вернулся в CodePlex, и исходный код был опубликован. [8]
СОДЕРЖАНИЕ
В настоящее время Sandcastle имеет облегченный графический интерфейс пользователя (GUI) в качестве альтернативы проекту MSBuild , пакетному сценарию и сценариям Windows PowerShell , которые также предоставляются. Для Sandcastle также доступны несколько инструментов с графическим интерфейсом пользователя, которые предоставляют дополнительные функции и упрощают его использование. [1]
Visual Studio SDKs на 2005 и 2008 включают в себя старые версии CTP из Sandcastle, [2] , хотя последняя версия доступна на GitHub .
Sandcastle состоит из нескольких программ, не все из которых используются в типичном процессе сборки справки. Ниже перечислены наиболее часто используемые инструменты.
- MrefBuilder использует общую инфраструктуру компилятора (CCI) для отражения управляемых сборок и создания выходного файла.
- XslTransform применяет преобразования XSL к XML-файлу. Обычно указанный входной файл является файлом, созданным MRefBuilder, или является производным от него.
- BuildAssembler выполняет стек компонентов сборки один раз для каждой темы, определенной в XML-манифесте. Стек компонентов сборки определяется в файле XML с расширением .config. Sandcastle предоставляет несколько компонентов сборки, которые используются в стеках компонентов сборки для выполнения таких задач, как создание индексов данных в памяти, разрешение ссылок, включая общий контент, выполнение преобразований XSL и сохранение окончательного вывода в файл.
Поскольку в текущем состоянии Sandcastle сам по себе довольно сложен в использовании, люди придумали инструменты и сценарии, которые могут автоматизировать задачу за них. В этом разделе содержится список таких инструментов и скриптов.
Sandcastle создает HTML-файлы на основе XML в выбранном стиле представления. (Это, однако, не означает, что файлы являются XHTML- совместимыми.) HTML определяется файлами преобразования XSL, которые включены в конкретный используемый стиль представления. Сборка обычно использует только один стиль представления за раз.
Файлы HTML, создаваемые Sandcastle, представляют собой либо концептуальную (пользовательскую) документацию, являющуюся результатом преобразования из тем Microsoft Assistance Markup Language (MAML), либо справочную документацию, которая автоматически создается из данных отражения и комментариев к документации XML. Эти два разных типа вывода HTML используют один и тот же стиль представления и могут быть скомпилированы вместе для создания смешанной пользовательской / справочной документации.
Процессы создания концептуальной документации и справочной документации аналогичны, с одним из основных отличий в том, что концептуальная документация не требует использования программы MRefBuilder.
Концептуальная документация состоит из тем, написанных с использованием схемы типа документа MAML, таких как инструкции, пошаговое руководство, устранение неполадок и ряд других. Sandcastle предоставляет стек концептуальных компонентов сборки (conceptual.config), который разрешает общий контент и ссылки и использует файлы XSL для преобразования элементов MAML в HTML.
Справочная документация создается автоматически для управляемых интерфейсов прикладного программирования (API) из данных отражения и комментариев документации XML. XSL-преобразование «модель документа», обеспечиваемое выбранным стилем представления, применяется для определения файлов, которые будут сгенерированы. Sandcastle предоставляет стек компонентов эталонной сборки (sandcastle.config), который создает индексы данных в памяти, разрешает совместно используемый контент и ссылки и использует XSL для генерации окончательного вывода HTML.
Sandcastle не производит скомпилированный вывод справки (хотя создаваемые им HTML-файлы могут использоваться в качестве входных данных для компиляторов справки HTML, таких как HTML Help Workshop и Microsoft Help 2 ).
Некоторые инструменты используются несколько раз во время одной сборки, например XslTransform и BuildAssembler. В зависимости от требований, другие инструменты и преобразования XSL могут использоваться на различных этапах процесса для изменения вывода Sandcastle.
Приложение Sandcastle было разработано Microsoft для создания масштабируемого и производительного генератора документации для документации по API . Microsoft выпустила Sandcastle как версию Community Technology Preview ( CTP ) в июле 2006 года, за несколько дней до того, как NDoc был объявлен мертвым [3] [4] Автор NDoc, Кевин Даунс, цитировал в электронном письме, отправленном через его список рассылки, причины прекращения работы. разработка его популярного инструмента из-за отсутствия поддержки сообщества, как финансовой, так и в виде вклада в разработку, автоматизированная почтовая бомба атака на его общедоступный адрес электронной почты и адрес списка рассылки NDoc2, а также его впечатление, что Sandcastle «станет стандартом де-факто, а NDoc постепенно превратится в застойную сторону».
В течение сентября 2010 года Sandcastle загружал в среднем 217 загрузок в день [5] , что сделало его одним из 25 самых загружаемых проектов на CodePlex .
6 июня 2008 г. проект SandCastle был удален с веб-сайта CodePlex [6] после того, как в ветке обсуждения на сайте CodePlex было указано, что исходный код недоступен; несмотря на то, что CodePlex требует этого, а проект SandCastle рекламируется как «открытый исходный код». [7] 2 июля проект вернулся в CodePlex, и исходный код был опубликован. [8]
Читайте также: