Quali sono i modi migliori per bilanciare le eccezioni informative e il codice pulito?

Con il nostro SDK pubblico, tendiamo a voler inviare messaggi molto informativi sul perché si verifica un'eccezione. Per esempio:

if (interfaceInstance == null)
{
     string errMsg = string.Format(
          "Construction of Action Argument: {0}, via the empty constructor worked, but type: {1} could not be cast to type {2}.",
          ParameterInfo.Name,
          ParameterInfo.ParameterType,
          typeof(IParameter)
    );

    throw new InvalidOperationException(errMsg);
}

Tuttavia, ciò tende a ingombrare il flusso del codice, in quanto tende a concentrarsi molto sui messaggi di errore piuttosto che su ciò che il codice sta facendo.

Un collega ha iniziato a refactoring alcune delle eccezioni lanciate a qualcosa del genere:

if (interfaceInstance == null)
    throw EmptyConstructor();

...

private Exception EmptyConstructor()
{
    string errMsg = string.Format(
          "Construction of Action Argument: {0}, via the empty constructor worked, but type: {1} could not be cast to type {2}.",
          ParameterInfo.Name,
          ParameterInfo.ParameterType,
          typeof(IParameter)
    );

    return new InvalidOperationException(errMsg);
}

Ciò rende la logica del codice più semplice da comprendere, ma aggiunge molti altri metodi per gestire gli errori.

Quali sono altri modi per evitare il problema "logica di disordine dei messaggi di eccezione lunga"? Sto principalmente chiedendo idiomatico C # /. NET, ma anche come altre lingue lo gestiscono sono utili.

[Modificare]

Sarebbe bello avere anche i pro e i contro di ogni approccio.

Perché non avere classi di eccezione specializzate?

if (interfaceInstance == null)
{
    throw new ThisParticularEmptyConstructorException(<maybe a couple parameters>);
}

Ciò spinge la formattazione e i dettagli all'eccezione stessa e lascia la classe principale ordinata.

