Titik Akhir Metadata Aman Kustom

Sampel CustomMexEndpoint menunjukkan cara mengimplementasikan layanan dengan titik akhir metadata aman yang menggunakan salah satu pengikatan pertukaran non-metadata, dan cara mengonfigurasi ServiceModel Metadata Utility Tool (Svcutil.exe) atau klien untuk mengambil metadata dari titik akhir metadata tersebut. Ada dua pengikatan yang disediakan sistem yang tersedia untuk mengekspos titik akhir metadata: mexHttpBinding dan mexHttpsBinding. mexHttpBinding digunakan untuk mengekspos titik akhir metadata melalui HTTP dengan cara yang tidak aman. mexHttpsBinding digunakan untuk mengekspos titik akhir metadata melalui HTTPS dengan cara yang aman. Sampel ini menggambarkan cara mengekspos titik akhir metadata aman menggunakan WSHttpBinding. Anda ingin melakukan ini ketika Anda ingin mengubah pengaturan keamanan pada pengikatan, tetapi Anda tidak ingin menggunakan HTTPS. Jika Anda menggunakan mexHttpsBinding titik akhir metadata Anda akan aman, tetapi tidak ada cara untuk mengubah pengaturan pengikatan.

Nota

Prosedur penyiapan dan instruksi build untuk sampel ini terletak di akhir topik ini.

Pelayanan

Layanan dalam sampel ini memiliki dua titik akhir. Titik akhir aplikasi melayani ICalculator kontrak pada WSHttpBinding dengan ReliableSession diaktifkan dan keamanan Message menggunakan sertifikat. Titik akhir metadata juga menggunakan WSHttpBinding, dengan pengaturan keamanan yang sama tetapi tanpa ReliableSession. Berikut adalah konfigurasi yang relevan:

<services>
    <service name="Microsoft.ServiceModel.Samples.CalculatorService"
             behaviorConfiguration="CalculatorServiceBehavior">
     <!-- use base address provided by host -->
     <endpoint address=""
       binding="wsHttpBinding"
       bindingConfiguration="Binding2"
       contract="Microsoft.ServiceModel.Samples.ICalculator" />
     <endpoint address="mex"
       binding="wsHttpBinding"
       bindingConfiguration="Binding1"
       contract="IMetadataExchange" />
     </service>
 </services>
 <bindings>
   <wsHttpBinding>
     <binding name="Binding1">
       <security mode="Message">
         <message clientCredentialType="Certificate" />
       </security>
     </binding>
     <binding name="Binding2">
       <reliableSession inactivityTimeout="00:01:00" enabled="true" />
       <security mode="Message">
         <message clientCredentialType="Certificate" />
       </security>
     </binding>
   </wsHttpBinding>
 </bindings>

Di banyak sampel lainnya, titik akhir metadata menggunakan default mexHttpBinding, yang tidak aman. Di sini metadata diamankan menggunakan WSHttpBinding dengan Message keamanan. Agar klien metadata mengambil metadata ini, mereka harus dikonfigurasi dengan pengikatan yang cocok. Sampel ini menunjukkan dua klien tersebut.

Klien pertama menggunakan Svcutil.exe untuk mengambil metadata dan menghasilkan kode dan konfigurasi klien pada waktu desain. Karena layanan menggunakan pengikatan non-default untuk metadata, alat Svcutil.exe harus dikonfigurasi secara khusus sehingga bisa mendapatkan metadata dari layanan menggunakan pengikatan tersebut.

Klien kedua menggunakan MetadataResolver untuk mengambil metadata secara dinamis untuk kontrak yang diketahui dan kemudian memanggil operasi pada klien yang dihasilkan secara dinamis.

Klien Svcutil

Saat menggunakan pengikatan default untuk menghosting titik akhir IMetadataExchange Anda, Anda dapat menjalankan Svcutil.exe dengan menggunakan alamat titik akhir itu.

svcutil http://localhost/servicemodelsamples/service.svc/mex

dan berhasil. Tetapi dalam sampel ini, server menggunakan titik akhir non-default untuk menghosting metadata. Jadi Svcutil.exe harus diinstruksikan untuk menggunakan pengikatan yang benar. Ini dapat dilakukan menggunakan file Svcutil.exe.config.

