Sdílet prostřednictvím

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 404, ke komunikaci neexistujícího URL koncového bodu (není k dispozici žádný koncový bod pro vrácení 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. Napří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řechází do stavu Chyby, pouze jedno volání vyvolá výjimku související se selháním a zbývající volání vyvolají CommunicationObjectFaultedException. 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řte nový objekt. 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žívané ICommunicationObject bylo přerušeno (další informace najdete v části Vysvětlení změn stavu). Podobně jako CommunicationObjectFaultedException, tato výjimka označuje, že aplikace volala Abort na objekt, pravděpodobně z jiného vlákna, a proto objekt již není použitelný. Pokud je k dispozici, zobrazí podrobnosti o vnitřní výjimce. Vytvořte nový objekt. 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ýjimkách

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 přihodilo. 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á sekce 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 "Neplatná konfigurační sekce <customBinding>". 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 začínat smyslem nebo důležitostí chyby. Chcete-li vylepšit předchozí příklad, zpráva by mohla být: 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 ve svazku pouze jeden transport.

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 a chyba SOAP 1.1
Chyba SOAP 1.2 (vlevo) a Chyba SOAP 1.1 (vpravo) V protokolu SOAP 1.1 je jako jediný kvalifikován v rámci jmenného prostoru 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. (Seznam povolených kódů chyb a jejich význam naleznete ve specifikaci SOAP 1.2 .) 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žívání MessageFault pro programování chyb se FaultCode.Name a FaultCode.Namespace mapují na název a obor názvů SOAP 1.2 env:Code nebo SOAP 1.1 faultCode. Kód FaultCode.SubCode odpovídá env:Subcode pro protokol SOAP 1.2 a je 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í notace s tečkou u kódů chyb SOAP 1.1. (Základní profilWS-I také nedoporučuje používat tečkovou notaci chybového kódu.)

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á lidsky čitelnému popisu chybového stavu env:Reason (nebo faultString v SOAP 1.1), 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ůhledný prvek k přenosu dalších podrobností o chybě. Toto je užitečné, pokud existuje nějaká libovolná strukturovaná podrobnost, kterou chcete zahrnout 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í zpětné zprávy o chybě v reakci na požadovanou zprávu, která obsahuje neplatná data.

Při generování chyby by vlastní kanál neměl chybu odesílat přímo, ale měl by vyhodit výjimku a nechat vrstvu nad sebou rozhodnout, zda tuto výjimku 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álFaultConverter. Pokud je kanál přenosem, musí buď převést výjimku, nebo ji delegovat na kodér FaultConverter nebo na výchozí FaultConverter, který je poskytován ve WCF. Výchozí mechanismus FaultConverter převádí chyby související s chybnými zprávami definovanými pomocí WS-Addressing a 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 procházející vrstvami kanálů by měly místo neprůhledných dat o chybách 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 na jakékoli vrstvě v komunikačním zásobníku, např. InvalidCardinalityAddressingException.

  2. Chyby, které mohou být zjištěny kdekoli nad určitou vrstvou ve vrstveném modelu, například chyby související s tokem transakce nebo s rolemi zabezpečení.

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

Kategorie 1. Mezi typické poruchy patří obecně WS-Addressing a SOAP chyby. Základní FaultConverter třída, kterou poskytuje WCF, převádí chyby odpovídající chybným zprávám určeným WS-Addressing 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á úplně nevyužívá informace o zprávě, jež 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 ignorování zprávy, trasování nebo vyvolání výjimky, která se převede na chybu. Mezi příklady patří případ, kdy zabezpečení obdrží zprávu, která není správně zabezpečená, nebo RM obdrží zprávu 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 chyba odmítnutí sekvence RM, která nemá význam pro vrstvy nad kanálem RM, což znamená selhání kanálu RM a přerušení čekajících operací.

  3. Jinak by zpráva měla být vrácena z Request() nebo Receive(). To zahrnuje případy, kdy vrstva chybu rozpozná, ale tato chyba pouze značí, že požadavek selhal a neznamená označení kanálu jako chybný ani ukončení č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řevedl. Přenosové kanály by měly delegovat na FaultConverter.GetDefaultFaultConverter k 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, aby signalizovala, že příjemce neporozuměl povinné hlavičce. 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ěčemu nebylo rozuměno, v tomto okamžiku se vygeneruje mustUnderstand 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 jde o mustUnderstand chybu. WasHeaderNotUnderstood vrátí true, pokud je hlavička se zadaným názvem a oborem názvů zahrnuta v chybě jako hlavička NotUnderstood. V opačném případě 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.

Trasová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:

Součásti 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í instance TraceSource se řetězec, který zadáte, 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, TraceEvent nebo TraceInformation metody k zápisu položek trasování do posluchačů 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 posluchači. Například nastavení úrovně trasování v konfiguraci tak, aby umožňovalo zápis trasovacích položek Warning, Warning a Error, ale blokovalo položky typu informace a podrobný výstup. Tady je příklad vytvoření instance zdroje trasování a napsání položky na úrovni úrovně informací.

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 se zobrazovačem trasování

Trasování vygenerované vaším kanálem může být exportováno ve formátu čitelném nástrojem Service Trace Viewer (SvcTraceViewer.exe) pomocí System.Diagnostics.XmlWriterTraceListener posluchače 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 pro trasování v konfiguračním souboru aplikace. Například následující konfigurace vypíše trasovací informace jak z System.ServiceModel, tak z Microsoft.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. Váš kanál by měl toto schéma používat při trasování strukturovaných dat aplikace, aby pomohl uživatelům Svctraceviewer.exe lépe číst data.

  • Last updated on