My NCBISign In
Print View 

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-.

Bookshelf ID: NBK55694

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

Go to:

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

Go to:

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

Go to:

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 ELink

// example retrieves links from Nuccore for to Protein GI 48819,7140345
try
{
    eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
    string[] id = {"48819,7140345"};
    // call NCBI ELink utility
    eUtils.eLinkRequest req = new eUtils.eLinkRequest();
    req.db = "protein";
    req.id = id;
    req.dbfrom = "nuccore";
    eUtils.eLinkResult res = serv.run_eLink(req);
    // results output
    textBox1.Text = "";
    for(int i=0; i<res.LinkSet.Length; i++)
    {
        textBox1.Text += "Links from " + res.LinkSet[i].DbFrom +
                         " to " + res.LinkSet[i].LinkSetDb[0].DbTo + "\r\n";
        textBox1.Text += "  " + res.LinkSet[i].DbFrom + " id(s): ";
        for(int k=0; k<res.LinkSet[i].IdList.Length; k++)
        {
            textBox1.Text +=  res.LinkSet[i].IdList[k].Value + " ";
        }
        textBox1.Text += "\r\n";
        textBox1.Text += "  " + res.LinkSet[i].LinkSetDb[0].DbTo + " id(s): ";
        for(int k=0; k<res.LinkSet[i].LinkSetDb[0].Link.Length; k++)
        {
            textBox1.Text += res.LinkSet[i].LinkSetDb[0].Link[k].Id.Value + " ";
        }
        textBox1.Text += "\r\n----------------------\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();
    }

Search, Link & Fetch 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_seq.wsdl files.

Name them eUtils and eFetchSeq correspondingly.

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

String[] ids = { "" };
    String fetchIds = "";


    // 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.sort = "PublicationDate";
        req.term = "cat+AND+pubmed_nuccore[sb]";
        req.RetMax = "5";
        eUtils.eSearchResult res = serv.run_eSearch(req);
       
        // store UIDs for use in ELink
        int N = res.IdList.Length;
        for (int i = 0; i < N; i++)
        {
            if (i > 0) ids[0] += ",";
            ids[0] += res.IdList[i];
        }
        textBox1.Text = "Search in PubMed for \"cat\" returned " + res.Count + " hits\r\n";
        textBox1.Text += "Search links in nuccore for the first 5 UIDs: " + ids[0]+"\r\n\r\n";
    }
    catch (Exception eee)
    {
        textBox1.Text += eee.ToString();
    }
           
    // STEP #2: get links in nucleotide database (nuccore)
    try
    {
        eUtils.eUtilsServiceSoapClient serv = new eUtils.eUtilsServiceSoapClient();
        // call NCBI ELink utility
        eUtils.eLinkRequest req = new eUtils.eLinkRequest();
        req.db = "nuccore";
        req.id = ids;
        req.dbfrom = "pubmed";
        eUtils.eLinkResult res = serv.run_eLink(req);
        // read result and create a list of UIDs to fetch
        for (int i = 0; i < res.LinkSet[0].LinkSetDb[0].Link.Length; i++)
        {
            if (i > 0) fetchIds += ",";
            fetchIds += res.LinkSet[0].LinkSetDb[0].Link[i].Id.Value;
        }
        textBox1.Text += "ELink returned the following UIDs from nuccore: " + fetchIds + "\r\n\r\n";
    }
    catch (Exception eee)
    {
        textBox1.Text += eee.ToString();
    }


    // STEP #3: fetch records from nuccore
    //
    try
    {
        eFetchSeq.eUtilsServiceSoapClient serv = new eFetchSeq.eUtilsServiceSoapClient();
        // call NCBI ESpell utility
        eFetchSeq.eFetchRequest req = new eFetchSeq.eFetchRequest();
        req.db = "nuccore";
        req.id = fetchIds;
        eFetchSeq.eFetchResult res = serv.run_eFetch(req);
        // results output
        for (int i = 0; i < res.GBSet.GBSeq.Length; i++)
        {
            textBox1.Text += "Organism: " + res.GBSet.GBSeq[i].GBSeq_organism + "\r\n";
            textBox1.Text += "Locus: " + res.GBSet.GBSeq[i].GBSeq_locus + "\r\n";
            textBox1.Text += "Definition: " + res.GBSet.GBSeq[i].GBSeq_definition + "\r\n";
            textBox1.Text += "----------------------\r\n\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();
    }

Copyright Notice: http://www.ncbi.nlm.nih.gov/books/about/copyright/

Print View 
Cover of Entrez Programming Utilities Help
Entrez Programming Utilities Help [Internet].

In this Page

Other titles in this collection

Recent activity

Clear Turn Off Turn On

Your browsing activity is empty.

Activity recording is turned off.

Turn recording back on

See more...
You are here: NCBI > Literature > Bookshelf
Write to the Help Desk