CA1055 : Les valeurs de retour URI ne doivent pas être des chaînes

Cause

Le nom d’une méthode contient « uri », « URI », « urn », « Urn », « URL » ou « Url », et la méthode retourne une chaîne.

Par défaut, cette règle examine uniquement les méthodes visibles en externe, mais elle est configurable.

Description de la règle

Cette règle divise le nom de la méthode en jetons en fonction de la convention de casse Pascal, et vérifie si chaque jeton est égal à « uri », « Uri », « urn », « Urn », « url » ou « Url ». S’il existe une correspondance, la règle part du principe que la méthode retourne un URI (Uniform Resource Identifier). Une représentation sous forme de chaîne d'un URI est sujette aux erreurs d'analyse et d'encodage, et peut entraîner des failles de sécurité. La classe System.Uri fournit ces services de manière sûre et sécurisée.

Comment corriger les violations

Pour corriger une violation de cette règle, remplacez le type de retour par un Uri.

Quand supprimer les avertissements

Vous pouvez sans risque supprimer un avertissement de cette règle si la valeur de retour ne représente pas un URI.

Supprimer un avertissement

Si vous voulez supprimer une seule violation, ajoutez des directives de préprocesseur à votre fichier source pour désactiver et réactiver la règle.

#pragma warning disable CA1055
// The code that's violating the rule is on this line.
#pragma warning restore CA1055

Pour désactiver la règle sur un fichier, un dossier ou un projet, définissez sa gravité sur none dans le fichier de configuration.

[*.{cs,vb}]
dotnet_diagnostic.CA1055.severity = none

Pour plus d’informations, consultez Comment supprimer les avertissements de l’analyse de code.

Configurer le code à analyser

Utilisez l’option suivante pour configurer les parties de votre codebase sur lesquelles exécuter cette règle.

• Inclure des surfaces d’API spécifiques
• Exclure des symboles spécifiques
• Exclure des types spécifiques et leurs types dérivés

Vous pouvez configurer ces options pour cette règle uniquement, pour toutes les règles auxquelles elles s’appliquent ou pour toutes les règles de cette catégorie (Conception) auxquelles elles s’appliquent. Pour plus d’informations, consultez Options de configuration des règles de qualité du code.

Inclure des surfaces d’API spécifiques

Vous pouvez configurer les parties de votre codebase sur lesquelles exécuter cette règle, en fonction de leur accessibilité. Par exemple, pour spécifier que la règle doit s’exécuter uniquement sur la surface d’API non publique, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exclure des symboles spécifiques

Vous pouvez exclure de l’analyse des symboles spécifiques, comme des types et des méthodes. Par exemple, pour spécifier que la règle ne doit pas s’exécuter sur du code dans des types nommés MyType, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formats de nom de symbole autorisés dans la valeur d’option (séparés par |) :

• Nom du symbole uniquement (inclut tous les symboles avec le nom, quel que soit le type ou l’espace de noms qui les contient).
• Noms qualifiés complets au format d’ID de documentation du symbole. Chaque nom de symbole nécessite un préfixe de type symbole, comme M: pour les méthodes, T: pour les types et N: pour les espaces de noms.
• .ctor pour les constructeurs et .cctor pour les constructeurs statiques.

Exemples :

Exclure des types spécifiques et leurs types dérivés

Vous pouvez exclure de l’analyse des types spécifiques et leurs types dérivés. Par exemple, pour spécifier que la règle ne doit s’exécuter sur aucune méthode dans des types nommés MyType et leurs types dérivés, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formats de nom de symbole autorisés dans la valeur d’option (séparés par |) :

• Nom du type uniquement (inclut tous les types avec le nom, quel que soit le type ou l’espace de noms qui les contient).
• Noms qualifiés complets au format d’ID de documentation du symbole, avec un préfixe T: facultatif.

Exemples :

Exemple

L’exemple suivant montre un type, ErrorProne, qui enfreint cette règle, et un type, SaferWay, qui satisfait à la règle.

public class ErrorProne
{
    // Violates rule UriPropertiesShouldNotBeStrings.
    public string? SomeUri { get; set; }

    // Violates rule UriParametersShouldNotBeStrings.
    public void AddToHistory(string uriString) { }

    // Violates rule UriReturnValuesShouldNotBeStrings.
    public string GetReferrerUri(string httpHeader)
    {
        return "http://www.adventure-works.com";
    }
}

public class SaferWay
{
    // To retrieve a string, call SomeUri.ToString().
    // To set using a string, call SomeUri = new Uri(string).
    public Uri? SomeUri { get; set; }

    public void AddToHistory(string uriString)
    {
        // Check for UriFormatException.
        AddToHistory(new Uri(uriString));
    }

    public void AddToHistory(Uri uriType) { }

    public Uri GetReferrerUri(string httpHeader)
    {
        return new Uri("http://www.adventure-works.com");
    }
}

Imports System

Namespace ca1055

    Public Class ErrorProne

        ' Violates rule UriPropertiesShouldNotBeStrings.
        Property SomeUri As String

        ' Violates rule UriParametersShouldNotBeStrings.
        Sub AddToHistory(uriString As String)
        End Sub

        ' Violates rule UriReturnValuesShouldNotBeStrings.
        Function GetRefererUri(httpHeader As String) As String
            Return "http://www.adventure-works.com"
        End Function

    End Class

    Public Class SaferWay

        ' To retrieve a string, call SomeUri.ToString().
        ' To set using a string, call SomeUri = New Uri(string).
        Property SomeUri As Uri

        Sub AddToHistory(uriString As String)
            ' Check for UriFormatException.
            AddToHistory(New Uri(uriString))
        End Sub

        Sub AddToHistory(uriString As Uri)
        End Sub

        Function GetRefererUri(httpHeader As String) As Uri
            Return New Uri("http://www.adventure-works.com")
        End Function

    End Class

End Namespace

Règles associées

• CA1056 : Les propriétés URI ne doivent pas être des chaînes
• CA1054 : Les paramètres URI ne doivent pas être des chaînes
• CA2234 : Passez des objets System.Uri à la place de chaînes