The LicenseProvider is passed a number of parameters: ❑ context: This object provides information about the environment that the control is executing in. The UsageMode property in this object, for instance, allows you to check whether the control is in design or run time mode. ❑ type: The datatype of the control. ❑ instance: A reference to the control. ❑ allowExceptions: When set to True, it indicates that a LicenseException is to be thrown if licensing fails. Now that your license and license provider are built, you need to attach the license provider to your custom control. Follow these steps: 1. Add the LicenseProviderAttribute to your class declaration and pass the attribute a reference to your license provider. This Visual Basic 2005 example uses the license provider created in the previous section: <LicenseProvider(GetType(MyLicensingProvider)), _ ToolboxData(“<{0}:MyControl1 runat=server></{0}:MyControl1>”)> _ Public Class MyControl In C#: [LicenseProvider(typeof(MyLicensingProvider))] [ToolboxData(“<{0}:MyControl1 runat=server></{0}:MyControl1>”)] public class MyControl { 2. In your control’s constructor, your control should call the Validate method of the LicenseManager object (the LicenseManager automatically references the LicenseProvider referenced by the attribute on the class). If the licensing fails, a LicenseException error is raised, terminating the control’s processing. This Visual Basic 2005 code demonstrates how the Validate method is used: Dim lic As System.ComponentModel.License Public Sub New() lic = LicenseManager.Validate(GetType(MyControl), Me) End Sub In C#: public class MyControl { System.ComponentModel.License lic; public MyControl() { lic = LicenseManager.Validate(typeof(MyControl), this); } } 198 Chapter 7 12_57860x ch07.qxd 10/4/05 9:25 PM Page 198 3. In the Dispose method of your control, call the Dispose method of any license that you retrieved in your control’s constructor and haven’t already disposed: Public Overloads Overrides Sub Dispose() If lic IsNot Nothing Then lic.Dispose() lic = Nothing End If End Sub In C#: public override void Dispose() { if(lic != null) { lic.Dispose(); lic = null; } } In Step 2, instead of using the Validate method, you can call the IsValid method, passing the type of the custom control. The IsValid method doesn’t throw an exception but returns False if licensing fails. This is a Visual Basic 2005 example of the IsValid property: Public Sub New() If LicenseManager.IsValid(GetType(CustomControl1)) = False Then Throw New System.Exception(“Licensing failed.”) End If End Sub In C#: public MyControl() { if(LicenseManager.IsValid(GetType(CustomControl1)) == false) { throw new System.Exception(“Licensing failed.”); } } The LicenseManager object that you call from your control is created for you automatically, and handles calling the GetLicense method of your License provider either through the LicenseManager’s Validate or IsValid method. This is just the bare bones of implementing licensing. You can have your License object check the licensing source (a text file, a Web Service) for any set of conditions. You might specify usage counts in your licensing, or list which functions on the control are to be enabled. In your license provider, you can add additional methods or properties that interact with the license object to check for these conditions. Finally, in your custom control, you can call these methods and properties to determine what your control is allowed to do. 199 Developer Tools 12_57860x ch07.qxd 10/4/05 9:25 PM Page 199 Rather than writing your own licensing provider, you can use the LicFileLicenseProvider, which is part of the .NET framework. You can create a licensing provider by inheriting from LicFileLicenseProvider and implementing only the functions that you want to override. If you have worked with licensing in COM applications, you’ll find that the LicFileLicenseProvider supports the same functionality as ActiveX licensing. Managing the Personalization Subsystem When you deploy your Web Parts they will take advantage of the membership subsystem that is part of ASP.NET. The membership subsystem is automatically activated and a membership data store is set up in SQL Server Express the first time you add a WebPartManager to a Web page in Visual Studio 2005. However, to take full advantage of personalization, you need to provide a method for users to identify themselves so that the personalizations that users make are applied to them. In addition, ASP.NET provides a mechanism for you to control where your personalization data is stored and allows you to switch between data stores from within your code. As you’ll see, there are many aspects of personalization that you can control from your code. You can even set up your page so that changes made by one user (the system administrator, for instance) are applied to all users. This all boils down to these three topics: ❑ Allowing users to identify themselves to the application ❑ Setting up personalization providers ❑ Managing personalization for your page Identifying the User ASP.NET 2.0 comes with a set of login controls that you can add to a Web page to create a login page. The key component is the Login control, which adds text boxes for entering the username and password, a button for logging in, and a checkbox for setting up a cookie that will let the user be remembered by the login process. Using these controls allows a user to log on to the site with a specific identity and be assigned the customizations that he has made. In order for users to log on to the membership system, you need to set up those user identities for the site. You can add new users to your site from Visual Studio 2005 with these simple steps: 1. Select ASP.NET Configuration from the Website menu. 2. When the Web site administration page is displayed (see Figure 7-11), click the Security tab. 3. Click the Create user link to display the Create User form. If your Web site is using Windows authentication, you won’t be able to create users and the Create User link won’t appear. To stop using Windows authentication, click the Select authentication type link (see Figure 7-12), and then select the From the Internet option and click Done. 4. Enter the information required by the form and click the Create User button to create the user. 200 Chapter 7 12_57860x ch07.qxd 10/4/05 9:25 PM Page 200 Figure 7-11 Figure 7-12 201 Developer Tools 12_57860x ch07.qxd 10/4/05 9:25 PM Page 201 In most cases, you probably already have a list of users with usernames and passwords stored in some datastore (such as a database or Active Directory repository). In these situations, it makes more sense to create code that will read users from your datastore and add them to your site’s membership system. To create a user from your code, you can use the CreateUser method of the Membership object. This method can accept a number of parameters that set the user’s name, password, e-mail address, and other items required on the Create User page of the administration pages. Some of the CreateUser methods accept a MembershipCreateStatus object while others do not. If you use one of the methods that doesn’t accept a MembershipCreateStatus object, if the user isn’t successfully created, a MembershipCreateUserException error is raised. On the other hand, if you use one of the methods that does accept a MembershipCreateStatus object, no error is thrown if the user isn’t successfully created. Instead, the MembershipCreateStatus object passed as a parameter is updated with the result from attempting to create the user. The following Visual Basic 2005 code uses one of the versions of the CreateUser methods that accepts a MembershipCreateStatus object. After calling the CreateUser method, the code tests the Membership- CreateStatus’s value using one of the MembershipCreateStatus enumerated values to see if the attempt to create a user succeeded. Dim nu As System.Web.Security.MembershipUser Dim stat As System.Web.Security.MembershipCreateStatus nu = System.Web.Security.Membership.CreateUser(“PeterVogel”, “CMingus”, _ “peter.vogel@phvis.com”, “Who is a bassist”, “Charlie”, True, stat) If stat <> MembershipCreateStatus.Success Then Me.txtError.Text = “User creation failed.” End If In C#: System.Web.Security.MembershipUser nu; System.Web.Security.MembershipCreateStatus stat; nu = System.Web.Security.Membership.CreateUser(“PeterVogel”, “CMingus”, “peter.vogel@phvis.com”, “Who is a bassist”, “Charlie”, true, out stat); if (stat != MembershipCreateStatus.Success){ this.txtError.Text = “User creation failed.”; } While administering your users from Visual Studio 2005 makes sense for your test site, you will want to use a more sophisticated tool on your production Web site. You can: ❑ Add the ASP.NET user creation controls to your pages to give you (or your users) the ability to create users. ❑ Administer users with the Web administration pages for your Web site by selecting ASP.NET Configuration from the Website menu from within Visual Studio 2005. From outside Visual Studio 2005 or on a deployed site, use http:/hostname/sitename/WebAdmin.axd. ❑ Build user management pages with the Membership objects. 202 Chapter 7 12_57860x ch07.qxd 10/4/05 9:25 PM Page 202 However, to test and develop your Web site, Visual Studio 2005 provides you with all the functionality that you need through the Website Administration tool. Setting up Personalization Providers The connection between your application, your personalization information, and the membership sys- tem is handled through personalization providers. Two personalization providers ship with the .NET Framework: one for working with Access (AspNetAccessPersonalizationProvider) and one for SQL Server (AspNetSqlPersonalizationProvider). The provider being used is specified in the web.config file in the NET directory using <add> tags within the <personalization> element inside the <webParts> element. In the <add> tag you must specify the type of the provider, a name to refer to the provider, and a connection string to the provider. The web.config file for the computer is kept in the .NET directory and, by default is set to use the SQL Server provider. In this example, the SQL Server provider is being used and the connection string is defined inside the connectionstrings element, which is also in the web.config file: <connectionStrings> <add name=”LocalSqlServer” connectionString=”data source=.\SQLEXPRESS;Integrated Security=SSPI; AttachDBFilename=|DataDirectory|aspnetdb.mdf;User Instance=true” providerName=”System.Data.SqlClient”/> </connectionStrings> <system.web> <webParts> <personalization> <providers> <add name=”AspNetSqlPersonalizationProvider” connectionStringName=”LocalSqlServer” type=”System.Web.UI.WebControls.WebParts.SqlPersonalizationProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a” /> </providers> You can change this setting to use the AspNetAccessPersonalizationProvider for the computer that the web.config file is installed on with these tags: <add name=”AspNetAccessPersonalizationProvider” connectionStringName=”AccessDBpath” type=”System.Web.UI.WebControls.WebParts.AccessPersonalizationProvider”/> Inserting these tags in your application’s web.config file allows you to set the personalization provider used just for your application. You can also set up multiple providers within the <providers> tag. The defaultProvider attribute on the personalization element lets you specify which provider should be used automatically (later in this section you’ll see how to switch between providers dynamically). This example defines both the Access and SQL providers but sets the Access provider as the default provider: 203 Developer Tools 12_57860x ch07.qxd 10/4/05 9:25 PM Page 203 <personalization defaultProvider=”AspNetAccessPersonalizationProvider”> <providers> <add name=”AspNetSqlPersonalizationProvider” connectionStringName=”LocalSqlServer” type=”System.Web.UI.WebControls.WebParts.SqlPersonalizationProvider, System.Web, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a” /> <add name=”AspNetAccessPersonalizationProvider” connectionStringName=”AccessDBpath” type=”System.Web.UI.WebControls.WebParts.AccessPersonalizationProvider”/> </providers> You can also set up several providers of the same type but with different connection strings. This enables you to switch between different SQL Server personalization datastores. In Chapter 11, you see how you can manage personalization options from your code (including changing providers at run time). Summary This chapter covered the essential issues that appear after you’ve created your custom control. You learned how to: ❑ Configure your control project to support design time debugging ❑ Update user controls, custom controls, and Web Parts after you’ve deployed your Web site ❑ License your control to ensure that only developers you have provided a license to can use your control ❑ Manage the personalization and membership system that supports Web Parts At this point, you’re ready to write and deploy controls with all of the functionality of a custom control. However, you won’t create a control for the fun of it— you want to use the control to support your application. So the next step is to look at how you can incorporate business functionality into your controls, which is the topic of the next chapter. 204 Chapter 7 12_57860x ch07.qxd 10/4/05 9:26 PM Page 204 Part III Extending Controls Chapter 8: Adding Business Functionality Chapter 9: Adding Advanced Functionality Chapter 10: Communicating Between Web Parts Chapter 11: Working with the Web Part Architecture 13_57860x pt03.qxd 10/4/05 9:21 PM Page 205 13_57860x pt03.qxd 10/4/05 9:21 PM Page 206 Adding Business Functionality Creating a custom control or a Web Part (or even a user control) isn’t an end in itself—you create these components to have them perform some business functionality. As discussed in Chapter 1, the reason that you create a control is to build a reusable component containing logic that belongs in your application’s user interface. At this point in the book, you can create a custom control or a Web Part and deploy it. You can use any of these controls on a page, as part of another user control, or as a Web Part. Now you want to go beyond simply implementing a control and add business-specific functionality: the methods, properties, and events that will support your application. This chapter gives you the tools to extend your controls by adding code to support your application. Specifically, you can add code to perform these tasks: ❑ Associate code with the events fired by your constituent controls ❑ Add new methods and properties with business-specific logic ❑ Have your control fire events that allow developers to integrate their processing with your own code ❑ Trigger events that normally execute only at run time to also execute at design time ❑ Control what happens as new constituent controls are added or removed from your custom control You’ve probably realized that you have many places to put your application code: the events for your control (such as Init and Load); methods and properties of the underlying object that you can override; custom methods and properties that you add to your control; and your control’s constructor. So one of the decisions that you have to make is how to divide up all of the code that you want to put in your custom control, a process known as factoring. 14_57860x ch08.qxd 10/4/05 9:29 PM Page 207 [...]... typical CreateChildControls method in Visual Basic 2005 with the constituent control’s events marked: Dim btn As System .Web. UI.WebControls.Button Dim txt As System .Web. UI.WebControls.TextBox btn = New System .Web. UI.WebControls.Button txt = New System .Web. UI.WebControls.TextBox ‘Button’s constructor runs ‘Button’s Init event fires ‘TextBox’s constructor runs ‘TextBox’s Init event fires Me .Controls. Add(btn)... ‘Button’s Load event fires Me .Controls. Add(txt) ‘TextBox’s Load event fires 215 Chapter 8 In C#: System .Web. UI.WebControls.Button btn; System .Web. UI.WebControls.TextBox txt; btn = new System .Web. UI.WebControls.Button(); //Button’s constructor runs //Button’s Init event runs txt = new System .Web. UI.WebControls.TextBox(); //TextBox’s constructor runs //TextBox’s Init event runs this .Controls. Add(btn); //Button’s... EventHandler(AddressOf UpdateTextBox) AddHandler txt.TextChanged, ev Me .Controls. Add(txt) In C#, the equivalent operation is handled by assigning a new EventHandler to the event for the object by using the += operator: System .Web. UI.WebControls.TextBox txt; EventHandler ev; txt = new System .Web. UI.WebControls.TextBox; txt.Text = “Hello, World”; txt.ID = “txtInput”; txt.Click += new System.EventHandler(this.UpdateTextBox);... tools and code in this chapter can be used not only in custom controls and Web Parts but also in user controls Factoring Your Code This chapter addresses three kinds of procedures that may seem very much alike: ❑ The methods discussed in previous chapters that were called automatically by ASP.NET (such as CreateChildControls, the control’s constructor) ❑ The events that you’re already familiar with. .. Property List Adding properties and events is handled in custom controls and user controls as it is in other objects So if you’re familiar with these techniques, you can skip over the discussion of those topics later in this chapter The Role of Events Events function differently than methods and properties Methods and properties enable code in the host page to communicate with the control: The host page’s... event is fired just before ASP.NET prepares the custom control to be returned to the browser After this event, ASP.NET calls the Render* methods on your custom control ❑ Unload: Indicates that the custom control has been sent to the browser and that ASP.NET is about to complete processing of the custom control ❑ 214 Init: Indicates that the custom control has been loaded but no ASP.NET processing has taken... created by the custom control Normally, the constituent control’s Load event fires when the constituent control is added to the custom control’s Controls collection Therefore, assuming that you create your constituent controls in the custom control’s CreateChildControls method, the constituent control’s constructor, Init, and Load events will execute during the custom control’s CreateChildControls method... from the browser, controls notify the host page (by raising events) that something has changed Events are supported in custom controls as they are in other objects but with a new ability: You can bubble events from constituent controls up to your custom controls, as discussed later in this chapter The Life Cycle of a Custom Control Knowing what the events are in the life cycle of your custom control,... (including changes to the custom control) during the invocation of these events may be overwritten by the ASP.NET standard processing For instance, in the PreInit event, code on the host page will have access to the WebPartZone but not to the custom controls within the zone At the end of the host page’s life cycle, the custom control’s Render method executes after the host page’s PreRender and PreRenderComplete... manipulate the methods and properties of your custom control before your custom control renders itself Constituent Control Events Constituent controls in the custom control fire the same events that the custom control does (Init, Load, and so on) These events are triggered by the creation of the constituent controls While not an event, the control’s constructor is also part of this process and executes before . Functionality Chapter 10: Communicating Between Web Parts Chapter 11: Working with the Web Part Architecture 13_57 860 x pt03.qxd 10/ 4 /05 9 :21 PM Page 20 5 13_57 860 x pt03.qxd 10/ 4 /05 9 :21 PM Page 20 6 Adding Business Functionality Creating. ch07.qxd 10/ 4 /05 9 :25 PM Page 20 0 Figure 7-11 Figure 7- 12 201 Developer Tools 12_ 57 860 x ch07.qxd 10/ 4 /05 9 :25 PM Page 20 1 In most cases, you probably already have a list of users with usernames and. http:/hostname/sitename/WebAdmin.axd. ❑ Build user management pages with the Membership objects. 20 2 Chapter 7 12_ 57 860 x ch07.qxd 10/ 4 /05 9 :25 PM Page 20 2 However, to test and develop your Web site, Visual Studio 20 05