建立彈性查詢應用程式

更新日期: 2014年2月

 

DataMarket 標誌

在 Visual Studio 中使用服務參考,即可以程式設計方式取用資料發行者已指定為彈性查詢資料集的 Marketplace 資料集。

Important重要事項
不得修改服務參考中的程式碼,因為修改可能會導致運作異常和副作用。此外,每次重新整理服務參考時,修改就會遭到覆寫。

繼續之前,請確定您具備:

  • 有效的 Windows Live ID 帳戶。如果您沒有 Live ID,請移至 Windows Live 首頁並註冊。

  • 有效的 Marketplace 帳戶。如果您沒有 Marketplace,請移至建立您的 Marketplace 帳戶主題,然後依照此處的指示執行。

  • 訂用您要用於應用程式中的 Marketplace 彈性查詢資料集。如果尚未訂用彈性查詢資料集,請移至訂用資料供應項目,然後依照此處的指示執行。

 

章節 描述

步驟 1:在 Visual Studio 中建立您的專案

在 Visual Studio 中啟動 Marketplace 的新主控台專案時所需採取的步驟。

步驟 2:加入資料服務的服務參考

您要加入服務參考以取用 Marketplace 資料時所需所採取的步驟。

步驟 3:利用 Managed 程式碼取用資料

您為了取用 Marketplace 彈性查詢資料集所撰寫的程式碼。

完成的程式碼

採用 C# 和 VB 的完整主控台應用程式

中繼資料

