Web Service Samples for .Net

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Table of Contents

• 1 API Options for Interacting with Alfresco


• 2 WCF Examples - .NET 3.0 and Above
  
  
  
  • 2.1 Service references
  
  
  • 2.2 Security configuration
  
  
  • 2.3 Alfresco client endpoints
  
  
  • 2.4 Authentication
  
  


• 3 WSE 2.0 and 3.0 Examples - .NET 2.0 and Above
  
  
  
  • 3.1 Project configuration
  
  
  • 3.2 Security configuration (programmatic)
  
  


• 4 Web Services (SOAP)


• 5 .NET 1.1 and .NET 2.0 Examples
  
  
  
  • 5.1 RESTful Calls
  
  


• 6 Resources
  
  
  
  • 6.1 WSE (.NET 2.0 and above)
  
  

API Options for Interacting with Alfresco

NOTE: I was writing code with .NET today (June 15th, 2010) for Alfresco and saw the documentation was pretty bad, so I am creating some. This will take a few days to get up.

• RESTful API
  

• Web Services API
  

WCF Examples - .NET 3.0 and Above

Service references

You will need to add a reference to each of the services you require. For example, it's not possible to perform authentication without 'AuthenticationService'.
You can access the service by using the following URLs (of course, replace 'server.name' and 'PORT' with your server name and port):

• http://server.nameORT/alfresco/api/AuthenticationService?wsdl
  
• http://server.nameORT/alfresco/api/RepositoryService?wsdl
  
• http://server.nameORT/alfresco/api/ContentService?wsdl
  
• other services...
  

See Alfresco_Content_Management_Web_Services for complete list of the services and for more documentation.

See oficial documentation for Service References management in VisualStudio for more details.

Security configuration

This section describes configuration of simple WCF security based on:

• 'basicHttpBinding' bindings configuration;
  
• 'security' with 'mode' equal to 'TransportWithMessageCredential';
  
• 'clientCredentialType' equal to 'UserName' that will allow WCF generate SOAP WSS headers for 'text' password type;
  
• 'timestamp' headers as one of the approaches of preventing replay attacks.
  

NOTE: Currently, Alfresco WEB Services support password type 'text' only! Additionally, 'timestamp' headers sending is required.




WCF requires secured connections for messages transferring with password type ‘digest’ or ‘text’ using 'HTTPS' protocol by default. This leads WCF validating server sertificates. This example will use 'hack return true' implementation of certificate validation callback for simplification:

System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate(object sender,
        System.Security.Cryptography.X509Certificates.X509Certificate certificate,
        System.Security.Cryptography.X509Certificates.X509Chain chain,
        System.Net.Security.SslPolicyErrors sslPolicyErrors)
{
    return true;
};

NOTE: This approach is not suitable for a production version of a product. For more information about 'ServerCertificateValidationCallback' and certificates validating configuration see official documentation for 'ServerCertificateValidationCallback' in MSDN.

For an example and more information about 'X509Certificate' see official documentation for 'X509Certificate' in MSDN.

Configuration for each service reference should be changed according to all conditions described above in 'app.config' configuration file:

<configuration>
   <system.serviceModel>
      <bindings>
         <basicHttpBinding>
            <binding name='RepositoryServiceSoapBinding' closeTimeout='00:01:00'
                     openTimeout='00:01:00' receiveTimeout='00:10:00'
                     sendTimeout='00:01:00' allowCookies='false'
                     bypassProxyOnLocal='false' hostNameComparisonMode='StrongWildcard'
                     maxBufferSize='65536' maxBufferPoolSize='524288'
                     maxReceivedMessageSize='65536' messageEncoding='Text'
                     textEncoding='utf-8' transferMode='Buffered' useDefaultWebProxy='true'>
               <security mode='TransportWithMessageCredential'>
                  <message clientCredentialType='UserName' /> 
               </security>
            </binding>
         </basicHttpBinding>
      </bindings>
   </system.serviceModel>
</configuration>

NOTE: 'AuthenticationService' doesn't require 'security' element configuration for its binding.

Sometimes, buffer sizes configured by default for messages exchanging are not enough. In this case application will crash with errors connected with buffer size and buffer read/write operations. For more information about configuration to avoid these problems and about WCF security configuration see oficial documentation for 'basicHttpBinding' configuration in MSDN.

Alfresco client endpoints

It's necessary to configure client endpoints pointing to your Alfresco server. All services which requre authentication should be configured against an HTTPS URL by default:

