Úvod k webovým službám

  • Článek

Tato příručka ukazuje, jak využívat různé technologie webových služeb. Zahrnutá témata zahrnují komunikaci se službami REST, službami SOAP a službami Windows Communication Foundation.

Aby fungovalo správně, mnoho mobilních aplikací závisí na cloudu a integrace webových služeb do mobilních aplikací je běžným scénářem. Platforma Xamarin podporuje využívání různých technologií webových služeb a zahrnuje integrované a třetí strany podporu pro využívání služeb RESTful, ASMX a Windows Communication Foundation (WCF).

Pro zákazníky používající Xamarin.Forms existují úplné příklady použití každé z těchto technologií v dokumentaci k webovým službám Xamarin.Forms.

Důležité

V iOSu 9 vynucuje služba App Transport Security (ATS) zabezpečená připojení mezi internetovými prostředky (jako je back-endový server aplikace) a aplikací, čímž brání náhodnému zpřístupnění citlivých informací. Vzhledem k tomu, že služba ATS je ve výchozím nastavení povolená v aplikacích vytvořených pro iOS 9, budou všechna připojení podléhat požadavkům na zabezpečení ATS. Pokud připojení nesplňují tyto požadavky, dojde k selhání s výjimkou.

AtS můžete odhlásit, pokud není možné používat HTTPS protokol a zabezpečenou komunikaci pro internetové prostředky. Toho lze dosáhnout aktualizací souboru Info.plist aplikace. Další informace najdete v tématu App Transport Security.

REST

Representational State Transfer (REST) je styl architektury pro vytváření webových služeb. Požadavky REST se provádějí přes HTTP pomocí stejných příkazů HTTP, které webové prohlížeče používají k načtení webových stránek a odesílání dat na servery. Příkazy jsou:

  • GET – tato operace slouží k načtení dat z webové služby.
  • POST – tato operace slouží k vytvoření nové položky dat ve webové službě.
  • PUT – tato operace slouží k aktualizaci položky dat ve webové službě.
  • PATCH – tato operace se používá k aktualizaci položky dat ve webové službě popisem sady pokynů o tom, jak se má položka upravit. Toto sloveso se v ukázkové aplikaci nepoužívá.
  • DELETE – tato operace slouží k odstranění položky dat ve webové službě.

Rozhraní API webové služby, která dodržují REST, se nazývají rozhraní RESTful API a definují se pomocí:

  • Základní identifikátor URI.
  • Metody HTTP, například GET, POST, PUT, PATCH nebo DELETE.
  • Typ média pro data, například JavaScript Object Notation (JSON).

Jednoduchost rest pomohla, aby byla primární metodou pro přístup k webovým službám v mobilních aplikacích.

Využívání služeb REST

Existuje celá řada knihoven a tříd, které lze použít k využívání služeb REST, a následující pododdíly je probírají. Další informace o využívání služby REST naleznete v tématu Využití webové služby RESTful.

HttpClient

Klientské knihovny Microsoft HTTP poskytují HttpClient třídu, která se používá k odesílání a přijímání požadavků přes protokol HTTP. Poskytuje funkce pro odesílání požadavků HTTP a příjem odpovědí HTTP z prostředku identifikovaného identifikátorem URI. Každý požadavek se odešle jako asynchronní operace. Další informace o asynchronníchoperacích

Třída HttpResponseMessage představuje zprávu odpovědi HTTP přijatou z webové služby po provedení požadavku HTTP. Obsahuje informace o odpovědi, včetně stavového kódu, záhlaví a textu. Třída HttpContent představuje tělo HTTP a hlavičky obsahu, například Content-Type a Content-Encoding. Obsah lze číst pomocí některé z ReadAs metod, například ReadAsStringAsync a ReadAsByteArrayAsyncv závislosti na formátu dat.

Další informace o HttpClient třídě naleznete v tématu Vytvoření objektu HTTPClient.

HTTPWebRequest

Volání webových služeb zahrnuje HTTPWebRequest :

  • Vytvoření instance požadavku pro konkrétní identifikátor URI
  • Nastavení různých vlastností HTTP v instanci požadavku
  • HttpWebResponse Načtení požadavku.
  • Čtení dat z odpovědi

