diff --git a/src/libraries/System.Net.WebProxy/src/System.Net.WebProxy.csproj b/src/libraries/System.Net.WebProxy/src/System.Net.WebProxy.csproj index 31f73cc666e8dc..bde282304c4895 100644 --- a/src/libraries/System.Net.WebProxy/src/System.Net.WebProxy.csproj +++ b/src/libraries/System.Net.WebProxy/src/System.Net.WebProxy.csproj @@ -3,7 +3,6 @@ $(NetCoreAppCurrent);$(NetCoreAppCurrent)-browser;$(NetCoreAppCurrent)-wasi true - false diff --git a/src/libraries/System.Net.WebProxy/src/System/Net/IWebProxyScript.cs b/src/libraries/System.Net.WebProxy/src/System/Net/IWebProxyScript.cs index 92f6a099d8d4eb..78094dfdb22d56 100644 --- a/src/libraries/System.Net.WebProxy/src/System/Net/IWebProxyScript.cs +++ b/src/libraries/System.Net.WebProxy/src/System/Net/IWebProxyScript.cs @@ -3,10 +3,39 @@ namespace System.Net { + /// + /// Provides the base interface to load and execute scripts for automatic proxy detection. + /// public interface IWebProxyScript { + /// + /// Closes a script. + /// void Close(); + + /// + /// Loads a script. + /// + /// The URI that identifies the location of the proxy auto-configuration script. + /// The script content to load and prepare for execution. + /// The type that provides helper methods or services available to the script at runtime. + /// A indicating whether the script was successfully loaded. bool Load(Uri scriptLocation, string script, Type helperType); + + /// + /// Runs a script. + /// + /// The destination URL for which proxy information is requested. + /// The host name associated with the destination URL. + /// + /// A that describes how to connect to the destination, such as a proxy configuration directive (for example, "DIRECT" or "PROXY host:port"). + /// + /// + /// + /// When the object is run, it might need to run the WPAD (Web Proxy Automatic Detection) protocol to detect whether a proxy is required for reaching the destination URL. + /// During this process, the system downloads and compiles the PAC (Proxy Auto-Configuration) script in memory and tries to execute the FindProxyForURL function as per the PAC specification. + /// + /// string Run(string url, string host); } } diff --git a/src/libraries/System.Net.WebProxy/src/System/Net/WebProxy.cs b/src/libraries/System.Net.WebProxy/src/System/Net/WebProxy.cs index 7004b685a5d056..dfe1a40bad1f5a 100644 --- a/src/libraries/System.Net.WebProxy/src/System/Net/WebProxy.cs +++ b/src/libraries/System.Net.WebProxy/src/System/Net/WebProxy.cs @@ -13,19 +13,94 @@ namespace System.Net { + /// + /// Contains HTTP proxy settings for the class. + /// + /// + /// + /// The class contains the proxy settings that instances use to determine whether a Web proxy is used to send requests. + /// Global Web proxy settings can be specified in machine and application configuration files, and applications can use instances of the class to customize Web proxy use. + /// The class is the base implementation of the interface. + /// + /// + /// To obtain instances of the Web proxy class, you can use any of the following methods: + /// + /// + /// The constructor. + /// The method. + /// + /// + /// These methods each supply a instance that you can further customize; the difference between them is how the instance is initialized before it is returned to your application. + /// The constructor returns an instance of the class with the property set to . + /// When a request uses a instance in this state, no proxy is used to send the request. + /// + /// + /// In .NET Framework, the method returns an instance of the class with the , , and properties set to the values used by the local computer. + /// + /// + /// The class supports automatic detection and execution of proxy configuration scripts. This feature is also known as Web Proxy Auto-Discovery (WPAD). + /// When using automatic proxy configuration, a configuration script, typically named Wpad.dat, must be located, downloaded, compiled, and run. + /// If these operations are successful, the script returns the proxies that can be used for a request. + /// + /// public partial class WebProxy : IWebProxy, ISerializable { private ChangeTrackingArrayList? _bypassList; private Regex[]? _regexBypassList; + /// + /// Initializes an empty instance of the class. + /// + /// + /// + /// The parameterless constructor initializes an empty instance of the class with the property set to . + /// + /// + /// When the property is , the method returns and the method returns the destination address. + /// + /// public WebProxy() : this((Uri?)null, false, null, null) { } + /// + /// Initializes a new instance of the class from the specified instance. + /// + /// The address of the proxy server. + /// + /// The instance is initialized with the property set to the parameter. + /// public WebProxy(Uri? Address) : this(Address, false, null, null) { } + /// + /// Initializes a new instance of the class with the instance and bypass setting. + /// + /// A instance that contains the address of the proxy server. + /// to bypass the proxy for local addresses; otherwise, . + /// + /// The instance is initialized with the property set to and with the property set to . + /// public WebProxy(Uri? Address, bool BypassOnLocal) : this(Address, BypassOnLocal, null, null) { } + /// + /// Initializes a new instance of the class with the specified instance, bypass setting, and list of URIs to bypass. + /// + /// A instance that contains the address of the proxy server. + /// to bypass the proxy for local addresses; otherwise, . + /// An array of regular expression strings that contains the URIs of the servers to bypass. + /// + /// The instance is initialized with the property set to , the property set to , and the property set to . + /// public WebProxy(Uri? Address, bool BypassOnLocal, [StringSyntax(StringSyntaxAttribute.Regex, RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] string[]? BypassList) : this(Address, BypassOnLocal, BypassList, null) { } + /// + /// Initializes a new instance of the class with the specified instance, bypass setting, list of URIs to bypass, and credentials. + /// + /// A instance that contains the address of the proxy server. + /// to bypass the proxy for local addresses; otherwise, . + /// An array of regular expression strings that contains the URIs of the servers to bypass. + /// An instance to submit to the proxy server for authentication. + /// + /// The instance is initialized with the property set to , the property set to , the property set to , and the property set to . + /// public WebProxy(Uri? Address, bool BypassOnLocal, [StringSyntax(StringSyntaxAttribute.Regex, RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] string[]? BypassList, ICredentials? Credentials) { this.Address = Address; @@ -38,35 +113,100 @@ public WebProxy(Uri? Address, bool BypassOnLocal, [StringSyntax(StringSyntaxAttr } } + /// + /// Initializes a new instance of the class with the specified host and port number. + /// + /// The name of the proxy host. + /// The port number on to use. + /// The URI formed by combining and is not a valid URI. + /// + /// The instance is initialized with the property set to a instance of the form http://:. + /// public WebProxy(string Host, int Port) : this(CreateProxyUri(Host, Port), false, null, null) { } + /// + /// Initializes a new instance of the class with the specified URI. + /// + /// The URI of the proxy server. + /// is an invalid URI. + /// + /// The instance is initialized with the property set to a instance containing . + /// public WebProxy(string? Address) : this(CreateProxyUri(Address), false, null, null) { } + /// + /// Initializes a new instance of the class with the specified URI and bypass setting. + /// + /// The URI of the proxy server. + /// to bypass the proxy for local addresses; otherwise, . + /// is an invalid URI. + /// + /// The instance is initialized with the property set to a instance that contains and the property set to . + /// public WebProxy(string? Address, bool BypassOnLocal) : this(CreateProxyUri(Address), BypassOnLocal, null, null) { } + /// + /// Initializes a new instance of the class with the specified URI, bypass setting, and list of URIs to bypass. + /// + /// The URI of the proxy server. + /// to bypass the proxy for local addresses; otherwise, . + /// An array of regular expression strings that contain the URIs of the servers to bypass. + /// is an invalid URI. + /// + /// The instance is initialized with the property set to a instance that contains , the property set to , and the property set to . + /// public WebProxy(string? Address, bool BypassOnLocal, [StringSyntax(StringSyntaxAttribute.Regex, RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] string[]? BypassList) : this(CreateProxyUri(Address), BypassOnLocal, BypassList, null) { } + /// + /// Initializes a new instance of the class with the specified URI, bypass setting, list of URIs to bypass, and credentials. + /// + /// The URI of the proxy server. + /// to bypass the proxy for local addresses; otherwise, . + /// An array of regular expression strings that contains the URIs of the servers to bypass. + /// An instance to submit to the proxy server for authentication. + /// is an invalid URI. + /// + /// The instance is initialized with the property set to a instance that contains , the property set to , the property set to , and the property set to . + /// public WebProxy(string? Address, bool BypassOnLocal, [StringSyntax(StringSyntaxAttribute.Regex, RegexOptions.IgnoreCase | RegexOptions.CultureInvariant)] string[]? BypassList, ICredentials? Credentials) : this(CreateProxyUri(Address), BypassOnLocal, BypassList, Credentials) { } + /// + /// Gets or sets the address of the proxy server. + /// + /// + /// A instance that contains the address of the proxy server. + /// public Uri? Address { get; set; } + /// + /// Gets or sets a value that indicates whether to bypass the proxy server for local addresses. + /// + /// + /// to bypass the proxy server for local addresses; otherwise, . The default value is . + /// public bool BypassProxyOnLocal { get; set; } + /// + /// Gets or sets an array of addresses that do not use the proxy server. + /// + /// + /// An array of regular expression strings that contains the URIs of servers that should not use the proxy server when accessed. + /// [AllowNull] public string[] BypassList { @@ -88,16 +228,42 @@ public string[] BypassList } } + /// + /// Gets or sets an of addresses that do not use the proxy server. + /// + /// + /// An that contains a list of regular expressions that represents URIs that do not use the proxy server when accessed. + /// public ArrayList BypassArrayList => _bypassList ??= new ChangeTrackingArrayList(); + /// + /// Gets or sets the credentials to submit to the proxy server for authentication. + /// + /// + /// An instance that contains the credentials to submit to the proxy server for authentication. + /// public ICredentials? Credentials { get; set; } + /// + /// Gets or sets a value that controls whether the are sent with requests. + /// + /// + /// if the default credentials are used; otherwise, . The default value is . + /// public bool UseDefaultCredentials { get => Credentials == CredentialCache.DefaultCredentials; set => Credentials = value ? CredentialCache.DefaultCredentials : null; } + /// + /// Returns the URI of a proxy. + /// + /// The instance of the requested Internet resource. + /// + /// The instance of the Internet resource, if the resource is on the bypass list; otherwise, the instance of the proxy. + /// + /// The parameter is . public Uri? GetProxy(Uri destination) { ArgumentNullException.ThrowIfNull(destination); @@ -192,6 +358,14 @@ private bool IsMatchInBypassList(Uri input) return false; } + /// + /// Indicates whether to use the proxy server for the specified host. + /// + /// The instance of the host to check for proxy use. + /// + /// if the proxy server should not be used for ; otherwise, . + /// + /// The parameter is . public bool IsBypassed(Uri host) { ArgumentNullException.ThrowIfNull(host); @@ -202,6 +376,15 @@ public bool IsBypassed(Uri host) IsMatchInBypassList(host); } + /// + /// Initializes an instance of the class using previously serialized content. + /// + /// The serialization data. + /// The context for the serialized data. + /// This method is not supported and will always throw . + /// + /// This method is called by the system to deserialize a instance; applications do not call it. + /// [Obsolete(Obsoletions.LegacyFormatterImplMessage, DiagnosticId = Obsoletions.LegacyFormatterImplDiagId, UrlFormat = Obsoletions.SharedUrlFormat)] [EditorBrowsable(EditorBrowsableState.Never)] protected WebProxy(SerializationInfo serializationInfo, StreamingContext streamingContext) => @@ -210,9 +393,22 @@ protected WebProxy(SerializationInfo serializationInfo, StreamingContext streami void ISerializable.GetObjectData(SerializationInfo serializationInfo, StreamingContext streamingContext) => throw new PlatformNotSupportedException(); + /// + /// Populates a with the data that is needed to serialize the target object. + /// + /// The to populate with data. + /// A that specifies the destination for this serialization. + /// This method is not supported and will always throw . protected virtual void GetObjectData(SerializationInfo serializationInfo, StreamingContext streamingContext) => throw new PlatformNotSupportedException(); + /// + /// Returns the proxy information configured by the system. + /// + /// + /// A instance that contains the nondynamic proxy settings from Internet options. + /// + /// This method is not supported on .NET Core and will always throw . [Obsolete("WebProxy.GetDefaultProxy has been deprecated. Use the proxy selected for you by default.")] public static WebProxy GetDefaultProxy() => // The .NET Framework here returns a proxy that fetches IE settings and