Zpracování výjimek a chyb

Výjimky se používají ke komunikaci chyb místně v rámci služby nebo implementace klienta. Chyby se na druhé straně používají ke komunikaci chyb přes hranice služeb, jako je například ze serveru do klienta nebo naopak. Kromě chyb používají přenosové kanály často mechanismy specifické pro přenos ke komunikaci chyb na úrovni přenosu. Například přenos HTTP používá stavové kódy, jako je například 404, ke komunikaci neexistující adresy URL koncového bodu (neexistuje žádný koncový bod pro odeslání chyby). Tento dokument se skládá ze tří částí, které poskytují pokyny pro autory vlastních kanálů. V první části najdete pokyny k tomu, kdy a jak definovat a vyvolat výjimky. Druhá část obsahuje pokyny týkající se generování a využívání chyb. Třetí část vysvětluje, jak poskytnout informace o trasování, které uživateli vašeho vlastního kanálu pomůžou při řešení potíží se spuštěnými aplikacemi.

Výjimky

Při vyvolání výjimky je potřeba mít na paměti dvě věci: Nejprve musí být typu, který uživatelům umožňuje psát správný kód, který může na výjimku správně reagovat. Za druhé musí uživateli poskytnout dostatek informací, aby porozuměl tomu, co se nepovedlo, jaký dopad na selhání a jak ho opravit. Následující části obsahují pokyny týkající se typů výjimek a zpráv pro kanály WCF (Windows Communication Foundation). Existují také obecné pokyny týkající se výjimek v .NET v dokumentu Pokyny k návrhu výjimek.

Typy výjimek

Všechny výjimky vyvolané kanály musí být buď System.TimeoutException, System.ServiceModel.CommunicationExceptionnebo typ odvozený z CommunicationException. (Výjimky, například ObjectDisposedException mohou být také vyvolány, ale pouze k označení, že volající kód zneužil kanál. Pokud se kanál používá správně, musí vyvolat pouze dané výjimky.) WCF poskytuje sedm typů výjimek, které jsou odvozeny a CommunicationException jsou navrženy tak, aby je používaly kanály. Existují další CommunicationExceptionodvozené výjimky, které jsou navrženy tak, aby je používaly jiné části systému. Mezi tyto typy výjimek patří:

