Microsoft sandcastle runtime что это

Обновлено: 04.07.2024

какие шаги мне нужно предпринять, чтобы автоматически создавать HTML-документацию с помощью шага сборки в Visual Studio? У меня есть все замечания и комментарии.создается xml-файл и устанавливается Sandcastle. Мне просто нужно знать, что добавить после построения шаг, чтобы создать документы.

С тех пор, как был задан этот вопрос, были внесены некоторые изменения. Sandcastle больше не включает SandcastleBuilderConsole.exe . Вместо этого он использует старый добрый MSBuild.exe .

чтобы интегрировать это с visual studio, вот что я сделал:

поместите это в событие после сборки:

это приведет к visual studio для создания документации, только когда вы строите в режиме" Release". Таким образом, вы не ждете вечно, когда вы строите в режиме "отладки" во время развитие.

моя система 64-разрядная, если ваша нет, то замените framework64 С framework на пути к msbuild.exe .

способ настройки - документировать каждый проект в моем решении индивидуально. Если у вас есть файл проекта "Sandcastle Help File Builder", который включает в себя несколько проектов вместе, то вы, вероятно, хотите избавиться от ProjectName\ и движение doc в каталоге решений. В этом если вы хотите поместить только команды событий после сборки в проект, который построен последним в вашем решении. Если вы поместите его в событие Post-build для каждого проекта, вы будете перестраивать документацию для каждого построенного проекта. Излишне говорить, что вы посидите там некоторое время. Лично я предпочитаю документировать каждый проект индивидуально, но это только я.

установка Sandcastle и " файл справки Sandcastle Строитель."

если вы не знаете, как правильно настроить Sandcastle и "Sandcastle Help File Builder", выполните следующие действия:

сохраните проект, и вы можете закрыть "Sandcastle Help File Builder". Теперь все готово. Просто не забудьте поместить файл проекта документации в соответствующую папку, на которую указывают пакетные команды в событии после сборки.

Я надеюсь, что мой короткий учебник поможет вам! Мне было очень трудно найти любые приличные учебники, показывающие мне, как использовать sandcastle, не говоря уже о том, как интегрировать его с visual studio. Надеюсь, в будущем поисковые запросы google поднимут этот вопрос.

Я рекомендую вам установить Sandcastle Help File Builder из сайте CodePlex.

вы можете запустить это из командной строки, например, из События после сборки. Самая простая командная строка:

Sandcastle очень медленный, поэтому я запускаю его только для сборки выпуска. Для этого создайте событие после сборки с помощью команды примерно следующего вида, которая передает имя конфигурации в пакетный файл:

затем внутри пакетного файла вы можно проверить, является ли первый аргумент "Release", и если да, запустите SandcastleBuilderConsole.исполняемый.

простой способ сделать это, как предложено выше, с помощью Sandcastle Help File Builder. Были внесены некоторые изменения в процесс сборки из командной строки, и теперь эти проекты могут быть построены с помощью MSbuild вместо SandcastleBuilderConsole.исполняемый. Поэтому все, что вам нужно сделать, это:

в MSBuild.exe имя проекта.шфб

Я должен признать, что нахожу текущую версию Sandcastle немного недостающей; для больших проектов она довольно медленная, и ее нелегко интегрировать (так как это еще рано).

для регулярного использования мне на самом деле проще просто указать reflector на папку с dll и xml - файлами-IIRC, он загрузит xml-файл(ы) при навигации.

плюс у меня почти всегда рефлектор открыт в любом случае.

[edit] проверено, и да-XML-комментарии отображаются в панель дизассемблера

Основные возможности Sandcastle

Подготовка к работе

Тестовый проект для документирования

В моем случае не буду усложнять пример и сделаю документацию для приложения «Hello World!». Документация будет содержать описание используемых классов, пространств имен, стартовую страницу и страницу дополнительной информации о приложении.
Наш главный класс консольного приложения:

namespace Atv.Research.HelloWorld
/// <summary>
/// Базовый класс тестового приложения
/// </summary>
public class Program
/// <summary>
/// Стартовый метод консольного приложения
/// </summary>
/// <param name="args">Аргументы консольного приложения</param>
public static void Main( string [] args)
Console .Out.WriteLine( "Hello World!" );
>
>
>

* This source code was highlighted with Source Code Highlighter .

В свойствах проекта необходимо выставить генерацию XML файла с нашими комментариями. Для этого в контекстном меню на проекте Properties/вкладка Build/раздел Output – выставите галочку для «XML documentation file». После компиляции проекта мы получим наше приложение Atv.Research.HelloWorld.exe и файл с комментариями Atv.Research.HelloWorld.XML.

Давайте сразу добавим в нашу документацию пару статических страниц. Очень часто бывает, что технической информации из кода недостаточно. Нужны более общие описания, с рисунками и диаграммами. Или, например, требуется вставить целиком текст конфигурационного файла или WSDL для веб-сервиса. В качестве примера мы вставим 2 статические HTML страницы. Одна из них будет стартовой для нашей документации.

<! DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >

< html xmlns ="http://www.w3.org/1999/xhtml" >
< head >
< title > About </ title >
</ head >
< body >
< div style ="height:140px;" > </ div >
< div style ="text-align:center" >
< h1 > Тестовое консольное приложение < br /> Hello World! </ h1 >

< div >< a href ="Details.htm" > Детальное описание </ a ></ div >
</ div >

</ body >
</ html >

* This source code was highlighted with Source Code Highlighter .

<! DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >
< html xmlns ="http://www.w3.org/1999/xhtml" >
< head >
< title > Details </ title >
</ head >
< body >
< h2 > Назначение </ h2 >
< p > Тестовое консольное приложение "Hello World" предназначено для демонстрации возможностей Sandcastle. </ p >
< h2 > Пример ссылок на автодокументацию </ h2 >
В качестве примера в консольное приложение добавлен следующий тестовый класс: < see cref ="Atv.Research.HelloWorld.MyTestClass" />

</ body >
</ html >

* This source code was highlighted with Source Code Highlighter .

@DefaultTopic — комментарий используется для того, что бы указать на то, что эта страница будет стартовой.
Тег <see> — поможет сослаться со статической страницы на страницу автоматически генерируемой документации по исходным кодам, содержащей конкретный класс, метод или пространство имен.
Тег <pre> — сделает подсветку синтаксиса в примерах кода для статических страниц.

Запуск программы

Собственно, входные данные у нас уже есть. Это наше приложение, XML файл с комментариями и 2 статические страницы для описания нашего приложения. Пришло время запускать «Sandcastle Help File Builder GUI».

Это статья-заметка о работе с 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 расходится с синтаксисом, который употребляется в метатегах <see /> и использует свой:

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;

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

Одна из таких абстракций — Windows Runtime (WinRT), и сегодня я собираюсь проиллюстрировать это, рассмотрев базовую модель приложений WinRT. Она построена вокруг класса CoreWindow, экземпляр которого находится внутри каждого «современного» приложения Windows Store и Windows Phone. Тем не менее, сравнительно немногие знают о его существовании, и еще меньше, как он работает. Видимо, это можно считать критерием успеха абстракции.

Со времени первого объявления Windows 8 API в 2011 году многое было сказано и написано о различных языковых проекциях, предоставляющих абстракцию над Windows Runtime. Однако лучший способ понять Windows Runtime — отказаться от языковых проекций, включая C++/CX, и использовать стандартный C++ в сочетании с традиционной COM. Только C++ позволяет раздвинуть плотные шторы и увидеть, что происходит на самом деле (с технической точки зрения, то же самое можно сделать и на C, но это было бы излишне болезненно). Возможно, вы все равно предпочтете использовать ту или иную языковую проекцию (скорее всего, C++/CX), но по крайней мере у вас будет гораздо более четкое понимание происходящего.

Для начала откройте Visual Studio 2012 и создайте новый проект Visual C++ для приложения Windows Store или Windows Phone. Не важно, какой шаблон вы используете. Как только он загрузится, перейдите в Solution Explorer и удалите все, что не существенно. Если вы выбрали шаблон на основе XAML, удалите все XAML-файлы. Вы также можете удалить все файлы исходного кода на C++. Вероятно, вы предпочтете сохранить предкомпилированный заголовочный файл, но обязательно удалите все его содержимое. У вас должны остаться лишь ресурсы пакета, необходимые для развертывания приложения, изображения, сертификата и XML-манифеста.

Затем откройте страницы свойств проекта и выберите свойства компилятора — узел C/C++ в дереве слева. Найдите строку для ключа компилятора /ZW — Consume Windows Runtime Extension — и укажите No, чтобы отключить языковые расширения C++/CX. Тем самым вы будете уверены, что ничего загадочного, помимо мистических чудес стандартного компилятора C++, не происходит. Там же установите уровень предупреждений компилятора /W4.

Если вы попробуете скомпилировать проект, то должны увидеть приветствие от компоновщика, который сообщает об ошибке из-за того, что не удалось найти функцию точки входа в проект — WinMain. Добавьте в проект новый файл исходного кода на C++ и первым делом поместите в него недостающую функцию WinMain:

Как видите, это традиционная функция WinMain для Windows-приложения на основе C Runtime Libraries (CRT). Конечно, HINSTANCE и PWSTR не являются фундаментальными типами C++, поэтому вам придется включить заголовочный файл windows.h:

Если вы сохранили предкомпилированный заголовочный файл проекта, то можете включить его здесь. Я также буду использовать ComPtr из Windows Runtime C++ Template Library (WRL), поэтому сейчас самое время включить и его:

Подробнее о WRL я буду рассказывать в следующих статьях из этой рубрики. А пока я буду просто использовать шаблон класса ComPtr для поддержки указателя на COM-интерфейс. На этом этапе достаточно знать, что WRL ComPtr — это просто смарт-указатель на COM-интерфейс. Хотя он предоставляет некоторые средства, уникальные для Windows Runtime, я не стану использовать их в этот раз. С тем же успехом вы могли бы задействовать CComPtr из Active Template Library (ATL) или любой другой смарт-указатель на COM-интерфейс по своему выбору. WRL ComPtr определен в пространстве имен Microsoft::WRL:

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

Первое, что ожидает модель приложений, — MTA (multithreaded apartment). Правильно, в ней находится COM-модель изоляции потоков (COM apartment model). Windows Runtime предоставляет функцию RoInitialize, которая является тонкой оболочкой CoInitializeEx:

Несмотря на тот факт, что обычно достаточно CoInitializeEx, я предлагаю вам использовать RoInitialize. Эта функция позволит поддерживать будущие усовершенствования в Windows Runtime без потенциальной угрозы поломать традиционную COM. Она аналогична OleInitialize, которая тоже вызывает CoInitializeEx и кое-что еще. Смысл в том, чтобы в основном потоке вашего приложения не было ничего загадочного. Единственное, что может слегка удивить, — это не STA (single-threaded apartment). Не волнуйтесь, окно вашего приложения по-прежнему будет выполняться в STA-потоке, но создавать его будет Windows Runtime. Эта STA — на самом деле Application STA (ASTA), и она немного отличается от чистой STA, но об этом позже.

WindowsCreateString выделяет достаточно памяти для хранения копии исходной строки и null-символа, завершающего строку, а затем копирует исходную строку в этот буфер. Чтобы освободить этот вспомогательный буфер, вы должны вызвать WindowsDeleteString, если только владелец строки не возвращается в вызвавшую функцию:

Располагая HSTRING, вы можете получить указатель на вспомогательный буфер этой строки с помощью функции WindowsGetStringRawBuffer:

