Generovanie dokumentácie k Ajax web službe

Webové služby využívajúce formát SOAP sa s pomocou WCF programujú veľmi ľahko hlavne vďaka tomu, že programátor sa môže sústrediť na biznis logiku, ktorú potrebuje implementovať. Na vytvorenie služby a rozchodenie komunikácie stačia štyri kroky:

1. Zadefinovanie interface-u,
2. Implementácia interface-u,
3. Spustenie služby pomocou ServiceHost a povolenie generovania metadát,
4. Zo schémy sa vytvorí proxy trieda pre prístup k službe.

[ServiceContract(Namespace="WebApplication1.Services")]
public interface IPublicApi
{
        [OperationContract]
        [WebGet]
        IList<TaskGroup> GetTaskGroups();

        [OperationContract]
        [WebGet]
        Guid CreateTaskGroup(string taskGroupName);
}

Utilitka svcutil.exe vie na základe XML schémy SOAP služby vygenerovať strongly-typed triedu pre .NET. Keď sa zmení rozhranie služby, stačí pregenerovať triedu a prípadne refektorovať kód.

S webovými službami pre Ajax to tiež nie je ťažké. WCF 3.5 podporuje Json a stačí použiť triedu WebScriptHostFactory ktorá vytvorí WebServiceHost s WebScriptEnablingBehavior. Ten pridáva podporu pre formát Json a XML a mapuje cestu /js na generátor JavaScript-ového proxy súbory. Vygenerovaný JavaScript je určený pre ASP.NET AJAX framework a generátor zatiaľ nie je plug-able, čiže sa nedá vymeniť za nejaký iný.

http://localhost/WebApplication1/PublicApi.svc/js

Objavil som však WCF REST Starter Kit (zdrojový kód je na Codeplex.com) – je to ukážka rozšíriteľnosti WCF stacku a záreveň implementácia podpory pre REST.

Tento kit obsahuje triedu HelpPageInvoker, ktorá si registruje url /help na ktorej sa zobrazí jednoduchý popis dostupných metód, ktoré HTTP príkazy (GET, POST, PUT, DELETE…) sa dajú použiť a taktiež odkazy na ukážkový request alebo response pre metódu.

http://localhost/WebApplication1/PublicApi.svc/help

REST Starter Kit je určený hlavne pre zjednodušenie práce so službou, ktorá používa POX a HTTP príkazy. Umožňuje použiť Json formát, ale cieľovou skupinou tohto kitu nie sú prímarne Ajax rozhrania.

Ak používate dependency injection v Ajax službách, tak zrejme budete potrebovať vlastnú implementáciu triedy HelpPageInvoker aby v nej správne fungovalo generovanie ukážkových hodnôt pre request alebo reponse. HelpPageInvoker si zistí návratový typ metódy, alebo jej parametre, tieto typy inštanciuje cez Activator.Cre­ateInstance() a objekt serializuje do XML alebo Json. Ak sú však tieto typy definované ako rozhrania (napr. GetTaskGroups() vracia IList<TaskGroup>) tak Activator ich samozrejme nevie ako vytvoriť.
Tu prichádza napomoc dependency injection. Do triedy HelpPageInvoker stačí poslať referenciu na kontajner z DI frameworku, ktorý využívate a nahradiť štyri volania Activator.Cre­ateInstance() za kontajner a jeho príslušné metódy.

Nasleduje kód, ako principiálne funguje vytvorenie ukážky návratovej hodnoty pre nejakú operáciu:

class HelpPageInvoker
{
  public Message GetResponseExample(OperationDescription od)
  {
    // z popisu operácie získa dátový typ návratovej hodnoty
    // a vytvorí objekt
    Type body = GetResponseBodyType(od);
    object instance = UnityContainer.Resolve(body);

    // vytvori Message serializovanu do Json
    Message result = Message.CreateMessage(MessageVersion.None, null,
      new JsonBodyWriter(instance, body));
    return result;
  }
}