Typ výjimky	Význam	Vnitřní obsah výjimky	Strategie obnovení
AddressAlreadyInUseException	Adresa koncového bodu zadaná pro naslouchání se už používá.	Pokud je k dispozici, zobrazí se další podrobnosti o chybě přenosu, která způsobila tuto výjimku. Příklad: PipeException, HttpListenerExceptionnebo SocketException.	Zkuste jinou adresu.
AddressAccessDeniedException	Proces nemá povolený přístup k adrese koncového bodu určené pro naslouchání.	Pokud je k dispozici, zobrazí se další podrobnosti o chybě přenosu, která způsobila tuto výjimku. Například , PipeExceptionnebo HttpListenerException.	Zkuste použít jiné přihlašovací údaje.
CommunicationObjectFaultedException	Použitý ICommunicationObject stav je ve stavu Chybný (další informace najdete v tématu Vysvětlení změn stavu). Všimněte si, že když se objekt s více nevyřízenými voláními přepojí do chybového stavu, vyvolá pouze jedno volání výjimku, která souvisí se selháním a zbývající volání vyvolá CommunicationObjectFaultedExceptionvýjimku . Tato výjimka je obvykle vyvolána, protože aplikace přehlédne určitou výjimku a pokusí se použít již vadný objekt, pravděpodobně na jiném vlákně, než je ten, který zachytil původní výjimku.	Pokud je k dispozici, zobrazí podrobnosti o vnitřní výjimce.	Vytvoření nového objektu. Mějte na paměti, že v závislosti na tom, co způsobilo ICommunicationObject selhání na prvním místě, může být potřeba provést další práci potřebnou k obnovení.
CommunicationObjectAbortedException	Použité ICommunicationObject změny byly přerušeny (další informace najdete v tématu Vysvětlení změn stavu). CommunicationObjectFaultedExceptionPodobně jako tato výjimka označuje, že aplikace volala Abort objekt, pravděpodobně z jiného vlákna, a objekt již není z tohoto důvodu použitelný.	Pokud je k dispozici, zobrazí podrobnosti o vnitřní výjimce.	Vytvoření nového objektu. Všimněte si, že v závislosti na tom, co způsobilo ICommunicationObject přerušení na prvním místě, může být potřeba provést další práci potřebnou k obnovení.
EndpointNotFoundException	Cílový vzdálený koncový bod nenaslouchá. To může mít za následek, že jakákoli část adresy koncového bodu je nesprávná, nespravitelná nebo koncový bod je mimo provoz. Mezi příklady patří chyba DNS, správce front není k dispozici a služba není spuštěná.	Vnitřní výjimka poskytuje podrobnosti, obvykle z podkladového přenosu.	Zkuste jinou adresu. Případně může odesílatel chvíli počkat a zkusit to znovu v případě, že služba nefunguje
ProtocolException	Komunikační protokoly popsané zásadami koncového bodu se neshodují mezi koncovými body. Například kvůli neshodě typu obsahu nebo překročení maximální velikosti zprávy.	Pokud je k dispozici, zobrazí se další informace o konkrétní chybě protokolu. Je to například vnitřní výjimka, QuotaExceededException pokud příčinou chyby je překročení MaxReceivedMessageSize.	Obnovení: Ujistěte se, že se shodují nastavení protokolu odesílatele a přijetí. Jedním ze způsobů, jak to udělat, je znovu naimportovat metadata koncového bodu služby (zásady) a použít vygenerovanou vazbu k opětovnému vytvoření kanálu.
ServerTooBusyException	Vzdálený koncový bod naslouchá, ale není připravený zpracovávat zprávy.	Pokud je k dispozici, vnitřní výjimka poskytuje podrobnosti o chybě protokolu SOAP nebo podrobnosti o chybě na úrovni přenosu.	Obnovení: Počkejte a zkuste operaci zopakovat později.
TimeoutException	Operaci se nepodařilo dokončit během časového limitu.	Může zadat podrobnosti o vypršení časového limitu.	Počkejte a zkuste operaci zopakovat později.

Definovat nový typ výjimky pouze v případě, že tento typ odpovídá konkrétní strategii obnovení, která se liší od všech existujících typů výjimek. Pokud definujete nový typ výjimky, musí být odvozen z nebo z CommunicationException jedné z jeho odvozených tříd.

Zprávy o výjimce

Zprávy o výjimce jsou zacílené na uživatele, který není programem, takže by měl poskytnout dostatek informací, aby uživateli pomohl pochopit a vyřešit problém. Mezi tři základní části dobré zprávy o výjimce patří:

Co se stalo. Zadejte jasný popis problému s použitím termínů, které souvisejí s uživatelským prostředím. Například chybná zpráva o výjimce by byla neplatná část konfigurace. Tím se uživatel ptá, který oddíl konfigurace je nesprávný a proč je nesprávný. Vylepšená zpráva by byla "CustomBinding> neplatného oddílu <konfigurace". Ještě lepší zpráva by byla "Nelze přidat přenos s názvem myTransport do vazby s názvem myBinding, protože vazba již má přenos s názvem myTransport". Jedná se o velmi specifickou zprávu používající termíny a názvy, které uživatel může snadno identifikovat v konfiguračním souboru aplikace. Stále však chybí několik klíčových komponent.

Význam chyby. Pokud zpráva jasně neposoudí, co chyba znamená, je pravděpodobné, že se uživatel bude ptát, jestli se jedná o závažnou chybu nebo jestli se dá ignorovat. Obecně platí, že zprávy by měly vést významem nebo významem chyby. Chcete-li vylepšit předchozí příklad, může být zpráva ServiceHost se nepodařilo otevřít kvůli chybě konfigurace: Nelze přidat přenos s názvem myTransport do vazby s názvem myBinding, protože vazba již má přenos s názvem myTransport.

