What the Class Is Used For

Use Chilkat.HttpRequest to build an HTTP request object that will later be sent by a Chilkat.Http method. The object can hold the HTTP verb, path, HTTP version, headers, query parameters, body data, upload parts, and multipart/form-data settings.

Important: HttpRequest is only used by the Chilkat Http class as an argument to certain methods. It does not connect to servers or send requests by itself.

Build Custom Requests Set HttpVerb, Path, HttpVersion, headers, and query parameters.

Create Form Requests Add URL-encoded parameters or build multipart/form-data requests with file and data upload parts.

Send Raw or Streamed Bodies Load request bodies from strings, bytes, files, BinData, or StringBuilder, and stream large files without loading them fully into memory.

Inspect Request Structure Enumerate headers and parameters, generate request text, or write the generated request to a file for diagnostics.

Typical Workflow

Create and configure a Http object for connection, TLS, proxy, authentication, timeout, and other transport-level behavior.
Create a HttpRequest object.
Set HttpVerb, such as GET, POST, PUT, DELETE, or a WebDAV/custom verb.
Set Path to the resource path, optionally including query parameters.
Set ContentType when the request has a body.
Add headers with AddHeader and query/form parameters with AddParam.
For body requests, use a body-loading method such as LoadBodyFromString, LoadBodyFromBd, or StreamBodyFromFile.
For multipart uploads, set ContentType to multipart/form-data and add upload parts.
Pass the configured HttpRequest to the appropriate Http method.
Use GenerateRequestText or GenerateRequestFile when you need to inspect what would be sent.

Core Concepts

Concept	Meaning	Important Members
Request Object	A structured description of an HTTP request that is sent by Chilkat.Http.	HttpVerb, Path, ContentType
Request Path	The resource path portion of the URL. It may also include query parameters.	Path, SetFromUrl
Query Parameters	Name/value pairs added to the request and URL-encoded by Chilkat when needed.	AddParam, GetUrlEncodedParams, RemoveParam
Request Headers	MIME-style HTTP header fields included in the request.	AddHeader, GetHeaderField, RemoveHeader
Request Body	The MIME body of a non-multipart HTTP request, loaded from memory or streamed from a file.	LoadBodyFromString, LoadBodyFromBytes, StreamBodyFromFile
Multipart Upload	A multipart/form-data request containing one or more file or in-memory upload parts.	Boundary, AddFileForUpload, AddBytesForUpload, AddStringForUpload

Core Properties

Property	Purpose	Guidance
HttpVerb	Sets the HTTP method used on the request start line.	Can be standard verbs such as GET, POST, PUT, and DELETE, WebDAV verbs, or custom verbs.
Path	Sets the requested resource path.	Use the path part of the URL, such as /api/items. Query parameters may also be included in this value.
HttpVersion	Sets the HTTP version in the request header.	Defaults to 1.1. Can only be 1.0 or 1.1.
ContentType	Sets the Content-Type header and identifies the request body type.	Common values include application/x-www-form-urlencoded, multipart/form-data, application/json, and application/xml. An empty string omits the Content-Type header.
Charset	Controls the character encoding used when URL-encoding query parameters.	Default is utf-8.
SendCharset	Controls whether the charset is explicitly included in the Content-Type header of an HTTP POST request.	Default is false.
Boundary	Sets an explicit boundary string for multipart/form-data requests.	Leave unset to allow Chilkat to generate a boundary automatically as needed.
EntireHeader	Composes and returns the entire MIME header of the HTTP request.	Useful for diagnostics or inspection.
NumHeaderFields	Returns the number of request header fields.	Use with GetHeaderName and GetHeaderValue to enumerate headers.
NumParams	Returns the number of query parameters.	Use with GetParamName and GetParamValue to enumerate parameters.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Path and Parameter Handling

Task	Member	Behavior
Set path directly	Path	Set the resource path, such as /over/there. A path of / indicates the default document of the domain.
Parse path and query from URL	SetFromUrl	Parses a URL and sets Path and request parameters.
Add parameter	AddParam	Adds a name/value request parameter. The name and value should not already be URL encoded.
Remove one parameter	RemoveParam	Removes a single request parameter by name.
Remove all parameters	RemoveAllParams	Clears all request parameters.
Get encoded parameter string	GetUrlEncodedParams	Returns the request parameters in URL-encoded form, as they would be sent for application/x-www-form-urlencoded.