Необязательный второй параметр возвращает длину строки. Длина хранится вместе со строкой, избавляя вас от необходимости сканировать строку, чтобы определить ее размер. Прежде чем вы начнете строчить класс-оболочку для C++, стоит отметить, что компилятор C++/CX не возится с WindowsCreateString и WindowsDeleteString при генерации кода для строкового литерала или массива const. Вместо них он использует так называемую быстро передаваемую строку (fast-pass string), позволяющую избегать дополнительных операций выделения памяти и копирования, о которых недавно упоминал. Кроме того, это исключает риск утечки памяти. Создается быстро передаваемая строка функцией WindowsCreateStringReference:

Она использует передаваемый вызвавшим кодом HSTRING_HEADER, чтобы избежать выделения памяти из кучи. В этом случае вспомогательный буфер для HSTRING — это сама исходная строка, поэтому вы должны гарантировать, что исходная строка (равно как и заголовок) останется неизменной в течение срока существования HSTRING. Очевидно, что этот подход бесполезен, когда нужно вернуть строку вызвавшей функции, но отличная оптимизация, если требуется передать строку как входной параметр другой функции, чей срок жизни ограничен стеком (т. е. это не относится к асинхронным функциям). WRL также предоставляет оболочки для HSTRING и быстро передаваемых строк.

RoGetActivationFactory — как раз такая функция, и она используется для получения фабрики активации или статического интерфейса для данного класса. Она аналогична COM-функции CoGetClassObject. Учитывая, что эта функция обычно применяется с массивом const, генерируемым компилятором MIDL, имеет смысл написать простой шаблон-функцию, предоставляющий оболочку быстро передаваемой строки. Как он может выглядеть, показано на рис. 1.

Рис. 1. Шаблон функции GetActivationFactory

Шаблон функции GetActivationFactory автоматически распознает длину строки, исключая необходимость передачи аргумента с длиной буфера (а здесь легко ошибиться) или весьма дорогостоящего сканирования строки в период выполнения. Затем перед вызовом функции RoGetActivationFactory подготавливает быстро передаваемую строку. И здесь шаблон функции вновь логически распознает идентификатор интерфейса и безопасно возвращает конечный указатель на COM-интерфейс, обернутый в WRL ComPtr.

Теперь вы можете использовать эту вспомогательную функцию для получения интерфейса ICoreApplication:

Интерфейс ICoreApplication — это то, что приводит в действие ваше приложение. Чтобы использовать этот COM-интерфейс, вам потребуется включить заголовочный файл модели приложений:

Этот заголовочный файл определяет ICoreApplication в пространстве имен ABI::Windows::ApplicationModel::Core, а также текстовый идентификатор класса CoreApplication. Единственный метод интерфейса, над которым вам придется хорошенько подумать, — это Run.

Прежде чем продолжить, было бы полезно оценить, как Windows Runtime выводит ваше приложение в свет, если так можно выразиться. Как уже упоминалось, Windows Runtime считает вас просто гостем в вашем процессе. Тут полная аналогия с тем, как годами работали Windows-службы. В случае Windows-службы Windows Service Control Manager (SCM) запускает ее, используя функцию CreateProcess или одну из ее вариаций. Затем ждет, когда процесс вызовет функцию StartServiceCtrlDispatcher. Эта функция устанавливает обратную связь с SCM, благодаря чему служба и SCM могут взаимодействовать друг с другом. Если, например, службе не удастся своевременно вызвать StartServiceCtrlDispatcher, SCM будет считать, что возникла какая-то ошибка, и уничтожит процесс. Функция StartServiceCtrlDispatcher возвращает управление только по окончании работы службы, поэтому SCM нужно создавать дополнительный поток для службы, чтобы принимать уведомления об обратных вызовах. Служба просто реагирует на события и находится полностью во власти SCM. Как вы увидите, это во многом напоминает модель приложений WinRT.