Jak by měl uživatel problém opravit. Nejdůležitější součástí zprávy je pomoct uživateli problém vyřešit. Zpráva by měla obsahovat některé pokyny nebo rady týkající se toho, co zkontrolovat nebo opravit, aby se problém odstranil. Například ServiceHost se nepodařilo otevřít kvůli chybě konfigurace: Nelze přidat přenos s názvem myTransport do vazby s názvem myBinding, protože vazba již má přenos s názvem myTransport. Ujistěte se, že je v vazbě pouze jeden přenos".

Komunikace chyb

PROTOKOL SOAP 1.1 i SOAP 1.2 definují specifickou strukturu chyb. Mezi těmito dvěma specifikacemi existují určité rozdíly, ale obecně se k vytváření a využívání chyb používají typy Message a MessageFault.

Chyba SOAP 1.2 (vlevo) a CHYBA SOAP 1.1 (vpravo) V protokolu SOAP 1.1 je kvalifikovaný pouze element Fault.

SOAP definuje chybovou zprávu jako zprávu, která obsahuje pouze prvek chyby (prvek, jehož název je <env:Fault>) jako podřízený prvek <env:Body>. Obsah prvku selhání se mírně liší mezi protokolem SOAP 1.1 a SOAP 1.2, jak je znázorněno na obrázku 1. System.ServiceModel.Channels.MessageFault Třída ale tyto rozdíly normalizuje do jednoho objektového modelu:

public abstract class MessageFault  
{  
    protected MessageFault();  
  
    public virtual string Actor { get; }  
    public virtual string Node { get; }  
    public static string DefaultAction { get; }  
    public abstract FaultCode Code { get; }  
    public abstract bool HasDetail { get; }  
    public abstract FaultReason Reason { get; }  
  
    public T GetDetail<T>();  
    public T GetDetail<T>( XmlObjectSerializer serializer);  
    public System.Xml.XmlDictionaryReader GetReaderAtDetailContents();  
  
    // other methods omitted  
}  

Vlastnost Code odpovídá env:Code (nebo faultCode v protokolu SOAP 1.1) a identifikuje typ chyby. SOAP 1.2 definuje pět povolených hodnot ( faultCode například Sender a Receiver) a definuje Subcode prvek, který může obsahovat libovolnou hodnotu podkódu. (Viz Specifikace PROTOKOLU SOAP 1.2 pro seznam povolených kódů chyb a jejich významu.) PROTOKOL SOAP 1.1 má mírně odlišný mechanismus: Definuje čtyři faultCode hodnoty (například Klient a Server), které lze rozšířit buď definováním úplně nových, nebo použitím zápisu tečky k vytvoření konkrétnější faultCodes, například Client.Authentication.

Při použití MessageFault programovat chyby, FaultCode.Name a FaultCode.Namespace mapuje na název a obor názvů SOAP 1.2 env:Code nebo SOAP 1.1 faultCode. Kód FaultCode.SubCode se mapuje na env:Subcode protokol SOAP 1.2 a má hodnotu null pro SOAP 1.1.

Pokud používáte SOAP 1.1, měli byste vytvořit nové podkódy chyb (nebo nové kódy chyb), pokud je zajímavé chybu rozlišit prostřednictvím kódu programu. To je analogické k vytvoření nového typu výjimky. Měli byste se vyhnout použití zápisu tečky s kódy chyb SOAP 1.1. (Základní profil WS-I také nedoporučuje používat tečkovaný zápis kódu chyby.)

public class FaultCode  
{  
    public FaultCode(string name);  
    public FaultCode(string name, FaultCode subCode);  
    public FaultCode(string name, string ns);  
    public FaultCode(string name, string ns, FaultCode subCode);  
  