Například následující kód načte data z webové služby Americké národní knihovny lékařství:

var rxcui = "198440";
var request = HttpWebRequest.Create(string.Format(@"https://rxnav.nlm.nih.gov/REST/RxTerms/rxcui/{0}/allinfo", rxcui));
request.ContentType = "application/json";
request.Method = "GET";

using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
  if (response.StatusCode != HttpStatusCode.OK)
     Console.Out.WriteLine("Error fetching data. Server returned status code: {0}", response.StatusCode);
  using (StreamReader reader = new StreamReader(response.GetResponseStream()))
  {
               var content = reader.ReadToEnd();
               if(string.IsNullOrWhiteSpace(content)) {
                       Console.Out.WriteLine("Response contained empty body...");
               }
               else {
                       Console.Out.WriteLine("Response Body: \r\n {0}", content);
               }

               Assert.NotNull(content);
  }
}

Výše uvedený příklad vytvoří HttpWebRequest , která vrátí data formátovaná jako JSON. Data jsou vrácena v objektu HttpWebResponse, ze kterého StreamReader lze získat ke čtení dat.

RestSharp

Dalším přístupem k využívání služeb REST je použití knihovny RestSharp . RestSharp zapouzdřuje požadavky HTTP, včetně podpory načítání výsledků buď jako nezpracovaného obsahu řetězce, nebo jako deserializovaný objekt jazyka C#. Například následující kód odešle požadavek na webovou službu Americké národní knihovny medicíny a načte výsledky jako formátovaný řetězec JSON:

var request = new RestRequest(string.Format("{0}/allinfo", rxcui));
request.RequestFormat = DataFormat.Json;
var response = Client.Execute(request);
if(string.IsNullOrWhiteSpace(response.Content) || response.StatusCode != System.Net.HttpStatusCode.OK) {
       return null;
}
rxTerm = DeserializeRxTerm(response.Content);

DeserializeRxTerm je metoda, která vezme nezpracovaný řetězec JSON z RestSharp.RestResponse.Content vlastnosti a převede ho na objekt jazyka C#. Deserializace dat vrácených z webových služeb je popsána dále v tomto článku.

NSUrl Připojení ion

Kromě tříd dostupných v knihovně základních tříd Mono( BCL), jako HttpWebRequestjsou knihovny jazyka C#, jako jsou knihovny jazyka C#třetích stran, jako jsou RestSharp, třídy specifické pro platformu jsou také k dispozici pro využívání webových služeb. Například v iOSu NSUrlConnection lze použít třídy a NSMutableUrlRequest třídy.

Následující příklad kódu ukazuje, jak volat webovou službu Americké národní knihovny medicíny pomocí tříd iOS:

var rxcui = "198440";
var request = new NSMutableUrlRequest(new NSUrl(string.Format("https://rxnav.nlm.nih.gov/REST/RxTerms/rxcui/{0}/allinfo", rxcui)),
       NSUrlRequestCachePolicy.ReloadRevalidatingCacheData, 20);
request["Accept"] = "application/json";

var connectionDelegate = new RxTermNSURLConnectionDelegate();
var connection = new NSUrlConnection(request, connectionDelegate);
connection.Start();

public class RxTermNSURLConnectionDelegate : NSUrlConnectionDelegate
{
       StringBuilder _ResponseBuilder;
       public bool IsFinishedLoading { get; set; }
       public string ResponseContent { get; set; }

       public RxTermNSURLConnectionDelegate()
               : base()
       {
               _ResponseBuilder = new StringBuilder();
       }

       public override void ReceivedData(NSUrlConnection connection, NSData data)
       {
               if(data != null) {
                       _ResponseBuilder.Append(data.ToString());
               }
       }
       public override void FinishedLoading(NSUrlConnection connection)
       {
               IsFinishedLoading = true;
               ResponseContent = _ResponseBuilder.ToString();
       }
}

Obecně platí, že třídy specifické pro platformu pro využívání webových služeb by měly být omezené na scénáře, kdy se nativní kód portuje do jazyka C#. Pokud je to možné, měl by být kód pro přístup k webové službě přenosný, aby se mohl sdílet mezi platformami.