Windows Runtime ждет от процесса получения интерфейса ICoreApplication и вызова его метода Run. Если процессу не удается своевременно сделать это, Windows Runtime подобно SCM считает, что что-то пошло не так и завершает процесс. К счастью, если к процессу подключен отладчик, Windows Runtime обнаруживает это и отключает тайм-аут — в отличие от SCM. Однако модель та же. Windows Runtime контролирует процесс и, когда происходят какие-то события, вызывает приложение в потоке, созданном исполняющей средой. Конечно, Windows Runtime основана на COM, поэтому вместо функции обратного вызова (как в случае SCM) эта исполняющая среда (которая в этом деле опирается на Process Lifetime Manager [PLM]) ожидает, что приложение предоставит метод Run с COM-интерфейсом, который можно использовать для вызова приложения.

Ваше приложение должно предоставить реализацию IFrameworkViewSource, который также находится в пространстве имен ABI::Windows::ApplicationModel::Core, и тогда CoreApplication вызовет его единственный метод CreateView, как только создаст UI-поток вашего приложения. На самом деле в IFrameworkViewSource содержится не только метод CreateView. Этот интерфейс наследует от IInspectable, базового интерфейса WinRT. В свою очередь IInspectable наследует от IUnknown, базового интерфейса COM.

WRL обеспечивает обширную поддержку реализации COM-классов, но об этом мы поговорим в следующей статье. А пока я хочу подчеркнуть, что корни Windows Runtime уходят в COM и что нет лучшего способа показать это, чем реализовать IUnknown. Для моих целей будет полезным отметить, что срок жизни C++-класса, который реализует IFrameworkViewSource и несколько других интерфейсов, определяется стеком. По сути, функция WinMain приложения сводится к следующему:

Остается лишь написать класс SampleWindow так, чтобы он должным образом реализовал интерфейс IFrameworkViewSource. Хотя CoreApplication безразлично, где реализуются интерфейсы, ваше приложение, как минимум, должно реализовать не только IFrameworkViewSource, но и интерфейсы IFrameworkView и IActivatedEventHandler. В данном случае класс SampleWindow может просто реализовать их всех:

Интерфейс IFrameworkView также определен в пространстве имен ABI::Windows::ApplicationModel::Core, а с IActivatedEventHandler дело обстоит несколько сложнее. Я определил его сам таким образом:

Если у вас есть некоторый опыт работы с COM, вы могли подумать, что это выглядит весьма не ортодоксально, — и были бы правы. Как и следовало бы ожидать, ITypedEventHandler — это просто шаблон класса, и довольно странно так определять COM-интерфейс; самая очевидная проблема в том, что вы, по-видимому, не смогли бы узнать, каким идентификатором интерфейса нужно его пометить. К счастью, все эти интерфейсы генерируются компилятором MIDL, который берет на себя задачу специализации каждого из них, и этим специализациям он назначает GUID, представляющий идентификатор интерфейса. Каким бы сложным ни выглядело предыдущее выражение typedef, оно определяет COM-интерфейс, который наследует непосредственно от IUnknown и предоставляет единственный метод — Invoke.

Я должен реализовать несколько методов интерфейсов, поэтому займемся делом. Первым идет IUnknown и его могущественный метод QueryInterface. Я не хочу тратить здесь слишком много времени на IUnknown и IInspectable, так как подробно опишу их в следующей статье. На рис. 2 приведена простая реализация QueryInterface для класса, основанного на стеке.

Рис. 2. Метод QueryInterface в SampleWindow