<configuration>
   <system.serviceModel>
      <client>
         <endpoint address='http://server.name:PORT/alfresco/api/AuthenticationService'
                   contract='AuthenticationService.AuthenticationServiceSoapPort'
                   binding='basicHttpBinding' name='AuthenticationService'
                   bindingConfiguration='AuthenticationServiceSoapBinding' />
         <endpoint address='https://server.name:PORT/alfresco/api/RepositoryService'
                   contract='RepositoryService.RepositoryServiceSoapPort'
                   binding='basicHttpBinding' name='RepositoryService'
                   bindingConfiguration='RepositoryServiceSoapBinding' />
      </client>
   </system.serviceModel>
</configuration>

Don't forget to enable SSL/TLS in your WEB Application Server!

Authentication

All Alfresco services except 'AuthenticationService' require authentication credentials for generating SOAP WSS headers. Currently, authentication for Alfresco WEB services performs through Alfresco tickets. It's necessary to start a session to receive a ticket:

AlfrescoAuthenticationService.AuthenticationServiceSoapPortClient authenticationService =
                     new AlfrescoAuthenticationService.AuthenticationServiceSoapPortClient();
AlfrescoAuthenticationService.AuthenticationResult ticket =
                                        authenticationService.startSession('admin', 'admin');

Each other service may be configured to authenticate with received ticket:



RepositoryService.RepositoryServiceSoapPortClient repositoryService =
                                     new RepositoryService.RepositoryServiceSoapPortClient();
repositoryService.ClientCredentials.UserName.UserName = ticket.username;
repositoryService.ClientCredentials.UserName.Password = ticket.ticket;
// Actions with 'repositoryService'...

Started session should be ended after finishing work with services which require user authentication:



// Actions with services which require user authentication...
authenticationService.endSession(ticket.ticket);

It's necessary to keep in mind that tickets have an expiration period.




Note, that 'AuthenticaionService' and 'RepositoryService' are namespaces specified during adding service references in VisualStudio using 'Add Service Reference' dialog.

WSE 2.0 and 3.0 Examples - .NET 2.0 and Above

Project configuration

WSE configuration may be accessed with right mouse click on the project name in ‘Solution Explorer’ tree and choosing ‘WSE Settings 3.0…’ menu item. Check 'Enable this project for Web Services Enhancements' on the 'General' tab. Click ‘Ok’ button after all required configurations will be changed.


Note, that it's necessary to configure .NET 2.0 in VisualStudio 2008 and above as target framework which will allow adding WEB references compatible with WSE framework for each service. It's possible to return to newer version of .NET framework afterwards.




It’s necessary to modify each WEB reference added into the project to enable WSE framework:

• open ‘Reference.cs’ source file (e.g. <project_root>\Web References\AuthenticationService\Reference.cs);
  
• find and replace all 'System.Web.Services.Protocols.SoapHttpClientProtocol' with 'Microsoft.Web.Services3.WebServicesClientProtocol'.
  

Security configuration (programmatic)

The approach of session starting is such the same as in WCF framework. The difference is in configuring credentials for services which require authentication:



// Ticket receiving logic
AuthenticationService.AuthenticationService authenticationService =
                                           new AuthenticationService.AuthenticationService();
AuthenticationService.AuthenticationResult ticket =
                                        authenticationService.startSession('admin', 'admin');

// Creating service client
RepositoryService.RepositoryService repositoryService =
                                                   new RepositoryService.RepositoryService();
// Creating UsernameToken instance to configure credentials as WSS headers
Microsoft.Web.Services3.Security.Tokens.UsernameToken token =
new Microsoft.Web.Services3.Security.Tokens.UsernameToken(ticket.username,
                                                          ticket.ticket,
                                                          PasswordOption.SendPlainText);

repositoryService.SetClientCredential(token);

WSE 3.0 requires that 'UsernameOverTransportAssertion' policy assertion was configured for the client security:



Microsoft.Web.Services3.Design.PolicyAssertion assertion =
                         new Microsoft.Web.Services3.Design.UsernameOverTransportAssertion();
Microsoft.Web.Services3.Design.Policy policy = new Microsoft.Web.Services3.Design.Policy(
                         new Microsoft.Web.Services3.Design.PolicyAssertion[] { assertion });
repositoryService.SetPolicy(policy);

It's necessary to configure endpoint addresses in 'app.config' for each WEB reference. This configuration should be available in the 'applicationSettings' section.




For more information about WSE security through XML configuring and about WSE 2.0 and 3.0 see Web_Service_Samples_for_.Net#Resources section.

Web Services (SOAP)

• Repository Services
  
• Content Services
  

.NET 1.1 and .NET 2.0 Examples

RESTful Calls

Resources

WSE (.NET 2.0 and above)

WSE 3.0 framework available for free download

How to: Add and Remove Web References

WS-Security Drilldown in Web Services Enhancements 2.0

Migrating to WSE 3.0

Implementing Direct Authentication with UsernameToken in WSE 3.0

Security Features in WSE 3.0

Configuring WSE framework for particular VS version
Web Services