ServiceStack

Další možností volání webových služeb je knihovna Služby Stack . Následující kód například ukazuje, jak použít metodu IServiceClient.GetAsync služby Service Stack k vydání žádosti o službu:

client.GetAsync<CustomersResponse>("",
          (response) => {
               foreach(var c in response.Customers) {
                       Console.WriteLine(c.CompanyName);
               }
       },
       (response, ex) => {
               Console.WriteLine(ex.Message);
       });

Důležité

I když nástroje, jako je ServiceStack a RestSharp, usnadňují volání a využívání služeb REST, někdy není jednoduché využívat XML nebo JSON, které nevyhovují standardním konvencím serializace DataContract . V případě potřeby vyvolejte požadavek a zpracujte příslušnou serializaci explicitně pomocí knihovny ServiceStack.Text, která je popsána níže.

Využívání dat RESTful

Webové služby RESTful obvykle používají zprávy JSON k vrácení dat klientovi. JSON je textový formát výměny dat, který vytváří kompaktní datové části, což má za následek snížení požadavků na šířku pásma při odesílání dat. V této části se prověří mechanismy pro využívání odpovědí RESTful ve formátu JSON a POX (Plain-Old-XML).

System.JSON

Platforma Xamarin se dodává s podporou FORMÁTU JSON. Pomocí znaku JsonObjecta lze načíst výsledky, jak je znázorněno v následujícím příkladu kódu:

var obj = JsonObject.Parse(json);
var properties = obj["rxtermsProperties"];
term.BrandName = properties["brandName"];
term.DisplayName = properties["displayName"];
term.Synonym = properties["synonym"];
term.FullName = properties["fullName"];
term.FullGenericName = properties["fullGenericName"];
term.Strength = properties["strength"];

Je ale důležité si uvědomit, že System.Json nástroje načítají celé data do paměti.

JSON.NET

Knihovna NewtonSoft JSON.NET je široce používaná knihovna pro serializaci a deserializaci zpráv JSON. Následující příklad kódu ukazuje, jak pomocí JSON.NET deserializovat zprávu JSON do objektu C#:

var term = new RxTerm();
var properties = JObject.Parse(json)["rxtermsProperties"];
term.BrandName = properties["brandName"].Value<string>();
term.DisplayName = properties["displayName"].Value<string>();
term.Synonym = properties["synonym"].Value<string>();;
term.FullName = properties["fullName"].Value<string>();;
term.FullGenericName = properties["fullGenericName"].Value<string>();;
term.Strength = properties["strength"].Value<string>();
term.RxCUI = properties["rxcui"].Value<string>();

ServiceStack.Text

ServiceStack.Text je knihovna serializace JSON navržená pro práci s knihovnou ServiceStack. Následující příklad kódu ukazuje, jak parsovat JSON pomocí ServiceStack.Text.JsonObject:

var result = JsonObject.Parse(json).Object("rxtermsProperties")
       .ConvertTo(x => new RxTerm {
               BrandName = x.Get("brandName"),
               DisplayName = x.Get("displayName"),
               Synonym = x.Get("synonym"),
               FullName = x.Get("fullName"),
               FullGenericName = x.Get("fullGenericName"),
               Strength = x.Get("strength"),
               RxTermDoseForm = x.Get("rxtermsDoseForm"),
               Route = x.Get("route"),
               RxCUI = x.Get("rxcui"),
               RxNormDoseForm = x.Get("rxnormDoseForm"),
       });

System.Xml.Linq

V případě použití webové služby REST založeného na JAZYCE XML lze linQ to XML použít k parsování XML a naplnění objektu jazyka C#, jak je znázorněno v následujícím příkladu kódu:

var doc = XDocument.Parse(xml);
var result = doc.Root.Descendants("rxtermsProperties")
.Select(x=> new RxTerm()
       {
               BrandName = x.Element("brandName").Value,
               DisplayName = x.Element("displayName").Value,
               Synonym = x.Element("synonym").Value,
               FullName = x.Element("fullName").Value,
               FullGenericName = x.Element("fullGenericName").Value,
               //bind more here...
               RxCUI = x.Element("rxcui").Value,
       });

webová služba ASP.NET (ASMX)

