Využívání webové služby ASP.NET (ASMX)Consume an ASP.NET Web Service (ASMX)

Stažení ukázky stažení ukázkyDownload Sample Download the sample

ASMX nabízí možnost vytvářet webové služby, které odesílají zprávy pomocí protokolu SOAP (Simple Object Access Protocol). Protokol SOAP je nezávislý na platformě a jazyk nezávislý na platformě pro vytváření a přístup k webovým službám. Uživatelé služby ASMX nepotřebují znát žádné informace o platformě, objektovém modelu nebo programovacím jazyce, který se používá k implementaci služby. Potřebují pouze pochopit, jak odesílat a přijímat zprávy SOAP. Tento článek ukazuje, jak ze aplikace využívat službu protokolu reasmx :::no-loc(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 :::no-loc(Xamarin.Forms)::: application.

Zpráva SOAP je dokument XML, který obsahuje následující prvky:A SOAP message is an XML document containing the following elements:

  • Kořenový element s názvem obálka , který IDENTIFIKUJE dokument XML jako zprávu SOAP.A root element named Envelope that identifies the XML document as a SOAP message.
  • Volitelný element záhlaví , který obsahuje informace specifické pro aplikaci, například ověřovací data.An optional Header element that contains application-specific information such as authentication data. Je-li element header přítomen, musí se jednat o první podřízený prvek elementu obálky .If the Header element is present it must be the first child element of the Envelope element.
  • Povinný prvek těla , který obsahuje zprávu SOAP, která je určená pro příjemce.A required Body element that contains the SOAP message intended for the recipient.
  • Volitelný prvek chyby , který se používá k označení chybových zpráv.An optional Fault element that's used to indicate error messages. Pokud je prvek Fault přítomen, musí být podřízeným prvkem elementu body .If the Fault element is present, it must be a child element of the Body element.

Protokol SOAP může pracovat přes mnoho přenosových protokolů, včetně protokolů HTTP, SMTP, TCP a UDP.SOAP can operate over many transport protocols, including HTTP, SMTP, TCP, and UDP. Služba ASMX ale může pracovat jenom přes HTTP.However, an ASMX service can only operate over HTTP. Platforma Xamarin podporuje standardní implementace protokolu SOAP 1,1 přes protokol HTTP a zahrnuje podporu pro spoustu standardních konfigurací služby ASMX.The Xamarin platform supports standard SOAP 1.1 implementations over HTTP, and this includes support for many of the standard ASMX service configurations.

Tato ukázka zahrnuje mobilní aplikace, které běží na fyzických nebo emulovaných zařízeních, a službu ASMX, která poskytuje metody pro získání, přidání, úpravu a odstranění dat.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. Když se spustí mobilní aplikace, připojí se k místně hostované službě ASMX, jak je znázorněno na následujícím snímku obrazovky:When the mobile applications are run, they connect to the locally-hosted ASMX service as shown in the following screenshot:

Ukázková aplikace

Poznámka

V systému iOS 9 a novějších vynutila služba Transport Security Security (ATS) zabezpečená připojení mezi internetovými prostředky (například back-end serverem aplikace) a aplikací, což zabrání nechtěnému zpřístupnění citlivých informací.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. Vzhledem k tomu, že služba ATS je ve výchozím nastavení povolená v aplikacích vytvořených pro iOS 9, budou se všechna připojení vztahovat na požadavky na zabezpečení ATS.Since ATS is enabled by default in apps built for iOS 9, all connections will be subject to ATS security requirements. Pokud připojení tyto požadavky nesplňují, dojde k jejich selhání s výjimkou.If connections do not meet these requirements, they will fail with an exception. ATS se může stát, že není možné používat HTTPS protokol a zabezpečenou komunikaci pro internetové prostředky.ATS can be opted out of if it is not possible to use the HTTPS protocol and secure communication for internet resources. Toho je možné dosáhnout aktualizací souboru info. plist aplikace.This can be achieved by updating the app's Info.plist file. Další informace najdete v tématu zabezpečení přenosu aplikací.For more information see App Transport Security.

Využívání webové službyConsume the web service

Služba ASMX poskytuje následující operace:The ASMX service provides the following operations:

OperaceOperation DescriptionDescription ParametryParameters
GetTodoItemsGetTodoItems Získat seznam úkolůGet a list of to-do items
CreateTodoItemCreateTodoItem Vytvořit novou položku úkolůCreate a new to-do item Serializovaná TodoItem XMLAn XML serialized TodoItem
EditTodoItemEditTodoItem Aktualizace položky úkolůUpdate a to-do item Serializovaná TodoItem XMLAn XML serialized TodoItem
DeleteTodoItemDeleteTodoItem Odstranění položky úkolůDelete a to-do item Serializovaná TodoItem XMLAn XML serialized TodoItem

Další informace o datovém modelu používaném v aplikaci najdete v tématu modelování dat.For more information about the data model used in the application, see Modeling the data.

Vytvoření proxy serveru TodoServiceCreate the TodoService proxy

Proxy třída, která se nazývá TodoService , rozšiřuje SoapHttpClientProtocol a poskytuje metody pro komunikaci se službou ASMX přes HTTP.A proxy class, called TodoService, extends SoapHttpClientProtocol and provides methods for communicating with the ASMX service over HTTP. Proxy je vygenerován přidáním webového odkazu do každého projektu specifického pro platformu v aplikaci Visual Studio 2019 nebo 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. Webový odkaz generuje metody a události pro každou akci definovanou v dokumentu WSDL (Web Services Description Language) služby.The web reference generates methods and events for each action defined in the service's Web Services Description Language (WSDL) document.

Například GetTodoItems Akce služby má za následek GetTodoItemsAsync metodu a GetTodoItemsCompleted událost v proxy serveru.For example, the GetTodoItems service action results in a GetTodoItemsAsync method and a GetTodoItemsCompleted event in the proxy. Vygenerovaná metoda má návratový typ void a vyvolá GetTodoItems akci u nadřazené SoapHttpClientProtocol třídy.The generated method has a void return type and invokes the GetTodoItems action on the parent SoapHttpClientProtocol class. Když vyvolaná metoda obdrží odpověď od služby, aktivuje GetTodoItemsCompleted událost a poskytne data odpovědi v rámci Result vlastnosti události.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.

Vytvoření implementace ISoapServiceCreate the ISoapService implementation

Pokud chcete sdílenému projektu pro různé platformy povolit spolupráci se službou, ukázka definuje ISoapService rozhraní, které následuje za asynchronním programovacím modelem úkolu v jazyce 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#. Každá Platforma implementuje ISoapService k vystavení proxy serveru pro konkrétní platformu.Each platform implements the ISoapService to expose the platform-specific proxy. Ukázka používá TaskCompletionSource objekty k zveřejnění proxy serveru jako asynchronního rozhraní úlohy.The sample uses TaskCompletionSource objects to expose the proxy as a task asynchronous interface. Podrobnosti o použití TaskCompletionSource najdete v implementacích každého typu akce v níže uvedených částech.Details on using TaskCompletionSource are found in the implementations of each action type in the sections below.

Ukázka SoapService :The sample SoapService:

  1. Vytvoří instanci TodoService jako instanci úrovně třídy.Instantiates the TodoService as a class-level instance
  2. Vytvoří kolekci s názvem Items pro ukládání TodoItem objektů.Creates a collection called Items to store TodoItem objects
  3. Určuje vlastní koncový bod pro volitelnou Url vlastnost na 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;
        ...
    }
}