File Svcutil.exe.config terlihat seperti file konfigurasi klien normal. Satu-satunya aspek yang tidak biasa adalah nama endpoint pelanggan dan kontrak.

<endpoint name="http"
          binding="wsHttpBinding"
          bindingConfiguration="Binding1"
          behaviorConfiguration="ClientCertificateBehavior"
          contract="IMetadataExchange" />

Nama titik akhir harus berupa nama skema alamat tempat metadata dihosting dan kontrak titik akhir harus IMetadataExchange. Dengan demikian, ketika Svcutil.exe dijalankan dengan baris perintah seperti berikut:

svcutil http://localhost/servicemodelsamples/service.svc/mex

ini mencari titik akhir bernama "http" dan kontrak IMetadataExchange untuk mengonfigurasi pengikatan dan perilaku pertukaran komunikasi dengan titik akhir metadata. File Svcutil.exe.config lainnya dalam sampel menentukan konfigurasi pengikatan dan kredensial perilaku agar sesuai dengan konfigurasi server dari titik akhir metadata.

Agar Svcutil.exe dapat mengambil konfigurasi di Svcutil.exe.config, Svcutil.exe harus berada di direktori yang sama dengan file konfigurasi. Akibatnya, Anda harus menyalin Svcutil.exe dari lokasi penginstalannya ke direktori yang berisi file Svcutil.exe.config. Kemudian dari direktori tersebut, jalankan perintah berikut:

.\svcutil.exe http://localhost/servicemodelsamples/service.svc/mex

Yang terdepan ".\" memastikan bahwa salinan Svcutil.exe dalam direktori ini (yang memiliki Svcutil.exe.configyang sesuai) dijalankan.

Klien MetadataResolver

Jika klien mengetahui kontrak dan cara berbicara dengan metadata pada waktu desain, klien dapat secara dinamis mengetahui pengikatan dan alamat titik akhir aplikasi menggunakan MetadataResolver. Contoh klien ini menunjukkan ini, menunjukkan cara mengonfigurasi pengikatan dan kredensial yang digunakan dengan MetadataResolver membuat dan mengonfigurasi MetadataExchangeClient.

Informasi pengikatan dan sertifikat yang sama yang muncul di Svcutil.exe.config dapat ditentukan secara imperatif pada MetadataExchangeClient:

// Specify the Metadata Exchange binding and its security mode
WSHttpBinding mexBinding = new WSHttpBinding(SecurityMode.Message);
mexBinding.Security.Message.ClientCredentialType = MessageCredentialType.Certificate;

// Create a MetadataExchangeClient for retrieving metadata, and set the // certificate details
MetadataExchangeClient mexClient = new MetadataExchangeClient(mexBinding);
mexClient.SoapCredentials.ClientCertificate.SetCertificate(    StoreLocation.CurrentUser, StoreName.My,
    X509FindType.FindBySubjectName, "client.com");
mexClient.SoapCredentials.ServiceCertificate.Authentication.CertificateValidationMode = X509CertificateValidationMode.PeerOrChainTrust;
mexClient.SoapCredentials.ServiceCertificate.SetDefaultCertificate(    StoreLocation.CurrentUser, StoreName.TrustedPeople,
    X509FindType.FindBySubjectName, "localhost");

Dengan mexClient dikonfigurasi, kita dapat mendaftar kontrak yang kita minati, dan menggunakan MetadataResolver untuk mengambil daftar endpoint dengan kontrak tersebut.

// The contract we want to fetch metadata for
Collection<ContractDescription> contracts = new Collection<ContractDescription>();
ContractDescription contract = ContractDescription.GetContract(typeof(ICalculator));
contracts.Add(contract);
// Find endpoints for that contract
EndpointAddress mexAddress = new EndpointAddress(ConfigurationManager.AppSettings["mexAddress"]);
ServiceEndpointCollection endpoints = MetadataResolver.Resolve(contracts, mexAddress, mexClient);

Akhirnya kita dapat menggunakan informasi dari titik akhir tersebut untuk menginisialisasi pengikatan dan alamat ChannelFactory yang digunakan dalam pembuatan saluran komunikasi dengan titik akhir aplikasi.

ChannelFactory<ICalculator> cf = new ChannelFactory<ICalculator>(endpoint.Binding, endpoint.Address);

Titik kunci dari klien sampel ini adalah untuk menunjukkan bahwa, jika Anda menggunakan MetadataResolver, dan Anda harus menentukan pengikatan atau perilaku kustom untuk komunikasi pertukaran metadata, Anda dapat menggunakan MetadataExchangeClient untuk menentukan pengaturan kustom tersebut.

Untuk menyiapkan dan membangun sampel

Pastikan Anda telah melakukan Prosedur Penyiapan One-Time untuk Sampel Windows Communication Foundation.
Untuk membangun solusi, ikuti instruksi dalam Membangun Sampel Windows Communication Foundation.

Untuk menjalankan sampel pada komputer yang sama

Jalankan Setup.bat dari folder instalasi sampel. Ini menginstal semua sertifikat yang diperlukan untuk menjalankan sampel. Perhatikan bahwa Setup.bat menggunakan alat FindPrivateKey.exe, yang diinstal dengan menjalankan setupCertTool.bat dari Prosedur PenyiapanOne-Time untuk Sampel Windows Communication Foundation.
Jalankan aplikasi klien dari \MetadataResolverClient\bin atau \SvcutilClient\bin. Aktivitas klien ditampilkan pada aplikasi konsol klien.
Jika klien dan layanan tidak dapat berkomunikasi, lihat Tips Pemecahan Masalah untuk Sampel WCF.
Hapus sertifikat dengan menjalankan Cleanup.bat setelah Anda selesai dengan sampel. Sampel keamanan lainnya menggunakan sertifikat yang sama.

Untuk menjalankan contoh kode di berbagai komputer

Di server, jalankan setup.bat service. Menjalankan setup.bat dengan argumen service membuat sertifikat layanan dengan nama domain sepenuhnya dari komputer dan mengekspornya ke file bernama Service.cer.
Di server, edit Web.config untuk mencerminkan nama sertifikat baru. Artinya, ubah findValue atribut dalam <elemen serviceCertificate> menjadi nama domain komputer yang sepenuhnya memenuhi syarat.
Salin file Service.cer dari direktori layanan ke direktori klien di komputer klien.
Pada klien, jalankan setup.bat client. Menjalankan setup.bat argumen client membuat sertifikat klien bernama Client.com dan mengekspor sertifikat klien ke file bernama Client.cer.
Dalam file App.config pada komputer klien MetadataResolverClient, ubah nilai alamat pada endpoint mex agar sesuai dengan alamat baru dari layanan Anda. Anda melakukan ini dengan mengganti localhost dengan nama domain server yang sepenuhnya memenuhi syarat. Ubah juga kemunculan "localhost" dalam file metadataResolverClient.cs ke nama sertifikat layanan baru (nama domain server yang sepenuhnya memenuhi syarat). Lakukan hal yang sama untuk App.config dari proyek SvcutilClient.
Salin file Client.cer dari direktori klien ke direktori layanan di server.
Pada klien, jalankan ImportServiceCert.bat. Ini mengimpor sertifikat layanan dari file Service.cer ke penyimpanan CurrentUser - TrustedPeople.
Di server, jalankan ImportClientCert.bat, Ini mengimpor sertifikat klien dari file Client.cer ke penyimpanan LocalMachine - TrustedPeople.
Pada mesin layanan, buat proyek layanan di Visual Studio dan pilih halaman bantuan di browser web untuk memverifikasi bahwa proyek tersebut berjalan.
Pada komputer klien, jalankan MetadataResolverClient atau SvcutilClient dari VS.
1. Jika klien dan layanan tidak dapat berkomunikasi, lihat Tips Pemecahan Masalah untuk Sampel WCF.

Untuk membersihkan setelah pengujian sampel

Jalankan Cleanup.bat di folder sampel setelah Anda selesai menjalankan sampel.

Nota

Skrip ini tidak menghapus sertifikat layanan pada klien saat menjalankan sampel ini di seluruh komputer. Jika Anda telah menjalankan sampel Windows Communication Foundation (WCF) yang menggunakan sertifikat di seluruh komputer, pastikan untuk menghapus sertifikat layanan yang telah diinstal di penyimpanan CurrentUser - TrustedPeople. Untuk melakukan ini, gunakan perintah berikut: certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name>. Misalnya: certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com.

Terakhir diperbarui pada 2025-06-17