Сервер ATL

Создание простого проекта ATL Server

Создадим проект ATL Server.

После нажатия на кнопку Finish (Готово) Visual Studio .NET начнет генерирование файлов согласно параметрам по умолчанию мастера проекта сервера ATL. Любой из упомянутых в шаге 3 шаблонов (ATL Server Web Service [Веб-служба сервера ATL] или ATL Server Project [Проект сервера ATL]) сгенерирует в Visual Studio .NET два проекта. Стартовый проект представляет собой главный проект, имя которого мы ввели в диалоговом окне New Project (Новый проект). Второй генерируемый проект носит то же имя, что и стартовый, но к его имени добавляется окончание ISAPI. Создаваемому проекту ATL Server присвоено имя NewSimpleATLServer (см. рис. 4.3). В Visual Studio .NET имеется Solution Explorer (Обозреватель решения) для просмотра проектов и связанных с ними файлов. В его окне представлено иерархическое дерево проектов и файлов, связанных с открытым в данный момент программным решением. Solution Explorer можно открыть с помощью команды View\Solution Explorer (Вид\Обозреватель решения). В окне Solution Explorer мы видим проекты NewSimpleATLServer и NewSimpleATLServerISAPI. Проект NewSimpleATLServer содержит код, специфичный для приложения. Его результатом является DLL-библиотека веб-приложения и файл ответа сервера (SRF). Продуктом проекта NewSimpleATLServerISAPI является только ISAPI DLL.

В отличие от шаблонов веб-служб для C# и Visual Basic, в локальный экземпляр IIS не добавляется автоматически виртуальный каталог. Visual Studio .NET можно настроить на реализацию файлов, устанавливающих программное решение ATL Server на IIS. При этом будет производиться установка лишь в первый веб-экземпляр, загруженный в IIS. При установке в другой веб-экземпляр (не в первый, являющийся веб-сайтом по умолчанию) следует провести данную операцию вручную. Для настройки Visual Studio на автоматическую установку решения ATL Server в IIS выполните следующие шаги.

В меню Visual Studio .NET выберите Project\Properties (Проект\Свойства) для открытия окна свойств (см. рис. 4.5). Проект сервера ATL состоит из двух проектов (если только он не настроен на использование одной библиотеки DLL). Окно свойств отображает параметры выбранного в данный момент проекта Visual Studio. Изменить проект можно, выделив его в окне Solution Explorer.(рис 4.5) Окно свойств проекта и окно Solution Explorer (Обозреватель решения)

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

В окне Solution Explorer выберите проект DLL-библиотеки расширения ISAPI. Если имя проекта не было изменено, то к имени обычно присоединяется окончание ISAPI.

Для свойства Relative Path (Относительный путь), отображаемого в области справа, введите значение bin. В результате DLL-библиотека расширения ISAPI будет расположена в подкаталоге bin папки, на которую указывает виртуальный каталог IIS. Вы можете указать другое имя каталога.

Установите параметр Virtual Directory Name (Имя виртуального каталога) равным имени виртуального каталога, в который устанавливаются файлы проекта ATL Server. Если виртуальный каталог не существует, он будет создан. Ниспадающий список позволяет легко выбрать имя проекта.

Параметр Application Mappings (Связи приложения) нужно установить равным .srf;.dll. В созданном виртуальном каталоге будут присутствовать эти связи.

Выберите проект DLL-библиотеки веб-приложения в Solution Explorer (Обозреватель решения) для обновления окна и отображения параметров проекта.

По аналогии с проектом ISAPI выберите узел Web Deployment (Веб-реализация) в левой области окна внизу (если вы еще не сделали это).

Установите такие же значения параметров, как в шагах 4 и 5. Имя виртуального каталога должно совпадать с именем проекта ISAPI. Параметр относительного пути может отличаться от относительного пути проекта ISAPI. Связи приложения устанавливать не нужно.

Нажмите на кнопку OK, чтобы сохранить изменения в конфигурации и закрыть окно.

После установки относительного пути, имени виртуального каталога и связей приложения для проектов в решении ATL Server реализация файлов произойдет при первом же выполнении команды построения.

