Share via

Creating a Web Service for Remote Check-In and Check-Out

  • Article

This programming task provides an overview of how to create a custom Web service that runs in the context of Microsoft® Windows® SharePoint™ Services. The task steps through the process of creating a Web service for checking documents in and out of a document library by using the server-side object model.

Basic steps for creating a Web service

  • Create a virtual server on the server running Windows SharePoint Services but on a different port. You must be a local administrator on the server.
  • Create a Web service project on the new virtual server.
  • Generate and edit a static discovery file and a Web Services Description Language (WSDL) file.
  • Deploy the Web service files to the _vti_bin directory.
  • Create a Windows Application to consume the Web service.

Creating a virtual server on a different port

  • On the server that is running Windows SharePoint Services, create a folder in the Local_Drive:\Inetpub\wwwroot directory in which to create the Web service project.

  • On the taskbar, click Start, point to Administrative Tools, and then click Internet Information Services (IIS) Manager.

  • In IIS Manager, expand the Server_Name (local computer) node of the server where you want to create the virtual server and select Web Sites.

  • On the Action menu, point to New and click Web Site, which launches the Web Site Creation Wizard.

  • Click Next, and on the Web Site Description page type a name in the Description box for the Web site that will host the Web service. Click Next.

  • In the Enter the IP address to use for this Web site box of the IP Address and Port Settings page , select the IP address that you want to use, or use the default value (All Unassigned).

  • In the TCP port this Web site should use box, type a port number that is not already in use and click Next.

    Note  You do not need to assign a host header because Windows SharePoint Services handles hosting.

  • On the Web Site Home Directory page, browse to or type the file system path for the folder created in step 1 and click Next.

    Note  If you do not want to permit anonymous access to your virtual server, clear the Allow anonymous access to this Web site check box.

  • On the Web Site Access Permissions page, select the permissions that you want to use, and then click Next.

    Note  For best results in most cases, accept the default permissions. By default, the Read permission and the Run Scripts (such as ASP) permission are selected. Windows SharePoint Services automatically adds the Execute (such as ISAPI applications or CGI) permission to the appropriate folders.

  • Click Finish to exit the wizard.

Creating a Web service on the new virtual server

To create a custom Web service that runs within the context of a Windows SharePoint Services deployment, perform the following steps:

  • In Microsoft Visual Studio® .NET, on the File menu, point to New, and then click Project.

  • In the New Project dialog box, select Visual Basic Projects or Visual C# Projects in the Project Types box, depending on which language you prefer.

  • In the Templates box, select ASP.NET Web Service.

  • In the Location box, type the following path, using the port number specified for the new virtual server and CheckInOut as the name of the project:

    http://Server_Name:Port_#/CheckInOut

  • Click OK.

    Creating a Web service in Visual Studio .NET from a remote computer involves an extra step in the procedure required for creating a Web service in Visual Studio .NET from the server.

    At this point, if you are working from a remote computer, a Web Access Failed dialog box appears, saying that the file path does not correspond to the URL previously specified in the New Project dialog box. Perform the following steps:

    • Under What would you like to do?, ensure that Retry using a different file share path is selected and type the following path in the Location box, which includes the server name, the file system path specified for the project folder in step 1 of the procedure for creating a virtual server, and the project name specified in step 5 of this procedure:

      \\Server_Name\Local_Drive$\Inetpub\wwwroot\Project_Folder\CheckInOut

    • Click OK.

    Completing this step creates an ASP.NET Web service project.

  • Add a reference to the Windows SharePoint Services assembly by performing the following steps:

    • In Solution Explorer, right-click the References node and click Add Reference on the shortcut menu.

      If you are using Visual Studio .NET on the server, on the .NET tab of the Add Reference dialog box, select Windows SharePoint Services in the list of components. Click Select, and then click OK.

      If you are using Visual Studio .NET on a remote computer, perform the following steps:

      • Click Browse, and in the Select Component dialog box, navigate to the Local_Drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI folder on the server running Windows SharePoint Services. You may instead prefer to first copy Microsoft.SharePoint.dll from this folder to a local drive on the remote computer and then open this local copy of the DLL in the Select Component dialog box.
      • Select Microsoft.SharePoint.dll, click Open, and then click OK.

  • Right-click the Service1.asmx file for the project in Solution Explorer, click Rename, and type CheckInOut.asmx.

  • Right-click CheckInOut.asmx in Solution Explorer, and then click View Code.

  • Add the following directives to CheckInOut.asmx.cs:

    [Visual Basic .NET]

Imports Microsoft.SharePoint
Imports Microsoft.SharePoint.WebControls

