Текст книги "C# 4.0: полное руководство"

Автор книги: Герберт Шилдт

сообщить о нарушении

Текущая страница: 83 (всего у книги 83 страниц)

Применение класса WebClient

В заключение этой главы уместно рассмотреть класс WebClient. Как упоминалось в самом ее начале, класс WebClient рекомендуется использовать вместо классов WebRequest и WebResponse в том случае, если в приложении требуется лишь выгружать или загружать данные из Интернета. Преимущество класса WebClient заключается в том, что он автоматически выполняет многие операции, освобождая от их программирования вручную.

В классе WebClient определяется единственный конструктор.

public WebClient()

Кроме того, в классе WebClient определяются свойства, сведенные в табл.26.6, а также целый ряд методов, поддерживающих как синхронную, так и асинхронную передачу данных. Но поскольку рассмотрение асинхронной передачи данных выходит за рамки этой главы, то в табл. 26.7 приведены только те методы, которые поддерживают синхронную передачу данных. Все методы класса WebClient генерируют исключение WebException, если во время передачи данных возникает ошибка.

Таблица 26.6. Свойства, определенные в классе WebClient

Свойство – Описание

public string BaseAddress { get; set; } – Получает или устанавливает базовый адрес требуемого URI. Если это свойство установлено, то адреса, задаваемые в методах класса WebClient, должны определяться относительно этого базового адреса

public RequestCachePolicy CachePolicy { get; set; } – Получает или устанавливает правила, определяющие, когда именно используется кэш

public ICredentials Credentials { get; set; } – Получает или устанавливает мандат, т.е. учетные данные пользователя. По умолчанию это свойство имеет пустое значение

public Encoding Encoding { get; set; } – Получает или устанавливает схему кодирования символов при передаче строк

public WebHeaderCollection Headers{ get; set; } – Получает или устанавливает коллекцию заголовков запроса

public bool IsBusy { get; } – Принимает логическое значение true, если данные по-прежнему передаются по запросу, а иначе – логическое значение false

public IWebProxy Proxy { get; set; } – Получает или устанавливает прокси-сервер

public NameValueCollection QueryString { get; set; } – Получает или устанавливает строку запроса, состоящую из пар “имя-значение”, которые могут быть присоединены к запросу. Строка запроса отделяется от URI символом ?. Если же таких пар несколько, то каждая из них отделяется символом @

public WebHeaderCollection ResponseHeaders{ get; } – Получает коллекцию заголовков ответа

public bool UseDefaultCredentials { get; set; } – Получает или устанавливает значение, которое определяет, используется ли для аутентификации устанавливаемый по умолчанию мандат. Если принимает логическое значение true, то используется мандат, устанавливаемый по умолчанию, т.е. учетные данные пользователя, в противном случае этот мандат не используется

Таблица 26.7. Методы синхронной передачи, определенные в классе WebClient

Метод – Определение

public byte[] DownloadData(stringaddress) – Загружает информацию по адресу URI, обозначаемому параметром address. Возвращает результат в виде массива байтов

public byte[] DownloadData(Uriaddress) – Загружает информацию по адресу URI, обозначаемому параметром address. Возвращает результат в виде массива байтов

public void DownloadFile(stringuri, stringfileName) – Загружает информацию по адресу URI, обозначаемому параметром fileName. Сохраняет результат в файле fileName

public void DownloadFile(Uri address,stringfileName) – Загружает информацию по адресу URI, обозначаемому параметром address. Сохраняет результат в файле fileName

public string DownloadString(string address) – Загружает информацию по адресу URI, обозначаемому параметром address. Возвращает результат в виде символьной строки типа string

public string DownloadString(Uriaddress) – Загружает информацию по адресу URI, обозначаемому параметром address. Возвращает результат в виде символьной строки типа string

public Stream OpenRead(stringaddress) – Возвращает поток ввода для чтения информации по адресу URI, обозначаемому параметром address. По окончании чтения информации этот поток необходимо закрыть

public Stream OpenRead(Uri address) – Возвращает поток ввода для чтения информации по адресу URI, обозначаемому параметром address. По окончании чтения информации этот поток необходимо закрыть

public Stream OpenWrite(stringaddress) – Возвращает поток вывода для записи информации по адресу URI, обозначаемому параметром address. По окончании записи информации этот поток необходимо закрыть

