Зміна повідомлень SOAP за допомогою розширень SOAP, Microsoft Docs
Цей розділ присвячений технології попередніх версій. Веб-служби XML та клієнти веб-служб XML повинні створюватися за допомогою Windows Communication Foundation.
Розширення SOAP дозволяють розробникам розширювати функціональні можливості веб-служби, змінюючи повідомлення SOAP, які приймаються та надсилаються веб-службою або її клієнтом. Наприклад, можна реалізувати алгоритм шифрування або стиснення, який виконується з існуючою веб-службою.
Перед тим, як вивчати принцип роботи розширень SOAP, рекомендується ознайомитися з поняттям часу існування веб-служби. Щоб отримати додаткові відомості, див. Схема часу існування веб-служби XML.
Наступний малюнок показує основні етапи виклику, що надходить від клієнта до веб-служби.
Як видно за схемою, платформа .NET Framework серіалізує та десеріалізує XML на обох етапах обробки: як на комп'ютері веб-служби, так і на комп'ютері клієнта. До цієї інфраструктури можна додати розширення SOAP для перевірки або зміни повідомлень SOAP до та після кожного з цих етапів серіалізації та десеріалізації. Наприклад, розширення SOAP для шифрування може зашифрувати XML-частину повідомлення SOAP після того, як .NET Framework серіалізує аргументи клієнта, а потім розшифрувати повідомлення SOAP на веб-сервері, перш ніж .NET Framework десеріалізує повідомлення SOAP. Ці етапи (у яких розширення SOAP може перевірити чи змінити повідомлення SOAP) визначаються переліком SoapMessageStage. У цьому випадку розширення SOAP виконує шифрування на етапіAfterSerialize, а розшифровку - на етапіBeforeDeserialize.
Як правило, якщо розширення SOAP змінює вміст повідомлення SOAP, зміни повинні бути виконані як наклієнта, і на сервері. Т. е., якщо розширення SOAP виконується на клієнті і зашифровує повідомлення SOAP, відповідне розширення SOAP має розшифрувати це повідомлення на сервері. Якщо повідомлення SOAP не розшифровується, інфраструктура ASP.NET не може десеріалізувати повідомлення SOAP в об'єкт.
Зрозуміло, якщо розширення SOAP не змінює повідомлення SOAP (наприклад, якщо воно лише веде журнал таких повідомлень), воно може виконуватися лише на клієнті чи сервері. У цьому випадку одержувачу надходить таке ж повідомлення SOAP, якби розширення SOAP не виконувалося і інфраструктура ASP.NET могла розшифрувати це повідомлення. Крім того, якщо зміна повідомлень SOAP розширенням SOAP не перешкоджає їх десеріалізації, виконання розширення SOAP на обох сторонах (на клієнті та сервері) не обов'язкове.
Розширення класу SOAPExtension
Щоб реалізувати розширення SOAP, створіть клас, успадкований класом SoapExtension. КласSOAPExtension має три методи, які слід (або необхідно) реалізувати:
GetInitializer - абстрактний метод з двома підписами
Спосіб реалізації цих методів наведено у покроковому посібнику "Зміна повідомлення SOAP за допомогою розширень SOAP".
МетодуChainStream передається об'єктStream, і він повертає об'єктStream. Оскільки розширення SOAP виконується на кожному етапіSoapMessageStage і змінює повідомлення SOAP, воно має зчитувати дані з об'єктаStream, що передається методуChainStream, і записувати їх в об'єктStream, що повертається методомChainStream. Тому важливо, щоб у методі ChainStream обидві посилання наStream були призначені змінним-членам.
Клас, успадкований відSoapExtension, використовує методиGetInitializer таInitialize для ініціалізації внутрішніх даних на підставі веб-служби, до якої він застосовується, або її методу. Наприклад, розширення SOAP, що веде журнал SOAP, що надсилаються та одержуються методом веб-служби, може ініціалізувати ім'я файлу для збереження інформації журналу (на підставі імені веб-служби або її методу, з яким виконується розширення SOAP).
Коли інфраструктура веб-служб викликає методGetInitializer, і які параметри передаються цьому методу, залежить від конфігурації розширення SOAP таким чином:
Якщо розширення SOAP налаштовано за допомогою атрибута, інфраструктура веб-служб викликає методGetInitializer, коли доступ до методу (method ) веб-служби здійснюється вперше.
Якщо розширення SOAP налаштовано за допомогою конфігураційного файлу, інфраструктура веб-служб викликає методGetInitializer, лише коли доступ до всієї веб-служби виконується вперше.
Інфраструктура веб-служб кешує об'єкт, який повертається методомGetInitializer. Потім, при кожному виконанні розширення SOAP з цією веб-службою або її методом, інфраструктура передає об'єкт ініціалізатора методуInitialize.
p align="justify"> Фактична розширена обробка (не передбачена в рамках стандартної обробки SOAP) виконується методом ProcessMessage. При кожному викликі інфраструктурою веб-служб методProcessMessage передає (як аргумент) екземпляр класу, успадкованого від SoapMessage, що містить інформацію про повідомлення SOAP саме на цьому етапі. Якщо розширення SOAP виконується з веб-службою, передається об'єкт SoapServerMessage. Якщо воно виконується з клієнтом веб-служби, передається об'єкт SoapClientMessage.
Розширення Soap та винятки
Самі по собі розширення Soapніколи не повинні видавати виняток. Втім, вони можуть додати відомості про виключення як Exception об'єкта SoapMessage, передане методу ProcessMessage.
Вони також можуть виконувати роль обробника винятків для всієї програми, за допомогою тих же можливостей відстежуючи всі винятки в додатку, для якого встановлено розширення SOAP, і виконувати деякі завдання, у тому числі змінювати помилку SOAP, що повертається.
Порядок виклику методів розширення SOAP
У попередній частині цієї статті показано, які методи перевизначає розширення SOAP. Тепер розглянемо порядок дій, у якому інфраструктура веб-служб викликає методи розширення SOAP у міру виклику методу веб-служби. Наступна послідовність передбачає, що розширення SOAP виконується і клієнта, і сервері. Дії, для яких необхідно, щоб розширення SOAP виконувалося і на клієнті, і на сервері, ігноруються платформою .NET Framework, якщо ця умова не виконується.
На стороні клієнта готується повідомлення запиту
Клієнт викликає метод проксі-класу.
На клієнті створюється новий екземпляр розширення SOAP.
Якщо це розширення SOAP виконується з цією веб-службою клієнта вперше, викликається метод GetInitializer розширення SOAP.
Викликається метод ProcessMessage, у своїй SoapMessageStage отримує значенняBeforeSerialize.
ASP.NET на клієнтському комп'ютері серіалізує аргументи методу веб-служби у XML.
Викликається методProcessMessage, причомуSoapMessageStage отримує значенняAfterSerialize.
ASP.NET на клієнтському комп'ютері надсилає повідомлення SOAP через мережу на веб-сервер, на якому розміщена веб-служба.
Сторона сервера отримує повідомлення запиту та готуєвідповідь
ASP.NET на веб-сервері отримує повідомлення SOAP.
На веб-сервері створюється новий екземпляр розширення SOAP.
Якщо це розширення SOAP виконується з цією веб-службою на клієнті вперше на стороні сервера, на веб-сервері викликається методGetInitializer розширення SOAP, що виконується на сервері.
Викликається методInitialize.
Викликається методChainStream.
Викликається методProcessMessage, при цьомуSoapMessageStage отримує значенняBeforeDeserialize.
ASP.NET десеріалізує аргументи у XML.
Викликається методProcessMessage, причомуSoapMessageStage отримує значенняAfterDeserialize.
ASP.NET створює новий екземпляр класу, що реалізує веб-службу, та викликає метод веб-служби, передаючи десеріалізовані аргументи. Цей об'єкт знаходиться на тому ж комп'ютері, що й веб-сервер.
Метод веб-служби виконує його код, і в кінцевому підсумку задає значення, що повертається, і вихідні параметри.
Викликається методProcessMessage, причомуSoapMessageStage отримує значенняBeforeSerialize.
ASP.NET на веб-сервері серіалізує значення, що повертається, і вихідні параметри в XML.
Викликається методProcessMessage, причомуSoapMessageStage отримує значенняAfterSerialize.
ASP.NET відправляє повідомлення SOAP у відповідь по мережі назад на клієнт веб-служби.
Сторона клієнта отримує повідомлення у відповідь
ASP.NET на клієнтському комп'ютері отримує повідомлення SOAP.
Викликається методProcessMessage, при цьомуSoapMessageStage отримує значенняBeforeDeserialize.
ASP.NET десеріалізує XML у значення, що повертається, і вихідні параметри.
Викликається методProcessMessage, при цьомуSoapMessageStage отримує значенняAfterDeserialize.
ASP.NET передає значення, що повертається, і вихідні параметри екземпляру проксі-класу.
Клієнт отримує значення, що повертається, і вихідні параметри.
Реалізація розширення SOAP
Існує два методи запуску розширення SOAP на клієнтському чи серверному додатку. Перший з них полягає в тому, щоб налаштувати програму так, щоб вона запускала розширення. Щоб налаштувати розширення SOAP для виконання з усіма веб-методами всіх веб-служб, особливо vroot, змініть розділ Елемент файлу Web.config. Наступний код показує, що значення атрибутуtype має знаходитися на одному рядку і містити повне ім'я розширення, його версію, мову та регіональні параметри та маркер відкритого ключа підписаного складання.
Другий спосіб полягає в створенні атрибута, що настроюється, який застосовується до методу веб-служби. Щоб створити атрибут, що настроюється, створіть клас, успадкований від SoapExtensionAttribute. Докладніші відомості про створення атрибута, що настроюється, див. у розділі Як реалізувати розширення SOAP. Додаткові відомості про створення атрибутів, що настроюються, див. у статті "Створення атрибутів, що настроюються".
| При реалізації розширення SOAP слід враховувати можливість атаки типу "відмова в обслуговуванні", якщо розширення використовує XmlTextReader для читання потоку даних. Один із способів запобігти такій атакі – забезпечити присвоєння властивості ProhibitDtd значенняtrue. |
Пріоритети та групи з пріоритетів
За допомогою атрибутів або конфігураційного файлу можна призначити розширенням SOAP пріоритети, які допоможуть визначити відносний порядок виконання.декількох розширень SOAP, налаштованих виконання з методом XML-веб-службы. Чим вище пріоритет розширення SOAP, тим швидше воно буде виконано (щодо повідомлення SOAP, яке надсилається або приймається по мережі в даний момент). Розширення SOAP можуть належати до будь-якої з трьох груп за пріоритетами. У кожній групі властивістьpriority визначає пріоритети окремих елементів. Чим нижчим є значення властивостіpriority, тим вище його відносний пріоритет (0 — вищий пріоритет).
Розширення SOAP поділяються на наступні три групи за відносними пріоритетами: налаштовані за допомогою атрибута, задані у файлі конфігурації з параметромgroup, що має значення0, та зі значенням1 для цього параметра. Порядок їхніх пріоритетів наступний:
Група з найвищим пріоритетом: розширення SOAP, налаштовані за допомогою конфігураційного файлу, для яких параметрgroup має значення0.
Група із середнім пріоритетом: розширення SOAP, налаштовані за допомогою атрибута.
Група з нижчим пріоритетом: розширення SOAP, налаштовані за допомогою конфігураційного файлу, для яких параметрgroup має значення1.