    public bool IsPredefinedFault { get; }  
    public bool IsReceiverFault { get; }  
    public bool IsSenderFault { get; }  
    public string Name { get; }  
    public string Namespace { get; }  
    public FaultCode SubCode { get; }  
  
//  methods omitted  
  
}  

Vlastnost Reason odpovídá env:Reason (nebo faultString v protokolu SOAP 1.1) popis chybového stavu, který je podobný zprávě výjimky. Třída FaultReason (a SOAP env:Reason/faultString) má integrovanou podporu pro více překladů v zájmu globalizace.

public class FaultReason  
{  
    public FaultReason(FaultReasonText translation);  
    public FaultReason(IEnumerable<FaultReasonText> translations);  
    public FaultReason(string text);  
  
    public SynchronizedReadOnlyCollection<FaultReasonText> Translations
    {
       get;
    }  
  
 }  

Obsah podrobností o chybách se zobrazí ve službě MessageFault pomocí různých metod, včetně GetDetail<T> a GetReaderAtDetailContents(). Podrobnosti o chybě jsou neprůmyslný prvek pro přenos dalších podrobností o chybě. To je užitečné, pokud existuje několik libovolných strukturovaných podrobností, které chcete nést s chybou.

Generování chyb

Tato část vysvětluje proces generování chyby v reakci na chybový stav zjištěný v kanálu nebo ve vlastnosti zprávy vytvořené kanálem. Typickým příkladem je odeslání chyby v reakci na zprávu požadavku, která obsahuje neplatná data.

Při generování chyby by vlastní kanál neměl chybu odesílat přímo, spíše by měl vyvolat výjimku a nechat vrstvu výše rozhodnout, zda má tato výjimka převést na chybu a jak ji odeslat. Pro podporu tohoto převodu by kanál měl poskytnout FaultConverter implementaci, která může převést výjimku vyvolanou vlastním kanálem na příslušnou chybu. FaultConverter je definován jako:

public class FaultConverter  
{  
    public static FaultConverter GetDefaultFaultConverter(  
                                   MessageVersion version);  
    protected abstract bool OnTryCreateFaultMessage(  
                                   Exception exception,
                                   out Message message);  
    public bool TryCreateFaultMessage(  
                                   Exception exception,
                                   out Message message);  
}  

Každý kanál, který generuje vlastní chyby, musí implementovat FaultConverter a vrátit ho z volání do GetProperty<FaultConverter>. Vlastní OnTryCreateFaultMessage implementace musí buď převést výjimku na chybu, nebo delegovat na vnitřní kanál .FaultConverter Pokud je kanál přenosem, musí buď převést výjimku nebo delegáta na kodér nebo FaultConverter výchozí FaultConverter zadaný ve WCF . Výchozí hodnota FaultConverter převede chyby odpovídající chybovým zprávám určeným pomocí WS-Adresování a PROTOKOLU SOAP. Tady je příklad OnTryCreateFaultMessage implementace.

public override bool OnTryCreateFaultMessage(Exception exception,
                                             out Message message)  
{  
    if (exception is ...)  
    {  
        message = ...;  
        return true;  
    }  
  
#if IMPLEMENTING_TRANSPORT_CHANNEL  
    FaultConverter encoderConverter =
                    this.encoder.GetProperty<FaultConverter>();  
    if ((encoderConverter != null) &&
        (encoderConverter.TryCreateFaultMessage(  
         exception, out message)))  
    {  
        return true;  
    }  
  
    FaultConverter defaultConverter =
                   FaultConverter.GetDefaultFaultConverter(  
                   this.channel.messageVersion);  
    return defaultConverter.TryCreateFaultMessage(  
                   exception,
                   out message);  
#else  
    FaultConverter inner =
                   this.innerChannel.GetProperty<FaultConverter>();  
    if (inner != null)  
    {  
        return inner.TryCreateFaultMessage(exception, out message);  
    }  
    else  
    {  
        message = null;  
        return false;  
    }  
#endif  
}  

