Использование службы веб-ASP.NET (ASMX)Consuming an ASP.NET Web Service (ASMX)

Загрузить образец загрузить примерDownload Sample Download the sample

ASMX предоставляет возможность создавать веб-служб, которые отправляют сообщения, используя Simple Object Access Protocol (SOAP). SOAP — это протокол независимо от платформы и независимый от языка, для создания и вызова веб-служб. Потребителям службы ASMX не нужно ничего знать об используемой платформе, объектной модели или язык программирования, используемый для реализации службы. Они должны понять, как отправлять и получать сообщения SOAP. В этой статье показано, как использовать службу ASMX SOAP из приложения Xamarin.Forms.ASMX provides the ability to build web services that send messages using the Simple Object Access Protocol (SOAP). SOAP is a platform-independent and language-independent protocol for building and accessing web services. Consumers of an ASMX service do not need to know anything about the platform, object model, or programming language used to implement the service. They only need to understand how to send and receive SOAP messages. This article demonstrates how to consume an ASMX SOAP service from a Xamarin.Forms application.

Сообщение SOAP — это документ XML, содержащий следующие элементы:A SOAP message is an XML document containing the following elements:

  • Корневой элемент с именем конверт , идентифицирующий XML-документа, как сообщение SOAP.A root element named Envelope that identifies the XML document as a SOAP message.
  • Необязательный заголовок элемент, содержащий сведения о приложении, такие как данные проверки подлинности.An optional Header element that contains application-specific information such as authentication data. Если заголовок присутствует элемент он должен быть первый дочерний элемент элемента конверт элемент.If the Header element is present it must be the first child element of the Envelope element.
  • Обязательный текст элемент, содержащий сообщение SOAP, предназначенное для получателя.A required Body element that contains the SOAP message intended for the recipient.
  • Необязательный сбоя элемент, который используется для указания сообщения об ошибках.An optional Fault element that's used to indicate error messages. Если сбоя элемент присутствует, он должен быть дочерним элементом элемента текст элемент.If the Fault element is present, it must be a child element of the Body element.

SOAP может работать много транспортных протоколов, включая HTTP, SMTP, TCP и UDP.SOAP can operate over many transport protocols, including HTTP, SMTP, TCP, and UDP. Тем не менее службы ASMX могут работать только по протоколу HTTP.However, an ASMX service can only operate over HTTP. Платформа Xamarin поддерживает стандартные реализации SOAP 1.1 по протоколу HTTP, и он также поддерживает многие из стандартных конфигураций службы ASMX.The Xamarin platform supports standard SOAP 1.1 implementations over HTTP, and this includes support for many of the standard ASMX service configurations.

Этот пример включает мобильных приложений, работающих на устройствах физическое или эмулируемое и службы ASMX, предоставляющий методы для получения, добавления, изменения и удаления данных.This sample includes the mobile applications that run on physical or emulated devices, and an ASMX service that provides methods to get, add, edit, and delete data. При запуске приложений для мобильных устройств, они подключаются к службе локально размещенные ASMX, как показано на следующем снимке экрана:When the mobile applications are run, they connect to the locally-hosted ASMX service as shown in the following screenshot:

Примечание