public Stream OpenWrite(Uri address) – Возвращает поток вывода для записи информации по адресу URI, обозначаемому параметром address. По окончании записи информации этот поток необходимо закрыть

public Stream OpenWrite(stringaddress, stringmethod) – Возвращает поток вывода для записи информации по адресу URI, обозначаемому параметром address. По окончании записи информации этот поток необходимо закрыть. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public Stream OpenWrite(Uri address,stringmethod) – Возвращает поток вывода для записи информации по адресу URI, обозначаемому параметром address. По окончании записи информации этот поток необходимо закрыть. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public byte[] UploadData(stringaddress, byte[]data) – Записывает информацию из массива data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ

public byte[] UploadData(Uri address,byte[]data) – Записывает информацию из массива data по адресу URI, 'обозначаемому параметром address. В итоге возвращается ответ

public byte[] UploadData(stringaddress, stringmethod,byte[]data) – Записывает информацию из массива data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public byte[] UploadData(Uri address,stringmethod, byte[]data) – Записывает информацию из массива data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public byte[] UploadFile(stringaddress, stringfileName) – Записывает информацию в файл fileName по адресу URI, обозначаемому параметром address. В итоге возвращается ответ

public byte[] UploadFile(Uri address,stringfileName) – Записывает информацию в файл fileName по адресу URI, обозначаемому параметром address. В итоге возвращается ответ

public byte[] UploadFile (stringaddress, stringmethod,string fileName) – Записывает информацию в файл fileName по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public byte[] UploadFile(Uri address,stringmethod, stringfileName) – Записывает информацию в файл fileName по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public string UploadString(stringaddress, stringdata) – Записывает строку data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ

public string UploadString(Uriaddress, stringdata) – Записывает строку data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ

public string UploadString(stringaddress, stringmethod,stringdata) – Записывает строку data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public string UploadString(Uriaddress, stringmethod,stringdata) – Записывает строку data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public byte[] UploadValues(stringaddress, NameValueCollectiondata) – Записывает значения из коллекции data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ

public byte[] UploadValues(Uriaddress, NameValueCollectiondata) – Записывает значения из коллекции data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ

public byte[] UploadValues(string address,stringmethod, NameValueCollectiondata) – Записывает значения из коллекции data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

public byte[] UploadValues(Uri address,stringmethod, NameValueCollectiondata) – Записывает значения из коллекции data по адресу URI, обозначаемому параметром address. В итоге возвращается ответ. В строке, передаваемой в качестве параметра method, указывается, как именно следует записывать информацию

В приведенном ниже примере программы демонстрируется применение класса WebClient для загрузки данных в файл по указанному сетевому адресу.

// Использовать класс WebClient для загрузки данных

// в файл по указанному сетевому адресу.

using System;

using System.Net;

using System.IO;

class WebClientDemo {

  static void Main() {

    WebClient user = new WebClient();

    string uri = «http://www.McGraw-Hill.com»;

    string fname = «data.txt»;

    try {

      Console.WriteLine("Загрузка данных по адресу "

              + uri + " в файл " + fname);

      user.DownloadFile(uri, fname);

    }

    catch (WebException exc) {

      Console.WriteLine(exc);

    }

    Console.WriteLine(«Загрузка завершена.»);

  }

}

Эта программа загружает информацию по адресу www .McGrawHill. com и помещает ее в файл data.txt. Обратите внимание на строки кода этой программы, в которых осуществляется загрузка информации. Изменив символьную строку uri, можно загрузить информацию по любому адресу URI, включая и конкретные файлы, доступные по указываемому URL

Несмотря на то что классы WebRequest и WebResponse предоставляют больше возможностей для управления и доступа к более обширной информации, для многих приложений оказывается достаточно и средств класса WebClient. Этим классом особенно удобно пользоваться в тех случаях, когда требуется только загрузка информации из веб-ресурса. Так, с помощью средств класса WebClient можно получить из Интернета обновленную документацию на приложение.

ПРИЛОЖЕНИЕ 
Краткий справочник по составлению документирующих комментариев

В языке C# предусмотрено три вида комментариев. К двум первым относятся комментарии // и /* */, а третий основан на дескрипторах языка XML и называется документирующим комментарием. (Иногда его еще называют XML-комментарием.) Однострочный документирующий комментарий начинается с символов ///, а многострочный начинается с символов /** и оканчивается символами */. Строки после символов /** могут начинаться с одного символа *, хотя это и не обязательно. Если все последующие строки многострочного комментария начинаются с символа *, то этот символ игнорируется.

Документирующие комментарии вводятся перед объявлением таких элементов языка С#, как классы, пространства имен, методы, свойства и события. С помощью документирующих комментариев можно вводить в исходный текст программы сведения о самой программе. При компиляции программы документирующие комментарии к ней могут быть помещены в отдельный XML-файл. Кроме того, документирующие комментарии можно использовать в средстве IntelliSense интегрированной среды разработки Visual Studio.

Дескрипторы XML-комментариев

В С# поддерживаются дескрипторы документации в формате XML, сведенные в табл. 1. Большинство дескрипторов XML-комментариев не требует особых пояснений и действуют подобно всем остальным дескрипторам XML, знакомым многим программистам. Тем не менее дескриптор – сложнее других. Он состоит из двух частей: заголовка и элементов списка. Ниже приведена общая форма дескриптора

:

  имя

  текст

где текст описывает имя. Для описания таблиц текст не используется. Ниже приведена общая форма элемента списка:

  имя_элемента

  текст

где текст описывает имя_элемента. Для описания маркированных и нумерованных списков, а также таблиц имя элемента не используется. Допускается применение нескольких элементов списка .

Таблица 1. Дескрипторы XML-комментариев

Дескриптор – Описание

<с> код  – Определяет текст, на который указывает код, как программный код

код  – Определяет несколько строк текста, на который указывает код, как программный код

пояснение  – Определяет текст, на который указывает пояснение, как описание примера кода

пояснение  – Описывает исключительную ситуацию, на которую указывает имя

 – Определяет файл, содержащий XML-комментарии для текущего исходного файла. При этом fname обозначает имя файла; path – путь к файлу; tagName – имя дескриптора; tagID – идентификатор дескриптора

заголовок списка элементы списка  – Определяет список. При.этом тип обозначает тип списка, который может быть маркированным, нумерованным или таблицей

<рага> текст  – Определяет абзац текста в другом дескрипторе

 пояснение  – Документирует параметр, на который указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр

 – Обозначает имя параметра как имя конкретного параметра

пояснение  – Описывает параметр разрешения, связанный с

членами класса, на которые указывает идентификатор. Текст, обозначаемый как пояснение, описывает параметры разрешения

пояснение  – Текст, обозначаемый как пояснение, представляет собой общие комментарии, которые часто используются для описания класса или структуры

пояснение  – Текст, обозначаемый как пояснение, описывает значение, возвращаемое методом

 – Объявляет ссылку на другой элемент, обозначаемый как идентификатор

 – Объявляет ссылку типа “см. также" на идентификатор

пояснение

 – Текст, обозначаемый как пояснение, представляет собой общие комментарии, которые часто используются для описания метода или другого члена класса

пояснение  – Документирует параметр типа, на который указывает имя параметра. Текст, обозначаемый как пояснение, описывает параметр типа

 – Обозначает имя параметра как имя параметра типа

Компилирование документирующих комментариев

Для получения XML-файла, содержащего документирующие комментарии, достаточно указать параметр /doc в командной строке компилятора. Например, для компилирования файла DocTest.cs, содержащего XML-комментарии, в командной строке необходимо ввести следующее.

csc DocTest.cs /doc:DocTest.xml

Для вывода результата в XML-файл из интегрированной среды разработки Visual Studio необходимо активизировать окно Свойства (Properties) для текущего проекта. Затем следует выбрать свойство Построение (Build), установить флажок XML-файл документации (XML Documentation File) и указать имя выходного XML-файла.

Пример составления документации в формате XML

В приведенном ниже примере демонстрируется применение нескольких документирующих комментариев: как однострочных, так и многострочных. Любопытно, что многие программисты пользуются последовательным рядом однострочных документирующих комментариев вместо многострочных, даже если комментарий занимает насколько строк. Такой подход применяется и в ряде комментариев из данного примера. Его преимущество заключается в том, что он позволяет ясно обозначить каждую строку как часть длинного документирующего комментария. Но это все же, скорее, дело стиля, чем общепринятая практика составления документирующих комментариев.

// Пример составления документирующих комментариев,

using System;

/**

Это пример многострочного документирования в формате XML.

В классе Test демонстрируется ряд дескрипторов.

*/

class Test {

  ///

  /// Выполнение программы начинается с метода Main().

  ///

  static void Main() {

    int sum;

    sum = Summation(5);

    Console.WriteLine("Сумма последовательных чисел " +

    5 + " равна " + sum);

  }

  ///

  /// Метод Summation() возвращает сумму его аргументов.

  ///

  /// Суммируемое значение передается в качестве параметра val.

  ///

  ///

  /// < returns >

  /// Сумма возвращается в виде значения типа int.

  ///

  ///

  static int Summation(int val) {

    int result = 0;

    for (int i = 1; i <= val; i++)

      result += i;

    return result;

  }

}

Если текст приведенной выше программы содержится в файле XmlTest.cs, то по следующей команде будет скомпилирована программа и получен файл XmlTest.xml, содержащий комментарии к ней.

csc XmlTest.cs /doc:XmlTest.xml

После компилирования получается XML-файл, содержимое которого приведено ниже.

   

        Program

   

   

       

           

            Это пример многострочного документирования в формате XML.

            В классе Test демонстрируется ряд дескрипторов.

           

       

       

           

             Выполнение программы начинается с метода Main().

           

       

       

           

             Метод Summation() возвращает сумму его аргументов.

           

             Суммируемое значение передается в качестве параметра val.

           

           

            

             Сумма возвращается в виде значения типа int.

           

            

       

   

Следует заметить, что каждому документируемому элементу присваивается уникальный идентификатор. Такие идентификаторы применяются в других программах, которые документируются в формате XML.

Предметный указатель

(Удален. Все-равно номеров страниц нет. См. Оригинал)

Спецификации

HERBERT SCHILDT ПОЛНОЕ РУКОВОДСТВО C# 4.0

Москва • Санкт-Петербург • Киев 2011

ББК 32.973.26-018.2.75 Ш 57 УДК 681.3.07

Издательский дом "Вильямс"

Зав. редакцией С.Н. Тригуб Перевод с английского и редакция И.В. Берштейна

По общим вопросам обращайтесь в Издательский дом "Вильямс" по адресу: [email protected], http://www.williamspublishing.com

Шилдт, Герберт.

Ш57 C# 4.0: полное руководство. : Пер. с англ. – М. : ООО "И.Д. Вильямс", 2011. – 1056 с.: ил. – Парал. тит. англ.

ISBN 978-5-8459-1684-6 (рус.)

ББК 32.973.26-018.2.75

Все названия программных продуктов являются зарегистрированными торговыми марками соответствующих фирм.

Никакая часть настоящего издания ни в каких целях не может быть воспроизведена в какой бы то ни было форме и какими бы то ни было средствами, будь то электронные или механические, включая фотокопирование и запись на магнитный носитель, если на это нет письменного разрешения издательства McGrow-Hill Higher Ed.

Authorized translation from the English language edition published by McGraw-Hill Companies, Copyright © 2010

All rights reserved. Except as permitted under the Copyright Act of 1976, no part of this publication may be reproduced or distributed in any form or by any means, or stored in a database or retrieval system, without the prior written permission of publisher, with the exception that the program listings may be entered, stored, and executed in a computer system, but they may not be reproduced for publication.

Russian language edition published by Williams Publishing House according to the Agreement with R&I Enterprises International, Copyright © 2011

Научно-популярное издание Герберт Шилдт C# 4.0: полное руководство

Литературный редактор Е.П. Перестюк

Верстка А.В. Чернокозинская Художественный редактор С А. Чернокозинский Корректор АЛ. Гордиенко

Подписано в печать 17.09.2010. Формат 70x100/16. Гарнитура Times. Печать офсетная.

Уел. печ. л. 85,14. Уч.-изд. л. 51,55.

Тираж 1500 экз. Заказ № 24007.

Отпечатано по технологии CtP в ОАО "Печатный двор" им. А. М. Горького 197110, Санкт-Петербург, Чкаловский пр., 15.

ООО "И. Д. Вильямс", 127055, г. Москва, ул. Лесная, д. 43, стр. 1

© Издательский дом "Вильямс", 2011 © by The McGraw-Hill Companies, 2010

ISBN 978-5-8459-1684-6 (рус.) ISBN 0-07-174116-Х (англ.)