Vytváření objektů pro přenos datCreate data transfer objects

Ukázková aplikace používá TodoItem třídu k modelování dat.The sample application uses the TodoItem class to model data. Chcete-li uložit TodoItem položku do webové služby, musí být nejprve převedena na typ generovaný proxy serverem TodoItem .To store a TodoItem item in the web service it must first be converted to the proxy generated TodoItem type. To je provedeno ToASMXServiceTodoItem metodou, jak je znázorněno v následujícím příkladu kódu: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
    };
}

Tato metoda vytvoří novou ASMService.TodoItem instanci a nastaví každou vlastnost na identickou vlastnost z TodoItem instance.This method creates a new ASMService.TodoItem instance, and sets each property to the identical property from the TodoItem instance.

Podobně platí, že když jsou data načítána z webové služby, musí být převedena z typu vygenerovaného proxy TodoItem na TodoItem instanci.Similarly, when data is retrieved from the web service, it must be converted from the proxy generated TodoItem type to a TodoItem instance. To je dosaženo FromASMXServiceTodoItem metodou, jak je znázorněno v následujícím příkladu kódu: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
    };
}

Tato metoda načte data z typu generovaného proxy TodoItem a nastaví je v nově vytvořené TodoItem instanci.This method retrieves the data from the proxy generated TodoItem type and sets it in the newly created TodoItem instance.

