编程实现Office 2003 Research 功能的代码详解C#篇(2)

作者：范维肖
The Registration Method

[WebMethod]
public string Registration(string regXML) {

This method accepts a string and returns a string.  The strings are valid XML streams.  The method uses an xmlTextWriter to build the XML.   It is also possible to use a static XML file resource in place of this process.  Let's look through the essential parts of the code to see how elements are added to the registration process.
这个webMethod会接受一个string然后返回一个string，字符串是有效的XML流（xml stream）。这个方法使用xmlTextWriter来建立xml，当然也可以使用一个静态的xml文件来代替。下面我们就深入到代码中相信的分析一下各个部分代码的功能。

MemoryStream ioMemStream = new MemoryStream();
XmlTextWriter xWriter = new XmlTextWriter(ioMemStream, null);

By referencing the system.xml.dll in our projects and including a using directive to the System.Xml namespace we can declare an object of type XMLTextWriter that writes XML to a Memory Stream.  It is important to use these XML classes for the Registration method to create an XML document that is both well-formed and valid.
在project中我们使用了system.xml.dll，并且using了一个System.Xml命名空间，使得我们能够声名一个类型为XMLTextWriter的对象，通过它可以把XML文件写到一个Memory Stream里。在Registration方法中使用这些XML类来建立一个格式良好而且有效的XML文档是非常重要的

  xWriter.Indentation=4;
//xWriter.IndentChar=" ";
xWriter.WriteStartDocument();
xWriter.WriteStartElement("ProviderUpdate", "urn:Microsoft.Search.Registration.Response");
xWriter.WriteElementString("Status", "SUCCESS");
xWriter.WriteStartElement("Providers");
xWriter.WriteStartElement("Provider");
xWriter.WriteElementString("Message","Registered with the Sim-Crea.com Message Service!");
xWriter.WriteElementString("Id","{E545CFA2-E5AC-408a-92D9-E8C8487E6D69}");
xWriter.WriteElementString("Name", "Sim-Crea.com Message Service");
xWriter.WriteElementString("QueryPath",queryPath);
xWriter.WriteElementString("RegistrationPath",registrationPath);
xWriter.WriteElementString("Type", "SOAP");
xWriter.WriteStartElement("Services");
xWriter.WriteStartElement("Service");
xWriter.WriteElementString("Id","31EC36F2-9FC7-473C-9E13-D007DC0D583C");
xWriter.WriteElementString("Name", "Sim-Crea.com Message Service");
xWriter.WriteElementString("Description","Sim-Crea.cm Message Service");
xWriter.WriteElementString("Copyright", "All Content Copyright (c) 2005.");
xWriter.WriteElementString("Display", "On");
xWriter.WriteElementString("Category", "INTRANET_GENERAL");

We then use the methods of the XMLTextWriter object instance to create our XML document stream.  Note that for our XML to be well-formed it must be syntactically correct, (e.g. each element must have a closing end element). It must also be well-formed (i.e. it must conform to the schema that is expected.)  If our document is not well-formed or valid then we won't be able to use the research service.
然后，我们使用这个方法的XMLTextWriter对象实例来建立我们的XML文档stream，注意，为了保持我们的XML文件格式良好，语法必须正确，比如，每个元素标记都必须有关闭符，而且要像RP期待的那样满足schema。
P.S.真罗嗦啊，其实就是说如果不Well－Formed或者不valid，那么我们就不能使用这个Research服务了

xWriter.WriteEndElement();  //' Service
xWriter.WriteEndElement();  //' Services
xWriter.WriteEndElement();  //' Provider
xWriter.WriteEndElement();  //' Providers
xWriter.WriteEndElement();  //' ProviderUpdate
xWriter.WriteEndDocument();

We can see that for the WriteStartDocument method and the WriteStartElement methods we have corresponding WriteEndDocument or WriteEndElement methods, which is an essential part of making the document well-formed.
为了保证格式良好和有效性.......继续强调
Finally once we have created the XML in memory, we can write it to a string and then return it from the Registration Method.  The StreamReader object is there to read the XML packet and return it from memory
最后，一旦在内存里建立了XML文件，我们就能把它写入到有个字符串中，然后从Registration方法中把它返回。StreamReader对象会读取这个XML包并且从内存里返回它。

xWriter.Flush();            
ioMemStream.Flush();
ioMemStream.Position = 0;
System.IO.StreamReader ioStreamReader = new StreamReader(ioMemStream);
return ioStreamReader.ReadToEnd().ToString();

上面这个方法最后返回的结果是：

<?xml version="1.0"?>
 <ProviderUpdate xmlns="urn:Microsoft.Search.Registration.Response">
    <Status>SUCCESS</Status>
    <Providers>
        <Provider>
           <Message>Registered with the Sim-Crea.com Message Service!</Message>
           <Id>{E545CFA2-E5AC-408a-92D9-E8C8487E6D69}</Id>
           <Name>Sim-Crea.com Message Service</Name>
           <QueryPath>http://VC/vcResearch.asmx</QueryPath>
           <RegistrationPath>http://VC/vcResearch.asmx</RegistrationPath>
           <Type>SOAP</Type>
           <Services>
                  <Service>
                      <Id>31EC36F2-9FC7-473C-9E13-D007DC0D583C</Id>
                     <Name>Sim-Crea.com Message Service</Name>
                     <Description>Sim-Crea.com Message Service</Description>
                     <Copyright>All Content Copyright (c) 2005.</Copyright>
                     <Display>On</Display>
                     <Category>INTRANET_GENERAL</Category>
                </Service>
            </Services>
         </Provider>
    </Providers>
 </ProviderUpdate>

 

When our users choose to install the research service, the registration method is called.  It returns everything needed to install the service, show an entry for it and call the Query Web method (which we'll examine in a moment).  Quite often, this Registration method is code that we can just modify from one Research Service to another, as the information that is needed is always the same.
当用户选择安装这个RP的时候，Registration方法就被调用了，它返回安装这个服务的所有的相关信息，显示服务的入口并且调用Query这个web方法(这个方法一会我们再相信的讲解)。通常，Registration方法的编码可是使我们能从一个Research服务修改成另一个Research服务，因为所需要的信息总是相同的。

The QueryPath element in the XML document identifies the web service that is called when we perform a query in the research pane.  It also identifies it's own address for Registration purposes.
XML文档中的QueryPath元素指明了当我们再RP里执行一个查询的时候被调用的web服务，同时它也指明了Registration的目的地址。

<QueryPath>http://VC/vcResearch.asmx</QueryPath>
<RegistrationPath>http://VC/vcResearch.asmx</RegistrationPath>

Whenever the user performs a search using our Research Service the Query method is called.  The method uses the query packet to determine the action that is required and then returns a response. 

无论何时用户使用我们的Research服务执行一个查询，Query方法就会被调用。这个方法使用查询信息包来决定需要和以后要返回的动作。

 

the Query method must accept a single string parameter called queryXml. 

Query方法必须接受一个以queryXml为参数的string。

 

Within the Query method, it is our role as a developer to carry out three essential tasks.  The first is to parse the incoming request to determine the request that has come from the calling application.  The second is to take that request and carry out a certain action (perhaps fetching some data from a database) and the third action is to prepare the XML response to be sent as the response.

在Query方法里，作为一个开发者我们需要完成3个基本任务。第一个就是要解析提交的请求内容从而确定这个来自请求调用的程序的请求。第二个是接受请求并且完成某个动作（或许是从一个数据库中取出一些数据），第三个任务是准备将要返回的XML信息。

P.S.这个Query方法的三个任务就像说一个机器人，首先要parse那些incoming的request,然后要分析指令知道自己该干什么了,再去完成，最后把结果（封装成XML格式）再response回去。
to be continue ...