此彈性查詢資料集的 XML 中繼資料範例。

  1. 在您的 [開始] 功能表中尋找 [Visual Studio]

  2. 以滑鼠右鍵按一下 [Visual Studio]

  3. 在下拉式功能表中按一下 [以系統管理員身分執行]

  4. 當系統詢問您是否允許此程式 (devenv.exe) 變更您的電腦時,請按一下 [是]

  1. 在 Visual Studio 的起始頁選取 [新增專案...].

  2. 在 [新增專案] 對話方塊中選取 [Visual C#][主控台應用程式] (如果您偏好 Visual Basic,則選取 [Visual Basic][主控台應用程式])。

  3. [新增專案] 對話方塊頂端的左側下拉式清單,選取 [.NET Framework 4]

    Visual Studio 2010 會預設為 [.NET Framework 4]。如果您使用舊版 Visual Studio 且未安裝 .NET Framework 4,請前往 .NET Framework 4 下載頁面下載並安裝它。

  4. 為您的專案提供有意義的名稱。例如,您可以將此專案命名為 USCrime2006and2007

  5. 按一下 [確定]

  6. 將下列程式碼加至 Program.cs (Program.vb) 的最前面,以便驗證您對於資料集的存取權。

    using System.Net; // needed for authentication
    

以系統管理員身分啟動 Visual Studio 並建立新的主控台應用程式 (步驟 1) 之後,為您要取用的資料服務加入服務參考。

  1. 移至 Marketplace 首頁

  2. 按一下 [我的資料] 索引標籤。

  3. 尋找 2006 - 2008 Crime in the United States 資料服務。

  4. 按一下資料集名稱右邊的 [使用]。這會帶您前往此資料集的 [詳細資料頁面]。

  5. 將頁面向下捲動至 [瞭解如何在 Visual Studio 中使用此資料] 下面的列索引標籤

  6. 按一下 [詳細資料] 索引標籤。

  7. 尋找 [服務根目錄 URL]

    服務根 URL


    圖 1 – 服務根目錄 URL

  8. [服務根目錄 URL] 複製到剪貼簿。

  1. 返回 Visual Studio 專案。

  2. [方案總管] 中以滑鼠右鍵按一下 [參考]

  3. 從下拉式功能表選取 [加入服務參考...]

  4. 將剪貼簿中的服務根目錄 URL 貼在 [位址] 下拉式清單中。

  5. 按一下 [移至]
    稍後片刻,讓服務文字方塊中填入您的專案可用的服務。

  6. [命名空間] 文字方塊中輸入有意義的命名空間名稱。
    例如:DataGovCrimes

  7. 按一下 [確定]
    服務參考的名稱會出現在 [方案總管][服務參考] 中。

  1. 在 [Visual Studio 程式碼窗格] 中選取 [Program.cs] ([Program.vb])。

  2. 加入下列陳述式,讓您的應用程式可存取您的服務參考。

    note附註
    使用程式命名空間加上您在上述步驟 6 中建立的服務參考命名空間名稱。

    using USCrime2006and2007.DataGovCrimes; // using ApplicationName.ServiceReferenceName
    

  1. 在您的專案命名空間內建立公用類別 CrimeData

  2. 在您的類別內建立兩個私用變數。

    • 服務的 Uri。

    • 將您的服務認證儲存在服務內容中的服務容器。

      1. 移至 [詳細資料頁面]。

      2. 按一下 [開始使用此資料集]

      3. 按一下 [概觀] 索引標籤。
        實體集名稱和實體集合名稱隨即顯示。

    
    class CrimeData
    {
        private Uri serviceURI;
        private datagovCrimesContainer context;
    }  // end class CrimeData
    
    
  3. 建立 CrimeData 類別的建構函式。
    此建構函式會初始化這兩個私用變數,並初始化使用者認證。
    SERVICE_ROOT_URL 就是您複製到上述剪貼簿的 https 連結。(請參閱 取得服務根目錄 URL。)
    context 是使用者認證所用的服務容器。
    IgnoreMissingProperties 屬性會設定為 true,讓用戶端達到健全狀態以處理加入至伺服器上此型別的屬性。(如需其他資訊,請參閱 MSDN 文件。)
    USER_ID 是您的 Live ID。
    SECURE_ACCOUNT_KEY 是您用於此應用程式的 Marketplace 帳戶金鑰。(請參閱<管理您的 Marketplace 帳戶>)。

    
    class CrimeData
    {
        private Uri serviceURI;
        private datagovCrimesContainer context;
    
        // constructor for the CrimeData class
        public CrimeData()  
        {
            serviceURI = new Uri(SERVICE_ROOT_URL);
            context = new datagovCrimesContainer(serviceURI);
            context.IgnoreMissingProperties = true;
            context.Credentials = new NetworkCredential(USER_ID,
                                                        SECURE_ACCOUNT_ID); // Your Marketplace account key
        }  // end constructor
    
    }  // end class CrimeData
    
    
  4. 在您的類別內建立可傳回泛型清單的公用方法。在我們程式中,泛型清單型別是 CityCrime
    這個方法會查詢服務,如果查詢成功,則會以清單形式傳回結果集。如果查詢因為任何原因而失敗,則方法會傳回 null (Nothing)。

    
    class CrimeData
    {
        private Uri serviceURI;
        private datagovCrimesContainer context;
    
        // constructor for the CrimeData class
        public CrimeData()
        {
            serviceURI = new Uri(SERVICE_ROOT_URL);
            context = new datagovCrimesContainer(serviceURI);
            context.IgnoreMissingProperties = true;
            context.Credentials = new NetworkCredential(USER_ID,
                                                        SECURE_ACCOUNT_ID);
        }  // end constructor
    
        // -- public method that returns a list of crime data
        public IList<CityCrime> GetCrimeData()
        {
            IEnumerable<CityCrime> query = context.CityCrime.Where(crime => crime.City == "Newport").OrderBy(crime => crime.Year);
    
            try
            {
                return query.ToList();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Error: {0}", ex.Message);
                return null;
            }  // end try
    
        }  // end function GetCrimeData
    
    }  // end class CrimeData
    
    

    查詢可以是任何有效的 Marketplace LINQ 查詢,並可選擇性地包含 where (Where) 篩選器和/或 orderby (Order By)。
    如需 LINQ 查詢的詳細資訊,請參閱 LINQ 查詢運算式 (C# 程式設計指南) (Visual Basic 中的 LINQ)。
    如需 Marketplace 中 LINQ 查詢限制的相關資訊,請參閱支援的 OData 查詢選項

    下列 LINQ 查詢適用於 Marketplace。

    
    query = from crimes in context.CityCrime
                where crimes.City == "Newport" 
                orderby crimes.Year Ascending
                select crimes;
    //  this query could also be written as
    //  IEnumerable<CityCrime> query = context.CityCrime.Where(crime => crime.City == "Newport").OrderBy(crime => crime.Year);
    
    
  5. Main() 中撰寫程式碼,以利用您的 CrimeData 類別和 GetCrimeData() 方法來取用資料並加以顯示。

    
    using System.Net;
    using USCrime2006and2007.DataGovCrimes; // using ApplicationName.ServiceReferenceName
    
    namespace USCrime2006and2007
    {
       class Program
       {
          public static void Main(string[] args)
          {
              IList<CityCrime> crimeList;  // CityCrime is the entity type returned by the service
              CrimeData crimeData = new CrimeData();
    
              crimeList = crimeData.GetCrimeData();
    
              if (crimeList != null)
              {
                  Console.WriteLine("{0,4} {1,-12} {2,-15} {3,10} {4,13}","Year",
                                                                          "City",
                                                                          "State",
                                                                          "Population",
                                                                          "Violent Crime");
    
                  foreach (CityCrime c in crimeList)
                  {
                      Console.WriteLine("{0,4} {1,-12} {2,-15} {3,10} {4,13}", c.Year, 
                                                                               c.City, 
                                                                               c.State, 
                                                                               c.Population,
                                                                               c.ViolentCrime);
                  } // end foreach
    
              }  // end if
    
              Console.Write("Tap any key to exit. ");
              Console.ReadKey();
    
          }  // end Main
    
        }  // end class Program
    
    }  // end namespace
    
    


using System.Net;
using USCrime2006and2007.DataGovCrimes; // using ApplicationName.ServiceReferenceName

namespace USCrime2006and2007
{
   class Program
   {
      public static void Main(string[] args)
      {
          IList<CityCrime> crimeList;  // CityCrime is the entity type returned by the service
          CrimeData crimeData = new CrimeData();

          crimeList = crimeData.GetCrimeData();

          if (crimeList != null)
          {
              Console.WriteLine("{0,4} {1,-12} {2,-15} {3,10} {4,13}","Year",
                                                                      "City",
                                                                      "State",
                                                                      "Population",
                                                                      "Violent Crime");

              foreach (CityCrime c in crimeList)
              {
                  Console.WriteLine("{0,4} {1,-12} {2,-15} {3,10} {4,13}", c.Year, 
                                                                           c.City, 
                                                                           c.State, 
                                                                           c.Population,
                                                                           c.ViolentCrime);
              } // end foreach

          }  // end if

          Console.Write("Tap any key to exit. ");
          Console.ReadKey();

      }  // end Main

    }  // end class Program

    class CrimeData
    {
        private Uri serviceUri;
        private datagovCrimesContainer context;

        // constructor for the CrimeData class
        public CrimeData()
        {
            serviceUri = new Uri(SERVICE_ROOT_URL);
            context = new datagovCrimesContainer(serviceUri);
            context.IgnoreMissingProperties = true;
            context.Credentials = new NetworkCredential USER_ID,
                                                        SECURE_ACCOUNT_KEY); // Your Marketplace account key
        }  // end constructor
 
        // – public function that returns a list of crime data
        public IList<CityCrime> GetCrimeData()
        {
            IEnumerable<CityCrime> query = context.CityCrime.Where(crime => crime.City == "Newport").OrderBy(crime => crime.Year);
 
            try
            {
                return query.ToList();
            }
            catch (Exception ex)
            {
                Console.WriteLine("Error: {0}", ex.Message);
                return null;
            }  // end try

        }  // end function

    }  // end class CrimeData

}  // end namespace

當您撰寫程式碼時,資料集的中繼資料會通知 Intellisense。如果您的 IDE 不支援 Intellisense 或 Intellisense 無法運作,您可以向服務取得中繼資料。

  1. 取得資料集的服務根目錄 URL。
    如需取得服務根目錄 URL 的指示,請參閱上述取得服務根目錄 URL 一節。

  2. /$metadata 加入至您的服務根目錄 URL 結尾。
    例如,如果您的服務根目錄 URL 是 https://api.datamarket.azure.com/Data.ashx/fabrikam.com/inventory,則中繼資料 URL 是 https://api. datamarket.azure.com/Data.ashx/fabrikam.com/inventory/$metadata

  3. 將瀏覽器瀏覽至中繼資料 URL。

  4. 剖析中繼資料。
    以下是 2006 - 2008 Crime in the United States 資料集的中繼資料 (https://api.datamarket.azure.com/Data.ashx/data.gov/Crimes/$metadata)。

    
    <?xml version="1.0" encoding="utf-8" standalone="yes" ?> 
    <edmx:Edmx Version="1.0" xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" xmlns:dr="http://schemas.microsoft.com/dallas/2010/04">   
       <edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="1.0">      
          <Schema Namespace="data.gov.Crimes"xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
                  xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
                  xmlns="http://schemas.microsoft.com/ado/2007/05/edm">
             <EntityType Name="CityCrime">
                <Key>
                   <PropertyRef Name="ROWID" />
                </Key>
                <Property Name="ROWID" Type="Edm.Int32" Nullable="false" dr:Queryable="true" dr:Returned="true" />
                <Property Name="State" Type="Edm.String" Nullable="true" dr:Queryable="true" dr:Returned="true" />
                <Property Name="City" Type="Edm.String" Nullable="true" dr:Queryable="true" dr:Returned="true" />
                <Property Name="Year" Type="Edm.Int32" Nullable="false" dr:Queryable="true" dr:Returned="true" />
                <Property Name="Population" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="ViolentCrime" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="MurderAndNonEgligentManslaughter" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="ForcibleRape" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="Robbery" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="AggravatedAssault" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="PropertyCrime" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="Burglary" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="LarcenyTheft" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="MotorVehicleTheft" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
                <Property Name="Arson" Type="Edm.Int32" Nullable="false" dr:Queryable="false" dr:Returned="true" />
             </EntityType>
             <EntityContainer Name="datagovCrimesContainer" m:IsDefaultEntityContainer="true">
                <EntitySet Name="CityCrime" EntityType="data.gov.Crimes.CityCrime" />
             </EntityContainer>
          </Schema>
       </edmx:DataServices>
    </edmx:Edmx>
    
    

    程式碼範例 1 – 中繼資料 XML

    您可以從結構描述取得很多實用的資訊。

    • 實體容器名稱。
      <EntityContainer Name="datagovCrimesContainer" m:IsDefaultEntityContainer="true">
      這是私用 context 識別碼的型別,可用來驗證服務的存取權。


    • 實體集名稱和型別。
      <EntitySet Name="CityCrime" EntityType="data.gov.Crimes.CityCrime" />
      這是 IEnumerable<T> 和 IList<T> 的型別。


    • 實體和類型。
      <EntityType Name="CityCrime">
      這是在查詢中使用的型別和 foreach (For Each) 迴圈變數。


    • 查詢傳回的每個欄位名稱。
      Name=”State”


    • 每個欄位的資料型別。
      Type=”Edm.String”


    • 欄位是否可以為 null。
      Nullable=”false”


    • 欄位是否可用來篩選查詢結果。
      dr:Queryable=”true”
      dr:Queryable="false"
      可查詢的欄位可用於查詢的 where (Where) 子句中。不可查詢的欄位不能用於查詢 where (Where) 子句中。


    • 當您查詢資料集時,是否會傳回此欄位。
      dr:Returned=”true”

顯示: