NCBI Bookshelf. A service of the National Library of Medicine, National Institutes of Health.

Entrez Programming Utilities Help [Internet]. Bethesda (MD): National Center for Biotechnology Information (US); 2010-.

Cover of Entrez Programming Utilities Help

Entrez Programming Utilities Help [Internet].

Show details

Using Entrez Utilities Web Service with C# and MS Visual Studio 2008

Last Update: November 10, 2010.

Entrez Utilities Web Service has been tested with:

  • Microsoft .NET Framework Version 3.5 SP1
  • Microsoft Visual Studio 2008 Version 9.0.30729.1 SP

Creating a Web Service Client Project

The following walkthrough describes how to create a new C# project to access the NCBI Entrez Utilities Web Service using MS Visual Studio 2008.

To create Windows application:

1.

Press Ctrl+Shift+N or Select File menu, then New, and then click Project to open the New Project dialog.

2.

Select Visual C# in Project types list.

3.

Select Windows Forms Application in Templates list.

4.

Click OK to create a new project.

5.

Select View menu and then Toolbox to open a Toolbox window.

6.

From the Toolbox, drag a Textbox and a Button to the design surface of Form1. Set Textbox’ Multiline property to true.

7.

On the Project menu, click Add Service Reference.

8.

In the Address field of the Add Service Reference dialog, type the URL http://eutils​.ncbi.nlm​.nih.gov/soap/v2.0/eutils.wsdl or path to local file (for example, C:\SOAP\eUtils\v2.0\eutils.wsdl) if you downloaded eUtils WSDL/XSD files from our FTP site

9.

Click the Go button to retrieve information about the XML Web service.

10.

In the Namespace field type eUtils.

11.

Click OK. The new eUtils item will appear in Service References list in the Solution Explorer view.

12.

Double-click the button on Form1 to create an event-handling method for this button.

13.

In the button1_Click method enter the following code:
// eInfo utility returns a list of available databases
try
{
eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
// call NCBI EInfo utility
eUtils.eInfoResult res = serv.run_eInfo(new eUtils.eInfoRequest());
// results output
textBox1.Text = "";
for(int i=0; i<res.DbList.Items.Length; i++) {
textBox1.Text += res.DbList.Items[i]+"\r\n";
}
}
catch (Exception eee)
{
textBox1.Text = eee.ToString();
}

14.

Build and run application.

Important: Currently, the default maximum length of the SOAP message is only 64Kb. C# application fails when Web Service response size exceeds this value. To increase the limit open app.config file located in the application’s root directory and change all maxReceivedMessageSize and maxBufferSize parameters to the same larger value, for example, 2000000.

NCBI Entrez Utilities Web Service API

Below is a list of available methods.

Click on parameter to get its description.

Click on method name to see the usage example.

public Result run_eGquery(eGqueryRequest params)

eGqueryRequest class properties:

public eInfoResult run_eInfo(eInfoRequest params)

eInfoRequest class properties:

public eLinkResult run_eLink(eLinkRequest params)

eLinkRequest class properties:

public ePostResult run_ePost(ePostRequest params)

ePostRequest class properties:

public eSearchResult run_eSearch(eSearchRequest params)

eSearchRequest class properties:

public eSpellResult run_eSpell(eSpellRequest params)

eSpellRequest class properties:

public eSummaryResult run_eSummary(eSummaryRequest params)

eSummaryRequest class properties:

public eFetchResult run_eFetch(eFetchRequest params)

eFetchRequest class properties:

Properties available for Sequence databases:

Examples

Call EGQuery

    try
    {
        eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
        // call NCBI EGQuery utility
        eUtils.eGqueryRequest req = new eUtils.eGqueryRequest();
        req.term = "mouse";
        eUtils.Result res = serv.run_eGquery(req);
        // results output
        textBox1.Text = "Search term: " + res.Term + "\r\n";
        textBox1.Text += "Results: \r\n";
        for(int i=0; i<res.eGQueryResult.ResultItem.Length; i++)
        {
            textBox1.Text += "  " + res.eGQueryResult.ResultItem[i].DbName +
                             ": " + res.eGQueryResult.ResultItem[i].Count + "\r\n";
        }
    }
    catch (Exception eee)
    {
        textBox1.Text = eee.ToString();
    }

Call Einfo

// eInfo utility returns an PMC db info
try
{
    eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
    // call NCBI EInfo utility
    eUtils.eInfoRequest req = new eUtils.eInfoRequest();
    req.db = "pmc";
    eUtils.eInfoResult res = serv.run_eInfo(req);
    // results output
    textBox1.Text = "DbName: " + res.DbInfo.DbName + "\r\n" +
                    "Description: " + res.DbInfo.Description + "\r\n" +
                    "MenuName: " + res.DbInfo.MenuName + "\r\n";
}
catch (Exception eee)
{
    textBox1.Text = eee.ToString();
}      

Call Epost

// Put ID list to history for later use
try
{
    eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
    // call NCBI ESpell utility
    eUtils.ePostRequest req = new eUtils.ePostRequest();
    req.db = "pubmed";
    req.id = "11237011";
    eUtils.ePostResult res = serv.run_ePost(req);
    // results output
    textBox1.Text = "WebEnv: "+res.WebEnv  + "\r\n";
    textBox1.Text += "QueryKey: "+res.QueryKey;
}
catch (Exception eee)
{
    textBox1.Text = eee.ToString();
}          

Call Esearch

    // search in PubMed Central for stem cells in free fulltext articles
    try
    {
        eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
        // call NCBI ESearch utility
        // NOTE: search term should be URL encoded
        eUtils.eSearchRequest req = new eUtils.eSearchRequest();
        req.db = "pmc";
        req.sort = "SortDate";
        req.term = "stem+cells+AND+free+fulltext[filter]";
        req.RetStart = "0";
        req.RetMax = "15";
        eUtils.eSearchResult res = serv.run_eSearch(req);
        // results output
        textBox1.Text = "Original query: stem cells AND free fulltext[filter]\r\n";
        textBox1.Text += "Found ids: " + res.Count+"\r\n";
        textBox1.Text += "First " + res.RetMax +" ids: ";
       
        for(int i=0; i<res.IdList.Length; i++)
        {
            textBox1.Text += res.IdList[i] + " ";
        }
    }
    catch (Exception eee)
    {
        textBox1.Text = eee.ToString();
    }

Call ESpell

    // retrieves spelling suggestions
    try
    {
        eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
        // call NCBI ESpell utility
        eUtils.eSpellRequest req = new eUtils.eSpellRequest();
        req.db = "pubmed";
        req.term = "mouss";
        eUtils.eSpellResult res = serv.run_eSpell(req);
        // results output
        textBox1.Text = "Misspelled word: "+res.Query + "\r\n";
        textBox1.Text += "Corrected word: "+res.CorrectedQuery;
    }
    catch (Exception eee)
    {
        textBox1.Text = eee.ToString();
    }

Call ESummary

    // retrieves document Summaries by list of primary IDs
    try
    {
        eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
        // call NCBI ESummary utility
        eUtils.eSummaryRequest req = new eUtils.eSummaryRequest();
        req.db = "nlmcatalog";
        req.id = "905";
        eUtils.eSummaryResult res = serv.run_eSummary(req);
        // results output
        textBox1.Text = "";
        for(int i=0; i<res.DocSum.Length; i++)
        {
            textBox1.Text += "ID: "+res.DocSum[i].Id+"\r\n";
            for(int k=0; k<res.DocSum[i].Item.Length; k++)
            {
                textBox1.Text += "    "+res.DocSum[i].Item[k].Name +": "+res.DocSum[i].Item[k].ItemContent + "\r\n";
            }
            textBox1.Text += "-----------------------\r\n\r\n";
        }
    }
    catch (Exception eee)
    {
        textBox1.Text = eee.ToString();
    }

Call EFetch

To fetch data from one of the supported databases add the corresponding Web Reference to project. For example, for taxonomy database in Add Service Reference dialog type http://eutils.ncbi.nlm.nih.gov/soap/v2.0/efetch_taxon.wsdl in Address field and eFetchTaxon in Namespace.

Taxonomy database example:

    // fetch a record from Taxonomy database
    try
    {
        eFetchTaxon.eUtilsServiceSoapClient serv = new eFetchTaxon.eUtilsServiceSoapClient();
        // call NCBI EFetch utility
        eFetchTaxon.eFetchRequest req = new eFetchTaxon.eFetchRequest();
        req.id = "9685";
        eFetchTaxon.eFetchResult res = serv.run_eFetch(req);
        // results output
        textBox1.Text = res.TaxaSet[0].ScientificName + ": " +
                        res.TaxaSet[0].Division + " (" +
                        res.TaxaSet[0].Rank + ")\r\n";
    }
    catch (Exception eee)
    {
        textBox1.Text = eee.ToString();
    }

Using WebEnv & QueryKey example

Add two Service References to the project: http://eutils.ncbi.nlm.nih.gov/soap/v2.0/eutils.wsdl and http://eutils.ncbi.nlm.nih.gov/soap/v2.0/efetch_pubmed.wsdl files.

Name them eUtils and eFetchPubmed correspondingly.

Important: Increase all maxReceivedMessageSize and maxBufferSize parameters in app.config file to 2000000 before running the application.

String WebEnv = "";
    String query_key = "";
    // STEP #1: search in PubMed for "cat"
    //
    try
    {
        eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
        // call NCBI ESearch utility
        // NOTE: search term should be URL encoded
        eUtils.eSearchRequest req = new eUtils.eSearchRequest();
        req.db = "pubmed";
        req.term = "cat";
        req.usehistory = "y";
        eUtils.eSearchResult res = serv.run_eSearch(req);
        // store WebEnv & QueryKey for use in eFetch
        WebEnv = res.WebEnv;
        query_key = res.QueryKey;
        textBox1.Text = "Search in PubMed for \"cat\" returned " + res.Count + " hits\r\n";
        textBox1.Text += "WebEnv: " + WebEnv + "\r\n";
        textBox1.Text += "QueryKey: " + query_key + "\r\n\r\n";
    }
    catch (Exception eee)
    {
        textBox1.Text += eee.ToString();
    }
    // STEP #2: fetch 5 records from pubmed starting from record #10
    //
    try
    {
        eFetchPubmed.eUtilsServiceSoapClient serv = new eFetchPubmed.eUtilsServiceSoapClient();
        // call NCBI EFetch utility
        eFetchPubmed.eFetchRequest req = new eFetchPubmed.eFetchRequest();
        req.WebEnv = WebEnv;
        req.query_key = query_key;
        req.retstart = "10";
        req.retmax = "5";
        eFetchPubmed.eFetchResult res = serv.run_eFetch(req);
        // results output
        // PubmedArticleSet array can include articles of PubmedArticleType and
        // PubmedBookArticleType types. There should be separate display method
        // for each article's type.
        for (int i = 0; i < res.PubmedArticleSet.Length; i++)
        {
            eFetchPubmed.PubmedArticleType art = null;
            eFetchPubmed.PubmedBookArticleType book = null;
            if (res.PubmedArticleSet[i] is eFetchPubmed.PubmedArticleType)
                art = (eFetchPubmed.PubmedArticleType)res.PubmedArticleSet[i];
            else
                book = (eFetchPubmed.PubmedBookArticleType)res.PubmedArticleSet[i];
            // show book or article
            if (art != null)
            {
                textBox1.Text += "Type: Pubmed Article\r\n";
                textBox1.Text += "Title: " + art.MedlineCitation.Article.ArticleTitle + "\r\n";
                textBox1.Text += "Abstract: " + art.MedlineCitation.Article.Abstract.AbstractText + "\r\n";
                textBox1.Text += "--------------------------\r\n\r\n";
            }
            else if (book != null)
            {
                textBox1.Text += "Type: Pubmed Book Article\r\n";
                textBox1.Text += "Title: " + book.BookDocument.ArticleTitle + "\r\n";
                textBox1.Text += "--------------------------\r\n\r\n";
            }
        }
    }
    catch (Exception eee)
    {
        textBox1.Text += eee.ToString();
    }
PubReader format: click here to try

Views

Other titles in this collection

Recent Activity

Your browsing activity is empty.

Activity recording is turned off.

Turn recording back on

See more...