Derivazione da WebRequest

La classe WebRequest è una classe base abstract che fornisce le proprietà e i metodi di base per la creazione di un gestore richieste specifico del protocollo adatto al modello di protocollo innestabile di .NET Framework. Nelle applicazioni che utilizzano la classe WebRequest è possibile richiedere dati mediante qualsiasi protocollo supportato senza la necessità di specificare quello utilizzato.

Affinché sia possibile utilizzare una classe specifica del protocollo come protocollo innestabile è necessario che siano soddisfatti due criteri: nella classe deve essere implementata l'interfaccia IWebRequestCreate e deve essere eseguita la registrazione con il metodo WebRequest.RegisterPrefix. La classe deve consentire di eseguire l'override di ogni proprietà e metodo abstract di WebRequest per fornire l'interfaccia innestabile.

Ogni istanza di WebRequest può essere utilizzata una sola volta; per effettuare un'altra richiesta, creare una nuova WebRequest. WebRequest supporta l'interfaccia ISerializable per consentire agli sviluppatori di serializzare una classe WebRequest template e ricostruire il template per richieste aggiuntive.

Metodo Create di IWebRequest

Mediante il metodo Create è possibile inizializzare una nuova istanza della classe specifica del protocollo. Quando viene creata una nuova interfaccia WebRequest il metodo WebRequest.Create consente di stabilire una corrispondenza tra l'URI richiesto e i prefissi URI registrati con il metodo RegisterPrefix. Con il metodo Create della derivazione appropriata specifico del protocollo deve essere restituita un'istanza inizializzata della derivazione in grado di eseguire una transazione di richiesta/risposta standard per il protocollo senza la necessità di modificare campi specifici del protocollo.

Proprietà ConnectionGroupName

La proprietà ConnectionGroupName consente di assegnare un nome a un gruppo di connessioni a una risorsa affinché sia possibile effettuare più richieste su una singola connessione. Per implementare la condivisione delle connessioni è necessario utilizzare un metodo specifico del protocollo per il pooling e l'assegnazione di connessioni. Con la classe ServicePointManager fornita, ad esempio, si implementa la condivisione di connessioni per la classe HttpWebRequest. Mediante la classe ServicePointManager si crea una classe ServicePoint che fornisce una connessione a un server specifico per ogni gruppo di connessioni.

Proprietà ContentLength

La proprietà ContentLength consente di specificare il numero di byte di dati che verranno inviati al server in fase di caricamento dei dati.

In genere è necessario impostare la proprietà Method per indicare che è in corso un caricamento quando la proprietà ContentLength è impostata su un valore maggiore di zero.

Proprietà ContentType

La proprietà ContentType consente di fornire eventuali informazioni speciali da inviare al server per l'identificazione del tipo di contenuto che si sta inviando. In genere si tratta del tipo di contenuto MIME dei dati caricati.

Proprietà Credentials

Nella proprietà Credentials sono contenute informazioni necessarie per autenticare la richiesta presso il server. È necessario implementare i dettagli del processo di autenticazione per il protocollo. La classe AuthenticationManager consente di gestire l'autenticazione delle richieste e fornire un token di autenticazione. Nella classe con cui sono fornite le credenziali utilizzate dal protocollo deve essere implementata l'interfaccia ICredentials.

Proprietà Headers

Nella proprietà Headers è contenuto un insieme arbitrario di coppie nome/valore di metadati associati alla richiesta. Nella proprietà Headers può essere incluso qualsiasi metadato richiesto dal protocollo, purché esprimibile come coppia nome/valore. Tali informazioni devono in genere essere impostate prima che abbia luogo la chiamata del metodo GetRequestStream o GetResponse; una volta effettuata la richiesta i metadati sono considerati di sola lettura.

Non è necessario utilizzare la proprietà Headers per utilizzare i metadati di intestazione. I metadati specifici del protocollo possono essere esposti come proprietà. Nella proprietà HttpWebRequest.UserAgent ad esempio si espone l'intestazione HTTP User-Agent. Quando si espongono i metadati di intestazione come una proprietà, evitare che la stessa proprietà venga impostata mediante la proprietà Headers.

Proprietà Method

Nella proprietà Method è contenuto un verbo o un'azione che deve essere eseguita dal server in seguito a una richiesta. Per impostazione predefinita la proprietà Method deve consentire l'attivazione di un'azione di richiesta/risposta standard senza la necessità di impostazione di proprietà specifiche del protocollo. L'impostazione predefinita del metodo HttpWebResponse, ad esempio, è GET, che richiede una risorsa a un server Web e restituisce la risposta.

In genere è necessario impostare la proprietà ContentLength su un valore maggiore di zero quando la proprietà Method è impostata su un verbo o su un'azione che indica un caricamento in corso.

Proprietà PreAuthenticate

La proprietà PreAuthenticate viene impostata dalle applicazioni per indicare che le informazioni di autenticazione devono essere inviate con la richiesta iniziale senza attendere una verifica di autenticazione. Questa proprietà ha significato solo se il protocollo supporta le credenziali di autenticazione inviate con la richiesta iniziale.

Proprietà Proxy

La proprietà Proxy contiene un'interfaccia IWebProxy utilizzata per accedere alla risorsa richiesta. La proprietà Proxy ha significato solo se il protocollo supporta le richieste proxy. È necessario impostare il proxy predefinito se richiesto dal protocollo.

In alcuni ambienti, come quelli protetti da firewall aziendali, è possibile che l'utilizzo di un proxy sia richiesto dal protocollo. In tal caso è necessario implementare l'interfaccia IWebProxy per creare una classe proxy appropriata al protocollo.

Proprietà RequestUri

Nella proprietà RequestUri è contenuto l'URI passato al metodo WebRequest.Create. Questa proprietà è di sola lettura e non può essere modificata dopo la creazione di WebRequest. Se il reindirizzamento è supportato dal protocollo la risposta può provenire da una risorsa identificata da un URI diverso. Qualora sia necessario consentire l'accesso all'URI che ha fornito la risposta occorre rendere disponibile una proprietà aggiuntiva contenente l'URI.

Proprietà Timeout

Nella proprietà Timeout è contenuto il periodo di tempo, espresso in millisecondi, che è necessario attendere prima che si verifichi il timeout della richiesta e venga generata un'eccezione. Timeout è applicabile unicamente alle richieste sincrone effettuate mediante il metodo GetResponse; per le richieste asincrone occorre utilizzare il metodo Abort che consente di annullare una richiesta in sospeso.

L'impostazione della proprietà Timeout ha significato solo se la classe specifica del protocollo implementa un processo di timeout.

Metodo Abort

Il metodo Abort consente di annullare una richiesta asincrona in sospeso inviata a un server. Dopo l'annullamento della richiesta, la chiamata di GetResponse, BeginGetResponse, EndGetResponse, GetRequestStream, BeginGetRequestStream o EndGetRequestStream comporterà la generazione di WebException con la proprietà Status impostata su RequestCanceled.

Metodi BeginGetRequestStream ed EndGetRequestStream

Mediante il metodo BeginGetRequestStream si avvia una richiesta asincrona per il flusso utilizzato per caricare i dati sul server. Con il metodo EndGetRequestStream si completa la richiesta asincrona e si restituisce il flusso richiesto. Questi metodi consentono di implementare il metodo GetRequestStream mediante il modello asincrono standard di .NET Framework.

Metodi BeginGetResponse ed EndGetResponse

Con il metodo BeginGetResponse si avvia una richiesta asincrona a un server. Con il metodo EndGetResponse si completa la richiesta asincrona e si restituisce la risposta richiesta. Questi metodi consentono di implementare il metodo GetResponse mediante il modello asincrono standard di .NET Framework.

Metodo GetRequestStream

Con il metodo GetRequestStream si restituisce un flusso utilizzato per scrivere dati sul server richiesto. Il flusso restituito deve essere di sola lettura e non effettuare ricerche, ovvero deve trattarsi di un flusso di dati unidirezionale scritto sul server. Il flusso restituisce false per le proprietà CanRead e CanSeek e true per la proprietà CanWrite.

Mediante il metodo GetRequestStream si apre in genere una connessione al server e, prima che venga restituito il flusso, vengono inviate informazioni di intestazione per indicare che è in corso l'invio di dati al server. Poiché GetRequestStream dà inizio alla richiesta, non è in genere consentito impostare una proprietà Header o la proprietà ContentLength dopo aver chiamato GetRequestStream.

Metodo GetResponse

Il metodo GetResponse restituisce una derivazione specifica del protocollo della classe WebResponse che rappresenta la risposta del server. A meno che la richiesta non sia già stata iniziata dal metodo GetRequestStream, con il metodo GetResponse si crea una connessione alla risorsa identificata da RequestUri, si inviano informazioni di intestazione per indicare il tipo di richiesta effettuata e si riceve la risposta dalla risorsa.

Dopo la chiamata al metodo GetResponse tutte le proprietà devono essere considerate di sola lettura. Ogni istanza di WebRequest può essere utilizzata una sola volta; per effettuare un'altra richiesta è necessario creare una nuova WebRequest.

Il metodo GetResponse consente di creare una derivazione appropriata di WebResponse per contenere la risposta in arrivo.

Vedere anche

Programmazione dei protocolli innestabili | Derivazione da WebResponse | Classe WebRequest | Classe HttpWebRequest | Classe FileWebRequest