ASMX umožňuje vytvářet webové služby, které odesílají zprávy pomocí protokolu SOAP (Simple Object Access Protocol). SOAP je protokol založený na platformě a nezávislý na jazyce pro vytváření a přístup k webovým službám. Uživatelé služby ASMX nemusí o platformě, objektovém modelu ani programovacím jazyce použitém k implementaci služby nic vědět. Potřebují jenom pochopit, jak odesílat a přijímat zprávy SOAP.

Zpráva SOAP je dokument XML obsahující následující prvky:

  • Kořenový element s názvem Obálka , který identifikuje dokument XML jako zprávu SOAP.
  • Volitelný element Header , který obsahuje informace specifické pro aplikaci, jako jsou ověřovací data. Pokud je prvek Header k dispozici, musí být prvním podřízeným prvkem elementu Obálka.
  • Povinný prvek textu , který obsahuje zprávu SOAP určenou pro příjemce.
  • Volitelný prvek Fault , který slouží k označení chybových zpráv. Pokud je prvek Fault, musí být podřízený prvek Body elementu.

Protokol SOAP může pracovat s mnoha přenosových protokoly, včetně protokolů HTTP, SMTP, TCP a UDP. Služba ASMX ale může fungovat pouze přes protokol HTTP. Platforma Xamarin podporuje standardní implementace PROTOKOLU SOAP 1.1 přes protokol HTTP a to zahrnuje podporu pro řadu standardních konfigurací služby ASMX.

Generování proxy serveru

Aby bylo možné využívat službu ASMX, musí být vygenerován proxy server , který aplikaci umožňuje připojit se ke službě. Proxy server se sestaví pomocí metadat služby, která definují metody a přidruženou konfiguraci služby. Tato metadata jsou vystavena jako dokument WSDL (Web Services Description Language), který je generován webovou službou. Proxy server je sestaven pomocí Visual Studio pro Mac nebo sady Visual Studio k přidání webového odkazu pro webovou službu do projektů specifických pro platformu.

Adresa URL webové služby může být hostovaný vzdálený zdroj nebo místní prostředek systému souborů přístupný prostřednictvím file:/// předpony cesty, například:

file:///Users/myUserName/projects/MyProjectName/service.wsdl

The web service URL can either be a hosted remote source or local file system resource accessible via the file path prefix

Tím se vygeneruje proxy server ve složce Odkazy na web nebo službu projektu. Vzhledem k tomu, že je vygenerovaný kód proxy serveru, neměl by být změněn.

Ruční přidání proxy serveru do projektu

Pokud máte existující proxy server, který byl vygenerován pomocí kompatibilních nástrojů, můžete tento výstup využívat, pokud je součástí projektu. V Visual Studio pro Mac přidejte proxy server pomocí možnosti nabídky Přidat soubory... . Kromě toho to vyžaduje, aby System.Web.Services.dll explicitně odkazoval pomocí dialogového okna Přidat odkazy...

Využívání proxy serveru

Generované třídy proxy poskytují metody pro využívání webové služby, které používají vzor návrhu asynchronního programovacího modelu (APM). V tomto vzoru je asynchronní operace implementována jako dvě metody s názvem BeginOperationName a EndOperationName, které začínají a končí asynchronní operace.

BeginOperationName metoda začíná asynchronní operace a vrátí objekt, který implementuje IAsyncResult rozhraní. Po volání BeginOperationName může aplikace pokračovat v provádění pokynů ve volajícím vlákně, zatímco asynchronní operace probíhá ve vlákně fondu vláken.

Pro každé volání BeginOperationName by aplikace měla také volat EndOperationName získat výsledky operace. Návratová hodnota EndOperationName je stejný typ vrácený synchronní metodou webové služby. Následující příklad kódu ukazuje příklad tohoto:

public async Task<List<TodoItem>> RefreshDataAsync ()
{
  ...
  var todoItems = await Task.Factory.FromAsync<ASMXService.TodoItem[]> (
    todoService.BeginGetTodoItems,
    todoService.EndGetTodoItems,
    null,
    TaskCreationOptions.None);
  ...
}