[C#]

using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

  • Change the class and constructor names from Service1 to CheckInOut.

  • Add the following methods to the CheckInOut class:

    [Visual Basic .NET]

<WebMethod()>
Public Function CheckInDocument(inFile As String, comment As String) As String

    Dim site As SPWeb = SPControl.GetContextWeb(Context)
    Dim file As SPFile = site.GetFile(inFile)

    If file.Exists Then

        If SPFile.SPCheckOutStatus.None = file.CheckOutStatus Then

            Return "File not checked out."

        Else

            Try

                file.CheckIn(comment)
                Return file.Name + " successfully checked in."

                Catch ex As System.Exception

                    Return ex.Message + " :: " + ex.Source

            End Try

        End If

    Else

        Return "File does not exist."

    End If

End Function 'CheckInDocument

<WebMethod()>
Public Function CheckOutDocument(outFile As String) As String

    Dim site As SPWeb = SPControl.GetContextWeb(Context)
    Dim file As SPFile = site.GetFile(outFile)

    If file.Exists Then

        If SPFile.SPCheckOutStatus.None = file.CheckOutStatus Then

            Try

                file.CheckOut()
                Return "Check-out status: " + file.CheckOutStatus.ToString()

                Catch ex As System.Exception

                    Return ex.Message + " :: " + ex.Source

            End Try

        Else

            Return "File already checked out."

        End If

    Else

        Return "File does not exist."

    End If

End Function 'CheckOutDocument

[C#]

[WebMethod]
public string CheckInDocument(string inFile, string comment)
{
    SPWeb site = SPControl.GetContextWeb(Context);
    SPFile file = site.GetFile(inFile);

    if (file.Exists)
    {
        if (SPFile.SPCheckOutStatus.None == file.CheckOutStatus)
        {
            return "File not checked out.";
        }

        else
        {
            try
            {
                file.CheckIn(comment);
                return file.Name + " successfully checked in.";
            }

            catch (System.Exception ex)
            {
                return ex.Message + " :: " + ex.Source;
            }
        }
    }

    else
    {
        return "File does not exist.";
    }
}

[WebMethod]
public string CheckOutDocument(string outFile)
{
    SPWeb site = SPControl.GetContextWeb(Context);
    SPFile file = site.GetFile(outFile);

    if (file.Exists)
    {
        if (SPFile.SPCheckOutStatus.None == file.CheckOutStatus)
        {
            try
            {
                file.CheckOut();
                return "Check-out status: " + file.CheckOutStatus.ToString();
            }

            catch (System.Exception ex)
            {
                return ex.Message + " :: " + ex.Source;
            }
        }

        else
        {
            return "File already checked out.";
        }
    }

    else
    {
        return "File does not exist.";
    }
}

  • Press F5 to compile the project.

Generating and modifying static discovery and WSDL files

This procedure uses the command line utility that is installed with Visual Studio .NET to generate the static discovery (.disco) file and the WSDL (.wsdl) file.

  • On the taskbar, click Start, point to All Programs, point to Microsoft Visual Studio .NET, point to Visual Studio .NET Tools, and then click Visual Studio .NET Command Prompt to open a command prompt.

  • At the prompt type the following command to generate CheckInOut.disco and CheckInOut.wsdl files in the Local_Drive:\Documents and Settings\User folder:

    Disco http://Server_Name:Port_#/CheckInOut/CheckInOut.asmx

  • Open the new .disco and .wsdl files and replace the following XML processing instructions in the files:

    <?xml version="1.0" encoding="utf-8"?>

    with the following page directives:

    <%@ Page Language="C#" Inherits="System.Web.UI.Page"%>
<%@ Assembly Name="Microsoft.SharePoint, Version=11.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> <%@ Import Namespace="Microsoft.SharePoint.Utilities" %> <%@ Import Namespace="Microsoft.SharePoint" %>
<% Response.ContentType = "text/xml"; %>

  • Modify the following lines in the .disco file:

    <contractRef ref="http://Server_Name:Port_#/CheckInOut/CheckInOut.asmx?wsdl" docRef="http://Server_Name:Port#/CheckInOut/CheckInOut.asmx" xmlns="http://schemas.xmlsoap.org/disco/scl/" />
<soap address="http://Server_Name:Port#/CheckInOut/CheckInOut.asmx" xmlns:q1="http://tempuri.org/" binding="q1:CheckInOutSoap" xmlns="http://schemas.xmlsoap.org/disco/soap/" />

    to be as follows:

    <contractRef ref=<% SPEncode.WriteHtmlEncodeWithQuote(Response, SPWeb.OriginalBaseUrl(Request) + "?wsdl", '"'); %>  docRef=<% SPEncode.WriteHtmlEncodeWithQuote(Response, SPWeb.OriginalBaseUrl(Request), '"'); %>  xmlns="http://schemas.xmlsoap.org/disco/scl/" />
<soap address=<% SPEncode.WriteHtmlEncodeWithQuote(Response, SPWeb.OriginalBaseUrl(Request), '"'); %>  xmlns:q1="http://tempuri.org/" binding="q1:CheckInOutSoap" xmlns="http://schemas.xmlsoap.org/disco/soap/" />

  • Modify the following line in the .wsdl file:

    <soap:address location="http://Server_Name:Port#/CheckInOut/CheckInOut.asmx" />

    to be as follows:

    <soap:address location=<% SPEncode.WriteHtmlEncodeWithQuote(Response, SPWeb.OriginalBaseUrl(Request), '"'); %> />

  • Save the files as CheckInOutdisco.aspx and CheckInOutwsdl.aspx respectively.

  • To include the CheckInOut service in the list of default Windows SharePoint Services Web services that is displayed in the Add Web Reference browser of Visual Studio .NET, perform the following steps:

    • In Notepad, open the spdisco.aspx file of the Local_Drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI folder.

    • Add the following lines to the end of the file within the discovery element and save the file:

      <contractRef ref=<% SPEncode.WriteHtmlEncodeWithQuote(Response, spWeb.Url + "/_vti_bin/CheckInOut.asmx?wsdl", '"'); %> docRef=<% SPEncode.WriteHtmlEncodeWithQuote(Response, spWeb.Url + "/_vti_bin/CheckInOut.asmx", '"'); %> xmlns="http://schemas.xmlsoap.org/disco/scl/" />
<soap address=<% SPEncode.WriteHtmlEncodeWithQuote(Response, spWeb.Url + "/_vti_bin/CheckInOut.asmx", '"'); %> xmlns:q1="http://schemas.microsoft.com/sharepoint/soap/directory/" binding="q1:CheckInOutSoap" xmlns="http://schemas.xmlsoap.org/disco/soap/" />

    Note  The text appearing before "Soap" in the binding attribute of the soap element (in this example, binding="q1:CheckInOutSoap") specifies the name of the class that is defined in the Web service.

Copy the Web service files to the _vti_bin directory

The _vti_bin virtual directory maps physically to the Local_Drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\ISAPI directory, which contains the default Web service files used in Windows SharePoint Services. Copy the new CheckInOutwsdl.aspx and CheckInOutdisco.aspx files, as well as the CheckInOut.asmx file of the Web service project, to the ISAPI folder. Also copy the corresponding assembly (CheckInOut.dll) from the bin folder of the project to the bin subfolder within the ISAPI folder.

From the _vti_bin directory, a Web service offers its functionality to the site that is specified when adding a Web reference for the service.

Creating a Windows Application to consume the Web service

  • On another computer, open Visual Studio .NET.

  • On the File menu, point to New, and then click Project.

  • In the New Project dialog box, click Visual C# Projects or Visual Basic Projects, and then select the Windows Application template.

  • Type a name for the application in the Name box, specify a location for the project files in the Location box, and then click OK.

  • In Solution Explorer, right-click Web References, and then click Add Web Reference.

  • In the address bar of the Add Web Reference browser, type the URL for the site to which to apply the service, as follows, and press ENTER:

    http://Server_Name/[sites/][Site_Name/]

  • In the Available references window, find the CheckInOut service in the list of Web services and click View Documentation.

    Note  Skipping this step results in adding a reference to all the Web services that are displayed.

  • Click Add Reference to download the service contract for the Web service.

  • Open Form1 in Design view, display the Toolbox, and then drag two text boxes and two buttons onto the form. The first text box is used to specify the URL of a document when checking it in or out, and the second text box is used for typing a comment when checking in a file.

  • Double-click the Button1 control on Form1 to display the code-behind file in the code editor, and add the following code for checking out documents to the button1_Click handler, replacingWeb_Reference_Folder_Name with the folder name used for the reference to the CheckInOut service as displayed in Solution Explorer under Web References.

    [Visual Basic .NET]

Dim svcDocLib As New Web_Reference_Folder_Name.CheckInOut()
svcDocLib.Credentials = System.Net.CredentialCache.DefaultCredentials

Dim str As String = svcDocLib.CheckOutDocument(textBox1.Text)
MessageBox.Show(str)

[C#]

Web_Reference_Folder_Name.CheckInOut svcDocLib = new Web_Reference_Folder_Name.CheckInOut();
svcDocLib.Credentials = System.Net.CredentialCache.DefaultCredentials;

string str = svcDocLib.CheckOutDocument(textBox1.Text);
MessageBox.Show(str);

  • Double-click the Button2 control on Form1 to display the code-behind file in the code editor, and add the following code for checking in documents to the button2_Click handler, replacingWeb_Reference_Folder_Name with the folder name used for the reference to the CheckInOut service as displayed in Solution Explorer under Web References.

    [Visual Basic .NET]

Dim svcDocLib As New Web_Reference_Folder_Name.CheckInOut()
svcDocLib.Credentials = System.Net.CredentialCache.DefaultCredentials

Dim str As String = svcDocLib.CheckInDocument(textBox1.Text, textBox2.Text)
MessageBox.Show(str)

[C#]

Web_Reference_Folder_Name.CheckInOut svcDocLib = new Web_Reference_Folder_Name.CheckInOut();
svcDocLib.Credentials = System.Net.CredentialCache.DefaultCredentials;

string str = svcDocLib.CheckInDocument(textBox1.Text, textBox2.Text);
MessageBox.Show(str);

  • Add the following directives to the top of the code-behind file for Form1.cs.

    [Visual Basic .NET]

Imports System.Net

[C#]

using System.Net;

  • Press F5 to compile and run the project.

To check out a document from a document library, type the site-relative URL of the file (Folder_Name/File_Name) in the first text box and click the first button. To check the document in, type the site-relative URL in the first text box, type a comment in the second text box, and then click the second button.