Нажмите на клавишу F5, и, независимо от того, какое окно выбрано в Visual Studio .NET, начнется построение, реализация и запуск проекта NewSimpleATLServer. Появится окно, информирующее об истечении срока действия файлов с запросом на разрешение повторной компиляции. После успешной компиляции двоичных файлов обработчика запросов DLL и расширения ISAPI эти файлы будут перемещены вместе с демонстрационным файлом SRF в место расположения в корневом веб-каталоге веб-сайта IIS по умолчанию. Visual Studio .NET попробует присоединить себя к IIS и провести пошаговую отладку кода, в результате чего, скорее всего, появится следующее сообщение об ошибке.

Visual Studio .NET не устанавливается с поддержкой отладки ATL Server. По умолчанию устанавливается компонент Full Remote Debugging (Полная удаленная отладка), обеспечивающий отладку веб-форм и веб-служб Visual Basic и C#. Решениям C++ необходима Native Remote Debugging (Обычная удаленная отладка). С помощью программы установки Visual Studio .NET добавляется необходимая поддержка (см. рис. 4.6). Откройте программу установки и запустите процесс инсталляции. В окне, показанном на рис. 4.6, выберите Native Remote Debugging (Обычная удаленная отладка).

После установки обычной удаленной отладки и правильной настройке ее параметров откроется окно браузера с отображением сообщения: "This is a test: Hello World!". На данном этапе может возникнуть ошибка по причине того, что файловые расширения .dll и .srf не связаны с ассоциированной DLL-библиотекой расширения ISAPI в рассматриваемом экземпляре IIS или виртуальном каталоге. В этом случае откройте связи приложения (см. рис. 4.2) и проверьте правильность связи файлов .dll и .srf с нужной библиотекой.

Поскольку сложная конфигурация ATL Server требует запуска программы Hello World, разработчик должен хорошо разбираться в процессах, происходящих внутри IIS и технологии .NET. Использование мощи ATL Server очень выгодно для разработки, но требует серьезных навыков и знаний от программиста.

Работа с мастером проекта сервера ATL

Мастер проекта сервера ATL позволяет настраивать параметры, используемые при создании проекта. Он предлагает множество возможных вариантов проекта ATL Server. Некоторые элементы можно изменить на страницах окна свойств проекта уже после создания проекта, а некоторые нужно установить в мастере, так как позже это сделать уже будет нельзя. Visual Studio .NET позволяет корректировать любой проект, менять его тип; а вот аналогичное изменение, производимое вручную, займет много времени. При смене типа проекта вы предотвратите появление проблем, просто сохранив нужный код и вставив его в проект, сгенерированный корректным шаблоном проекта в Visual Studio .NET. Знание опций, доступных в мастере проекта сервера ATL, позволит сэкономить время и более детально ознакомиться с этим компонентом.

Параметры проекта

Во вкладке Project Settings (Параметры проекта) мастера проекта сервера ATL (см. рис. 4.7) указывается виртуальный каталог, в который будет записан проект после компиляции. Этот каталог можно сменить в любое время с помощью окна свойств проекта. Вы можете также переименовать проект и каталоги после генерирования мастером проекта сервера ATL файлов программного решения, но возможность генерации одной DLL для хранения кода ISAPI и кода веб-приложения нужно указать до окончания работы мастера.

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

Параметры сервера в мастере проекта сервера ATL

Во вкладке Server Options (Параметры сервера) мастера проекта сервера ATL (см. рис. 4.8) устанавливается поддержка дополнительной интеграции со службами узла сервера и управление сеансами. Следует отметить, что сеанс может записываться в источник данных, имеющий провайдера OLE-DB. Это относится к разработке веб-кластера, когда требуется размещение данных сеанса внутри источника данных, если другие серверы, участвующие в поддержке веб-решения, должны иметь доступ к сеансу.

Если проект сервера ATL создан для функционирования на одном сервере, или если не требуется взаимодействие с другими веб-серверами, использующими сеанс, выберите опцию Memory-Backed Session State Services (Службы состояния сеанса, хранимые в памяти) для обеспечения более высокой производительности. Опция OLE DB-Backed Session State Services (Службы состояния сеанса, хранимые в OLE DB) позволяет расширять программное решение, т.е. установить его в распределенной аппаратной среде без изменения кода. Если программное решение требует поддержки сеансов, отметьте опцию Session Services (Службы сеансов). В зависимости от требуемого уровня поддержки выберите соответствующую опцию хранения: в OLE DB или в памяти.