Načtení datRetrieve data

ISoapServiceRozhraní očekává, že RefreshDataAsync Metoda vrátí hodnotu Task s kolekcí položek.The ISoapService interface expects the RefreshDataAsync method to return a Task with the item collection. TodoService.GetTodoItemsAsyncMetoda však vrátí typ void.However, the TodoService.GetTodoItemsAsync method returns void. Pro splnění vzoru rozhraní musíte zavolat GetTodoItemsAsync , počkat na GetTodoItemsCompleted vyvolání události a naplnit kolekci.To satisfy the interface pattern, you must call GetTodoItemsAsync, wait for the GetTodoItemsCompleted event to fire, and populate the collection. To umožňuje vrátit platnou kolekci do uživatelského rozhraní.This allows you to return a valid collection to the UI.

Následující příklad vytvoří nový TaskCompletionSource , zahájí asynchronní volání v RefreshDataAsync metodě a očekává operátor, který Task poskytuje TaskCompletionSource .The example below creates a new TaskCompletionSource, begins the async call in the RefreshDataAsync method, and awaits the Task provided by the TaskCompletionSource. Když TodoService_GetTodoItemsCompleted je obslužná rutina události vyvolána, naplní Items kolekci a aktualizuje 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);
        }
    }

    ...
}

Další informace naleznete v tématu asynchronní programování modelu a TPL a tradiční .NET Framework asynchronní programování.For more information, see Asynchronous Programming Model and TPL and Traditional .NET Framework Asynchronous Programming.

Vytvoření nebo úprava datCreate or edit data

Při vytváření nebo úpravách dat je nutné implementovat ISoapService.SaveTodoItemAsync metodu.When you create or edit data, you must implement the ISoapService.SaveTodoItemAsync method. Tato metoda zjišťuje, zda TodoItem je nová nebo aktualizovaná položka a volá odpovídající metodu todoService objektu.This method detects whether the TodoItem is a new or updated item and calls the appropriate method on the todoService object. CreateTodoItemCompleted EditTodoItemCompleted Obslužné rutiny události a by měly být také implementovány, abyste věděli, kdy todoService obdržela odpověď od služby ASMX (mohou být kombinovány do jediné obslužné rutiny, protože provádějí stejnou operaci).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). Následující příklad ukazuje implementaci obslužné rutiny rozhraní a události a také TaskCompletionSource objekt použitý k asynchronnímu provozování: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);
    }

    ...
}

Odstranění datDelete data

Odstranění dat vyžaduje podobnou implementaci.Deleting data requires a similar implementation. Definujte TaskCompletionSource , Implementujte obslužnou rutinu události a ISoapService.DeleteTodoItemAsync metodu: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);
    }

    ...
}

Otestování webové službyTest the web service

Testování fyzických nebo emulovaných zařízení pomocí místně hostované služby vyžaduje, aby byla na místě vlastní konfigurace služby IIS, adresy koncových bodů a pravidla brány firewall.Testing physical or emulated devices with a locally-hosted service requires custom IIS Configuration, endpoint addresses, and firewall rules to be in place. Další informace o tom, jak nastavit prostředí pro testování, najdete v tématu Konfigurace vzdáleného přístupu pro IIS Express.For more detail on how to set up your environment for testing, see the Configure remote access to IIS Express. Jediným rozdílem mezi testováním WCF a ASMX je číslo portu TodoService.The only difference between testing WCF and ASMX is the port number of the TodoService.