Exemplo de introdução
O exemplo GettingStarted demonstra como implementar um serviço típico e um cliente típico usando o WCF (Windows Communication Foundation). Esse exemplo é a base para todos os outros exemplos básicos de tecnologia.
Observação
O procedimento de instalação e as instruções de compilação desse exemplo estão no final deste tópico.
O serviço descreve as operações executadas em um contrato de serviço que expõe publicamente como metadados. O serviço também contém o código para implementar as operações.
O cliente contém uma definição do contrato de serviço e uma classe proxy para acessar o serviço. O código proxy é gerado a partir dos metadados de serviço usando a Ferramenta do utilitário de metadados do ServiceModel (Svcutil.exe).
No Windows Vista, o serviço é hospedado no WAS (Serviço de Ativação do Windows). No Windows XP e no Windows Server 2003, ele é hospedado pelos Serviços de Informações da Internet (IIS) e ASP.NET. Hospedar um serviço no IIS ou WAS permite que o serviço seja ativado automaticamente quando ele é acessado pela primeira vez.
Observação
Se você preferir começar a usar um exemplo que hospeda o serviço em um aplicativo de console em vez do IIS, confira o exemplo Self-Host.
O serviço e o cliente especificam detalhes de acesso nas configurações do arquivo de configuração, que fornecem flexibilidade no momento da implantação. Isso inclui uma definição de ponto de extremidade que especifica um endereço, associação e contrato. A associação especifica os detalhes de transporte e segurança de como o serviço deve ser acessado.
O serviço configura um comportamento em tempo de execução para publicar seus metadados.
O serviço implementa um contrato que define um padrão de comunicação solicitação-resposta. O contrato é definido pela interface ICalculator, que expõe operações matemáticas (adicionar, subtrair, multiplicar e dividir). O cliente faz solicitações para uma determinada operação matemática, e o serviço responde com o resultado. O serviço implementa um contrato ICalculator conforme definido no código a seguir.
' Define a service contract.
<ServiceContract(Namespace:="http://Microsoft.Samples.GettingStarted")>
Public Interface ICalculator
<OperationContract()>
Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double
<OperationContract()>
Function Subtract(ByVal n1 As Double, ByVal n2 As Double) As Double
<OperationContract()>
Function Multiply(ByVal n1 As Double, ByVal n2 As Double) As Double
<OperationContract()>
Function Divide(ByVal n1 As Double, ByVal n2 As Double) As Double
End Interface
// Define a service contract.
[ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]
public interface ICalculator
{
[OperationContract]
double Add(double n1, double n2);
[OperationContract]
double Subtract(double n1, double n2);
[OperationContract]
double Multiply(double n1, double n2);
[OperationContract]
double Divide(double n1, double n2);
}
A implementação do serviço calcula e retorna o resultado apropriado, conforme mostrado no código de exemplo a seguir.
' Service class which implements the service contract.
Public Class CalculatorService
Implements ICalculator
Public Function Add(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculator.Add
Return n1 + n2
End Function
Public Function Subtract(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculator.Subtract
Return n1 - n2
End Function
Public Function Multiply(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculator.Multiply
Return n1 * n2
End Function
Public Function Divide(ByVal n1 As Double, ByVal n2 As Double) As Double Implements ICalculator.Divide
Return n1 / n2
End Function
End Class
// Service class that implements the service contract.
public class CalculatorService : ICalculator
{
public double Add(double n1, double n2)
{
return n1 + n2;
}
public double Subtract(double n1, double n2)
{
return n1 - n2;
}
public double Multiply(double n1, double n2)
{
return n1 * n2;
}
public double Divide(double n1, double n2)
{
return n1 / n2;
}
}
O serviço expõe um ponto de extremidade para comunicação com o serviço, definido usando um arquivo de configuração (Web.config), conforme mostrado na configuração de exemplo a seguir.
<services>
<service
name="Microsoft.ServiceModel.Samples.CalculatorService"
behaviorConfiguration="CalculatorServiceBehavior">
<!-- ICalculator is exposed at the base address provided by
host: http://localhost/servicemodelsamples/service.svc. -->
<endpoint address=""
binding="wsHttpBinding"
contract="Microsoft.ServiceModel.Samples.ICalculator" />
...
</service>
</services>
O serviço expõe o ponto de extremidade no endereço base fornecido pelo host IIS ou WAS. A associação é configurada com um padrão WSHttpBinding, que fornece comunicação HTTP e protocolos de serviço Web padrão para endereçamento e segurança. O contrato é o ICalculator implementado pelo serviço.
Conforme configurado, o serviço pode ser acessado em http://localhost/servicemodelsamples/service.svc por um cliente no mesmo computador. Para que os clientes em computadores remotos acessem o serviço, um nome de domínio totalmente qualificado deve ser especificado em vez do localhost.
A estrutura não expõe nenhum metadado por padrão. Dessa forma, o serviço ativa ServiceMetadataBehavior e expõe um ponto de extremidade MEX (troca de metadados) em http://localhost/servicemodelsamples/service.svc/mex. O arquivo de configuração a seguir demonstra isso.
<system.serviceModel>
<services>
<service
name="Microsoft.ServiceModel.Samples.CalculatorService"
behaviorConfiguration="CalculatorServiceBehavior">
...
<!-- the mex endpoint is exposed at
http://localhost/servicemodelsamples/service.svc/mex -->
<endpoint address="mex"
binding="mexHttpBinding"
contract="IMetadataExchange" />
</service>
</services>
<!--For debugging purposes set the includeExceptionDetailInFaults
attribute to true-->
<behaviors>
<serviceBehaviors>
<behavior name="CalculatorServiceBehavior">
<serviceMetadata httpGetEnabled="True"/>
<serviceDebug includeExceptionDetailInFaults="False" />
</behavior>
</serviceBehaviors>
</behaviors>
</system.serviceModel>
O cliente se comunica usando um determinado tipo de contrato usando uma classe cliente gerada pela ServiceModel Metadata Utility Tool (Svcutil.exe). Esse cliente gerado está contido no arquivo generatedClient.cs ou generatedClient.vb. Esse utilitário recupera metadados de um determinado serviço e gera um cliente para uso pelo aplicativo cliente para se comunicar usando um determinado tipo de contrato. O serviço hospedado deve estar disponível para gerar o código do cliente, pois o serviço é usado para recuperar os metadados atualizados.
Execute o comando a seguir em um prompt de comando do SDK no diretório do cliente para gerar o proxy com tipo:
svcutil.exe /n:"http://Microsoft.ServiceModel.Samples,Microsoft.ServiceModel.Samples" http://localhost/servicemodelsamples/service.svc/mex /out:generatedClient.cs
Para gerar cliente no Visual Basic, digite o seguinte no prompt de comando do SDK:
Svcutil.exe /n:"http://Microsoft.ServiceModel.Samples,Microsoft.ServiceModel.Samples" http://localhost/servicemodelsamples/service.svc/mex /l:vb /out:generatedClient.vb
Usando o cliente gerado, o cliente pode acessar um determinado ponto de extremidade de serviço configurando o endereço e a associação adequados. Assim como o serviço, o cliente usa um arquivo de configuração (App.config) para especificar o ponto de extremidade com o qual quer se comunicar. A configuração do ponto de extremidade do cliente consiste em um endereço absoluto para o ponto de extremidade de serviço, a associação e o contrato, conforme mostrado no exemplo a seguir.
<client>
<endpoint
address="http://localhost/servicemodelsamples/service.svc"
binding="wsHttpBinding"
contract=" Microsoft.ServiceModel.Samples.ICalculator" />
</client>
A implementação do cliente cria uma instância do cliente e usa a interface tipada para começar a se comunicar com o serviço, conforme mostrado no código de exemplo a seguir.
' Create a client
Dim client As New CalculatorClient()
' Call the Add service operation.
Dim value1 = 100.0R
Dim value2 = 15.99R
Dim result = client.Add(value1, value2)
Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result)
' Call the Subtract service operation.
value1 = 145.00R
value2 = 76.54R
result = client.Subtract(value1, value2)
Console.WriteLine("Subtract({0},{1}) = {2}", value1, value2, result)
' Call the Multiply service operation.
value1 = 9.00R
value2 = 81.25R
result = client.Multiply(value1, value2)
Console.WriteLine("Multiply({0},{1}) = {2}", value1, value2, result)
' Call the Divide service operation.
value1 = 22.00R
value2 = 7.00R
result = client.Divide(value1, value2)
Console.WriteLine("Divide({0},{1}) = {2}", value1, value2, result)
'Closing the client gracefully closes the connection and cleans up resources
// Create a client.
CalculatorClient client = new CalculatorClient();
// Call the Add service operation.
double value1 = 100.00D;
double value2 = 15.99D;
double result = client.Add(value1, value2);
Console.WriteLine("Add({0},{1}) = {2}", value1, value2, result);
// Call the Subtract service operation.
value1 = 145.00D;
value2 = 76.54D;
result = client.Subtract(value1, value2);
Console.WriteLine("Subtract({0},{1}) = {2}", value1, value2, result);
// Call the Multiply service operation.
value1 = 9.00D;
value2 = 81.25D;
result = client.Multiply(value1, value2);
Console.WriteLine("Multiply({0},{1}) = {2}", value1, value2, result);
// Call the Divide service operation.
value1 = 22.00D;
value2 = 7.00D;
result = client.Divide(value1, value2);
Console.WriteLine("Divide({0},{1}) = {2}", value1, value2, result);
//Closing the client releases all communication resources.
client.Close();
Quando você executa a amostra, as solicitações de operação e as respostas são exibidas na janela do console do cliente. Pressione ENTER na janela do cliente para desligá-lo.
Add(100,15.99) = 115.99
Subtract(145,76.54) = 68.46
Multiply(9,81.25) = 731.25
Divide(22,7) = 3.14285714285714
Press <ENTER> to terminate client.
O exemplo GettingStarted mostra a maneira padrão de criar um serviço e um cliente. O outro, Basic, se baseia nesse exemplo para demonstrar recursos específicos do produto.
Para configurar, compilar, e executar o exemplo
Verifique se você executou o Procedimento de instalação única para os exemplos do Windows Communication Foundation.
Para compilar a edição .NET do C# ou do Visual Basic da solução, siga as instruções contidas em Como Compilar as Amostras do Windows Communication Foundation.
Para executar o exemplo em uma configuração de computador único ou em vários, siga as instruções em Como executar os exemplos do Windows Communication Foundation.