В этой реализации стоит отметить несколько моментов. Прежде всего, метод проверяет, что его аргументы допустимы. Более политкорректная реализация могла бы возвращать E_POINTER, но предполагается, что такие ошибки являются дефектами, которые можно устранить на этапе разработки, поэтому незачем тратить на них лишние процессорные ресурсы в период выполнения. Это обеспечивает наилучшее из возможных поведение, немедленно вызывая ошибку доступа к памяти и создавая аварийный дамп, который довольно легко проанализировать. Если бы вы возвращали E_POINTER, вызвавший дефектный код скорее всего просто проигнорировал бы это. Поэтому лучшая политика — провал на раннем этапе. По сути, такой позиции придерживаются во многих реализациях, включая DirectX и Windows Runtime. Корректная реализация QueryInterface требует уймы усилий. Спецификация COM весьма требовательна к тому, чтобы COM-классы всегда корректно и согласованно обеспечивали определенные гарантии идентификации объектов. Не волнуйтесь, если цепочка выражений if кажется вам устрашающей. В свое время я расскажу и об этом.

И последнее, на что хотелось бы обратить внимание в этой реализации, — она не вызывает AddRef. Обычно перед возвратом управления QueryInterface должен вызывать AddRef применительно к полученному указателю на интерфейс IUnknown. Однако, так как класс SampleWindow находится в стеке, смысла в учете ссылок нет. По той же причине реализация IUnknown-методов AddRef и Release предельно проста:

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

Теперь мне нужно реализовать IInspectable, но, поскольку он не будет использоваться в этом простом приложении, я схитрю и оставлю его методы нереализованными, как показано на рис. 3. Это нерекомендуемая реализация, и нет никаких гарантий, что она будет работать в других случаях. И вновь описание IInspectable я отложу до следующей статьи, а пока замечу лишь, что этого достаточно для подготовки и работы интерфейсов, производных от IInspectable, в классе SampleWindow.

Рис. 3. IInspectable-методы в SampleWindow

Далее я должен реализовать IFrameworkViewSource и его метод CreateView. Поскольку класс SampleWindow тоже реализует IFrameworkView, реализация проста. И вновь заметьте, что обычно перед возвратом управления вы должны были бы вызывать AddRef применительно к полученному указателю на интерфейс, производный от IUnknown. Возможно, вы предпочтете на всякий случай вызывать AddRef в теле этой функции:

Интерфейс IFrameworkView — то место, где наконец начинают происходить интересные вещи. После вызова CreateView из приложения для получения указателя на этот интерфейс Windows Runtime вызывает большинство его методов в быстрой последовательности. Важно так же быстро реагировать на эти вызовы, так как все они засчитываются в тот период времени, в течение которого пользователь ожидает запуска вашего приложения. Первым вызывается Initialize, и в нем приложение должно регистрироваться на событие Activated. Это событие уведомляет, что приложение активировано, но вы сами должны активировать его CoreWindow. Метод Initialize довольно прост:

Затем вызывается метод SetWindow, который предоставляет приложению реализацию ICoreWindow, который просто моделирует обычный HWND рабочего стола в Windows Runtime. В отличие от остальных интерфейсов модели приложений ICoreWindow определен в пространстве имен ABI::Windows::UI::Core. В методе SetWindow обязательно делайте копию указателя на интерфейс, так как достаточно скоро он вам понадобится:

Следующий метод — Load; в нем вы должны собрать весь код, отвечающий за подготовку вашего приложения к начальному отображению:

Как минимум, вы должны регистрироваться на события, относящиеся к изменениям размера окна и видимости, а также к изменениям в масштабировании DPI (dots per inch). Кроме того, вы, вероятно, захотите воспользоваться возможностью создать различные объекты фабрики DirectX, загрузить аппаратно-независимые ресурсы и т. д. Это хорошее место для выполнения всех таких операций по той причине, что в этот момент пользователь видит экран-заставку вашего приложения.

Когда метод Load возвращает управление, Windows Runtime считает, что ваше приложение готово к активации, и генерирует событие Activated, которое я буду обрабатывать, реализовав метод Invoke интерфейса IActivatedEventHandler примерно так:

После активации окна приложение наконец готово к выполнению:

Выражаю благодарность за рецензирование статьи эксперту Microsoft Джеймсу Макнеллису (James McNellis).

Читайте также: