Using E-Utilities Web Service with C# in MS Visual Studio .NET
Updated: January 12, 2006
SOAP Interface for E-Utilities was tested with:
- Microsoft Windows XP Professional Version 2002 (Service Pack2)
- Microsoft .NET Framework 1.1 Version 1.1.4322
- Microsoft Development Environment 2003 Version 7.1.3088
Note: Microsoft .NET Framework 1.0 does not work with eutils. You should update it to version 1.1 at least.
Creating an NCBI Web Service Client Project
The following walkthrough describes the process for accessing the NCBI E-Utilities Web service from an application created with Visual C#.
To create Windows application:
- On the File menu, point to New, and then click Project to open the New Project dialog box.
- Expand the Visual C# Projects folder.
- Click the Windows Application icon.
- Click OK to create the project.
- From the Toolbox, drag a Label and a Button to the design surface of Form1 and arrange them to your liking.
- On the Project menu, click Add Web Reference.
- In the URL box of the Add Web Reference dialog box, type the URL http://eutils.ncbi.nlm.nih.gov/entrez/eutils/soap/eutils.wsdl
- Click the Go button to retrieve information about the XML Web service.
- In the Web reference name box, rename the Web reference to eUtils.
- Click Add Reference to add a Web reference for the target XML Web service.
- Double-click the button on Form1 to create an event-handling method for this button.
- In the button1_Click method enter the following code:
// eInfo utility returns a list of available databases
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI EInfo utility
eUtils.eInfoResultType res = serv.run_eInfo_MS("", "", "");
// results output
label1.Text = "";
for(int i=0; i<res.DbList.Items.Length; i++) label1.Text += res.DbList.Items[i]+"\n";
}
catch
{
label1.Text = "Failed";
}
|
- Build and run application.
SOAP E-Utilities API
Below is a list of methods we recommend for use with C#.
SOAP interface provides user with two functionally identical sets of methods.
Methods which name ends with _MS are designed for use with Microsoft Visual Studio and SOAP Toolkit 3.0
Click on parameter to get its description.
Click on method name to see the example of use.
- public GQueryResultType run_eGquery_MS( string term,
string tool,
string email );
- public eInfoResultType run_eInfo_MS( string db,
string tool,
string email );
- public eLinkResultType run_eLink_MS( string db,
string[] id,
string reldate,
string mindate,
string maxdate,
string datetype,
string term,
string dbfrom,
string WebEnv,
string query_key,
string cmd,
string tool,
string email );
- public eSearchResultType run_eSearch_MS( string db,
string term,
string WebEnv,
string query_key,
string usehistory,
string tool,
string email,
string field,
string reldate,
string mindate,
string maxdate,
string datetype,
string retstart,
string retmax,
string rettype,
string sort );
- public eSpellResultType run_eSpell_MS( string db,
string term,
string tool,
string email );
- public eSummaryResultType run_eSummary_MS( string db,
string id,
string WebEnv,
string query_key,
string retstart,
string retmax,
string tool,
string email );
- public eFetchResultType run_eFetch_MS(
string db,
string id,
string WebEnv,
string query_key,
string tool,
string email,
string retstart,
string retmax,
string rettype, // *rettype for Molecular Biology Databases
string strand,
string seq_start,
string seq_stop,
string complexity,
string report );
Examples
// run_eGquery_MS provides Entrez database counts for a single search
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI EGQuery utility
eUtils.GQueryResultType res = serv.run_eGquery_MS("mouse", "", "");
// results output
label1.Text = "Search term: " + res.Term + "\n";
label1.Text += "Results: \n";
for(int i=0; i<res.eGQueryResult.ResultItem.Length; i++)
{
label1.Text += " " + res.eGQueryResult.ResultItem[i].DbName +
": " + res.eGQueryResult.ResultItem[i].Count + "\n";
}
}
catch
{
label1.Text = "Failed";
}
|
// eInfo utility returns a list of available databases
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI EInfo utility
eUtils.eInfoResultType res = serv.run_eInfo_MS("", "", "");
// results output
label1.Text = "";
for(int i=0; i<res.DbList.Items.Length; i++) label1.Text += res.DbList.Items[i]+"\n";
}
catch
{
label1.Text = "Failed";
}
|
// example retrieves IDs from Nucleotide for GI 48819,7140345 to Protein
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
string[] id = {"48819,7140345"};
// call NCBI ELink utility
eUtils.eLinkResultType res = serv.run_eLink_MS("protein", id, "", "", "", "", "",
"nucleotide", "", "", "", "", "");
// results output
label1.Text = "";
for(int i=0; i<res.LinkSet.Length; i++)
{
label1.Text += "Links from " + res.LinkSet[i].DbFrom + " to " + res.LinkSet[i].LinkSetDb[0].DbTo + "\n";
label1.Text += " " + res.LinkSet[i].DbFrom + " id(s): ";
for(int k=0; k<res.LinkSet[i].IdList.Length; k++)
{
label1.Text += res.LinkSet[i].IdList[k].Value + " ";
}
label1.Text += "\n";
label1.Text += " " + res.LinkSet[i].LinkSetDb[0].DbTo + " id(s): ";
for(int k=0; k<res.LinkSet[i].LinkSetDb[0].Items.Length; k++)
{
eUtils.LinkType1 lt = (eUtils.LinkType1)res.LinkSet[i].LinkSetDb[0].Items[k];
label1.Text += lt.Id.Value + " ";
}
label1.Text += "\n----------------------\n";
}
}
catch
{
label1.Text = "Failed";
}
|
// search in PubMed Central for stem cells in free fulltext articles
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI ESearch utility
// NOTE: search term should be URL encoded
eUtils.eSearchResultType res = serv.run_eSearch_MS("pmc", "stem+cells+AND+free+fulltext[filter]",
"", "", "", "", "", "", "", "", "", "", "0",
"15", "", "");
// results output
label1.Text = "Original query: stem cells AND free fulltext[filter]\n";
label1.Text += "Found ids: " + res.Count+"\n";
label1.Text += "First " + res.RetMax +" ids: ";
for(int i=0; i<res.IdList.Length; i++)
{
label1.Text += res.IdList[i] + " ";
}
}
catch
{
label1.Text = "Failed";
}
|
// retrieves spelling suggestions
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI ESpell utility
eUtils.eSpellResultType res = serv.run_eSpell_MS("pubmed", "mouss", "", "");
// results output
label1.Text = "Misspelled word: "+res.Query + "\n";
label1.Text += "Corrected word: "+res.CorrectedQuery;
}
catch
{
label1.Text = "Failed";
}
|
// retreives document Summaries by list of primary IDs
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI ESummary utility
eUtils.eSummaryResultType res = serv.run_eSummary_MS("nucleotide", "28864546,28800981",
"", "", "", "", "", "");
// results output
label1.Text = "";
for(int i=0; i<res.DocSum.Length; i++)
{
label1.Text += "ID: "+res.DocSum[i].Id+"\n";
for(int k=0; k<res.DocSum[i].Item.Length; k++)
{
if(res.DocSum[i].Item[k].Text!=null)
label1.Text += " "+res.DocSum[i].Item[k].Name +": "+res.DocSum[i].Item[k].Text[0]+"\n";
}
label1.Text += "-----------------------\n\n";
}
}
catch
{
label1.Text = "Failed";
}
|
Literature database example
// fetch article from pubmed and displays its abstract
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI EFetch utility
eUtils.eFetchResultType res = serv.run_eFetch_MS("pubmed", "11748933,11700088", "", "",
"", "", "", "", "", "", "", "", "", "");
// results output
label1.Text = "";
for(int i=0; i<res.PubmedArticleSet.Length; i++)
{
label1.Text += "ID: "+res.PubmedArticleSet[i].MedlineCitation.PMID + "\n";
label1.Text += "Abstract: "+res.PubmedArticleSet[i].MedlineCitation.Article.Abstract.AbstractText + "\n";
label1.Text += "--------------------------\n\n";
}
}
catch
{
label1.Text = "Failed";
}
|
Taxonomy database example
// fetch a record from Taxonomy database
try
{
eUtils.eUtilsService serv = new eUtils.eUtilsService();
// call NCBI EFetch utility
eUtils.eFetchResultType res = serv.run_eFetch_MS("taxonomy", "9685", "", "", "",
"", "", "", "", "", "", "", "", "");
// results output
label1.Text = res.TaxaSet[0].ScientificName + ": " +
res.TaxaSet[0].Division + " (" +
res.TaxaSet[0].Rank + ")\n";
}
catch
{
label1.Text = "Failed";
}
|
<< Back