Knihovna TPL (Task Parallel Library) může zjednodušit proces využívání dvojice počáteční/koncové metody APM zapouzdřením asynchronních operací ve stejném Task objektu. Tato zapouzdření je poskytována více přetíženími Task.Factory.FromAsync metody. Tato metoda vytvoří Task , která spustí metodu TodoService.EndGetTodoItems po TodoService.BeginGetTodoItems dokončení metody s parametrem null označujícím, že do delegáta BeginGetTodoItems nejsou předána žádná data. Nakonec hodnota výčtu TaskCreationOptions určuje, že se má použít výchozí chování při vytváření a provádění úkolů.

Další informace o APM naleznete v tématu Asynchronní programovací model a TPL a Tradiční .NET Framework Asynchronní programování na MSDN.

Další informace o využívání služby ASMX najdete v tématu Využití webové služby ASP.NET (ASMX).

WCF (Windows Communication Foundation)

WCF je sjednocená architektura Microsoftu pro vytváření aplikací orientovaných na služby. Umožňuje vývojářům vytvářet zabezpečené, spolehlivé, transactované a interoperabilní distribuované aplikace.

WCF popisuje službu s různými kontrakty, které zahrnují následující:

  • Kontrakty dat – definují datové struktury, které tvoří základ obsahu ve zprávě.
  • Kontrakty zpráv – vytváření zpráv z existujících kontraktů dat
  • Kontrakty chyb – umožňují zadat vlastní chyby SOAP.
  • Kontrakty služeb – určují operace, které služby podporují, a zprávy potřebné pro interakci s jednotlivými operacemi. Určují také jakékoli vlastní chování selhání, které může být přidruženo k operacím v každé službě.

Mezi webovými službami ASP.NET (ASMX) a WCF existují rozdíly, ale je důležité si uvědomit, že WCF podporuje stejné funkce, které SLUŽBA ASMX poskytuje – zprávy SOAP přes protokol HTTP.

Důležité

Podpora platformy Xamarin pro WCF je omezena na textově kódované zprávy SOAP přes HTTP/HTTPS pomocí BasicHttpBinding třídy. Kromě toho podpora WCF vyžaduje použití nástrojů, které jsou k dispozici pouze v prostředí Systému Windows k vygenerování proxy serveru.

Generování proxy serveru

Aby bylo možné využívat službu WCF, musí být vygenerován proxy server , který aplikaci umožňuje připojit se ke službě. Proxy server se sestaví pomocí metadat služby, která definují metody a přidruženou konfiguraci služby. Tato metadata jsou vystavena ve formě dokumentu WSDL (Web Services Description Language), který je generován webovou službou. Proxy server lze vytvořit pomocí zprostředkovatele odkazu webové služby Microsoft WCF v sadě Visual Studio 2017 a přidat odkaz na službu pro webovou službu do knihovny .NET Standard.

Alternativou k vytvoření proxy serveru pomocí zprostředkovatele odkazu webové služby Microsoft WCF v sadě Visual Studio 2017 je použití nástroje ServiceModel Metadata Utility (svcutil.exe). Další informace naleznete v tématu ServiceModel Metadata Utility Tool (Svcutil.exe).

Konfigurace proxy serveru

Konfigurace vygenerovaného proxy serveru bude během inicializace obecně trvat dva argumenty konfigurace (v závislosti na protokolu SOAP 1.1/ASMX nebo WCF), a EndpointAddress /nebo související informace o vazbě, jak je znázorněno v následujícím příkladu:

var binding = new BasicHttpBinding () {
       Name= "basicHttpBinding",
       MaxReceivedMessageSize = 67108864,
};

binding.ReaderQuotas = new System.Xml.XmlDictionaryReaderQuotas() {
       MaxArrayLength = 2147483646,
       MaxStringContentLength = 5242880,
};

var timeout = new TimeSpan(0,1,0);
binding.SendTimeout= timeout;
binding.OpenTimeout = timeout;
binding.ReceiveTimeout = timeout;

client = new Service1Client (binding, new EndpointAddress ("http://192.168.1.100/Service1.svc"));