Implikací tohoto modelu je, že výjimky vyvolané mezi vrstvami pro chybové stavy, které vyžadují chyby, musí obsahovat dostatek informací pro odpovídající generátor chyb k vytvoření správné chyby. Jako autor vlastního kanálu můžete definovat typy výjimek, které odpovídají různým stavům selhání, pokud tyto výjimky ještě neexistují. Všimněte si, že výjimky vrstvy procházení kanálů by měly místo neprůhlených dat chyb informovat o chybovém stavu.

Kategorie chyb

Obecně existují tři kategorie chyb:

1. Chyby, které jsou pervasivní v celém zásobníku. K těmto chybám může dojít v libovolné vrstvě v zásobníku kanálu, například InvalidCardinalityAddressingException.

2. Chyby, které mohou být zjištěny kdekoli nad určitou vrstvou v zásobníku, například některé chyby týkající se toku transakce nebo role zabezpečení.

3. Chyby, které jsou směrovány na jednu vrstvu v zásobníku, například chyby, jako jsou chyby s pořadovým číslem WS-RM.

Kategorie 1. Chyby jsou obecně chyb WS-Adresování a SOAP. Základní FaultConverter třída poskytovaná WCF převádí chyby odpovídající chybovým zprávám určeným adresováním WS a SOAP, takže nemusíte zpracovávat převod těchto výjimek sami.