Path guidance: Set Path to the path part of the URL. The fragment portion of a URL is never needed in an HTTP request because it is only a browser navigation instruction.

Query/body guidance: If the request is not application/x-www-form-urlencoded, query parameters normally belong in the path/query string. If the request is application/x-www-form-urlencoded, parameters are passed in the request body. Avoid placing the same parameter in both places.

Header Methods

Method	Purpose	Important Details
AddHeader	Adds or replaces a request header field.	If a header with the same field name already exists, it is replaced.
RemoveHeader	Removes all occurrences of a request header field.	Always returns true.
GetHeaderField	Gets a request header value by field name.	Use when you know the header name.
GetHeaderName	Gets the Nth request header field name.	Indexing begins at 0. Use with NumHeaderFields.
GetHeaderValue	Gets the Nth request header field value.	Indexing begins at 0. Use with NumHeaderFields.
AddSubHeader	Adds or replaces a header in the Nth sub-header.	Used for multipart-style request structures where sub-headers exist.

Do not set Content-Length manually: Chilkat automatically computes and adds the correct Content-Length header for POST, PUT, and other requests where it is needed. GET requests have a zero-length body and do not need a Content-Length header.

Request Body Methods

Method	Input	Best Use
LoadBodyFromString	String plus charset	Set a non-multipart request body from text, converted to the specified charset.
LoadBodyFromSb	StringBuilder plus charset	Set a text body from a StringBuilder.
LoadBodyFromBytes	Byte array	Set the request body to exact bytes held in memory.
LoadBodyFromBd	BinData	Set the request body from BinData.
LoadBodyFromFile	File path	Set the request body to the exact contents of a file.
StreamBodyFromFile	File path	Stream a large request body directly from a file when the request is sent, avoiding full in-memory loading.
StreamChunkFromFile	File path, offset, and byte count	Stream only a specified chunk of a file. The offset and byte count are passed as strings.

Non-multipart body rule: For non-multipart HTTP requests, the request consists of the HTTP start line, MIME header fields, and the MIME body. The LoadBody* methods set the MIME body.

Multipart/Form-Data Upload Methods

To create a multipart upload request, set ContentType to multipart/form-data, then add one or more upload parts.

Method	Upload Source	Content-Type Handling
AddFileForUpload	Existing local file.	Content type is automatically determined from the file extension.
AddFileForUpload2	Existing local file.	Caller specifies the part Content-Type.
AddBytesForUpload	In-memory byte array.	Content type is automatically determined from the remote filename extension.
AddBytesForUpload2	In-memory byte array.	Caller specifies the part Content-Type.
AddBdForUpload	BinData.	Caller provides the part Content-Type, or passes an empty string to let Chilkat determine it from the filename extension.
AddStringForUpload	In-memory string plus charset.	Content type is automatically determined from the filename extension.
AddStringForUpload2	In-memory string plus charset.	Caller specifies the part Content-Type.

Large upload advantage: AddFileForUpload does not read the file into memory. When the upload occurs, the data is streamed directly from the file, allowing very large files to be uploaded without consuming large amounts of memory.

Parameter Inspection Methods

Need	Method / Property	Behavior
Count parameters	NumParams	Returns the number of request parameters.
Get parameter by name	GetParam	Returns a request parameter value by name.
Get Nth parameter name	GetParamName	Returns the Nth parameter name. Indexing begins at 0.
Get Nth parameter value	GetParamValue	Returns the Nth parameter value. Indexing begins at 0.
Get URL-encoded parameter string	GetUrlEncodedParams	Returns the parameters in URL-encoded form.

Request Generation and Diagnostics

Method / Property	Purpose	When to Use
GenerateRequestText	Returns the request text that would be sent by Http.SynchronousRequest.	Use to inspect the generated request before sending.
GenerateRequestFile	Writes the generated request to a file.	Use when the generated request should be saved for troubleshooting or comparison.
EntireHeader	Returns the composed MIME header of the HTTP request.	Use to inspect headers without generating the full request body.
LastErrorText	Diagnostic text for the last method or property access.	Check after failed or unexpected request-building operations.

Method Summary by Category

Category	Methods	Purpose
Headers	AddHeader, AddSubHeader, RemoveHeader, GetHeaderField, GetHeaderName, GetHeaderValue	Add, replace, remove, and inspect request headers.
Parameters	AddParam, RemoveParam, RemoveAllParams, GetParam, GetParamName, GetParamValue, GetUrlEncodedParams, SetFromUrl	Build, parse, inspect, URL-encode, and remove query/form parameters.
Request body	LoadBodyFromString, LoadBodyFromSb, LoadBodyFromBytes, LoadBodyFromBd, LoadBodyFromFile, StreamBodyFromFile, StreamChunkFromFile	Set or stream the body of non-multipart HTTP requests.
Multipart uploads	AddFileForUpload, AddFileForUpload2, AddBytesForUpload, AddBytesForUpload2, AddBdForUpload, AddStringForUpload, AddStringForUpload2	Add file, byte-array, BinData, or string parts to multipart/form-data requests.
Diagnostics	GenerateRequestText, GenerateRequestFile, EntireHeader	Generate or inspect the request before sending.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
Request is not sent	HttpRequest	Remember that HttpRequest does not send the request by itself. It must be passed to a suitable Chilkat.Http method.
Incorrect path or query string	Path, SetFromUrl, AddParam	Confirm the path is only the URL path/query portion, not the full URL, unless using SetFromUrl.
Parameters are double-encoded	AddParam	Pass unencoded names and values to AddParam. Chilkat performs URL encoding when needed.
Wrong body format	ContentType	Make sure ContentType matches the body style: JSON, XML, URL-encoded form, or multipart/form-data.
Large body consumes too much memory	StreamBodyFromFile, StreamChunkFromFile, AddFileForUpload	Stream the body or upload file directly from disk instead of loading the entire content into memory.
Multipart upload boundary problems	Boundary	Normally leave Boundary unset so Chilkat generates it automatically. Set it only when an explicit boundary is required.
Server rejects manual Content-Length	AddHeader	Do not manually add Content-Length. Chilkat calculates it automatically.
Need to inspect what would be sent	GenerateRequestText, GenerateRequestFile, EntireHeader	Generate or inspect the composed request for debugging.

Common Pitfalls

Pitfall	Better Approach
Treating HttpRequest as an object that sends HTTP requests.	Use it only to build the request, then pass it to a Chilkat.Http method.
Putting the full URL in Path.	Put only the path and optional query in Path, or use SetFromUrl to parse a URL.
Including the URL fragment in the request.	Do not include fragments such as #section; they are browser-side navigation instructions.
Manually URL-encoding values before calling AddParam.	Pass raw parameter names and values. Let Chilkat encode them according to Charset.
Adding the same parameter in both the path query string and form body.	Choose one location for each parameter to avoid ambiguity.
Setting Content-Length manually.	Let Chilkat compute and add Content-Length.
Using multipart upload methods without setting ContentType.	Set ContentType = "multipart/form-data" before adding upload parts.
Loading very large request bodies into memory.	Use StreamBodyFromFile, StreamChunkFromFile, or file-based multipart upload methods.

Best Practices

Recommendation	Reason
Use HttpRequest only where a Chilkat Http method expects it.	The object is a request-building helper, not an HTTP transport object.
Set HttpVerb, Path, and ContentType deliberately.	These define the core shape of the request.
Use AddParam with unencoded values.	Chilkat handles URL encoding using the configured Charset.
Use body-loading methods that match the data source.	Strings, StringBuilder, byte arrays, BinData, and files each have dedicated methods.
Use streaming methods for large bodies.	Streaming avoids loading large files entirely into memory.
Let Chilkat manage Content-Length and multipart boundaries.	Chilkat automatically calculates content length and can generate multipart boundaries as needed.
Use generated request output for debugging.	GenerateRequestText and GenerateRequestFile help inspect the composed request before sending.
Check LastErrorText after failures.	It provides useful diagnostic detail for request construction, body loading, file streaming, multipart upload setup, and parameter/header handling.

Summary

Chilkat.HttpRequest is a helper class for constructing HTTP requests that are sent by the Chilkat.Http class. It is used as an argument to certain Http methods and does not perform network communication on its own. It provides structured control over the request method, HTTP version, path, headers, parameters, content type, request body, multipart uploads, streamed file bodies, and diagnostic request generation.

The most important practical guidance is to use HttpRequest only as a request-building object for Chilkat.Http, let Chilkat handle URL encoding and Content-Length, choose the correct body or multipart method for the data source, and use streaming methods for large files.

Chilkat.HttpRequest Class Overview