CA2234: Pass System.Uri objects instead of strings

TypeName	PassSystemUriObjectsInsteadOfStrings
CheckId	CA2234
Category	Microsoft.Usage
Breaking Change	Non Breaking

Cause

A call is made to a method that has a string parameter whose name contains "uri", "Uri", "urn", "Urn", "url", or "Url"; and the declaring type of the method contains a corresponding method overload that has a System.Uri parameter.

Rule Description

A parameter name is split into tokens based on the camel casing convention, and then each token is checked to see whether it equals "uri", "Uri", "urn", "Urn", "url", or "Url". If there is a match, the parameter is assumed to represent a uniform resource identifier (URI). A string representation of a URI is prone to parsing and encoding errors, and can lead to security vulnerabilities. The Uri class provides these services in a safe and secure manner. When there is a choice between two overloads that differ only regarding the representation of a URI, the user should choose the overload that takes a Uri argument.

How to Fix Violations

To fix a violation of this rule, call the overload that takes the Uri argument.

When to Suppress Warnings

It is safe to suppress a warning from this rule if the string parameter does not represent a URI.

Example

The following example shows a method, ErrorProne, which violates the rule and a method, SaferWay, which correctly calls the Uri overload.

Imports System

Namespace DesignLibrary

   Class History

      Friend Sub AddToHistory(uriString As String)
      End Sub

      Friend Sub AddToHistory(uriType As Uri)
      End Sub

   End Class

   Public Class Browser

      Dim uriHistory As New History()

      Sub ErrorProne()
         uriHistory.AddToHistory("https://www.adventure-works.com")
      End Sub

      Sub SaferWay()
         Try
            Dim newUri As New Uri("https://www.adventure-works.com")
            uriHistory.AddToHistory(newUri)
         Catch uriException As UriFormatException
         End Try
      End Sub

   End Class

End Namespace

using System;

namespace DesignLibrary
{
   class History
   {
      internal void AddToHistory(string uriString) {}
      internal void AddToHistory(Uri uriType) {}
   }

   public class Browser
   {
      History uriHistory = new History();

      public void ErrorProne()
      {
         uriHistory.AddToHistory("https://www.adventure-works.com");
      }

      public void SaferWay()
      {
         try
         {
            Uri newUri = new Uri("https://www.adventure-works.com");
            uriHistory.AddToHistory(newUri);
         }
         catch(UriFormatException uriException) {}
      }
   }
}

#using <system.dll>
using namespace System;

namespace DesignLibrary
{
   ref class History
   {
   public:
      void AddToHistory(String^ uriString) {}
      void AddToHistory(Uri^ uriType) {}
   };

   public ref class Browser
   {
      History^ uriHistory;

   public:
      Browser()
      {
         uriHistory = gcnew History();
      }

      void ErrorProne()
      {
         uriHistory->AddToHistory("https://www.adventure-works.com");
      }

      void SaferWay()
      {
         try
         {
            Uri^ newUri = gcnew Uri("https://www.adventure-works.com");
            uriHistory->AddToHistory(newUri);
         }
         catch(UriFormatException^ uriException) {}
      }
   };
}

Related Rules

CA1057: String URI overloads call System.Uri overloads

CA1056: URI properties should not be strings

CA1054: URI parameters should not be strings

CA1055: URI return values should not be strings