Kategorie 2. K chybám dochází, když vrstva přidá vlastnost do zprávy, která zcela nevyužívají informace o zprávě, které se týkají této vrstvy. Chyby mohou být zjištěny později, když vyšší vrstva požádá vlastnost zprávy o další zpracování informací o zprávě. Tyto kanály by měly implementovat GetProperty uvedené dříve, aby vyšší vrstva mohla odeslat zpět správnou chybu. Příkladem je TransactionMessageProperty. Tato vlastnost je přidána do zprávy bez úplné ověření všech dat v hlavičce (to může zahrnovat kontaktování koordinátoru distribuovaných transakcí (DTC).

Kategorie 3. Chyby se generují a odesílají pouze jednou vrstvou v procesoru. Proto jsou všechny výjimky obsaženy v rámci vrstvy. Pokud chcete zlepšit konzistenci mezi kanály a usnadnit údržbu, měl by váš vlastní kanál použít vzor zadaný dříve k vygenerování chybových zpráv i pro vnitřní chyby.

Interpretace přijatých chyb

Tato část obsahuje pokyny pro generování příslušné výjimky při příjmu chybové zprávy. Rozhodovací strom pro zpracování zprávy v každé vrstvě zásobníku je následující:

1. Pokud vrstva považuje zprávu za neplatnou, měla by vrstva zpracovat neplatnou zprávu. Takové zpracování je specifické pro vrstvu, ale může zahrnovat vyřazení zprávy, trasování nebo vyvolání výjimky, která se převede na chybu. Mezi příklady patří zabezpečení při příjmu zprávy, která není správně zabezpečená, nebo přijetí zprávy s chybným pořadovým číslem.

2. Jinak pokud je zpráva chybovou zprávou, která se vztahuje konkrétně na vrstvu a zpráva není smysluplná mimo interakci vrstvy, měla by vrstva zpracovat chybový stav. Příkladem této chyby je odmítnutá sekvence RM, která není smysluplná pro vrstvy nad kanálem RM, což znamená selhání kanálu RM a vyvolání čekajících operací.

3. Jinak by zpráva měla být vrácena z požadavku() nebo receive(). To zahrnuje případy, kdy vrstva chybu rozpozná, ale tato chyba pouze značí, že požadavek selhal a neznamená selhání kanálu a vyvolání čekajících operací. Aby se v takovém případě zlepšila použitelnost, měla by vrstva implementovat GetProperty<FaultConverter> a vrátit odvozenou FaultConverter třídu, která může převést chybu na výjimku přepsáním OnTryCreateException.

Následující objektový model podporuje převod zpráv na výjimky:

public class FaultConverter  
{  
    public static FaultConverter GetDefaultFaultConverter(  
                                  MessageVersion version);  
    protected abstract bool OnTryCreateException(  
                                 Message message,
                                 MessageFault fault,
                                 out Exception exception);  
    public bool TryCreateException(  
                                 Message message,
                                 MessageFault fault,
                                 out Exception exception);  
}  

Vrstva kanálu může implementovat GetProperty<FaultConverter> podporu převodu chybových zpráv na výjimky. Provedete to tak, že přepíšete OnTryCreateException a zkontrolujete zprávu o chybě. Pokud je rozpoznán, proveďte převod, jinak požádejte vnitřní kanál, aby ho převeďte. Přenosové kanály by měly delegovat na FaultConverter.GetDefaultFaultConverter získání výchozího protokolu SOAP/WS-Addressing FaultConverter.

Typická implementace vypadá takto:

public override bool OnTryCreateException(  
                            Message message,
                            MessageFault fault,
                            out Exception exception)  
{  
    if (message.Action == "...")  
    {  
        exception = ...;  
        return true;  
    }  
    // OR  
    if ((fault.Code.Name == "...") && (fault.Code.Namespace == "..."))  
    {  
        exception = ...;  
        return true;  
    }  
  
    if (fault.IsMustUnderstand)  
    {  
        if (fault.WasHeaderNotUnderstood(  
                   message.Headers, "...", "..."))  
        {  
            exception = new ProtocolException(...);  
            return true;  
        }  
    }  
  
#if IMPLEMENTING_TRANSPORT_CHANNEL  
    FaultConverter encoderConverter =
              this.encoder.GetProperty<FaultConverter>();  
    if ((encoderConverter != null) &&
        (encoderConverter.TryCreateException(  
                              message, fault, out exception)))  
    {  
        return true;  
    }  
  
    FaultConverter defaultConverter =  
             FaultConverter.GetDefaultFaultConverter(  
                             this.channel.messageVersion);  
    return defaultConverter.TryCreateException(  
                             message, fault, out exception);  
#else  
    FaultConverter inner =
                    this.innerChannel.GetProperty<FaultConverter>();  
    if (inner != null)  
    {  
        return inner.TryCreateException(message, fault, out exception);  
    }  
    else  
    {  
        exception = null;  
        return false;  
    }  
#endif  
}  

V případě konkrétních chybových podmínek, které mají odlišné scénáře obnovení, zvažte definování odvozené třídy ProtocolException.

Zpracování MustUnderstand

Protokol SOAP definuje obecnou chybu pro signalizaci, že příjemce nepochopil požadovanou hlavičku. Tato chyba se označuje jako mustUnderstand chyba. Ve WCF vlastní kanály nikdy nevygenerují mustUnderstand chyby. Místo toho dispečer WCF, který se nachází v horní části komunikačního zásobníku WCF, kontroluje, že všechny hlavičky označené jako MustUnderstand=true byly pochopeny v podkladovém zásobníku. Pokud nějaké nepochopilo, v tomto okamžiku mustUnderstand se vygeneruje chyba. (Uživatel může toto zpracování vypnout mustUnderstand a nechat aplikaci přijímat všechna záhlaví zpráv. V takovém případě je aplikace zodpovědná za zpracování mustUnderstand .) Vygenerovaná chyba obsahuje hlavičku NotUnderstood, která obsahuje názvy všech hlaviček s MustUnderstand=true, které nebyly srozumitelné.

Pokud váš kanál protokolu odešle vlastní hlavičku s MustUnderstand=true a obdrží mustUnderstand chybu, musí zjistit, jestli je tato chyba způsobená hlavičkou, kterou odeslal. Pro tuto třídu jsou užitečné dva členy MessageFault :

public class MessageFault  
{  
    ...  
    public bool IsMustUnderstandFault { get; }  
    public static bool WasHeaderNotUnderstood(MessageHeaders headers,
        string name, string ns) { }  
    ...  
  
}  

IsMustUnderstandFault vrátí true , pokud je chyba chybou mustUnderstand . WasHeaderNotUnderstood vrátí true , pokud hlavička se zadaným názvem a oborem názvů je zahrnuta v chybě jako hlavička NotUnderstood. V opačném případě se vrátí false.

Pokud kanál vygeneruje hlavičku označenou Jako MustUnderstand = true, měla by tato vrstva také implementovat vzor rozhraní API pro generování výjimek a měla by převést mustUnderstand chyby způsobené touto hlavičkou na užitečnější výjimku, jak je popsáno výše.

Sledování

Rozhraní .NET Framework poskytuje mechanismus trasování provádění programu jako způsob, jak pomoct diagnostikovat produkční aplikace nebo občasné problémy, kdy není možné pouze připojit ladicí program a procházet kód. Základní součásti tohoto mechanismu jsou v System.Diagnostics oboru názvů a skládají se z:

• System.Diagnostics.TraceSource, což je zdroj informací o trasování, které mají být zapsány, což je abstraktní základní třída pro konkrétní naslouchací procesy, System.Diagnostics.TraceListenerkteré přijímají informace, které mají být sledovány z TraceSource a výstupem do cíle specifického pro naslouchací proces. Výstupem je například XmlWriterTraceListener trasování informací do souboru XML. Nakonec , System.Diagnostics.TraceSwitchkterý umožňuje uživateli aplikace řídit trasování podrobností a je obvykle specifikován v konfiguraci.

• Kromě základních komponent můžete pomocí nástroje Service Trace Viewer (SvcTraceViewer.exe) zobrazit a prohledávat trasování WCF. Nástroj je navržen speciálně pro trasovací soubory generované WCF a zapsané pomocí XmlWriterTraceListener. Následující obrázek znázorňuje různé komponenty, které jsou součástí trasování.

Trasování z vlastního kanálu

Vlastní kanály by měly zapisovat zprávy trasování, které pomáhají při diagnostice problémů, když není možné připojit ladicí program ke spuštěné aplikaci. To zahrnuje dvě úlohy vysoké úrovně: Vytvoření instance TraceSource a volání jeho metod pro zápis trasování.

Při vytváření TraceSourceinstance řetězce, který zadáte, se stane názvem tohoto zdroje. Tento název slouží ke konfiguraci zdroje trasování (povolení, zakázání nebo nastavení úrovně trasování). Zobrazí se také v samotném výstupu trasování. Vlastní kanály by měly používat jedinečný název zdroje, který čtenářům výstupu trasování pomůže pochopit, odkud informace o trasování pocházejí. Běžným postupem je použití názvu sestavení, které zapisuje informace jako název zdroje trasování. WCF například používá System.ServiceModel jako zdroj trasování pro informace napsané ze sestavení System.ServiceModel.

Jakmile budete mít zdroj trasování, zavoláte jeho TraceData, TraceEventnebo TraceInformation metody zápisu trasovací položky do naslouchací procesy trasování. Pro každou položku trasování, kterou napíšete, musíte klasifikovat typ události jako jeden z typů událostí definovaných v TraceEventType. Tato klasifikace a nastavení úrovně trasování v konfiguraci určují, jestli je položka trasování výstupem do naslouchacího procesu. Například nastavení úrovně trasování v konfiguraci tak, aby Warning umožňovalo ErrorWarningzápis a Critical položky trasování, ale blokuje informace a podrobné položky. Tady je příklad vytvoření instance zdroje trasování a napsání položky na úrovni Informace:

using System.Diagnostics;  
//...  
TraceSource udpSource = new TraceSource("Microsoft.Samples.Udp");  
//...  
udpsource.TraceInformation("UdpInputChannel received a message");  

Důležité

Důrazně doporučujeme zadat název zdroje trasování, který je jedinečný pro váš vlastní kanál, aby čtenáři výstupu pochopili, odkud výstup pochází.

Integrace s prohlížečem trasování

Trasování vygenerované kanálem může být výstup ve formátu čitelném nástrojem Service Trace Viewer (SvcTraceViewer.exe) pomocí System.Diagnostics.XmlWriterTraceListener naslouchacího procesu trasování. To není něco, co musíte udělat, jako vývojář kanálu. Spíše se jedná o uživatele aplikace (nebo osobu, která řeší potíže s aplikací), která potřebuje nakonfigurovat tento naslouchací proces trasování v konfiguračním souboru aplikace. Následující konfigurace například vypíše trasování informací z obou a System.ServiceModelMicrosoft.Samples.Udp do souboru s názvem TraceEventsFile.e2e:

<configuration>  
  <system.diagnostics>  
    <sources>  
      <!-- configure System.ServiceModel trace source -->  
      <source name="System.ServiceModel" switchValue="Verbose"
              propagateActivity="true">  
        <listeners>  
          <add name="e2e" />  
        </listeners>  
      </source>  
      <!-- configure Microsoft.Samples.Udp trace source -->  
      <source name="Microsoft.Samples.Udp" switchValue="Verbose" >  
        <listeners>  
          <add name="e2e" />  
        </listeners>  
      </source>  
    </sources>  
    <!--   
    Define a shared trace listener that outputs to TraceFile.e2e  
    The listener name is e2e   
    -->  
    <sharedListeners>  
      <add name="e2e" type="System.Diagnostics.XmlWriterTraceListener"  
        initializeData=".\TraceFile.e2e"/>  
    </sharedListeners>  
    <trace autoflush="true" />  
  </system.diagnostics>  
</configuration>  

Trasování strukturovaných dat

System.Diagnostics.TraceSource má metodu TraceData , která přebírá jeden nebo více objektů, které mají být zahrnuty do položky trasování. Obecně platí, že Object.ToString metoda je volána pro každý objekt a výsledný řetězec je zapsán jako součást položky trasování. Při použití System.Diagnostics.XmlWriterTraceListener k výstupu trasování můžete předat System.Xml.XPath.IXPathNavigable jako datový objekt do TraceData. Výsledná položka trasování zahrnuje XML, který System.Xml.XPath.XPathNavigatorposkytuje . Tady je příklad položky s daty aplikace XML:

<E2ETraceEvent xmlns="http://schemas.microsoft.com/2004/06/E2ETraceEvent">  
  <System xmlns="...">  
    <EventID>12</EventID>  
    <Type>3</Type>  
    <SubType Name="Information">0</SubType>  
    <Level>8</Level>  
    <TimeCreated SystemTime="2006-01-13T22:58:03.0654832Z" />  
    <Source Name="Microsoft.ServiceModel.Samples.Udp" />  
    <Correlation ActivityID="{00000000-0000-0000-0000-000000000000}" />  
    <Execution  ProcessName="UdpTestConsole"
                ProcessID="3348" ThreadID="4" />  
    <Channel />  
    <Computer>COMPUTER-LT01</Computer>  
  </System>  
<!-- XML application data -->  
  <ApplicationData>  
  <TraceData>  
   <DataItem>  
   <TraceRecord
     Severity="Information"  
     xmlns="…">  
        <TraceIdentifier>some trace id</TraceIdentifier>  
        <Description>EndReceive called</Description>  
        <AppDomain>UdpTestConsole.exe</AppDomain>  
        <Source>UdpInputChannel</Source>  
      </TraceRecord>  
    </DataItem>  
  </TraceData>  
  </ApplicationData>  
</E2ETraceEvent>  

Prohlížeč trasování WCF rozumí schématu dříve zobrazeného TraceRecord prvku a extrahuje data z podřízených prvků a zobrazuje je v tabulkovém formátu. Kanál by měl toto schéma používat při trasování strukturovaných dat aplikací, aby pomohl Svctraceviewer.exe uživatelům číst data.