При генерации мастером кода создается класс с таким же именем, как у проекта, к началу имени присоединяется символ "C", а к концу добавляется слово "Handler". Этот класс будет интерфейсом веб-приложения в IIS за счет включения в себя обработчиков тегов. Пусть проект называется atlServer4 ((см. рис. 4.7), тогда мастер для поддержки обработчиков тегов создаст класс CatlServer4Handler.

Включение любой из следующих опций во вкладке Server Options (Параметры сервера) мастера позволит добавить в класс обработчик кода, объявляющий и инициализирующий указатели на соответствующий класс поддержки.

Если в мастере выбраны опции File Cache (Кэш файлов), Blob Cache (Кэш памяти) и Browser Capabilities Support (Поддержка возможностей браузера), а проект называется SimpleATLServer, то будет сгенерирован класс CSimpleATLServerHandler и записан в заголовок SimpleATLServer.h. В частной секции класса CSimpleATLServerHandler будут сгенерированы следующие объявления с комментариями перед кодом:

// File cache support
//      CComPtr<IFileCache> m_spFileCache;

      // Blob cache support
//      CComPtr<IMemoryCache> m_spBlobCache;

      // Data Source cache support
//      CComPtr<IBrowserCapsSvc> m_spBrowserCaps;

При использовании указателей на File Cache (Кэш файлов), Blob Cache (Кэш памяти) и Browser Capabilities Support (Поддержка возможностей браузера) с каждого из них нужно снять статус комментария. Указатели инициализируются в общей функции ValidateAndExchange. Она включается в каждый класс обработчика, генерируемый мастером проекта сервера ATL, если отмечена опция Validation Support (Поддержка подтверждения) во вкладке Application Options (Параметры приложения) (см. следующий раздел). С фрагментов кода, отвечающих за инициализацию соответствующего указателя, также нужно снять статус комментария.

HTTP_CODE ValidateAndExchange()
{
      // TODO: Put all initialization and validation code here

      // Set the content-type
      m_HttpResponse.SetContentType("text/html");

      // uncomment the service initialization(s) if you want to use
      // a service that was generated with your ISAPI extension


      // Get the IFileCache service from the ISAPI extension
//      if (FAILED(m_spServiceProvider->QueryService
//                  (__uuidof(IFileCache), 
//                  m_spFileCache)))
//            return HTTP_FAIL;

      // Get the IMemoryCache service from the ISAPI extension
//      if (FAILED(m_spServiceProvider->QueryService
//                 (__uuidof(IMemoryCache), 
//                 m_spBlobCache)))
//            return HTTP_FAIL;

      // Get the IBrowserCapsSvc service from the ISAPI extension
//      if (FAILED (m_spServiceProvider->QueryService
//                  (__uuidof(IBrowserCapsSvc), 
//                   m_spBrowserCaps)))
//            return HTTP_FAIL;

      return HTTP_SUCCESS;
}

В ассоциированное расширение ISAPI следует добавить код для поддержки элементов, выбранных во вкладке Server Options (Параметры сервера) мастера. В отличие от кода класса обработчиков код поддержки в расширении ISAPI не является закомментированным, он входит в программное решение независимо от того, используется он или нет. Не включайте поддержку функциональности – это позволит сократить количество ресурсов.

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

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

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

При выборе опции Predefined Performance Counters (Предопределенные счетчики производительности) в расширении ISAPI размещается код, реализующий обновление счетчиков ISAPI для perfmon согласно взаимодействию веб-приложения с IIS. Разработчик не участвует в написании кода, весь код, необходимый для обеспечения функциональности, генерируется мастером в файле реализации расширения ISAPI.

Предопределенными счетчиками производительности являются следующие.

Для поддержки возможностей браузера имеется указатель класса IbrowserCapsSvc и код инициализации, предназначенный для настройки указателя на IbrowserCapsSvc. Если указатель на указатель класса IbrowserCaps передается функции GetCaps класса IbrowserCapsSvc вместе с указателем на контекст сервера, то экземпляр IbrowserCaps позволяет выполнить запрос возможностей браузера. Эта информация определяется экземпляром класса IbrowserCaps с помощью сравнения значения HTTP_USER_AGENT, отправленного веб-серверу с запросом HTTP, с соответствующим значением в файле browsercap.ini (он обычно находится в папке $(windows)\system32\inetsrv\ ). В файле browsercap.ini приведен HTTP User Agent и определены его параметры. Например, для браузера Internet Explorer (IE) 5 в файле browsercap.ini указано следующее:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; IE 5.0
[IE 5.0]
browser=IE
Version=5.0
majorver=5
minorver=0
frames=True
tables=True
cookies=True
backgroundsounds=True
vbscript=True
javaapplets=True
javascript=True
ActiveXControls=True
Win16=False
beta=True
AK=False
SK=False
AOL=False
Update=False

[Mozilla/4.0 (compatible; MSIE 5.*; Windows 95*)]
parent=IE 5.0
platform=Win95
beta=True

[Mozilla/4.0 (compatible; MSIE 5.*; Windows 98*)]
parent=IE 5.0
platform=Win98
beta=True

[Mozilla/4.0 (compatible; MSIE 5.*; Windows NT*)]
parent=IE 5.0
platform=WinNT
beta=True

[Mozilla/4.0 (compatible; MSIE 5.*; Windows 2000*)]
parent=IE 5.0
platform=Win2000
beta=True

[Mozilla/4.0 (compatible; MSIE 5.*)]
parent=IE 5.0

Опция Resource Language (Язык источника) во вкладке Server Options (Параметры сервера) обеспечивает поддержку использования других языков для генерирования текста копии в файлах источников проекта. Необходимо установить Visual Studio .NET с поддержкой языков для нужного ресурса, чтобы открыть доступ к этой опции.

Параметры приложения в мастере проекта сервера ATL

Параметры приложения обычно базируются на особенностях выбранного шаблона проекта (см. рис. 4.9). При создании веб-службы с помощью ATL Server следует отметить опцию Create As Web Service (Создать как веб-службу). Она исключает использование прочих опций вкладки Application Options (Опции приложения). При создании проекта ATL Serverа доступ к этим опциям открыт. Если опция Stencil Processing Support (Поддержка обработки шаблона) не включена, то недоступны два элемента, подчиненные опциям в секции начального файла ответа сервера.

Опция Validation Support (Поддержка подтверждения) обеспечивает функцию ValidateAndExchange в файле заголовка класса обработчика. В других мастерах инициализационный код вставляется в функцию ValidateAndExchange. Эта функция является членом базового класса CRequestHandlerT, предназначенного для замены особым кодом инициализации и подтверждения, связанным с библиотекой DLL веб-приложения. DLL веб-приложения наследуется из класса CRequestHandlerT, и поэтому библиотека DLL веб-приложения также называется DLL-библиотекой обработчика запросов (см. рис. 4.1). CRequestHandlerT осуществляет HTTP-взаимодействия между DLL-библиотекой обработчика запросов и ISAPI, обеспечивая определенный уровень абстракции для ISAPI. Среди прочих возможностей этой библиотеки, наследуемой из класса CRequestHandlerT, можно выделить экземпляры классов m_HttpResponse и m_HttpRequest. Эти классы дают разработчику механизмы чтения и записи запроса или ответа HTTP.

Опция Stencil Processing Support (Поддержка обработки шаблона) добавляет в код демонстрационную функцию hello world и демонстрационный обработчик этой функции. Доступ к области Options For The Initial Server Response File (Опции начального файла ответа сервера) открывается при включении опции Stencil Processing Support (Поддержка обработки шаблона) и позволяет изменять настройки начального файла SRF, сгенерированном мастером.

Если во вкладке Application Options (Параметры приложения) не отмечено ни одной опции, то будет сгенерирована программная структура, аналогичная простому проекту расширения ISAPI. Для многих программистов, работающих с ISAPI и не нуждающихся в функциональности SRF, этот вариант более предпочтителен. ATL Server не нужен файл SRF для функционирования, так как в любой момент можно осуществить прямые вызовы DLL-библиотеки обработчика запросов. Действительно, при выборе опции Generate Combined DLL (Генерировать комбинированную DLL) во вкладке Project Settings (Параметры проекта), если не включены опции вкладки Application Settings (Параметры приложения), будет создана структура, аналогичная проекту расширения ISAPI, в котором отсутствуют многие функции поддержки ATL.

Ниже приведен код класса для DLL-библиотеки обработчика запросов, при создании которого во вкладке Application Options (Параметры приложения) не были включены опции:

// singleDLLNoOptions.h : 
//Defines the ATL Server request handler class
//
#pragma once

[ request_handler("Default") ]
class CsingleDLLNoOptionsHandler
{
private:
      // Put private members here

protected:
      // Put protected members here

public:
      // Put public members here

public:
      HTTP_CODE HandleRequest(AtlServerRequest *pRequest, 
                              IServiceProvider *pProvider)
      {
         // Initialize the CHttpResponse
         CHttpResponse Response;
         BOOL bRet = Response.Initialize(
                                 pRequest->pServerContext);
         if (!bRet)
               return HTTP_FAIL;

         // Set the content-type
         Response.SetContentType("text/html");

         // TODO: Add your handler code here
         // Write the response
         Response << 
            "<html><body><H1>Hello World!</H1></body></html>";
         return HTTP_SUCCESS;
      }
}; // class CsingleDLLNoOptionsHandler

Опции поддержки разработчика в мастере проекта сервера ATL

Вкладка Developer Support Options (Опции поддержки разработчика) мастера проекта сервера ATL содержит три опции (см. рис.4.10).

Опция Attributed Code (Код с атрибутами) размещает в DLL-библиотеке обработчика запросов уже знакомые нам обработчики тегов для связывания тегов, используемых в SRF-файлах, с ее функциями. В качестве примера рассмотрим демонстрационный метод hello world с кодом с атрибутами:

[ tag_name("Hello") ]
HTTP_CODE OnHello(void)
{
      m_HttpResponse << "Hello World!";
      return HTTP_SUCCESS;
}

Код без атрибутов поддерживает имена обработчиков тегов в SRF, связываемые с рассматриваемой функцией. Он используется макрос REPLACEMENT_METHOD_ENTRY для привязки имени тега к имени функции. Отказ от использования атрибутов предпочтителен при решении задачи о присвоении обработчиков тегов функциям в проектах с большим объемом кода. DLL-библиотека обработчика запросов не содержит путаницы тегов, присущей синтаксису тегов в виде скобок; все функции с тегами определяются в одном месте. В следующем листинге приведен фрагмент кода, использующий для функции OnHello обработчики тегов без атрибутов:

// TODO: Add additional tags to the replacement method map
BEGIN_REPLACEMENT_METHOD_MAP(CNonAttributedCodeHandler)
      REPLACEMENT_METHOD_ENTRY("Hello", OnHello)
END_REPLACEMENT_METHOD_MAP()

HTTP_CODE ValidateAndExchange()
{
      // TODO: Put all initialization and validation code here

      // Set the content-type
      m_HttpResponse.SetContentType("text/html");

      return HTTP_SUCCESS;
}

protected:
// Here is an example of how to use 
//a replacement tag with the stencil processor
HTTP_CODE OnHello(void)
{
      m_HttpResponse << "Hello World!";
      return HTTP_SUCCESS;
}

Опция Custom Assert And Trace Hendling Support (Поддержка особых опций отладки) объявляет глобально доступный экземпляр класса CDebugReportHook в DLL-библиотеке расширения ISAPI. С помощью ATLTRACE и других макросов разработчик записывает код в DLL-библиотеку обработчика запросов, исполняемый только в процессе отладки, а также осуществляет вывод данных в программу, предназначенную для считывания каналов с именами типа WebDbg.exe. В следующем листинге объявление CDebugReportHook действительно только в том случае, если определен макрос _DEBUG:

// For custom assert and trace handling with WebDbg.exe
#ifdef _DEBUG
CDebugReportHook g_ReportHook;
#endif

Завершение работы мастера проекта сервера ATL

По окончании генерирования код проекта ATL Server можно выполнить немедленно. Пока в DLL-библиотеке обработчика запросов находится функция, проект можно скомпилировать и реализовать. Если при генерировании проекта использованы опции мастера по умолчанию, то готовый проект соответствует следующим параметрам:

Файлы ответа сервера

Далее нужно выполнить анализ информации, полученной от веб-пользователя, вынесение решения относительно полученных данных и возврат ответа пользователю. Посредством добавления определенного кода в проект NewSimpleATLServer файл SRF веб-приложения Hello World связывается с другим приложением, которое выполняет либо запрос имени и любимого цвета веб-пользователя, либо сообщает пользователю его имя и любимый цвет. После настройки файла SRF можно изменить класс DLL-библиотеки обработчика запросов в соответствии с требованиями SRF.

Теги в файлах ответа сервера

Файл SRF является хорошей альтернативой языкам Extensible Styleshet Language (XSL) или Extensible Stylesheet Language Transformation (XSLT) и веб-формам ASP.NET за счет предоставления механизма форматирования и отображения выходных данных ATL Server при отделении логики представления от бизнес-логики. Представление Design (Дизайн) в ATL Server предоставляет определенный уровень абстракции для доступа к DLL-библиотеке обработчика запросов и записи кода HTML (см. рис. 4.11). Используя теги в файле SRF, можно реализовать упрощенные сценарии, оптимизированные для управления вызовами функций в DLL-библиотеке обработчика запросов, аналогично файлам XSL и XSLT, которые анализируют и управляют содержимым XML. Файл XSL или XSLT содержат в верхней части инструкции для обозначения того, как нужно использовать файл, и в файле SRF имеется такой же элемент. Файл SRF поддерживает упрощенные возможности циклов и вынесения решений, как и файлы XSL и XSLT.

Теги в SRF обозначаются двумя парами фигурных скобок, содержащих внутри аргумент, обычно соответствующий атрибуту тега внутри DLL-библиотеки обработчика запросов. Атрибуты тега в DLL-библиотеке обработчика запросов связаны с функциями, выполняющими определенную задачу и возвращающими данные, предназначенные для вставки в файл SRF. Один файл SRF способен вызвать много DLL-библиотек обработки запросов. Файл SRF может включать в себя другие файлы SRF с помощью тега include и поддерживает комментарии в коде.

Теги Handler и Subhandler

Первым тегом любого файла SRF является тег handler. Тег handler указывает библиотеку DLL, к которой осуществляется доступ при поиске функций, указанных тегами замещения в файле SRF. Также можно указать тег subhandler. В одном файле SRF можно вызвать функции из одной или нескольких DLL-библиотек обработки запросов. В теге handler или subhandler используются псевдонимы, с помощью которых формируются теги замещения для вызова функций из рассматриваемой библиотеки DLL обработчика запросов с применением имени alias.function. Тег handler имеет следующий синтаксис:

{{handler <handler name>.dll/Default}}

По умолчанию Visual Studio .NET записывает файлы DLL в каталог с файлами SRF. Размещение двоичных файлов, как правило, представляет определенный уровень абстракции, отличающийся от кода файлов SRF, поэтому двоичные файлы предпочтительнее записывать в отдельный каталог на сервере. Для этого обычно используется подкаталог корневого веб-каталога или каталог корневого виртуального каталога с именем bin. При использовании подкаталога bin для хранения библиотек DLL тег handler выглядит следующим образом:

{{handler bin\<handler name>.dll/Default}}

Теги замещения

Тег замещения наиболее часто используется в файле SRF. Теги замещения являются точкой доступа разработчика к функциям DLL-библиотек обработки запросов. Тег замещения осуществляет запрос ответа от библиотеки, содержащей нужную функцию, и вставляет ответ в том месте файла SRF, в котором находится тег замещения. Теги замещения поддерживают инструкции для вызова функций, выполняют передачу аргументов функции в DLL-библиотеку обработки запросов. Например, блок if..else..endif можно реализовать с помощью команды {{if<FunctionName>}}, являющейся начальной точкой блока if. Блоки Else и endif обозначаются командами {{else}} и {{endif}} соответственно.

В проекте NewSimpleATLServer SRF вызывает функцию по имени атрибута HaveNameAndColor, как показано в следующем коде. Если HaveNameAndColor возвращает значение "истина", отображаются имя и любимый цвет, введенные пользователем. Если один из элементов неизвестен, то функция HaveNameAndColor возвращает значение "ложь", и SRF запрашивает у пользователя имя, фамилию и любимый цвет. Теги замещения поддерживают инструкции while..endwhile для реализации циклов.

<html>
<HEAD>
</HEAD>
<BODY>
<P>{{//comments can appear before handler tag}}</P>
<P>{{handler bin\NewSimpleATLServer.dll/Default}}</P>
<P>First let me say : {{Hello}}<br>
</P>
<P>{{if HaveNameAndColor}}
</P>
<P>I can rest easy now because I know your name is: 
{{YourName}}</P>
<P>
and your favorite color is: {{YourFavoriteColor}}
<P>
{{else}}
<P>Tell me this:</P>
<FORM id="Form1" action="NewSimpleATLServer.srf" method="post">
<P>First Name <INPUT id="Text1" type="text" name="firstname"></P>
<P>Last Name <INPUT id="Text2" type="text" name="lastname"></P>
<P>Favorite color <INPUT id="Text3" type="text" name="color"></P>
<P>
<INPUT id="Submit1" type="submit" value="Submit" name="Submit1">
</P>
</FORM>
<P>{{endif}}</P>
</BODY>
</html>

Мы видим, что листинг исходного кода файла NewSimpleATLServer.srf (см. рис. 4.11) является документом HTML. Единственным различием между файлом HTML и SRF является присутствие тегов, заключенных в парные фигурные скобки ("{{ }}"). Элементы управления сервера, предоставляемых проектами веб-службы или веб-формы, по умолчанию недоступны в проекте сервера ATL. Расширение файла SRF связано с библиотекой расширения ISAPI, поэтому файл HTM, HTML или любой другой файл можно связать с DLL-библиотекой расширения ISAPI и реализовать его обработку так, как если бы речь шла о файле SRF с расширением .srf.

DLL-библиотека обработки запросов

DLL-библиотека обработки запросов, создаваемая мастером проекта сервера ATL, реализуется таким образом, что разработчик изменяет код в файле заголовка, имя которого отражает имя проекта. Прототип класса с именем C<имя_проекта>Handler находится в файле заголовка. В проекте NewSimpleATLServer классу присвоено имя CNewSimpleATLServerHandler. В следующем листинге файла NewSimpleATLServer.h этот класс выполняет роль шлюза между классами, представляющими создаваемое программное обеспечение для интернета, и файлами SRF. Весь код можно разместить в классе обработки, однако это сделает его сложным для чтения и работы. Наилучшей стратегией в данном случае является использование данного класса для поддержки атрибутов тегов замещения файла SRF и для построения классов системы согласно структуре программы.

// NewSimpleATLServer.h : Defines the ATL Server request handler class
//
#pragma once

[ request_handler("Default") ]
class CNewSimpleATLServerHandler
{
private:
      //locals for holding the state of the class
      CString FName;                  //first name
      CString LName;                  //last name
      CString FavoriteColor;      //name of color

      //flag to identify if color and name are known
      bool HaveNameandColor;      

public:
      //initialization function 
      HTTP_CODE ValidateAndExchange()
      {
       //for debug purposes
       ATLTRACE("ValidateAndExchange started \n");

       //used to validate data passed in
       CValidateContext c;

       //assume that we have everything
       HaveNameandColor = true;
  
       //get the form fields 
       const CHttpRequestParams Formdata = 
             m_HttpRequest.GetFormVars();

       //Check validation failures
       if (VALIDATION_S_OK != 
        Formdata.Validate("firstname", FName, 1, 10000, c))
                   HaveNameandColor = false;

       if (VALIDATION_S_OK != 
        Formdata.Validate("lastname", LName, 1, 10000, c))
                   HaveNameandColor = false;

       if (VALIDATION_S_OK != 
      Formdata.Validate("color", FavoriteColor, 1, 10000, c))
                   HaveNameandColor = false;


       // Set the content-type
       m_HttpResponse.SetContentType("text/html");
  
       ATLTRACE("ValidateAndExchange completed \n");
       return HTTP_SUCCESS;
 }
 
protected:
 [ tag_name(name="Hello") ]
 HTTP_CODE OnHello(void)
 {
       ATLTRACE("OnHello started \n");

       m_HttpResponse << "Hello World!";
  
       ATLTRACE("OnHello completed \n");
       return HTTP_SUCCESS;
 }

 [ tag_name(name = "HaveNameAndColor") ]
 HTTP_CODE OnHaveNameAndColor(void)
 {
       ATLTRACE("OnHaveNameAndColor started \n");

       if (HaveNameandColor)
             return HTTP_SUCCESS;
       else
             return HTTP_S_FALSE;
 }

 [ tag_name(name = "YourName") ]
 HTTP_CODE OnYourName(void)
 {
       m_HttpResponse << FName + " " + LName;

       return HTTP_SUCCESS;
 }

 [ tag_name(name = "YourFavoriteColor") ]
 HTTP_CODE OnYourFavoriteColor(void)
 {
       m_HttpResponse << FavoriteColor;

       return HTTP_SUCCESS;
 }

}; // class CNewSimpleATLServerHandler

Класс CNewSimpleATLServerHandler выполняет следующие задачи:

Весь код проекта NewSimpleATLServer расположен в файле заголовка для упрощения примера. Функция ValidateAndExchange является первой функцией, вызываемой при обработке запроса в DLL-библиотеке обработки, поэтому экземпляр класса m_HttpRequest проверяется на отправленные посредством HTTP данные с помощью функции m_HttpRequest.GetFormVars и размещения данных в экземпляре класса ChttpRequestParams с использованием ссылки Formdata. Функция Validate ссылки Formdata определяет отправление указанного значения ввода, его соответствие заданному диапазону, после чего значение записывается в переменную. Например, для подтверждения введенного значения используется следующая строка фрагмента кода, в которой Fname – это переменная типа Cstring, предназначенная для записи имени пользователя с длиной от 1 до 10 000 символов.

Validate("firstname", FName, 1, 10000, c)

Макрос ATLTRACE повсюду встречается в листинге обработчика CNewSimpleATLServer наряду с различными выражениями отладки в качестве аргументов. ATLTRACE размещает аргумент в окне WebDbg при выполнении на узле (см. рис. 4.12). WebDbg представляет собой утилиту, поставляемую в комплекте со средствами Visual Studio .NET. В группе программ Visual Studio .NET обычно находится ссылка для запуска данной утилиты и именем ISAPI Web Debug Tool.

После запуска утилиту WebDbg нужно присоединить к имени канала AtlsDbgPipe с помощью команды File\Select Pipe\Pipe Name (Файл\Выбрать канал\Имя канала). Отлаживаемый процесс должен иметь разрешение на запись в указанный канал. Аутентификационные данные, под которыми работает IIS, устанавливаются с помощью команды File\Permissions (Файл\Разрешения). Если WebDbg выполняется на том же компьютере, что и веб-сайт, группе Everyone предоставляются разрешение на запись в канал. Если работа сайта осуществляется удаленно, то следует указать аутентификационные данные для определенного компьютера или домена.

Утилита WebDbg принимает через канал сообщения от программы, осуществляющей запись в этот канал. Сообщения по мере записи отображаются в окне WebDbg. Пошаговая обработка кода с помощью Visual Studio .NET IDE является хорошим способом первоначального тестирования кода, однако для использования в тех средах, где будет находиться программное обеспечение после перемещения из среды сервера разработки, целесообразно применение команды trace.

ATLTRACE работает только в конфигурации debug. Если программное решение скомпилировано в конфигурации release, макросы ATLTRACE игнорируются, и не нужно удалять какие-либо коды отладки. При запуске проекта NewSimpleATLServer пользователю отображается фраза hello world. Затем с помощью тега замещения HaveNameAndColor в файле SRF вызывается функция OnHaveNameAndColor. Она проверяет возвращаемое значение локальной переменной HaveNameandColor ("истина" или "ложь"), после чего возвращает соответствующий ответ, т.е. файл SRF либо отображает информацию, либо запрашивает у пользователя имя и любимый цвет. На рисунке 4.13 показан результат выполнения проекта NewSimpleATLServer после ввода пользователем информации. При получении результата, показанного на рисунке, файл SRF определяет значение, возвращенное переменной HaveNameandColor. Поскольку оно истинно, выполняется вызов функции OnYourFavoriteColor и OnYourName с помощью тегов замещения YourFavorityColor и YourName соответственно.