Vazba se používá k určení podrobností přenosu, kódování a protokolu požadovaných pro vzájemné komunikace aplikací a služeb. Určuje BasicHttpBinding , že textově kódované zprávy SOAP budou odeslány přes přenosový protokol HTTP. Zadáním adresy koncového bodu se aplikace může připojit k různým instancím služby WCF za předpokladu, že existuje více publikovaných instancí.

Využívání proxy serveru

Generované třídy proxy poskytují metody pro využívání webových služeb, které používají vzor návrhu asynchronního programovacího modelu (APM). V tomto vzoru je asynchronní operace implementována jako dvě metody s názvem BeginOperationName a EndOperationName, které začínají a ukončuje asynchronní operaci.

BeginOperationName metoda začíná asynchronní operace a vrátí objekt, který implementuje IAsyncResult rozhraní. Po volání BeginOperationName může aplikace pokračovat v provádění pokynů ve volajícím vlákně, zatímco asynchronní operace probíhá ve vlákně fondu vláken.

Pro každé volání BeginOperationName by aplikace měla také volat EndOperationName získat výsledky operace. Návratová hodnota EndOperationName je stejný typ vrácený synchronní metodou webové služby. Následující příklad kódu ukazuje příklad tohoto:

public async Task<List<TodoItem>> RefreshDataAsync ()
{
  ...
  var todoItems = await Task.Factory.FromAsync <ObservableCollection<TodoWCFService.TodoItem>> (
    todoService.BeginGetTodoItems,
    todoService.EndGetTodoItems,
    null,
    TaskCreationOptions.None);
  ...
}

Knihovna TPL (Task Parallel Library) může zjednodušit proces využívání dvojice počáteční/koncové metody APM zapouzdřením asynchronních operací ve stejném Task objektu. Tato zapouzdření je poskytována více přetíženími Task.Factory.FromAsync metody. Tato metoda vytvoří Task , která spustí metodu TodoServiceClient.EndGetTodoItems po TodoServiceClient.BeginGetTodoItems dokončení metody s parametrem null označujícím, že do delegáta BeginGetTodoItems nejsou předána žádná data. Nakonec hodnota výčtu TaskCreationOptions určuje, že se má použít výchozí chování při vytváření a provádění úkolů.

Další informace o APM naleznete v tématu Asynchronní programovací model a TPL a Tradiční .NET Framework Asynchronní programování na MSDN.

Další informace o využívání služby WCF naleznete v tématu Využití webové služby WCF (Windows Communication Foundation).

Použití zabezpečení přenosu

Služby WCF mohou využívat zabezpečení na úrovni přenosu k ochraně před zachycením zpráv. Platforma Xamarin podporuje vazby, které využívají zabezpečení na úrovni přenosu pomocí PROTOKOLU SSL. Může se však stát, že zásobník bude muset ověřit certifikát, což má za následek neočekávané chování. Ověření lze přepsat registrací delegáta ServerCertificateValidationCallback před vyvoláním služby, jak je znázorněno v následujícím příkladu kódu:

System.Net.ServicePointManager.ServerCertificateValidationCallback +=
(se, cert, chain, sslerror) => { return true; };

Tím se zachová šifrování přenosu a současně ignoruje ověření certifikátu na straně serveru. Tento přístup však efektivně ignoruje obavy týkající se důvěryhodnosti spojené s certifikátem a nemusí být vhodné. Další informace naleznete v tématu Použití důvěryhodných kořenových certifikátů respektu na mono-project.com.

Použití zabezpečení přihlašovacích údajů klienta

Služby WCF mohou také vyžadovat, aby se klienti služby ověřili pomocí přihlašovacích údajů. Platforma Xamarin nepodporuje protokol WS-Security, který umožňuje klientům odesílat přihlašovací údaje uvnitř obálky zprávy SOAP. Platforma Xamarin však podporuje možnost odesílat na server přihlašovací údaje základního ověřování HTTP zadáním vhodného ClientCredentialTypekódu:

basicHttpBinding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;

Potom je možné zadat základní ověřovací přihlašovací údaje:

client.ClientCredentials.UserName.UserName = @"foo";
client.ClientCredentials.UserName.Password = @"mrsnuggles";

Další informace o základním ověřování HTTP, i když v kontextu webové služby REST naleznete v tématu Ověřování webové služby RESTful.