В iOS 9 и более поздней версии приложение Transport Security (ATS) обеспечивает безопасных соединений между Интернет-ресурсов (например, server серверной части приложения) и приложения, тем самым предотвращая случайное раскрытие конфиденциальной информации.In iOS 9 and greater, App Transport Security (ATS) enforces secure connections between internet resources (such as the app's back-end server) and the app, thereby preventing accidental disclosure of sensitive information. Поскольку ATS включена по умолчанию в приложениях, созданных для iOS 9, все подключения будут применяться требования к безопасности ATS.Since ATS is enabled by default in apps built for iOS 9, all connections will be subject to ATS security requirements. Если соединения не удовлетворяют этим требованиям, они вызовут сбой с исключением.If connections do not meet these requirements, they will fail with an exception. Если невозможно использовать из могут быть присоединены ATS HTTPS протокола и безопасный обмен данными для Интернет-ресурсов.ATS can be opted out of if it is not possible to use the HTTPS protocol and secure communication for internet resources. Это достигается путем обновления приложения Info.plist файла.This can be achieved by updating the app's Info.plist file. Дополнительные сведения см. в разделе безопасность транспорта приложения.For more information see App Transport Security.

Использование веб-службыConsume the web service

Служба ASMX предоставляет следующие операции:The ASMX service provides the following operations:

ОперацияOperation ОписаниеDescription ПараметрыParameters
GetTodoItemsGetTodoItems Получение списка элементов задачGet a list of to-do items
CreateTodoItemCreateTodoItem Создать новый элемент списка делCreate a new to-do item XML-сериализации TodoItemAn XML serialized TodoItem
EditTodoItemEditTodoItem Обновление элемента задачиUpdate a to-do item XML-сериализации TodoItemAn XML serialized TodoItem
DeleteTodoItemDeleteTodoItem Удаление элемента задачиDelete a to-do item XML-сериализации TodoItemAn XML serialized TodoItem

Дополнительные сведения о модели данных, используемых в приложении, см. в разделе моделирования данных.For more information about the data model used in the application, see Modeling the data.

Создание прокси-сервер TodoServiceCreate the TodoService proxy

Класс прокси-сервера с именем TodoService, расширяет SoapHttpClientProtocol и предоставляет методы для взаимодействия со службой ASMX по протоколу HTTP.A proxy class, called TodoService, extends SoapHttpClientProtocol and provides methods for communicating with the ASMX service over HTTP. Прокси создается путем добавления веб-ссылки для каждого проекта под конкретную платформу в 2019 г. Visual Studio или Visual Studio 2017.The proxy is generated by adding a web reference to each platform-specific project in Visual Studio 2019 or Visual Studio 2017. Веб-ссылки создает методы и события для каждого действия, определенного в документе языка описания служб (WSDL) для службы.The web reference generates methods and events for each action defined in the service's Web Services Description Language (WSDL) document.

Например GetTodoItems службы приводит к тому GetTodoItemsAsync метод и GetTodoItemsCompleted событие в прокси-сервер.For example, the GetTodoItems service action results in a GetTodoItemsAsync method and a GetTodoItemsCompleted event in the proxy. Созданный метод имеет возвращаемый тип void и вызывает GetTodoItems действия на родительском SoapHttpClientProtocol класса.The generated method has a void return type and invokes the GetTodoItems action on the parent SoapHttpClientProtocol class. Когда вызванный метод получает ответ от службы, он срабатывает GetTodoItemsCompleted событий и предоставляет данные ответа в событии Result свойство.When the invoked method receives a response from the service, it fires the GetTodoItemsCompleted event and provides the response data within the event's Result property.

Создать реализацию ISoapServiceCreate the ISoapService implementation

Чтобы включить общий, кросс платформенных проект для работы со службой, в образце определяется ISoapService интерфейса, которые соответствуют задачи модели асинхронного программирования в C# .To enable the shared, cross-platform project to work with the service, the sample defines the ISoapService interface, which follows the Task asynchronous programming model in C#. Каждая платформа реализует ISoapService для предоставления платформы прокси-сервер.Each platform implements the ISoapService to expose the platform-specific proxy. В образце используется TaskCompletionSource объектов для предоставления прокси-сервер как интерфейс асинхронной задачи.The sample uses TaskCompletionSource objects to expose the proxy as a task asynchronous interface. Сведения об использовании TaskCompletionSource находятся в реализациях каждый тип действия в следующих разделах.Details on using TaskCompletionSource are found in the implementations of each action type in the sections below.

Образец SoapService:The sample SoapService:

  1. Создает экземпляр TodoService как экземпляр уровня классаInstantiates the TodoService as a class-level instance
  2. Создает коллекцию с именем Items для хранения TodoItem объектовCreates a collection called Items to store TodoItem objects
  3. Указывает настраиваемую конечную точку для необязательного Url свойство TodoServiceSpecifies a custom endpoint for the optional Url property on the TodoService
public class SoapService : ISoapService
{
    ASMXService.TodoService todoService;
    public List<TodoItem> Items { get; private set; } = new List<TodoItem>();

    public SoapService ()
    {
        todoService = new ASMXService.TodoService ();
        todoService.Url = Constants.SoapUrl;
        ...
    }
}

Создание объектов передачи данныхCreate data transfer objects

В примере приложения используется TodoItem для модели данных.The sample application uses the TodoItem class to model data. Для хранения TodoItem элемента в веб-службы, оно сначала должно быть преобразовано в прокси, созданный TodoItem типа.To store a TodoItem item in the web service it must first be converted to the proxy generated TodoItem type. Это достигается путем ToASMXServiceTodoItem метод, как показано в следующем примере кода:This is accomplished by the ToASMXServiceTodoItem method, as shown in the following code example:

ASMXService.TodoItem ToASMXServiceTodoItem (TodoItem item)
{
    return new ASMXService.TodoItem {
        ID = item.ID,
        Name = item.Name,
        Notes = item.Notes,
        Done = item.Done
    };
}

Этот метод создает новую ASMService.TodoItem экземпляра и задает каждое свойство в свойстве идентичные из TodoItem экземпляра.This method creates a new ASMService.TodoItem instance, and sets each property to the identical property from the TodoItem instance.

Аналогичным образом, при получении данных из веб-службы, оно должно быть преобразовано из прокси, созданный TodoItem тип TodoItem экземпляра.Similarly, when data is retrieved from the web service, it must be converted from the proxy generated TodoItem type to a TodoItem instance. Это осуществляется с помощью FromASMXServiceTodoItem метод, как показано в следующем примере кода:This is accomplished with the FromASMXServiceTodoItem method, as shown in the following code example:

static TodoItem FromASMXServiceTodoItem (ASMXService.TodoItem item)
{
    return new TodoItem {
        ID = item.ID,
        Name = item.Name,
        Notes = item.Notes,
        Done = item.Done
    };
}

Этот метод получает данные из прокси, созданный TodoItem введите и задает его в только что созданный TodoItem экземпляра.This method retrieves the data from the proxy generated TodoItem type and sets it in the newly created TodoItem instance.

Получить данныеRetrieve data

ISoapService Ожидает, что интерфейс RefreshDataAsync метод для возврата Task с коллекцией элементов.The ISoapService interface expects the RefreshDataAsync method to return a Task with the item collection. Тем не менее TodoService.GetTodoItemsAsync метод возвращает значение void.However, the TodoService.GetTodoItemsAsync method returns void. Чтобы соответствует шаблону интерфейса, необходимо вызвать GetTodoItemsAsync, дождитесь GetTodoItemsCompleted событий включался и заполнения коллекции.To satisfy the interface pattern, you must call GetTodoItemsAsync, wait for the GetTodoItemsCompleted event to fire, and populate the collection. Это позволяет возвращать допустимую коллекцию в пользовательский интерфейс.This allows you to return a valid collection to the UI.

В приведенном ниже примере создает новую TaskCompletionSource, начинает асинхронный вызов в RefreshDataAsync метод и ожидает Task предоставляемые TaskCompletionSource.The example below creates a new TaskCompletionSource, begins the async call in the RefreshDataAsync method, and awaits the Task provided by the TaskCompletionSource. Когда TodoService_GetTodoItemsCompleted обработчик событий вызывается он заполняет Items коллекции и обновления TaskCompletionSource:When the TodoService_GetTodoItemsCompleted event handler is invoked it populates the Items collection and updates the TaskCompletionSource:

public class SoapService : ISoapService
{
    TaskCompletionSource<bool> getRequestComplete = null;
    ...

    public SoapService()
    {
        ...
        todoService.GetTodoItemsCompleted += TodoService_GetTodoItemsCompleted;
    }

    public async Task<List<TodoItem>> RefreshDataAsync()
    {
        getRequestComplete = new TaskCompletionSource<bool>();
        todoService.GetTodoItemsAsync();
        await getRequestComplete.Task;
        return Items;
    }

    private void TodoService_GetTodoItemsCompleted(object sender, ASMXService.GetTodoItemsCompletedEventArgs e)
    {
        try
        {
            getRequestComplete = getRequestComplete ?? new TaskCompletionSource<bool>();

            Items = new List<TodoItem>();
            foreach (var item in e.Result)
            {
                Items.Add(FromASMXServiceTodoItem(item));
            }
            getRequestComplete?.TrySetResult(true);
        }
        catch (Exception ex)
        {
            Debug.WriteLine(@"\t\tERROR {0}", ex.Message);
        }
    }

    ...
}

Дополнительные сведения см. в разделе модели асинхронного программирования и TPL и традиционное .NET Framework асинхронное программирование.For more information, see Asynchronous Programming Model and TPL and Traditional .NET Framework Asynchronous Programming.

Создание или изменение данныхCreate or edit data

При создании или изменении данных, необходимо реализовать ISoapService.SaveTodoItemAsync метод.When you create or edit data, you must implement the ISoapService.SaveTodoItemAsync method. Этот метод также обнаруживает ли TodoItem — это новый или обновленный элемент и вызывает соответствующий метод для todoService объекта.This method detects whether the TodoItem is a new or updated item and calls the appropriate method on the todoService object. CreateTodoItemCompleted И EditTodoItemCompleted обработчики событий также должен быть реализован, чтобы знать, когда todoService получил ответ от службы ASMX (они могут быть объединены в один обработчик поскольку они выполняют ту же операцию).The CreateTodoItemCompleted and EditTodoItemCompleted event handlers should also be implemented so you know when the todoService has received a response from the ASMX service (these can be combined into a single handler because they perform the same operation). Ниже приведен пример реализации обработчика интерфейс и событий, а также TaskCompletionSource объект, используемый для работать асинхронно:The following example demonstrates the interface and event handler implementations, as well as the TaskCompletionSource object used to operate asynchronously:

public class SoapService : ISoapService
{
    TaskCompletionSource<bool> saveRequestComplete = null;
    ...

    public SoapService()
    {
        ...
        todoService.CreateTodoItemCompleted += TodoService_SaveTodoItemCompleted;
        todoService.EditTodoItemCompleted += TodoService_SaveTodoItemCompleted;
    }

    public async Task SaveTodoItemAsync (TodoItem item, bool isNewItem = false)
    {
        try
        {
            var todoItem = ToASMXServiceTodoItem(item);
            saveRequestComplete = new TaskCompletionSource<bool>();
            if (isNewItem)
            {
                todoService.CreateTodoItemAsync(todoItem);
            }
            else
            {
                todoService.EditTodoItemAsync(todoItem);
            }
            await saveRequestComplete.Task;
        }
        catch (SoapException se)
        {
            Debug.WriteLine("\t\t{0}", se.Message);
        }
        catch (Exception ex)
        {
            Debug.WriteLine("\t\tERROR {0}", ex.Message);
        }
    }

    private void TodoService_SaveTodoItemCompleted(object sender, System.ComponentModel.AsyncCompletedEventArgs e)
    {
        saveRequestComplete?.TrySetResult(true);
    }

    ...
}

Удаление данныхDelete data

Для удаления данных требуется похожая реализация.Deleting data requires a similar implementation. Определение TaskCompletionSource, Реализуйте обработчик события и ISoapService.DeleteTodoItemAsync метод:Define a TaskCompletionSource, implement an event handler, and the ISoapService.DeleteTodoItemAsync method:

public class SoapService : ISoapService
{
    TaskCompletionSource<bool> deleteRequestComplete = null;
    ...

    public SoapService()
    {
        ...
        todoService.DeleteTodoItemCompleted += TodoService_DeleteTodoItemCompleted;
    }

    public async Task DeleteTodoItemAsync (string id)
    {
        try
        {
            deleteRequestComplete = new TaskCompletionSource<bool>();
            todoService.DeleteTodoItemAsync(id);
            await deleteRequestComplete.Task;
        }
        catch (SoapException se)
        {
            Debug.WriteLine("\t\t{0}", se.Message);
        }
        catch (Exception ex)
        {
            Debug.WriteLine("\t\tERROR {0}", ex.Message);
        }
    }

    private void TodoService_DeleteTodoItemCompleted(object sender, System.ComponentModel.AsyncCompletedEventArgs e)
    {
        deleteRequestComplete?.TrySetResult(true);
    }

    ...
}

Тестирование веб-службыTest the web service

Тестирование физическое или эмулируемое устройств с помощью локально размещенной службы требует настраиваемой конфигурации IIS, адреса конечных точек и правил брандмауэра на месте.Testing physical or emulated devices with a locally-hosted service requires custom IIS Configuration, endpoint addresses, and firewall rules to be in place. Дополнительные сведения о том, как настроить среду для тестирования, см. в разделе настроить удаленный доступ к IIS Express.For more detail on how to set up your environment for testing, see the Configure remote access to IIS Express. Единственное различие между WCF и ASMX тестирования — номер порта из TodoService.The only difference between testing WCF and ASMX is the port number of the TodoService.