Microsoft sembra (guardando l'origine .NET) a volte utilizzare stringhe di risorse / ambiente. Ad esempio ParseDecimal:

throw new OverflowException(Environment.GetResourceString("Overflow_Decimal"));

Professionisti:

• Centralizzare i messaggi delle eccezioni, consentendo il riutilizzo
• Mantenere il messaggio di eccezione (probabilmente che non ha importanza codificare) lontano dalla logica dei metodi
• Il tipo di eccezione generata è chiaro
• I messaggi possono essere localizzati

Contro:

• Se viene modificato un messaggio di eccezione, cambiano tutti
• Il messaggio di eccezione non è così facilmente disponibile per il codice che genera l'eccezione.
• Il messaggio è statico e non contiene informazioni sui valori errati. Se vuoi formattarlo, è più disordinato nel codice.

Per lo scenario SDK pubblico, prenderei in seria considerazione l'utilizzo dei Contratti di codice Microsoft in quanto forniscono errori informativi, controlli statici e puoi anche generare documentazione da aggiungere in documenti XML e file di aiuto generati da Sandcastle . È supportato in tutte le versioni a pagamento di Visual Studio.

Un ulteriore vantaggio è che se i tuoi clienti utilizzano C #, possono sfruttare i tuoi assiemi di riferimento del contratto di codice per rilevare potenziali problemi anche prima che eseguano il loro codice.

La documentazione completa per i contratti di codice è qui .

La tecnica che uso è quella di combinare ed esternalizzare la convalida e lanciare del tutto una funzione di utilità.

Il singolo vantaggio più importante è che è ridotto a una linea nella logica aziendale .

Scommetto che non puoi fare di meglio se non riesci a ridurlo ulteriormente - per eliminare tutte le convalide degli argomenti e le protezioni stato-oggetto dalla logica aziendale, mantenendo solo le condizioni operative eccezionali.

Esistono, ovviamente, modi per farlo: linguaggio fortemente tipizzato, design "nessun oggetto non valido consentito in qualsiasi momento", design per contratto , ecc.

Esempio:

internal static class ValidationUtil
{
    internal static void ThrowIfRectNullOrInvalid(int imageWidth, int imageHeight, Rect rect)
    {
        if (rect == null)
        {
            throw new ArgumentNullException("rect");
        }
        if (rect.Right > imageWidth || rect.Bottom > imageHeight || MoonPhase.Now == MoonPhase.Invisible)
        {
            throw new ArgumentException(
                message: "This is uselessly informative",
                paramName: "rect");
        }
    }
}

public class Thing
{
    public void DoSomething(Rect rect)
    {
        ValidationUtil.ThrowIfRectNullOrInvalid(_imageWidth, _imageHeight, rect);
        // rest of your code
    }
}

[nota] Ho copiato questo dalla domanda in una risposta nel caso in cui ci siano commenti a riguardo.

Sposta ogni eccezione in un metodo della classe, prendendo in considerazione tutti gli argomenti che richiedono la formattazione.

private Exception EmptyConstructor()
{
    string errMsg = string.Format(
          "Construction of Action Argument: {0}, via the empty constructor worked, but type: {1} could not be cast to type {2}.",
          ParameterInfo.Name,
          ParameterInfo.ParameterType,
          typeof(IParameter)
    );

    return new InvalidOperationException(errMsg);
}

Racchiudere tutti i metodi di eccezione nella regione e posizionarli alla fine della classe.

Professionisti:

• Mantiene il messaggio fuori dalla logica principale del metodo
• Consente di aggiungere informazioni logiche a ciascun messaggio (è possibile passare argomenti al metodo)

Contro:

• Metodo disordinato. Potenzialmente potresti avere molti metodi che restituiscono solo eccezioni e non sono realmente correlati alla logica aziendale.
• Impossibile riutilizzare i messaggi in altre classi

Se riesci a cavartela con errori un po 'più generali, potresti scrivere una funzione di cast generica statica pubblica per te, che determina il tipo di sorgente:

public static I CastOrThrow<I,T>(T t, string source)
{
    if (t is I)
        return (I)t;

    string errMsg = string.Format(
          "Failed to complete {0}, because type: {1} could not be cast to type {2}.",
          source,
          typeof(T),
          typeof(I)
        );

    throw new InvalidOperationException(errMsg);
}


/// and then:

var interfaceInstance = SdkHelper.CastTo<IParameter>(passedObject, "Action constructor");

Ci sono variazioni possibili (si pensi SdkHelper.RequireNotNull()), che controllano solo i requisiti sugli input e che generano se falliscono, ma in questo esempio combinare il cast con la produzione del risultato è auto-documentale e compatto.

Se si utilizza .net 4.5, è possibile che il compilatore inserisca il nome del metodo / file corrente come parametro del metodo (vedere CallerMemberAttibute ). Ma per un SDK, probabilmente non puoi richiedere ai tuoi clienti di passare alla 4.5.

Ciò che ci piace fare per gli errori di logica aziendale (non necessariamente errori di argomento ecc.) È avere un unico enum che definisca tutti i potenziali tipi di errori:

/// <summary>
/// This enum is used to identify each business rule uniquely.
/// </summary>
public enum BusinessRuleId {

    /// <summary>
    /// Indicates that a valid body weight value of a patient is missing for dose calculation.
    /// </summary>
    [Display(Name = @"DoseCalculation_PatientBodyWeightMissing")]
    PatientBodyWeightMissingForDoseCalculation = 1,

    /// <summary>
    /// Indicates that a valid body height value of a patient is missing for dose calculation.
    /// </summary>
    [Display(Name = @"DoseCalculation_PatientBodyHeightMissing")]
    PatientBodyHeightMissingForDoseCalculation = 2,

    // ...
}

Gli [Display(Name = "...")]attributi definiscono la chiave nei file di risorse da utilizzare per tradurre i messaggi di errore.

Inoltre, questo file può essere utilizzato come punto di partenza per trovare tutte le occorrenze in cui un determinato tipo di errore viene generato nel codice.

Il controllo delle regole aziendali può essere delegato a classi specializzate di convalida che producono elenchi di regole aziendali violate.

Quindi utilizziamo un tipo di eccezione personalizzato per trasportare le regole violate:

[Serializable]
public class BusinessLogicException : Exception {

    /// <summary>
    /// The Business Rule that was violated.
    /// </summary>
    public BusinessRuleId ViolatedBusinessRule { get; set; }

    /// <summary>
    /// Optional: additional parameters to be used to during generation of the error message.
    /// </summary>
    public string[] MessageParameters { get; set; }

    /// <summary>
    /// This exception indicates that a Business Rule has been violated. 
    /// </summary>
    public BusinessLogicException(BusinessRuleId violatedBusinessRule, params string[] messageParameters) {
        ViolatedBusinessRule = violatedBusinessRule;
        MessageParameters = messageParameters;
    }
}

Le chiamate al servizio back-end sono racchiuse in un codice di gestione degli errori generico, che traduce la regola busines violata in un messaggio di errore leggibile dall'utente:

public object TryExecuteServiceAction(Action a) {
    try {
        return a();
    }
    catch (BusinessLogicException bex) {
        _logger.Error(GenerateErrorMessage(bex));
    }
}

public string GenerateErrorMessage(BusinessLogicException bex) {
    var translatedError = bex.ViolatedBusinessRule.ToTranslatedString();
    if (bex.MessageParameters != null) {
        translatedError = string.Format(translatedError, bex.MessageParameters);
    }
    return translatedError;
}

Ecco ToTranslatedString()un metodo di estensione enumche può leggere le chiavi delle risorse dagli [Display]attributi e usare il ResourceManagerper tradurre queste chiavi. Il valore per la rispettiva chiave di risorsa può contenere segnaposto per string.Format, che corrispondono a quelli forniti MessageParameters. Esempio di una voce nel file resx:

<data name="DoseCalculation_PatientBodyWeightMissing" xml:space="preserve">
    <value>The dose can not be calculated because the body weight observation for patient {0} is missing or not up to date.</value>
    <comment>{0} ... Patient name</comment>
</data>

Esempio di utilizzo:

throw new BusinessLogicException(BusinessRuleId.PatientBodyWeightMissingForDoseCalculation, patient.Name);

Con questo approccio, è possibile separare la generazione del messaggio di errore dalla generazione dell'errore, senza la necessità di introdurre una nuova classe di eccezione per ogni nuovo tipo di errore. Utile se frontend diversi devono visualizzare messaggi diversi, se il messaggio visualizzato dipende dalla lingua dell'utente e / o dal ruolo, ecc.

Vorrei usare le clausole di protezione come in questo esempio in modo che i controlli dei parametri possano essere riutilizzati.

Inoltre, è possibile utilizzare il modello builder in modo da poter concatenare più di una convalida. Sembrerà un po ' asserzioni fluide .